Tax Calculation

Sales tax is calculated server-side at checkout from the customer's shipping state and your tenant's tax configuration.

Where to configure

Tax rates are stored in commerce__tax_rates per tenant. Admins configure them via the tenant config (or direct DB for now — a UI is planned).

Each rule has:

• tenant_id
• label (e.g. "NY Sales Tax")
• rate (decimal, e.g. 0.0875 for 8.75%)
• state (optional — state code like "NY")
• country (default "US")

How it works

1. Customer enters shipping address → state detected
2. Frontend calls POST /checkout/calculate-tax with cart_id and shipping_state
3. Server picks the most specific matching rule (state + country → country only → no tax)
4. Returns tax_amount and tax_rate
5. Checkout summary displays tax on its own line

Server-side enforcement

The tax amount is always recomputed server-side during order creation. Even if the frontend sends tax_amount: 0, the server will set it to the correct value based on the shipping address. This prevents tax evasion via modified client-side values.

Exemptions

Currently tax is calculated uniformly per state. Future enhancements:

• Per-category tax exemption (e.g. clothing in NJ)
• Tax-exempt customer flag (e.g. resellers)
• Integration with TaxJar or Avalara for real-time multi-jurisdiction rates

Testing

Use a test address in a state you've configured. Verify:

• The right rate applies
• Tax is added to the grand total
• Tax appears in order history