Exempt a Sale
You can use a customer’s exemption certificate when you calculate cart tax or create an order.
- Cart calculation (
POST /merchant/cart/calculate) for self-managed and TaxCloud-connected merchants. - Order creation (
POST /merchant/order/create) for TaxCloud-connected merchants. - Rate lookups (
GET /request/v60), which report the customer’s certificates but never change the rate.
Ask for an exemption
To request an exemption, add an exemption object.
exemptionId is the certificateId returned by
cert/create. Letter case and
surrounding spaces do not matter.
Omit exemption to calculate tax as usual. A null or empty object,
isExempt: false without an ID, and a blank ID without isExempt: true
all leave Ziptax’s exemption logic inactive.
How a certificate is matched
Ziptax checks that its certificate covers the sale.
- It belongs to the merchant, and its
customerIdis exactly the cart’scustomerId. - It is not disabled.
- The evaluation date is on or after its
effectiveDateand on or before itsexpirationDate, when those are set. - Its
statesinclude the sale’s destination state. This is true even when the sale is taxed at the origin, such as an in-state sale in an origin-sourced state. - If it is a single-purchase certificate, it was named by
exemptionIdand itsorderNumberequals the cart’scartId(or, on an order, theorderId).isExempt: truenever picks a single-purchase certificate.
The evaluation date is the calendar day of the request’s transactionDate,
read in that timestamp’s own UTC offset, so 2026-11-30T22:00:00-08:00 is
November 30. Without a transactionDate, it is today in UTC.
When isExempt: true finds more than one certificate, Ziptax uses the one with
the latest effectiveDate (a certificate with none counts as oldest), then the
lowest certificateId.
When a certificate applies, the whole cart is exempt: every line item, including shipping and handling. Ziptax does not exempt part of a cart.
Exempt a cart
Add exemption to each cart that should be exempt. This self-managed cart
uses the certificate from Create a certificate.
A connected cart uses the same exemption object with TaxCloud taxability codes.
For a self-managed merchant, a covered cart comes back with every line at rate
0 and amount 0, plus an exemption block that says which certificate
applied:
The exemption block in the response
A self-managed cart includes these fields when you request an exemption. Connected carts and orders include them when Ziptax applies its own certificate and TaxCloud returns the sale as exempt.
notAppliedReason values:
For an automatic match, send "exemption": { "isExempt": true } in place of the
named ID above. If no certificate matches, a self-managed cart returns 200
with the usual tax amounts and this exemption block.
If you name a certificate and it fails Ziptax’s checks, see Errors.
Self-managed merchants
- Destination state. The certificate is checked against the state the
destination address resolves to, not the
stateyou sent. - No partial results. The whole request fails if any cart’s named certificate does not cover it.
- Billing. A named certificate that is not found, belongs to another
customer, or is disabled, expired, or not yet effective is refused before any
address is looked up, so nothing is billed.
state_not_coveredandsingle_purchase_mismatchare known only after the destination is resolved, and that lookup is billed. A covered cart still bills its destination lookup. - Rate breakdown. With
taxRateDetail=base, each line of an exempt cart has"baseRates": []. - Unknown fields.
exemptionmay contain onlyexemptionId(a string) andisExempt(a boolean). Anything else returns400.
See Self-Managed Cart Calculation.
TaxCloud-connected merchants
TaxCloud does not hold Ziptax certificates, so Ziptax decides the exemption and tells TaxCloud only that the sale is exempt:
Because TaxCloud receives isExempt: true with no certificate id, TaxCloud
records the sale as exempt without a certificate attached (“Exempt, no
certificate”). The certificate itself stays in Ziptax.
On the connected path, the destination state is the state you sent. A full
state name is read as its two-letter code.
For a connected cart, use the named request above with the merchant’s TaxCloud
taxability codes (for example, 11010 for shipping). If TaxCloud returns the
sale as exempt, Ziptax adds the certificate fields to TaxCloud’s exemption
object. Requests forwarded as-is, including requests when the Ziptax certificate
store is disabled, return TaxCloud’s response unchanged.
Record the order
For a connected merchant, create the order from the cart as usual with
order/create-from-cart. That call is
forwarded unchanged: TaxCloud records the cart exactly as it was calculated,
exemption included, so you do not send the exemption again.
Exempt an order
POST /merchant/order/create (TaxCloud-connected
merchants only) follows the same rules as a connected cart. A single-purchase
certificate is matched against the order’s orderId, and the evaluation date
is the order’s transactionDate.
See certificates in a rate lookup
Add merchantId, and optionally customerId, to a v60 rate lookup to see
which of the merchant’s certificates cover the looked-up state. The response
gains an exemptionDetail block. Rates are never changed. See
Exemption certificates on a rate lookup.
Errors
On carts, the message starts with the cart’s position, for example:
A certificate that is not found, or belongs to another customer, gives
exemption certificate not found for this customer.