Merchant Compliance

Exemption Certificates

Store, retrieve, list, and delete customer exemption certificates for a connected merchant.

Exemption certificates record that a merchant’s customer is exempt from sales tax in one or more states. Store a certificate so future orders for that customer are treated correctly, then retrieve, list, or delete certificates as needed. All operations act on a single connected merchant identified by merchantId.

All endpoints use POST and the X-API-KEY header. See Merchant Transactions for the shared conventions, error shapes, and usage rules.

Create a certificate

1POST https://api.zip-tax.com/merchant/cert/create
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded.
customerIdstringYesYour identifier for the exempt customer. Carts and orders submitted with this customerId can use the certificate.
customerNamestringYesThe customer or organization name as it appears on the certificate.
customerBusinessTypestringYesThe type of business the customer is. One of the business type values below.
customerBusinessDescriptionstringNoFree-text description of the business. Provide when customerBusinessType is Other.
reasonstringYesThe reason for the exemption. One of the reason values below.
reasonDescriptionstring (max 20 chars)YesShort free-text elaboration of the exemption reason.
addressAddressYesThe customer’s address.
statesarray of objectsYesThe states the exemption applies to, each as { "abbreviation": "NV" } with a two-letter state abbreviation.

Business types

AccommodationAndFoodServices, AgriculturalForestryFishingHunting, Construction, FinanceAndInsurance, InformationPublishingAndCommunications, Manufacturing, Mining, RealEstate, RentalAndLeasing, RetailTrade, TransportationAndWarehousing, Utilities, WholesaleTrade, BusinessServices, ProfessionalServices, EducationAndHealthCareServices, NonprofitOrganization, Government, NotABusiness, Other

Exemption reasons

FederalGovernment, StateOrLocalGovernment, TribalGovernment, ForeignDiplomat, CharitableOrganization, ReligiousOrganization, EducationalOrganization, Resale, AgriculturalProduction, IndustrialProductionOrManufacturing, DirectPayPermit, DirectMail, Other

cURL
$curl -X POST "https://api.zip-tax.com/merchant/cert/create" \
>  -H "X-API-KEY: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>    "customerId": "cust-5567",
>    "customerName": "Acme Wholesale LLC",
>    "customerBusinessType": "WholesaleTrade",
>    "reason": "Resale",
>    "reasonDescription": "Purchased for resale",
>    "address": { "line1": "500 Industrial Way", "city": "Reno", "state": "NV", "zip": "89502" },
>    "states": [ { "abbreviation": "NV" }, { "abbreviation": "CA" } ]
>  }'

Returns the created certificate, including the certificateId you use to retrieve or delete it, and which you can reference as exemptionId on carts and orders.

Get a certificate

Retrieve a single certificate by its id.

1POST https://api.zip-tax.com/merchant/cert/get
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant.
certificateIdstringYesThe certificateId returned when the certificate was created.
cURL
$curl -X POST "https://api.zip-tax.com/merchant/cert/get" \
>  -H "X-API-KEY: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>    "certificateId": "cert_7a4b6c8e"
>  }'

Returns the certificate.

List certificates

List the certificates stored for a merchant, with cursor-based pagination.

1POST https://api.zip-tax.com/merchant/cert/list
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant.
limitinteger (0–100)NoMaximum number of certificates per page. Defaults to 20.
cursorstringNoOpaque pagination cursor from the nextCursor field of a previous response. Omit to start at the first page.
ascendingbooleanNoWhether to sort results in ascending order. Defaults to false.
sortBystringNoField to sort by: createdDate or id. Defaults to id.
customerIdstringNoFilter to certificates belonging to this customer.
disabledbooleanNoSet true to list disabled (deleted) certificates instead of active ones. Defaults to false.

Returns { "items": [...], "limit": 20, "nextCursor": "..." } where each item is a certificate and nextCursor is null on the last page.

cert/get and cert/list are separate endpoints: use cert/get to fetch one certificate by id, and cert/list to enumerate a merchant’s certificates.

Delete a certificate

Deletes (disables) a certificate so it can no longer be applied to new transactions. Returns 204 No Content on success.

1POST https://api.zip-tax.com/merchant/cert/delete
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant.
certificateIdstringYesThe certificateId returned when the certificate was created.
cURL
$curl -X POST "https://api.zip-tax.com/merchant/cert/delete" \
>  -H "X-API-KEY: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>    "certificateId": "cert_7a4b6c8e"
>  }'

Certificate response

cert/create, cert/get, and each cert/list item return the certificate record:

FieldTypeDescription
certificateIdstringIdentifier for the certificate. Use with cert/get, cert/delete, and as exemptionId on carts and orders.
connectionIdstringThe TaxCloud connection the certificate belongs to.
accountIdintegerThe TaxCloud account the certificate belongs to.
customerIdstringYour identifier for the exempt customer.
customerNamestringName of the customer the certificate was issued to.
customerBusinessTypestringThe type of business the customer is.
customerBusinessDescriptionstringFree-text description, present when the business type is Other.
reasonstringThe reason the customer is exempt.
reasonDescriptionstringFree-text elaboration of the exemption reason.
addressAddressAddress of the exempt customer.
states[]arrayThe states the certificate is valid in, each as { "abbreviation": "NV" }.
singlePurchasebooleanWhether the certificate covers a single purchase only, rather than being a blanket certificate.
createdDatestring (RFC3339 date-time)When the certificate was created.
disabledAtstring (RFC3339 date-time) or nullWhen the certificate was disabled, or null while it is active.
Orders

Record orders that honor a customer’s exemptions.

Merchant Transactions

Shared conventions, errors, and usage.