Classification and Tax

Helm separates product classification from tax rate governance. Classification assigns HS codes to items. Tax estimation calculates duties and taxes from approved tax data, item values, and exchange rates.

Classification flow

1. Normalize item descriptions from the original invoice or 1688 parser.
2. Add simplified product names, material, and product use when available from invoice review, 1688 parsing, or translation utilities.
3. Run bulk classification for missing items.
4. Review China HS and Uganda HS outputs separately.
5. Manually edit uncertain codes before calculating taxes.

Tax estimate behavior

Tax estimates are cached by consignment input hash. Helm marks a cached estimate stale when input values change. A stale estimate can still explain previous calculations, but it should not be treated as current.

When estimates are recomputed, confirm:

• Every taxable item has a Uganda HS code.
• Item value and quantity reflect the invoice.
• Exchange rate source is current. URA currency rates are fetched by Supabase cron, so investigate the scheduled job before manually overriding rate data.
• The displayed totals include each applicable component.

AI rate proposals

The default tax estimate path uses configured tax rates and default rates where appropriate. AI-estimated rates are not silently used as production rates. They are submitted to the draft review workflow, where an admin can approve or reject them.

Review draft rates for:

• HS code validity.
• Duty rate source.
• VAT and withholding treatment.
• Excise applicability.
• Notes that explain the approval decision.

Escalation

Escalate to engineering when a valid item cannot be calculated because of missing approved rates, cache mismatch, repeated stale estimate behavior, or a classification endpoint failure.