Tax exemptions and resale certificates
Flint keeps each buyer's tax exemption certificates on the customer, applies the right one to every sale in automatic and external tax, and snapshots it on the order, the invoice, and the tax report row as evidence. Resellers, schools, nonprofits, government agencies, and other exempt buyers check out, pay invoices, and renew subscriptions without tax, and you can show an auditor which certificate covered each sale.
What a resale or exemption certificate is#
A resale certificate is a form a business gives its supplier to buy goods tax-free because it will resell them, and charge sales tax to its own customers. An exemption certificate does the same for buyers whose purchases are exempt for another reason, such as a nonprofit, a government agency, or a manufacturer buying production materials. The buyer usually needs its state's sales tax permit to use one, and fills in a form its state accepts.
The seller keeps the certificate on file and, for each exempt sale, needs evidence of which certificate applied. That is the part Flint handles. Flint records your declaration; it doesn't verify that a certificate is legally valid. Confirm which certificates you can accept with a qualified tax professional.
Ways to exempt a sale#
| Use | When |
|---|---|
| An exemption record on the customer | The buyer gave you a certificate with a reason, states, and dates. This is the usual choice. |
tax_exempt: true on the customer | The buyer is exempt everywhere, with no dates or state limits. This flag wins over records. |
| An order declaration | One sale is exempt, such as a one-off purchase with a single-use certificate. |
tax.taxable: false on a variant or line item | The product is exempt, whoever buys it. |
An exempt sale gets zero tax in automatic and external mode. The order's tax.status is exempt, every line item and charge has zero tax_money, and tax.exemption records what applied.
Record a certificate#
Create an exemption record under the customer with POST /v1/customers/{customer_id}/tax-exemptions, or under Tax exemptions on the customer's page in the Dashboard:
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", "OK"]},
"certificate_number": "RESALE-1234",
"evidence_reference": "merchant-records/resale-1234.pdf",
"start_date": "2026-01-01",
"end_date": "2027-12-31"
}'
The response is the record, with a ctex_ ID in customer_tax_exemption_id and its current status.
| Field | What to send |
|---|---|
reason | Required. One of the reasons. |
coverage | Required. {"type": "all_states", "country": "US"}, or {"type": "states", "country": "US", "states": [...]} with 1 to 60 distinct US state codes or DC. Codes are case-sensitive. |
start_date | Required. The first day the certificate applies, YYYY-MM-DD, inclusive. Up to 365 days ahead. |
end_date | The last day, inclusive. Leave it out, or send null, when the certificate doesn't expire. Must be on or after start_date and today. |
certificate_number | The number printed on the certificate, up to 255 characters. Buyers see it on receipts and invoices. |
evidence_reference | Where you keep the certificate, such as a file path or a document ID in your records system, up to 1,024 characters. Only you see it: it's never shown to buyers or printed on their documents. It doesn't upload a file. |
description | Up to 500 characters. Required when reason is other. |
metadata | Your own key-value data, such as the ID in your CRM. |
A customer can hold up to 100 unarchived records, including expired ones. Reading records requires customers.read, and writing them customers.write. Customer sessions, checkout sessions, and partner app tokens can't reach them. Live and sandbox records are separate. Customer tax exemptions documents every route and field.
Reasons#
reason | Buyer |
|---|---|
resale | Buys to resell |
federal_government | A federal government purchaser |
state_or_local_government | A state or local government purchaser |
tribal_government | A tribal government purchaser |
foreign_diplomat | A foreign diplomat |
charitable_organization | A charity or nonprofit |
religious_organization | A religious organization |
educational_organization | A school, college, or other educational organization |
agricultural_production | Buys for agricultural production |
industrial_production | Buys for manufacturing or industrial production |
direct_pay_permit | Holds a direct pay permit and pays the tax to the state itself |
direct_mail | Buys direct mail |
other | Any other reason, explained in description |
Dates and status#
A record's status follows today's date in your merchant timezone, or UTC when no timezone is set:
status | Meaning |
|---|---|
scheduled | Before start_date. It doesn't apply yet. |
active | Within its dates. It applies to sales its coverage contains. |
expired | After end_date. It no longer applies. |
archived | Archived with DELETE. It no longer applies, and stays readable as history. |
Expiry happens at read time, without a write. Expired and archived records can't be edited: a change returns 409 ACTION_NOT_ALLOWED with reason terminal_status. When a buyer renews a certificate, create a new record. The old one keeps the evidence for the sales it covered.
Change an active or scheduled record with PATCH, sending only the fields that change. Send the record's version as expected_version; it is required when you replace coverage. Archive a record with DELETE /v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}?expected_version=2. Editing or archiving a record never changes past sales.
How Flint applies an exemption#
Flint assesses the customer's exemption every time it calculates tax for an order, a checkout session, an invoice, or a subscription renewal.
- A customer with
tax_exempt: trueis exempt, everywhere. - Otherwise Flint takes the customer's
activerecords whose coverage contains every taxable destination on the order. - When several match, the record with the latest
start_dateapplies, and when start dates tie, the newest record. - If any taxable destination falls outside a record's coverage, that record doesn't apply, and the whole order is taxed when none does. One exemption covers the whole order, never part of it.
The destination is the state Flint taxes:
- Automatic tax compares the state of each destination it calculates: the delivery destination, the pickup store, or the order's tax location. A ZIP code alone is enough; Flint resolves its state.
- External tax compares the
stateof each component'sjurisdiction.
An all_states record needs no location. With automatic tax, Flint then skips the tax calculation entirely and charges no automatic tax fee. A record limited to some states can leave the order in requires_location until Flint knows where it's going.
With external tax, send your components as usual. Their rows record zero tax_money with taxability_reason: customer_exempt, and flat order taxes, such as a retail delivery fee, are left off.
Exemption records cover US states only, and coverage.country must be US. For business buyers in the EU, the UK, Australia, and New Zealand, save their VAT or GST number instead: automatic tax applies the reverse charge. An exemption and a reverse charge never apply to the same order. When an exemption applies, Flint sends no tax ID, and tax.reverse_charge is null.
Checkout, invoices, and subscriptions#
- Checkout sessions and payment links assess the exemption of the order's customer. A sale with no customer has no records to apply, so it's taxed.
- Invoices assess the exemption when they're issued and freeze it in
snapshot.tax_exemption. A later change to the customer's records or flag doesn't change an issued invoice. - Subscription renewals always use the customer's records and flag, assessed on each renewal's date. A renewal calculated after the certificate's
end_dateis taxed.
Declare an exemption on one order#
Set tax.exemption when you create or update an order. Its type is customer, the default, order, or none:
{
"tax": {
"enabled": true,
"exemption": {
"type": "order",
"reason": "resale",
"coverage": {"type": "states", "country": "US", "states": ["TX"]},
"certificate_number": "RESALE-1234",
"evidence_reference": "merchant-records/resale-1234.pdf"
}
}
}
orderdeclares an exemption for this order only, with the samereasonandcoveragevalues as a record.certificate_number,description, andevidence_referenceare optional, except thatreason: otherrequires adescription. An order declaration that doesn't cover the order's destination stays on the order and doesn't exempt it.nonetaxes the order, even for an exempt customer, such as a reseller buying for its own use.customergoes back to the customer's flag and records.
Subscription renewals always use customer. Once an order's tax commits, at the first collected payment, an issued invoice, or a confirmed return replacement, changing tax.exemption returns 409 ACTION_NOT_ALLOWED with reason payment_collected.
What the sale records#
tax.exemption on the order records the latest assessment, and freezes when the order's tax commits. Read tax_exempt to tell whether it applied:
{
"tax": {
"status": "exempt",
"exemption": {
"source": "customer",
"tax_exempt": true,
"customer_id": "cus_01J00000000000000000000000",
"customer_tax_exemption_id": "ctex_01KEZF7C009N0YTK0NMWP1XZPW",
"reason": "resale",
"coverage": {"type": "states", "country": "US", "states": ["TX", "OK"]},
"certificate_number": "RESALE-1234",
"start_date": "2026-01-01",
"end_date": "2027-12-31",
"evidence_reference": "merchant-records/resale-1234.pdf"
}
}
}
source is customer for the flag or a record, and order for an order declaration. customer_tax_exemption_id names the record that applied, and is absent for the flag and for declarations. Only merchant reads include evidence_reference.
Buyers see the exemption too. The receipt and the invoice PDF show a "Tax exempt" row with the reason and certificate number in place of the tax, and the hosted invoice labels the tax "Tax exempt". Buyer copies never include evidence_reference. See The exemption snapshot for every field.
When a certificate expires#
A record stops applying at the first calculation after its end_date, or once it's archived. Because an order can be calculated well before it's paid, Flint checks the exemption again before the order's first payment, and again before a pending payment attempt's first confirmation or authorization.
If the record expired, was archived, or changed by then, or the customer's tax_exempt flag is now false:
- An unpaid order. The payment is refused with
409 ACTION_NOT_ALLOWEDand reasonconfiguration_required, and Flint recalculates the tax without the exemption. Show the buyer the new total, then start payment again. - An issued invoice. It keeps its frozen amounts. To charge tax, void it, then create and issue a new invoice for the order.
- A paid sale. Nothing changes. The snapshot stays as evidence of the certificate that applied.
When an exemption expires covers return replacements and payment attempts in progress. To keep a reseller's renewals exempt, create the renewed certificate's record before the old end_date, with a start_date no later than the day after it.
Exempt products and tax categories#
Some products are exempt whoever buys them. Set them up on the product, not the customer:
- Nontaxable products. Set
taxable: falseon the variant. Its lines owe no tax in either mode. Ad-hoc line items and charges taketax.taxabledirectly. - Categories.
line_item_tax_categorytells automatic tax what the product is, such asphysical_goods,digital_goods,saas, orservices, so each state's rules for that category apply. See Tax categories. - Food, clothing, medical goods, and admission. States treat these differently, often with partial exemptions or thresholds the tax provider can't express. Automatic tax refuses the
food,clothing,medical_goods, andadmissioncategories; send those items' tax from your own engine as external tax. - Shipping. A shipment method's
tax_exempt_us_stateslists the states where its shipping charge is exempt.
With external tax, nontaxable lines still send components, so tax_summarized_v1 reports nontaxable sales by jurisdiction.
Wholesale and B2B sales#
A wholesale buyer usually needs three things: its own prices, invoice terms, and no sales tax on what it resells. Flint keeps all three on the customer:
- Prices. Assign a price list to the customer, or to its
segment. - Terms. Set the customer's
default_invoice_payment_term_idand bill it with invoices. - The certificate. Record its resale certificate with
reason: resaleand coverage for the states it gave you certificates for, one record per certificate.
The buyer's orders, invoices, and subscription renewals are then priced from its list and exempt in the states its certificates cover. A shipment to a state outside them is taxed, because no record covers it.
Exemptions in tax reports#
Every exempt sale is in the tax reports, with the exemption it recorded:
tax_transactions_itemized_v2, for automatic tax, writes anexempt_collectionrow for each exempt sale. Itstaxable_moneyandtax_moneyare zero,nontaxable_moneyis the gross less pre-tax discounts, andexemption.source,exemption.reason,exemption.certificate_number, andexemption.customer_tax_exemption_idsay which certificate applied. Flint reads them from the assessment frozen at collection, so changing or archiving a record later doesn't change an earlier report.tax_transactions_summarized_v2totals exempt sales by jurisdiction. Exempt sales with no recorded jurisdiction, such as anall_statesexemption with no location, are grouped asunresolved.tax_itemized_v1andtax_summarized_v1, for external tax, include exempt sales with zero tax.
See Rows in the v2 tax transactions report for how rows are built.
Errors#
Related docs#
- Customer tax exemptions: every route, field, and rule for exemption records.
- Sales tax: how exemptions fit automatic and external tax.
- VAT, GST, and international tax: reverse charge for business buyers outside the US.
- Wholesale pricing: price lists for customers and segments.
- Invoicing: bill business buyers on terms.
- Reports: request and download tax reports.