Skip to content

Customer tax exemptions

Customer tax exemptions are nested records under a customer. Each has its own ctex_ ID, reason, jurisdiction coverage, certificate reference, and inclusive date window. Use them to keep exemption evidence for resellers, schools, nonprofits, and other exempt buyers.

Flint applies an active record to orders, checkout sessions, invoices, and subscription renewals whose taxable destinations its coverage contains, and snapshots it on each exempt sale. The customer's blanket tax_exempt flag still wins and is unchanged. Archiving or editing a record doesn't change past sales. See Tax-exempt customers for which record applies and what happens when one expires.

Merchant API keys and Dashboard sessions can access these routes. Reads require customers.read; writes require customers.write. Customer sessions, checkout sessions, and partner app tokens cannot access them. Live and sandbox records are separate.

Routes#

All routes identify the owning customer. There is no top-level exemption collection or lookup.

MethodPathResult
POST/v1/customers/{customer_id}/tax-exemptionsCreates a record and returns 201.
GET/v1/customers/{customer_id}/tax-exemptionsLists records, excluding archives by default.
GET/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}Retrieves a record, including an archive.
PATCH/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}Changes the supplied fields.
DELETE/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}Archives the record and returns its archived snapshot.

An exemption belongs to one customer for its lifetime. Looking it up or changing it under another customer returns 404 RESOURCE_NOT_FOUND.

Create an exemption#

Send reason, coverage, and start_date. description is also required when reason is other. A customer can hold up to 100 unarchived records, including expired records. Creating another returns 409 LIMIT_REACHED with reason customer_tax_exemptions.

cURL
curl -X POST https://api.withflintpay.com/v1/customers/cus_01J00000000000000000000000/tax-exemptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: resale-certificate-1234" \
  -d '{
    "reason": "resale",
    "coverage": {"type": "states", "country": "US", "states": ["TX"]},
    "certificate_number": "RESALE-1234",
    "evidence_reference": "merchant-records/resale-1234.pdf",
    "start_date": "2026-01-01",
    "end_date": "2027-12-31",
    "metadata": {"source": "crm"}
  }'
FieldMeaning
customer_tax_exemption_id, customer_idThe record's identity and owning customer.
reasonOne of the closed reasons.
descriptionUp to 500 characters. Required for other; otherwise optional.
coverageAll US states or a list of states, as described in Coverage.
certificate_numberOptional certificate identifier, up to 255 characters.
evidence_referenceOptional reference to the document you keep, up to 1,024 characters. Merchant-only: never shown to buyers or printed on buyer documents. It does not upload a file.
start_dateRequired YYYY-MM-DD date, inclusive. May be up to 365 days ahead.
end_dateOptional YYYY-MM-DD date, inclusive. Must be on or after start_date and today. null means no end date.
statusscheduled, active, expired, or archived.
metadataYour key-value data, using the usual metadata limits and key patch rules.
versionPositive resource version. Send it as expected_version when changing the record.
created_at, updated_atUTC timestamps for creation and the most recent saved change.

Responses always include the optional scalar fields, with null when no value is recorded. metadata is {} when empty.

Reasons#

The closed reason vocabulary is:

federal_government, state_or_local_government, tribal_government, foreign_diplomat, charitable_organization, religious_organization, educational_organization, resale, agricultural_production, industrial_production, direct_pay_permit, direct_mail, and other.

For other, provide a description that explains the exemption. Flint records your declaration; recording it does not verify a certificate's legal validity.

Coverage#

Coverage is replaced as a whole. Every create or replacement supplies type and country; country must be US.

Response
{"type": "all_states", "country": "US"}

all_states forbids states, including states: null or an empty array.

JSON
{"type": "states", "country": "US", "states": ["CA", "TX"]}

states requires 1 to 60 distinct US postal state codes or DC. Codes are case-sensitive. Replacing coverage requires expected_version and every field of the new coverage object.

Dates and status#

Status uses today's date in the merchant's timezone, with UTC when no timezone is set. The start and end dates are inclusive. Before start_date, status is scheduled; within the date window it is active; after end_date it is expired. A record with no end date stays active after its start date.

Expiry changes at read time, without advancing version. expired and archived records cannot be edited: a change returns 409 ACTION_NOT_ALLOWED with reason terminal_status. Create a new record when an expired certificate is replaced.

DELETE archives a record. Its response is the same resource schema as GET, with status: archived. The archive stays retrievable by its nested ID route and appears in lists when the status filter includes archived. Customer erasure deletes the customer's exemption records.

Update and archive#

PATCH changes only supplied fields. Omission leaves a field unchanged. Send null to clear description, certificate_number, evidence_reference, or end_date; a record with reason other must keep a description. Empty strings are invalid.

Metadata merges by key. {"metadata":{"old":null,"source":"crm"}} removes old and sets source. metadata: null clears caller-owned keys. An empty metadata object makes no change.

