Skip to content

VAT, GST, and international tax

Flint's automatic tax calculates VAT, GST, HST, and provincial tax on digital goods, software, and SaaS that a US business sells to buyers in Canada, the 27 EU member states, the UK, Australia, and New Zealand. It applies reverse charge when a business buyer gives you a valid VAT or GST number, prices VAT inside tax-inclusive prices, states EU and UK VAT in local currency on invoices, and records every sale in tax reports by country and tax type.

You turn it on once with a tax connection, add the registrations you hold, and every order, checkout session, payment link, invoice, and subscription renewal with tax on calculates from there. The rates come from a Quaderno account that Flint sets up for you. For sales automatic tax doesn't cover, your own tax engine can send its result as external tax, and Flint applies it, invoices it, refunds it, and reports it the same way.

Flint calculates and reports tax. It isn't a merchant of record: your business is the seller, and you decide where you must register, file the returns, and pay the tax you collect. Confirm your obligations with a qualified tax professional.

Coverage by country#

DestinationTaxCategories automatic tax calculatesRegistration you add
United StatesSales taxEvery supported category, including saas, software, and digital_goodsOne per state
CanadaGST/HST, plus PST in BC and SK, RST in MB, and QST in QCdigital_goods, software, saasCA for GST/HST, plus one per province
27 EU member statesVATdigital_goods, software, saasEU, your non-Union OSS number
United KingdomVATdigital_goods, software, saasGB
AustraliaGSTdigital_goods, software, saasAU
New ZealandGSTdigital_goods, software, saasNZ

GET /v1/tax-connection returns the same list in coverage, with category_scope: all for the US and digital everywhere else. Read it rather than hard-coding the table, and handle category_scope values you don't recognize.

Outside the US, automatic tax covers digital supplies only:

  • Physical goods are refused, because the tax provider can't apply the import thresholds for low-value goods.
  • services and professional_services are refused, because the tax provider treats them as supplied where you are, not where the buyer is.
  • Taxable charges, such as a service_fee, are refused. Set the charge's taxable: false, or use external tax.

Each of these returns 400 INVALID_REQUEST naming the line item's category (detail INVALID_VALUE) or the charge (detail NOT_ALLOWED). Every amount stays in USD, the currency of every Flint order.

Sales tax on SaaS and digital products#

In the US, automatic tax calculates saas and software lines as software as a service, and digital_goods lines as electronically supplied services, from your registrations and the buyer's address. A state where you aren't registered calculates zero tax. Outside the US, the same three categories are the ones automatic tax calculates. Set the category on each variant, or set tax.default_line_item_tax_category in settings. A variant of a product_type: digital product stores digital_goods when you leave its category out. See Tax categories for every category.

Add your registrations#

A destination calculates tax only while a registration for it is in effect on the sale's date. Without one, the sale calculates zero tax, as an unregistered US state does. Add each registration with POST /v1/tax-connection/registrations, which needs the settings.write scope, or under Where you're registered in Settings > Tax in the Dashboard:

cURL
curl -X POST https://api.withflintpay.com/v1/tax-connection/registrations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: register-eu-oss-2026" \
  -d '{"country": "EU", "registration_number": "EU372012345", "start_date": "2026-07-01"}'
  • EU. Send country: EU with your non-Union OSS number, EU followed by nine digits. One registration covers all 27 member states. The non-Union scheme is for businesses established outside the EU; any other number returns 400 INVALID_REQUEST on registration_number.
  • UK, Australia, and New Zealand. Send GB, AU, or NZ with your national VAT or GST registration number.
  • Canada. Send CA with no state for GST/HST, and a separate registration with state BC, MB, QC, or SK for that province's tax. Each tax needs its own registration in effect: a missing, future, or ended registration zeroes only its own tax.

Omit state for EU, GB, AU, and NZ. A start_date up to 365 days ahead schedules a registration, and an optional end_date sets its last day. Responses return only the number's last four characters. Tax registrations covers changing a number and the rest of the lifecycle, and Connect automatic tax covers the connection itself.

Automatic tax records the provider's non-taxable answer for EU territories outside the VAT area, including the Canary Islands, Åland, Guadeloupe, Martinique, Réunion, Guyane, Mayotte, Büsingen, and Livigno.

Put your VAT number on invoices#

