Skip to navigation

Exemption Certificate Changes

What changed when exemption certificates moved to the Ziptax certificate store, and what to update in an existing integration.
View as Markdown

Ziptax now stores new exemption certificates for both merchant types. If your integration already calls /merchant/cert/* or requests exemptions on carts and orders, review the changes below before switching over.

What’s new

  • Self-managed merchants can use certificates. The four certificate endpoints no longer return 403 for self-managed merchants, and their cart calculations accept an exemption object.
  • One store for both merchant types. New certificates are kept in Ziptax for TaxCloud-connected merchants too. Nothing is written to TaxCloud.
  • Connected carts and orders apply Ziptax certificates. When a Ziptax certificate covers a cart, Ziptax forwards it to TaxCloud as exempt. See Exempt a Sale.
  • New certificate fields. Use orderNumber with singlePurchase, set an effectiveDate or expirationDate, and add an identificationNumber for each state.
  • Certificate origin and status. source identifies where the certificate is stored. status reports whether it is active, disabled, or expired.
  • Rate lookups can report certificates. GET /request/v60 accepts merchantId and customerId and returns an exemptionDetail block.

Breaking changes

AreaBeforeNowWhat to do
Certificate idsTaxCloud certificate idsNew certificates get a lowercase UUIDStore certificateId as an opaque string up to 128 characters. Do not parse it.
Existing TaxCloud certificatesRead and deleted through these endpointsReadable with cert/get and cert/list ("source": "taxcloud"); cert/delete returns 409Manage them in TaxCloud, or create a Ziptax certificate and disable the TaxCloud one there.
List cursorsTaxCloud’s cursorA new opaque cursorA cursor saved from the old list returns 400 on cursor. Start again from the first page.
List page sizelimit 0–100, default 20limit 1–100, default 25Send limit explicitly if you depend on the page size.
List sortsortBy createdDate or id, default idCreation order only. sortBy accepts createdDate, createdAt, or created; id returns 400Remove sortBy: "id".
Delete response204 No Content200 with the disabled certificateAccept a 200 with a body. Retrying a delete is now safe.
Error bodiesTaxCloud’s error body, passed through{ "status", "message", "errors": [{ "field", "message" }] } for every 400, { "status", "message" } otherwiseUpdate error parsing. See Errors.
TaxCloud failuresTaxCloud’s status passed throughTaxCloud’s 429 is 503; other unexpected TaxCloud answers are 502 or 504Retry 503 with backoff.
Certificate objectIncluded connectionId and accountIdThose fields are gone. Adds merchantId, status, source, and the new fields aboveSee the certificate object.
ValidationChecked by TaxCloudChecked by Ziptax, every invalid field reported at onceSee the field limits in Create a certificate.

Certificates already in TaxCloud

Certificates created before this release stay in the merchant’s TaxCloud account. They are not copied into Ziptax.

  • For a connected merchant with TaxCloud credentials on file, cert/get and cert/list return them, after the merchant’s Ziptax certificates in a list. orderNumber, effectiveDate, expirationDate, and identification numbers are null on them.
  • They are read-only through Ziptax until certificate sync with TaxCloud is available. cert/delete returns 409.
  • A cart that names one by exemptionId is forwarded to TaxCloud unchanged, so TaxCloud applies it as before.
  • A self-managed merchant, or a connected merchant without TaxCloud credentials, has no TaxCloud certificates to read.

Checklist

  1. Treat certificateId as an opaque string. Expect both UUIDs and TaxCloud ids for connected merchants.
  2. Drop saved list cursors and any sortBy: "id".
  3. Handle 200 with a body from cert/delete, and 409 for TaxCloud certificates.
  4. Parse the new error body.
  5. For self-managed merchants, stop stripping exemption from carts. See Self-Managed Cart Calculation.