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.
| Method | Path | Result |
|---|---|---|
POST | /v1/customers/{customer_id}/tax-exemptions | Creates a record and returns 201. |
GET | /v1/customers/{customer_id}/tax-exemptions | Lists 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 -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"}
}'
| Field | Meaning |
|---|---|
customer_tax_exemption_id, customer_id | The record's identity and owning customer. |
reason | One of the closed reasons. |
description | Up to 500 characters. Required for other; otherwise optional. |
coverage | All US states or a list of states, as described in Coverage. |
certificate_number | Optional certificate identifier, up to 255 characters. |
evidence_reference | Optional 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_date | Required YYYY-MM-DD date, inclusive. May be up to 365 days ahead. |
end_date | Optional YYYY-MM-DD date, inclusive. Must be on or after start_date and today. null means no end date. |
status | scheduled, active, expired, or archived. |
metadata | Your key-value data, using the usual metadata limits and key patch rules. |
version | Positive resource version. Send it as expected_version when changing the record. |
created_at, updated_at | UTC 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.
{"type": "all_states", "country": "US"}
all_states forbids states, including states: null or an empty array.
{"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#
/v1/customers/{customer_id}/tax-exemptionsRequires 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_idstringRequiredFlint 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_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, 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 enumFilter 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.
scheduledactiveexpiredarchived
Response · 200
The customer tax exemption resource.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
certificate_numberstring or nullRequiredMerchant's exemption certificate number. Null when none is recorded.
coverageone ofRequiredReplaced as a whole: send every field you want to keep.
created_atstringRequiredWhen the exemption was recorded.
customer_idstringRequiredThe customer that owns this nested child for its lifetime.
customer_tax_exemption_idstringRequiredFlint customer tax exemption ID, prefixed ctex_.
descriptionstring or nullRequiredExplanation of the exemption. Required for other. Null when none is recorded.
end_datestring or nullRequiredLast day of the exemption, inclusive, in YYYY-MM-DD format. Null when the exemption has no end date.
evidence_referencestring or nullRequiredMerchant-only reference to the supporting document. Never shown to buyers or printed on buyer documents. Null when none is recorded.
metadatamap of stringRequiredCaller-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.
reasonenumRequiredExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringRequiredFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
statusenumRequiredDerived from dates in the merchant timezone, using UTC when unset. DELETE archives the record.
scheduledactiveexpiredarchived
updated_atstringRequiredWhen the exemption last changed.
versionintegerRequiredCurrent resource version. Date-derived status changes do not advance it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier 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.
{
"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#
/v1/customers/{customer_id}/tax-exemptionsIdempotentRequires 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_idstringRequiredFlint 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 nullMerchant's exemption certificate number. Null when none is recorded.
coverageone ofRequiredReplaced as a whole: send every field you want to keep.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded.
end_datestring or nullLast day of the exemption, inclusive, in YYYY-MM-DD format. Null when the exemption has no end date.
evidence_referencestring or nullMerchant-only reference to the supporting document. Never shown to buyers or printed on buyer documents. Null when none is recorded.
metadatamap of stringCaller-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.
reasonenumRequiredExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringRequiredFirst 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
certificate_numberstring or nullRequiredMerchant's exemption certificate number. Null when none is recorded.
coverageone ofRequiredReplaced as a whole: send every field you want to keep.
created_atstringRequiredWhen the exemption was recorded.
customer_idstringRequiredThe customer that owns this nested child for its lifetime.
customer_tax_exemption_idstringRequiredFlint customer tax exemption ID, prefixed ctex_.
descriptionstring or nullRequiredExplanation of the exemption. Required for other. Null when none is recorded.
end_datestring or nullRequiredLast day of the exemption, inclusive, in YYYY-MM-DD format. Null when the exemption has no end date.
evidence_referencestring or nullRequiredMerchant-only reference to the supporting document. Never shown to buyers or printed on buyer documents. Null when none is recorded.
metadatamap of stringRequiredCaller-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.
reasonenumRequiredExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringRequiredFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
statusenumRequiredDerived from dates in the merchant timezone, using UTC when unset. DELETE archives the record.
scheduledactiveexpiredarchived
updated_atstringRequiredWhen the exemption last changed.
versionintegerRequiredCurrent resource version. Date-derived status changes do not advance it.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/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_idstringRequiredFlint 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_idstringRequiredFlint 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.
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.
{
"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#
/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}IdempotentRequires 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_idstringRequiredFlint 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_idstringRequiredFlint 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 nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumRequiredExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullRequiredExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofRequiredReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullRequiredMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullRequiredMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringRequiredFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullRequiredLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
certificate_numberstring or nullMerchant's exemption certificate number. Null when none is recorded. Send null to clear it.
coverageone ofReplaced as a whole: send every field you want to keep. Requires expected_version when present.
Send exactly one of these
Replaced as a whole: send every field you want to keep. Covers all US states or an explicit list of US states and DC.
countryenumRequiredCountry covered by this exemption. Only US is accepted. Uses ISO 3166-1 alpha-2 country codes.
US
typeenumRequiredChoose all_states or states explicitly.
all_states
descriptionstring or nullExplanation of the exemption. Required for other. Null when none is recorded. Send null to clear it.
end_datestring or nullLast 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 nullMerchant-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_versionintegerResource version last read by the caller. Required when replacing coverage; optional for other changes.
metadatamap of string or nullRequiredCaller-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.
reasonenumExemption reason. Other requires a description.
federal_governmentstate_or_local_governmenttribal_governmentforeign_diplomatcharitable_organizationreligious_organizationeducational_organizationresaleagricultural_productionindustrial_productiondirect_pay_permitdirect_mailother
start_datestringFirst day of the exemption, inclusive, in YYYY-MM-DD format. May be up to 365 days in the future.
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#
/v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}IdempotentRequires 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_idstringRequiredFlint 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_idstringRequiredFlint 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_versionintegerResource version last read by the caller. Omit to archive the current record.
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?