New France e-invoicing mandate goes live September 2026 — our implementation is ready. See all mandates →
Tax Calculations

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: true rather than an error.

Where to go next

ℹ
Tax Calculations use the same base URL (https://api.clearvo.io/v1) and the same csk_live_* / csk_test_* keys as every other Clearvo product. No separate credentials are needed.
Tax Calculations

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.

Tax Calculations

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
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):

JSON Response
{
  "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

  • jurisdiction says where the sale is taxed and why: here the shipping address, resolved to ZIP-code precision.
  • lineItems[].rate is the combined rate (0.08625 is 8.625%), and jurisdictionBreakdown splits it into state, county, district and local components that add up to the rate and to the tax amount.
  • totalTax and summary give the amounts to charge: $8.63 of tax on $100.00, so $108.63 in total.
  • degraded: false means every rate was found. If a rate source is unavailable you get degraded: true rather 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.

Tax Calculations

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

Step 1 — calculate
{
  // 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
  }]
}
Step 2 — invoice (POST /v1/send)
{
  "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

CodeNameWhen used
SStandard rateStandard or reduced VAT/GST applied to the transaction
AALower rateA lower rate than the standard rate applies (e.g. reduced band in EU)
AEVAT Reverse ChargeNon-EU seller to EU B2B buyer — buyer accounts for VAT
KVAT exempt (intra-community)EU-to-EU cross-border B2B — intra-community supply
GFree export item, tax not chargedEU seller, non-EU buyer — export outside the EU VAT area
EExempt from taxTransaction is exempt under local rules (financial services, health, education)
ZZero-rated goodsGoods or services taxable at 0% (e.g. children's clothing in UK)
OServices outside scope of taxTransaction falls outside the indirect tax scope, or seller is not registered in the jurisdiction
Tax Calculations

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 committed is
curl — sandbox
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" }]
  }'
JSON Response — sandbox
{
  "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 }
}
✓
The sandbox is the right place to validate your full calculate→invoice workflow end-to-end. Rates are real, jurisdiction resolution is real, and the rate/taxCode output is identical to production — the only difference is that the sandbox flag is set and no charge is incurred.