Tax Calculations
Send a customer and a list of line items; get back the correct tax for every line, with the rate, the jurisdiction and the reasoning. One API call covers US sales tax, VAT, GST and other indirect taxes in 80 countries and territories.
Clearvo works out where the sale is taxed, classifies each product, applies the right rate and returns a line-by-line result. Your own business details (the supplier on a sale) are optional: they are filled in from your business profile.
What you get
- US sales tax down to the address — all 50 states plus local authorities (state, county, city and district), with partial taxability, marketplace-facilitator rules and exemption certificates.
- VAT, GST and other indirect taxes in 80 countries and territories: EU multi-band VAT, Canadian GST/HST/PST, and more. See the full list.
- Product classification — describe a product in plain language; no HS codes or slug mapping needed.
- Jurisdiction resolution from the shipping address, billing address, IP address or card country. See Jurisdiction resolution.
- B2B treatment — reverse charge and zero-rating applied from the buyer's and seller's tax numbers.
- Forgiving input — country names, ISO codes, currency names and US state names are all accepted. See Input formats.
- Recorded by default, preview on request — every calculation is stored in your audit trail unless you send
"commit": false. See Recording and previews. - Never blocks checkout — if a rate source is unavailable you get a result with
degraded: truerather than an error.
Where to go next
https://api.clearvo.io/v1) and the same csk_live_* / csk_test_* keys as every other Clearvo product. No separate credentials are needed.Authentication
Tax Calculations uses the same x-api-key header, key scoping, and X-Entity-Id rules as every other Clearvo product — see Authentication in the Account & Platform reference for the full header table and examples.
Use a csk_test_* key for sandbox requests — rate lookups and jurisdiction resolution run normally, but no external rate-authority calls are made and results are not billed. See the Sandbox section for details.
Quickstart
The simplest calculation: a $100 product sold to a consumer in San Francisco, California. Send the customer's address and the line item. Your own business details are filled in from your business profile, so you do not send a supplier.
Prices are sent before tax (amountIncludesTax: false), which is how US sales tax works. This request uses "commit": false so it is a preview that is not recorded; omit it to record the calculation.
curl https://api.clearvo.io/v1/tax/calculate \
-X POST \
-H "x-api-key: csk_test_..." \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"commit": false,
"customer": {
"billingAddress": {
"country": "US",
"region": "CA",
"city": "San Francisco",
"postalCode": "94105"
}
},
"lineItems": [
{
"id": "line-1",
"amount": 100.00,
"amountIncludesTax": false,
"productName": "Wireless headphones",
"taxCategory": "physical_goods_general"
}
]
}'
The response (abridged to the fields that matter here):
{
"calculationId": "cl_calc_ddde1aac846f4358a96e",
"sandbox": true,
"committed": false,
"jurisdiction": {
"country": "US",
"region": "CA",
"resolutionMethod": "SHIPPING_ADDRESS",
"resolutionPrecision": "REGION",
"addressPrecision": "ZIP",
"sourcingMethod": "DESTINATION"
},
"entityRole": "supplier",
"customer": { "country": "US", "region": "CA", "postalCode": "94105", "isEntity": false, "b2bOverride": false },
"taxTreatment": "STANDARD",
"totalTax": 8.63,
"lineItems": [
{
"id": "line-1",
"taxCategory": "physical_goods_general",
"rate": 0.08625,
"taxableAmount": 100,
"taxAmount": 8.63,
"totalAmount": 108.63,
"jurisdictionBreakdown": [
{ "level": "STATE", "name": "CALIFORNIA, STATE OF", "rate": 0.06, "taxAmount": 6 },
{ "level": "COUNTY", "name": "SAN FRANCISCO, CITY AND COUNTY OF", "rate": 0.0025, "taxAmount": 0.25 },
{ "level": "DISTRICT", "name": "SAN FRANCISCO, CITY AND COUNTY OF", "rate": 0.01375, "taxAmount": 1.38 },
{ "level": "LOCAL", "name": "SAN FRANCISCO, CITY AND COUNTY OF", "rate": 0.01, "taxAmount": 1 }
]
}
],
"summary": { "totalAmount": 100, "totalDiscount": 0, "totalTax": 8.63, "totalAmountWithTax": 108.63 },
"degraded": false
}
Reading the result
jurisdictionsays where the sale is taxed and why: here the shipping address, resolved to ZIP-code precision.lineItems[].rateis the combined rate (0.08625is 8.625%), andjurisdictionBreakdownsplits it into state, county, district and local components that add up to the rate and to the tax amount.totalTaxandsummarygive the amounts to charge: $8.63 of tax on $100.00, so $108.63 in total.degraded: falsemeans every rate was found. If a rate source is unavailable you getdegraded: truerather than an error.
Every field is described in the Response reference. Selling outside the US works the same way: send the customer's country, plus their tax number for a B2B sale. See Calculate.
This example uses a csk_test_* sandbox key, so it is safe to run before you touch production. Sandbox calculations never count toward usage or Compliance Radar totals. See Sandbox.
E-Invoicing Integration
Tax Calculations output is designed to feed directly into Clearvo e-invoice submissions. The rate and taxAmount on each calculated line item become the taxRate (as a percentage) and taxAmount on the matching lines[] entry of POST /v1/send — no mapping layer is needed, and the invoice line never carries a taxCode.
Example: calculate then invoice
{
// POST /v1/tax/calculate response (line items)
"lineItems": [{
"id": "line-1",
"taxCode": "S",
"rate": 0.19,
"taxableAmount": 100.00,
"taxAmount": 19.00,
"totalAmount": 119.00
}]
}
{
"invoiceNumber": "INV-2026-001",
"issueDate": "2026-06-21",
"currency": "EUR",
"country": "DE",
// supplier and customer fields …
"lines": [{
"description": "Annual SaaS subscription",
"quantity": 1,
"unitPrice": 100.00,
"taxRate": 19, // ← rate 0.19 from calculation response, as a percentage
"taxAmount": 19.00 // ← from calculation response
}]
}
EN16931 tax code reference
| Code | Name | When used |
|---|---|---|
S | Standard rate | Standard or reduced VAT/GST applied to the transaction |
AA | Lower rate | A lower rate than the standard rate applies (e.g. reduced band in EU) |
AE | VAT Reverse Charge | Non-EU seller to EU B2B buyer — buyer accounts for VAT |
K | VAT exempt (intra-community) | EU-to-EU cross-border B2B — intra-community supply |
G | Free export item, tax not charged | EU seller, non-EU buyer — export outside the EU VAT area |
E | Exempt from tax | Transaction is exempt under local rules (financial services, health, education) |
Z | Zero-rated goods | Goods or services taxable at 0% (e.g. children's clothing in UK) |
O | Services outside scope of tax | Transaction falls outside the indirect tax scope, or seller is not registered in the jurisdiction |
Sandbox
Use a csk_test_* API key to run calculations in sandbox mode. Sandbox calculations are identical to production in every respect except that they never count toward usage or Compliance Radar totals, and the sandbox field on the response is true.
What runs normally in sandbox
- Jurisdiction resolution (all signals, postal territory detection, 2-of-3 rule)
- Rate lookup (same rate tables as production)
- Product classification (catalogue lookup and account default)
- Tax treatment determination (all rules, including IOSS and reverse charge)
- DB write on a recorded calculation (
commit: true, or omitted since it now defaults to true) — written to the sandbox DB, not production - Idempotency key enforcement (scoped to the sandbox DB)
What is skipped in sandbox
- VIES customer VAT ID verification — the customer's VAT ID is accepted at face value; no live VIES call is made
- Usage counting and Compliance Radar threshold contribution — a sandbox calculation never counts toward either, whatever
committedis
curl https://api.clearvo.io/v1/tax/calculate \
-X POST \
-H "x-api-key: csk_test_..." \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"supplier": { "billingAddress": { "country": "IE" }, "taxId": "IE1234567T" },
"customer": { "billingAddress": { "country": "FR" } },
"lineItems": [{ "id": "l1", "amount": 99.00, "amountIncludesTax": false, "productName": "SaaS subscription" }]
}'
{
"calculationId": "cl_calc_test_...",
"sandbox": true,
"committed": true,
"degraded": false,
"jurisdiction": { "country": "FR", "resolutionMethod": "BILLING_ADDRESS" },
"taxTreatment": "STANDARD",
"taxCode": "S",
"lineItems": [{
"id": "l1",
"taxCode": "S",
"rate": 0.20,
"taxableAmount": 99.00,
"taxAmount": 19.80,
"totalAmount": 118.80
}],
"summary": { "totalAmount": 99.00, "totalDiscount": 0.00, "totalTax": 19.80, "totalAmountWithTax": 118.80 }
}
rate/taxCode output is identical to production — the only difference is that the sandbox flag is set and no charge is incurred.