Skip to content

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#

UseWhen
An exemption record on the customerThe buyer gave you a certificate with a reason, states, and dates. This is the usual choice.
tax_exempt: true on the customerThe buyer is exempt everywhere, with no dates or state limits. This flag wins over records.
An order declarationOne sale is exempt, such as a one-off purchase with a single-use certificate.
tax.taxable: false on a variant or line itemThe 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
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.

FieldWhat to send
reasonRequired. One of the reasons.
coverageRequired. {"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_dateRequired. The first day the certificate applies, YYYY-MM-DD, inclusive. Up to 365 days ahead.
end_dateThe 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_numberThe number printed on the certificate, up to 255 characters. Buyers see it on receipts and invoices.
evidence_referenceWhere 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.
descriptionUp to 500 characters. Required when reason is other.
metadataYour 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#

reasonBuyer
resaleBuys to resell
federal_governmentA federal government purchaser
state_or_local_governmentA state or local government purchaser
tribal_governmentA tribal government purchaser
foreign_diplomatA foreign diplomat
charitable_organizationA charity or nonprofit
religious_organizationA religious organization
educational_organizationA school, college, or other educational organization
agricultural_productionBuys for agricultural production
industrial_productionBuys for manufacturing or industrial production
direct_pay_permitHolds a direct pay permit and pays the tax to the state itself
direct_mailBuys direct mail
otherAny 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:

statusMeaning
scheduledBefore start_date. It doesn't apply yet.
activeWithin its dates. It applies to sales its coverage contains.
expiredAfter end_date. It no longer applies.
archivedArchived 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.

  1. A customer with tax_exempt: true is exempt, everywhere.
  2. Otherwise Flint takes the customer's active records whose coverage contains every taxable destination on the order.
  3. When several match, the record with the latest start_date applies, and when start dates tie, the newest record.
  4. 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 state of each component's jurisdiction.

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_date is 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:

Response
{
  "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"
    }
  }
}
  • order declares an exemption for this order only, with the same reason and coverage values as a record. certificate_number, description, and evidence_reference are optional, except that reason: other requires a description. An order declaration that doesn't cover the order's destination stays on the order and doesn't exempt it.
  • none taxes the order, even for an exempt customer, such as a reseller buying for its own use.
  • customer goes 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:

JSON
{
  "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_ALLOWED and reason configuration_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: false on the variant. Its lines owe no tax in either mode. Ad-hoc line items and charges take tax.taxable directly.
  • Categories. line_item_tax_category tells automatic tax what the product is, such as physical_goods, digital_goods, saas, or services, 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, and admission categories; send those items' tax from your own engine as external tax.
  • Shipping. A shipment method's tax_exempt_us_states lists 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:

  1. Prices. Assign a price list to the customer, or to its segment.
  2. Terms. Set the customer's default_invoice_payment_term_id and bill it with invoices.
  3. The certificate. Record its resale certificate with reason: resale and 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 an exempt_collection row for each exempt sale. Its taxable_money and tax_money are zero, nontaxable_money is the gross less pre-tax discounts, and exemption.source, exemption.reason, exemption.certificate_number, and exemption.customer_tax_exemption_id say 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_v2 totals exempt sales by jurisdiction. Exempt sales with no recorded jurisdiction, such as an all_states exemption with no location, are grouped as unresolved.
  • tax_itemized_v1 and tax_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#

  • HTTP 400
    A record or order declaration is missing reason, coverage, or start_date, has a description missing for other, has coverage with a country other than US, has states with all_states, or has a date out of range. param names the field.
  • HTTP 409
    Reason customer_tax_exemptions: the customer already holds 100 unarchived records. Archive records you no longer need.
  • HTTP 409
    Reason terminal_status: the record is expired or archived. Create a new record. Reason payment_collected: tax.exemption changed after the order's tax committed. Reason configuration_required: a payment started after the exemption stopped applying; read the recalculated total and start payment again.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    expected_version is stale. Read the record again, reapply your change, and retry.

Was this helpful?