Skip to navigation

Exempt a Sale

Apply an exemption certificate to a cart or order and find certificates with a v60 rate lookup.
View as Markdown

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.

RequestMeaning
{ "exemptionId": "01a1f456-..." }Use a specific certificate. A Ziptax certificate must belong to the merchant and customer and cover the sale. A connected merchant can also pass a TaxCloud certificate ID.
{ "isExempt": true }Look for a blanket certificate that covers the sale. If no Ziptax certificate matches, self-managed carts are taxed as usual and connected carts go to TaxCloud unchanged.

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.

  1. It belongs to the merchant, and its customerId is exactly the cart’s customerId.
  2. It is not disabled.
  3. The evaluation date is on or after its effectiveDate and on or before its expirationDate, when those are set.
  4. Its states include 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.
  5. If it is a single-purchase certificate, it was named by exemptionId and its orderNumber equals the cart’s cartId (or, on an order, the orderId). isExempt: true never 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.

cURL
curl -X POST "https://api.zip-tax.com/merchant/cart/calculate" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
"transactionDate": "2026-11-19T15:30:00Z",
"items": [
{
"cartId": "cart-1001",
"customerId": "customer-123",
"currency": { "currencyCode": "USD" },
"origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043" },
"destination": { "line1": "100 Example Ave", "city": "Reno", "state": "NV", "zip": "89501" },
"exemption": { "exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71" },
"lineItems": [
{ "index": 0, "itemId": "sku-1", "price": 120.00, "quantity": 2, "tic": 0 },
{ "index": 1, "itemId": "ship", "price": 15.00, "quantity": 1, "tic": 10001 }
]
}
]
}'

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:

{
"transactionDate": "2026-11-19T15:30:00Z",
"items": [
{
"cartId": "cart-1001",
"customerId": "customer-123",
"origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043", "countryCode": "US" },
"destination": { "line1": "100 Example Ave", "city": "Reno", "state": "NV", "zip": "89501", "countryCode": "US" },
"exemption": {
"exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
"isExempt": false,
"applied": true,
"certificateId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
"reason": "Resale",
"notAppliedReason": null
},
"currency": { "currencyCode": "USD" },
"lineItems": [
{ "index": 0, "itemId": "sku-1", "tic": 0, "price": 120, "originalPrice": 120, "quantity": 2, "tax": { "rate": 0, "amount": 0 } },
{ "index": 1, "itemId": "ship", "tic": 10001, "price": 15, "originalPrice": 15, "quantity": 1, "tax": { "rate": 0, "amount": 0 } }
]
}
]
}

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.

FieldTypeDescription
exemptionIdstring or nullThe exemptionId you sent, or null.
isExemptbooleanThe isExempt you sent (false when omitted). On the TaxCloud-connected path this is TaxCloud’s value.
appliedbooleantrue when a certificate covered the cart and it was quoted without tax.
certificateIdstring or nullThe certificate that applied.
reasonstring or nullThat certificate’s exemption reason.
notAppliedReasonstring or nullWhy no certificate applied, or null when one did.

notAppliedReason values:

ValueMeaning
no_matching_certificateNo certificate for this customer matched, or the candidates failed for different reasons.
disabledThe certificate is disabled.
expiredThe evaluation date is after the certificate’s expirationDate.
not_effectiveThe evaluation date is before the certificate’s effectiveDate.
state_not_coveredThe certificate does not list the destination state.
single_purchase_mismatchA single-purchase certificate whose orderNumber does not match the cartId or orderId.

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.

{
"exemption": {
"exemptionId": null,
"isExempt": true,
"applied": false,
"certificateId": null,
"reason": null,
"notAppliedReason": "no_matching_certificate"
}
}

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 state you 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_covered and single_purchase_mismatch are 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. exemption may contain only exemptionId (a string) and isExempt (a boolean). Anything else returns 400.

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:

You sendWhat Ziptax does
exemptionId of a Ziptax certificate that covers the cartForwards the cart to TaxCloud with "exemption": { "isExempt": true }.
exemptionId of a Ziptax certificate that does not cover the cartReturns 400 CertificateNotValid. Nothing is sent to TaxCloud.
exemptionId that is not a Ziptax certificateForwards the cart unchanged, so TaxCloud can apply a certificate it holds.
isExempt: true and a Ziptax certificate covers the cartForwards "exemption": { "isExempt": true }.
isExempt: true and no Ziptax certificate covers the cartForwards the cart unchanged. TaxCloud may apply one of its own certificates.

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.

{
"exemption": {
"exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
"isExempt": true,
"applied": true,
"certificateId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
"reason": "Resale",
"notAppliedReason": null
}
}

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

HTTPBodyWhen it happens
400{"status": "error", "code": "CertificateNotValid", "message": "..."}A named Ziptax certificate belongs to another customer or fails the sale’s checks. For self-managed carts, this also covers an ID the merchant does not hold.
400{"status": "error", "message": "..."}exemption is not a valid object (self-managed), or the request is otherwise invalid.
500{"status": "error", "message": "internal error"}An internal error prevented the exemption check. This includes an auto-match for a customer with more than 500 stored certificates.
503{"status": "error", "message": "exemption certificate storage is not available"}The certificate store could not be read. The request fails. Retry with backoff.

On carts, the message starts with the cart’s position, for example:

{
"status": "error",
"code": "CertificateNotValid",
"message": "items[0]: exemption certificate does not apply to this cart: state_not_covered"
}

A certificate that is not found, or belongs to another customer, gives exemption certificate not found for this customer.