Send expected_version in the PATCH body. It is required when replacing coverage and optional for scalar or metadata changes. For DELETE, send it as one query parameter: ?expected_version=7. A stale version returns 409 VERSION_CONFLICT, with the current version in details[0].current_version, before any effect. Read again, reconcile your change, and follow the key instruction in next_steps.

Writes accept an optional Idempotency-Key. Retry a lost response with the same request and key. If the retry returns IDEMPOTENCY_RECOVERY_REQUIRED, keep the key and inspect the customer's list and individual records. For a lost create response, match the submitted fields across list pages; do not create again under a new key if the outcome remains unclear. Contact support with the original key and request ID when you cannot identify the outcome.

List records#

The list excludes archived records by default and is ordered by created_at descending, then customer_tax_exemption_id descending. page_size defaults to 20 and accepts 1 to 100. Continue with next_page_token as page_token; page size may change during traversal.

Optionally filter by status: scheduled, active, expired, or archived. Use status=archived to list archive history, or combine statuses, such as status=active,archived. Repeated query keys and comma-separated values both work. The filter and customer must stay the same between pages. The 100-record limit applies only to unarchived records; archive history can span any number of pages.

List customer tax exemptions#

GET/v1/customers/{customer_id}/tax-exemptions

Requires scope customers.read or customers.write

Rate limit: read

Returns the customer's exemption records ordered by created_at descending, then customer_tax_exemption_id descending. Archived records are excluded by default. Status may filter scheduled, active, expired and archived records, alone or together. Default order: created_at descending, then customer_tax_exemption_id descending.

Path parameters

customer_idstringRequired

Flint ID of the customer that owns this nested child. Must be a valid ID with prefix cus_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.

statusarray of enum

Filter by status. Omitted, the list leaves out archived rows; name archived to include them. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • scheduled
  • active
  • expired
  • archived

Response · 200

The customer tax exemption resource.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD/tax-exemptions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The customer tax exemption resource.

