Calculate Cart Tax

Calculates sales tax for one cart of up to 250 line items with the Ziptax rate engine. Nothing is stored: the returned cartId correlates the response with the request only.

Sourcing. The destination is resolved first and its sourcing rule decides where the cart is quoted: at the destination, or at the origin when the destination’s rule is origin-based and the origin resolves into the same state. Origin sourcing never crosses a state line. A product line’s own rate rules can override the cart’s sourcing: the most granular state, statewide, county or conditional rule that sets isDestinationTaxType quotes the line at the destination (true) or the origin (false), still never across a state line.

Lines. General goods (no taxabilityCode, or 0) are quoted at the SALES_TAX total of the address the cart is quoted at. Shipping (10001) and handling (11000) follow that address’s shipping taxability: Y taxes both, N neither, L handling only. Any other code is a product code and needs the product_rates entitlement. It is quoted with its product rate rules: the most granular rule that carries a value applies to the whole rate, and a place or tax-code rule applies once to the summed rate of the components it covers; a rule exempts the line when price x quantity, rounded to cents, is strictly above exemptOver or strictly below exemptUnder, and otherwise taxes the amount above taxablePortionOver, times percentTaxable, at effectiveTaxRate or the rate it applies to. Prepared food (41000, 41041) is quoted from its meal tax when meal tax applies, which takes precedence over the rate rules: a STATE_SPECIAL_TOTAL component replaces all sales tax, ADD_ON components are added on top, and an OCCUPATION_TAX component is added and the sales tax is charged on it too. tax.rate is the total rate the line collects.

transactionDate. Optional RFC 3339 date-time, defaulting to now. A date in a past month is quoted from that month’s historical rates, with rate rules and meal tax dated on the exact day in the date’s own offset. The current month or a later one is quoted from current rates. A past month whose tax_table rates the running service has not loaded uses the current tax_table rates, while SST states and other dated sources keep the month, and rate rules and meal tax stay dated on its own day. A date before the historical rates start, or one that is not RFC 3339, is rejected with 400 before any address is resolved. The response echoes it.

Failures. A destination that cannot be resolved fails the cart with 422 and is never quoted at the origin, which can be in another state. An origin that cannot be resolved falls back to the destination. A rate response without a SALES_TAX total fails with 500 rather than quoting 0%. A failed rate lookup names the line item it failed on.

Billing. Each distinct address the cart resolved is one geo request, however many taxability codes it is resolved with, and an address that resolved is billed even when a later line fails. The origin is resolved only when the cart or a line is sourced there, or for a prepared-food line, whose seller-located meal tax comes from it, unless the destination’s meal tax already reports RULES_NOT_LOADED, LOCATION_NOT_RESOLVED or STATE_NOT_COVERED and the line is not due at the origin. The addresses are free-form strings, so the origin’s state is known only once it resolves: an origin-sourced cart whose origin is in another state never resolves it again for a line, while on a destination-sourced cart such a line resolves, and bills, the origin to learn its state, even when it turns out to be in another state.