Registrations decide what tax is calculated. They don't print anything. Before you issue an invoice with UK or EU VAT, set the seller details in tax_identity with PATCH /v1/settings: legal_name, registered_address, and tax_ids with your VAT number. Use a GB entry for UK VAT, and for EU VAT a member state's VAT entry or an EU entry with identifier_type: oss. Until they're set, issuing refuses with 409 ACTION_NOT_ALLOWED, reason configuration_required, and a next action to update /v1/settings. Drafts still save. The same identity prints on receipts.

Calculate VAT on an order#

Create the order with automatic tax, the buyer's address in tax.location, and the customer whose tax IDs Flint should check. This sells a $100.00 SaaS plan to a consumer in Berlin:

cURL
curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Idempotency-Key: vat-order-de-001" \
  -d '{
    "customer_id": "cus_01KEZF7C006X9JK6NZNA2SM9XD",
    "line_items": [{
      "type": "custom",
      "name": "Team plan, annual",
      "quantity": 1,
      "unit_price_money": {"amount": 10000, "currency": "USD"},
      "fulfillment": {"requirement": "none"},
      "tax": {"taxable": true, "line_item_tax_category": "saas"}
    }],
    "tax": {
      "enabled": true,
      "calculation": {"mode": "automatic", "price_mode": "additive"},
      "location": {
        "address_source": "provided",
        "address_type": "tax_address",
        "address": {
          "line1": "Friedrichstraße 68",
          "city": "Berlin",
          "postal_code": "10117",
          "country": "DE"
        }
      }
    }
  }'

Germany's standard rate is 19%, so the order owes $19.00 of VAT. Outside the US, automatic tax returns one row per national or provincial tax for each line item and charge in tax.tax_breakdowns:

Response
{
  "data": {
    "order_id": "ord_01KEZF7C0054GQKJ142A8X367A",
    "tax": {
      "enabled": true,
      "mode": "automatic",
      "status": "calculated",
      "reverse_charge": null,
      "tax_breakdowns": [{
        "tax_breakdown_id": "txb_01KEZF7C00SHMN8QWCA8PT1HSB",
        "order_id": "ord_01KEZF7C0054GQKJ142A8X367A",
        "order_line_item_id": "li_01KEZF7C008YPRCK7VDKTGWR31",
        "jurisdiction": {"code": "DE", "country": "DE", "level": "country", "name": "Germany"},
        "tax_type": "vat",
        "calculation_type": "percentage",
        "percent": 19,
        "price_mode": "additive",
        "taxability_reason": "standard_rated",
        "taxable_money": {"amount": 10000, "currency": "USD"},
        "tax_money": {"amount": 1900, "currency": "USD"}
      }]
    },
    "pricing_amounts": {
      "subtotal_money": {"amount": 10000, "currency": "USD"},
      "tax_money": {"amount": 1900, "currency": "USD"},
      "total_money": {"amount": 11900, "currency": "USD"}
    }
  }
}

EU member states and the UK record a vat row, and Australia and New Zealand a gst row, each with the country as its jurisdiction at level country. Canadian orders record gst, hst, pst, or qst rows. Read amounts from the response: Flint recalculates whenever something that affects tax changes.

tax.location takes line1, city, and country. state is required only for US and Canadian addresses, and postal_code everywhere except Ireland, where addresses often have no Eircode. Flint checks that a Canadian postal code matches its province. When the order ships or the buyer picks up, Flint uses that destination instead; see Tax location. tax.supported_countries on the order lists the countries automatic tax can calculate for its current lines, for your own address picker.

For EU and UK sales, Flint keeps the buyer's billing country as private location evidence on the order's tax record: the billing-address tax location's country, otherwise the customer's billing address country. It doesn't change the calculation, never blocks a sale, isn't returned by the API, and is erased when the customer is deleted.

Buyer tax IDs#

A business buyer's VAT or GST number lives on its customer, in tax_identity.tax_ids. Hosted checkout doesn't collect tax IDs, so save the number before the order is calculated, with the API or in the customer's Tax identity panel in the Dashboard. Replacing the list requires the customer's current version as expected_version:

cURL
curl -X PATCH https://api.withflintpay.com/v1/customers/cus_01KEZF7C006X9JK6NZNA2SM9XD \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 3,
    "tax_identity": {
      "legal_name": "Kraus Software GmbH",
      "tax_ids": [{"country": "DE", "identifier_type": "eu_vat", "value": "DE123456788"}]
    }
  }'