JSON
{
  "data": [
    {
      "certificate_number": "RESALE-1234",
      "coverage": {
        "country": "US",
        "states": [
          "TX"
        ],
        "type": "states"
      },
      "created_at": "2026-11-05T12:00:00Z",
      "customer_id": "cus_01J00000000000000000000000",
      "customer_tax_exemption_id": "ctex_01J00000000000000000000000",
      "description": null,
      "end_date": null,
      "evidence_reference": "merchant-records/resale-1234.pdf",
      "metadata": {},
      "reason": "resale",
      "start_date": "2026-01-01",
      "status": "active",
      "updated_at": "2026-11-05T12:00:00Z",
      "version": 1
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "next_page_token": "",
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Create a customer tax exemption#

POST/v1/customers/{customer_id}/tax-exemptionsIdempotent

Requires scope customers.write

Rate limit: write

Records a nested customer exemption with reason, coverage and an inclusive date window. At most 100 unarchived exemptions may belong to a customer; exceeding that limit returns LIMIT_REACHED with reason customer_tax_exemptions. An active record applies to the customer's sales whose taxable destination its coverage contains, within its date range. Saving a record doesn't change the customer's blanket tax_exempt flag, which still takes precedence. Only API keys and dashboard sessions can access these records. Retry a lost response with the same request and Idempotency-Key. If IDEMPOTENCY_RECOVERY_REQUIRED is returned, inspect this customer's list and GET records before sending a new write. Match a lost create against submitted fields across list pages; contact support with the original key and request ID if its outcome is unclear.

Path parameters

customer_idstringRequired

Flint ID of the customer that owns this nested child. Must be a valid ID with prefix cus_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

certificate_numberstring or null

Merchant's exemption certificate number. Null when none is recorded.

coverageone ofRequired

Replaced as a whole: send every field you want to keep.

descriptionstring or null

Explanation of the exemption. Required for other. Null when none is recorded.

end_datestring or null

Last day of the exemption, inclusive, in YYYY-MM-DD format. Null when the exemption has no end date.

evidence_referencestring or null

Merchant-only reference to the supporting document. Never shown to buyers or printed on buyer documents. Null when none is recorded.

metadatamap of string

Caller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.

reasonenumRequired

Exemption reason. Other requires a description.

  • federal_government
  • state_or_local_government
  • tribal_government
  • foreign_diplomat
  • charitable_organization
  • religious_organization
  • educational_organization
  • resale
  • agricultural_production
  • industrial_production
  • direct_pay_permit
  • direct_mail
  • other
start_datestringRequired

First day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.

Response · 201

The customer tax exemption resource.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD/tax-exemptions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "coverage": {
      "country": "US",
      "states": [
        "TX"
      ],
      "type": "states"
    },
    "reason": "resale",
    "start_date": "2026-01-01"
  }'

Get a customer tax exemption#

GET/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}

Requires scope customers.read or customers.write

Rate limit: read

Returns one exemption belonging to this customer, including an archived record. A record belonging to another customer returns RESOURCE_NOT_FOUND. Evidence references are merchant-only; customer and checkout sessions cannot access this route.

Path parameters

customer_idstringRequired

Flint ID of the customer that owns this nested child. Must be a valid ID with prefix cus_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

customer_tax_exemption_idstringRequired

Flint customer tax exemption ID, prefixed ctex_. Must be a valid ID with prefix ctex_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The customer tax exemption resource.

Same response as Create a customer tax exemption.

curl https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD/tax-exemptions/ctex_01KEZF7C009N0YTK0NMWP1XZPW \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The customer tax exemption resource.

JSON
{
  "data": {
    "certificate_number": "RESALE-1234",
    "coverage": {
      "country": "US",
      "states": [
        "TX"
      ],
      "type": "states"
    },
    "created_at": "2026-11-05T12:00:00Z",
    "customer_id": "cus_01J00000000000000000000000",
    "customer_tax_exemption_id": "ctex_01J00000000000000000000000",
    "description": null,
    "end_date": null,
    "evidence_reference": "merchant-records/resale-1234.pdf",
    "metadata": {},
    "reason": "resale",
    "start_date": "2026-01-01",
    "status": "active",
    "updated_at": "2026-11-05T12:00:00Z",
    "version": 1
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Update a customer tax exemption#

PATCH/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}Idempotent

Requires scope customers.write

Rate limit: write

Updates only fields supplied. Coverage is replaced as a whole and requires expected_version. Null clears optional description, certificate_number, evidence_reference and end_date. Metadata merges by key; null values remove individual keys and a null map clears caller-owned metadata. Expired and archived records reject edits with ACTION_NOT_ALLOWED and reason terminal_status. A stale expected_version returns VERSION_CONFLICT before effects. Retry a lost response with the same request and Idempotency-Key. If IDEMPOTENCY_RECOVERY_REQUIRED is returned, inspect this customer's list and GET records before sending a new write. Match a lost create against submitted fields across list pages; contact support with the original key and request ID if its outcome is unclear.

Path parameters

customer_idstringRequired

Flint ID of the customer that owns this nested child. Must be a valid ID with prefix cus_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

customer_tax_exemption_idstringRequired

Flint customer tax exemption ID, prefixed ctex_. Must be a valid ID with prefix ctex_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

Send at least one of these

certificate_numberstring or null

Merchant's exemption certificate number. Null when none is recorded. Send null to clear it.

coverageone of

Replaced as a whole: send every field you want to keep. Requires expected_version when present.

descriptionstring or null

Explanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.

end_datestring or null

Last day of the exemption, inclusive, in YYYY-MM-DD format. Null when the exemption has no end date. Send null to clear it.

evidence_referencestring or null

Merchant-only reference to the supporting document. Never shown to buyers or printed on buyer documents. Null when none is recorded. Send null to clear it.

expected_versioninteger

Resource version last read by the caller. Required when replacing coverage; optional for other changes.

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all caller-owned metadata. An empty object makes no change. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.

reasonenumRequired

Exemption reason. Other requires a description.

  • federal_government
  • state_or_local_government
  • tribal_government
  • foreign_diplomat
  • charitable_organization
  • religious_organization
  • educational_organization
  • resale
  • agricultural_production
  • industrial_production
  • direct_pay_permit
  • direct_mail
  • other
start_datestring

First day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.

Response · 200

The customer tax exemption resource.

Same response as Create a customer tax exemption.

curl -X PATCH https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD/tax-exemptions/ctex_01KEZF7C009N0YTK0NMWP1XZPW \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "certificate_number": null,
    "expected_version": 1
  }'

Archive a customer tax exemption#

DELETE/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}Idempotent

Requires scope customers.write

Rate limit: write

Archives the record and returns its archived snapshot in the same schema as GET. It stays readable by ID and is excluded from lists unless status includes archived. Expired and archived records cannot be edited. An optional expected_version query parameter rejects a stale write before effects. Retry a lost response with the same request and Idempotency-Key. If IDEMPOTENCY_RECOVERY_REQUIRED is returned, inspect this customer's list and GET records before sending a new write. Match a lost create against submitted fields across list pages; contact support with the original key and request ID if its outcome is unclear.

Path parameters

customer_idstringRequired

Flint ID of the customer that owns this nested child. Must be a valid ID with prefix cus_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

customer_tax_exemption_idstringRequired

Flint customer tax exemption ID, prefixed ctex_. Must be a valid ID with prefix ctex_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Query parameters

expected_versioninteger

Resource version last read by the caller. Omit to archive the current record.

Response · 200

The customer tax exemption resource.

Same response as Create a customer tax exemption.

curl -X DELETE https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD/tax-exemptions/ctex_01KEZF7C009N0YTK0NMWP1XZPW \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?