Create Customer Tax Exemption Certificate
POST/api/customers/:customer/tax-exemption-certificates
Record a tax exemption certificate a customer has provided. Send as multipart/form-data when attaching the certificate file (file: PDF, JPG, PNG, WEBP or HEIC, up to 10 MB); a JSON body works when there is no file.
customers:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
The certificate starts pending review. Set approve_now to approve it immediately — an approved certificate must carry evidence, so approve_now needs a file or an external_url.
Fields:
certificate_number(string, required, max 100)exemption_type(required):resale,nonprofit,government,manufacturing,agricultural,otherform_type(required):state_specific(a state's own form),sst(Streamlined Sales Tax multistate),mtc(MTC uniform),otherform_code(string, optional, max 60) — the form's own code, e.g.01-339orDR-13issued_on(dateY-m-d, optional)expires_on(dateY-m-d, optional, on or afterissued_on)expiry_rule(required):fixed_date(expires onexpires_on),annual(renews every year),never,lapse_after_inactivity(lapses after 12 months without a purchase)states— the US state codes the certificate covers (at least one; two-letter codes, e.g.TX,FL,DC). In multipart requests sendstates[]once per state, or one comma-separatedstatesvalue.external_url(URL, optional, max 2048) — a link to the certificate held elsewhere, instead of or as well as a filenotes(string, optional, max 5000)verification_status(optional):pending,verified,mismatch,unverifiable,manual_check_needed,no_certificate,not_applicable— the outcome of a state registry lookup you ran yourselfverification_payload(JSON string, optional) — the raw lookup result to keep alongside itfile(file, optional)approve_now(boolean, optional)
Combination rules (422 on violation): the MTC uniform certificate (form_type: mtc) can only be used for resale; Maryland, Hawaii and the District of Columbia (MD, HI, DC) accept no multistate (sst / mtc) certificate — ask for the state's own form.
Only approved, in-date certificates exempt a customer's sales; the customer's legacy exemption fields (tax_exemption_reference, tax_exemption_state, tax_exemption_expires_on) are kept in step with the certificates automatically.
Returns 201 with the certificate.
Authentication: Requires Bearer token with the customers:write scope. Permission: customers.update.
Request
Responses
- 201
- 401
- 403
- 404
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.