The list holds up to 20 IDs. Each entry keeps a document_tax_id: send it to keep the entry, leave the entry out to remove it, and omit the ID to add one. Issued invoices and credit notes print the buyer's tax IDs.

How Flint validates a VAT or GST number#

For a destination in the EU, the UK, Australia, or New Zealand, Flint sends the customer's tax ID to the tax provider only when it is a VAT or GST registration in that country's format. Spaces, dots, and hyphens are ignored, and letters are uppercased.

Countryidentifier_typeWhat Flint checks
EU member statesvat, eu_vat, or the country code plus _vat, such as de_vatThe country prefix, such as DE, followed by that country's VAT number format. Greece uses the EL prefix.
United Kingdomvat or gb_vatGB followed by 9 or 12 digits, or by GD or HA and three digits
Australiaabn, au_abn, gst, or au_gstAn 11-digit ABN with a valid check digit
New Zealandgst or nz_gstAn 8- or 9-digit GST number with a valid check digit

A tax ID that isn't one of these types, or doesn't match its format, is never sent, and the buyer pays tax as a consumer. That covers personal IDs, such as an Italian codice fiscale or a Portuguese NIF, and mistyped numbers.

Neither Flint nor the tax provider checks that the number is currently registered. Check it before you save it on the customer, with the EU's VIES service for EU VAT numbers, HMRC's VAT number checker for UK numbers, or ABN Lookup for Australian numbers, and keep the result with your records.

Which tax ID an order uses#

Each order uses one buyer tax ID. Flint picks the customer's entry for the country of the order's tax location, or of the first item's destination when the order has none. A Greek EL ID counts as GR. For an EU destination without one, it picks the first entry from an EU country, because an EU VAT number applies to every EU destination. A UK, Australian, or New Zealand number applies only to its own country, and items going to a country where the chosen ID doesn't apply are charged tax.

Guest orders, and customers without a usable ID, are charged tax as consumers.

Reverse charge for business buyers#

Under the reverse charge, a business buyer accounts for the VAT or GST itself, so the seller charges none. When the tax provider applies it for the customer's tax ID:

  • The tax is zero, and tax.status stays calculated.
  • Each row has taxability_reason: reverse_charge, percent: 0, and the full taxable amount.
  • tax.reverse_charge.customer_tax_id records the tax ID Flint sent. It's frozen once the order is paid; recalculating before payment reads the customer's current tax IDs again.
  • On a tax-inclusive order, the buyer pays the same price, and none of it is tax.
Response
{
  "tax": {
    "status": "calculated",
    "reverse_charge": {
      "customer_tax_id": {"country": "DE", "region": null, "identifier_type": "eu_vat", "value": "DE123456788"}
    }
  }
}

tax.reverse_charge is null when no reverse charge applies. Issued invoices freeze it as snapshot.tax_reverse_charge, and the invoice PDF and its credit notes print "Reverse charge" with the buyer's tax ID.

Canada has no automatic reverse charge: a Canadian business number on the customer doesn't change the tax. A customer with an exemption is never reverse charged, because the exemption applies first and Flint sends no tax ID; see Tax exemptions and resale certificates.

Tax-inclusive prices#

Consumer prices in the EU, the UK, and Australia usually include VAT or GST. Set the order's tax.calculation.price_mode to inclusive, and the buyer pays the price you entered while Flint works out the tax inside it. To make inclusive pricing the default for orders that turn tax on without their own calculation, including checkout and payment link orders, set tax.default_price_mode to inclusive in settings.

A $12.00 SaaS plan sold to a UK consumer at 20% includes $2.00 of VAT: 1200 × 20 ÷ 120 = 200 cents. Its tax_money is $2.00, pricing_amounts.inclusive_tax_money includes it, and the order's total stays $12.00. A business buyer under the reverse charge pays the same $12.00, with no tax in it.

Subscription orders, including renewals, are always additive. The price mode is part of an order's committed tax: after a payment, changing it returns 409 ACTION_NOT_ALLOWED with reason payment_collected. Tax-inclusive prices with automatic tax covers the rounding.

Invoices and receipts#

An invoice recalculates tax when it is issued and freezes the result: the VAT, GST, HST, and provincial tax rows in snapshot.tax_breakdowns, the reverse charge, and the seller and buyer tax identities. Later changes to the order or customer don't reach an issued invoice.

