Skip to main content

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.

Required scope: customers:write

Grant 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, other
  • form_type (required): state_specific (a state's own form), sst (Streamlined Sales Tax multistate), mtc (MTC uniform), other
  • form_code (string, optional, max 60) — the form's own code, e.g. 01-339 or DR-13
  • issued_on (date Y-m-d, optional)
  • expires_on (date Y-m-d, optional, on or after issued_on)
  • expiry_rule (required): fixed_date (expires on expires_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 send states[] once per state, or one comma-separated states value.
  • external_url (URL, optional, max 2048) — a link to the certificate held elsewhere, instead of or as well as a file
  • notes (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 yourself
  • verification_payload (JSON string, optional) — the raw lookup result to keep alongside it
  • file (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​

Created

Response Headers
    Content-Type