VAT in local currency#

EU and UK rules require an invoice to state its VAT in the currency of the country that charges it. When an issued invoice has VAT above zero for an EU member state or the UK, issue converts that VAT and its taxable amount and freezes them in snapshot.tax_currency_conversions:

CountryCurrencyRate
Euro-area member states, including Bulgaria and CroatiaEURECB euro reference rate, the latest on or before the issue date
Czechia, Denmark, Hungary, Poland, Romania, SwedenCZK, DKK, HUF, PLN, RON, SEKECB euro reference rate, through the euro
United KingdomGBPHMRC exchange rate for the month of issue

The invoice PDF, the hosted invoice, and the buyer's invoice page print the converted taxable amount, the converted VAT, and the rate with its source and date. Credit notes reuse the invoice's rate. A reverse charge records zero VAT, so it needs no conversion, and Australian and New Zealand GST isn't converted. If the rate for the issue date isn't published yet, issue fails with 503 SERVICE_UNAVAILABLE and nothing is issued; retry later with the same Idempotency-Key. VAT in local currency in the Invoicing guide covers the arithmetic.

What buyers see#

DocumentShows
Invoice PDFYour legal name, registered address, and tax IDs from settings.tax_identity; the buyer's legal identity and tax IDs, frozen at issue; a row per tax with its jurisdiction; tax included in prices as an informational "Includes tax" amount; "Reverse charge" with the buyer's tax ID; EU and UK VAT in local currency. The hosted invoice shows the same local-currency VAT.
Credit note PDFThe same identities, the reversed tax, the reverse charge, and VAT in the invoice's local-currency rate
Receipt email and PDFYour legal name and tax IDs; the tax with its rate, such as "VAT 20%", or "Includes VAT 20%" for an inclusive price; and, on a receipt sent to the customer's email on file, the reverse-charge statement with the buyer's VAT number

Orders, receipts, payments, and reports stay in USD.

Refunds and reports#

A refund reverses tax in proportion to what it refunds, from the payment that collected it. You don't send anything extra.

Use tax_transactions_itemized_v2 for each automatic-tax collection and refund reversal, and tax_transactions_summarized_v2 for collected, refunded, and payable tax by country, state or province, and tax type. Canadian GST and provincial taxes stay separate tax types. External-tax sales appear in tax_itemized_v1 and tax_summarized_v1, with their countries and their vat, gst, hst, pst, and qst types preserved. The tax CSV reports have no taxability-reason column, so a reverse-charged sale shows its taxable amount with zero tax. See Reports for every column.

What automatic tax doesn't support#

Automatic tax refuses an order it can't calculate correctly instead of guessing. Use external tax for:

  • Physical goods, services, or professional_services sold to a buyer outside the US.
  • Taxable charges on orders to a buyer outside the US.
  • Countries outside the coverage table, such as Switzerland, Norway, Japan, or Singapore.

Automatic tax also doesn't:

  • Check that a buyer's VAT or GST number is registered. Validate it yourself before saving it.
  • Collect tax IDs in hosted checkout. Save them on the customer.
  • Record card-issuing country or IP country as location evidence.
  • Charge in a currency other than USD. Only EU and UK invoices restate their VAT in local currency.
  • Apply reverse charge in Canada.
  • Register you, file returns, or pay the tax you collect.

External tax for everything else#

With external tax, your tax engine decides the rates and Flint applies them. External tax accepts any ISO 3166-1 alpha-2 country, country and province jurisdiction levels, and the vat, gst, hst, pst, and qst tax types. For a business buyer, send a percentage component with taxability_reason: reverse_charge and percent: 0:

JSON
{
  "jurisdiction": {"code": "GB", "country": "GB", "level": "country", "name": "United Kingdom"},
  "tax_type": "vat",
  "calculation_type": "percentage",
  "percent": 0,
  "taxability_reason": "reverse_charge"
}

Your engine decides whether reverse charge applies; a customer tax ID alone doesn't apply it in external mode. Flint records the customer's tax ID for that country in tax.reverse_charge, of any type or format. Issued invoices state EU and UK VAT in local currency for external tax too. If your engine runs on your own server, a tax calculation callback lets Flint ask it for every order, including checkout, payment link, and subscription renewal orders.

Was this helpful?