Tax Calculations

The Tax Calculation API determines the correct tax amount for any transaction — VAT, GST, sales tax, and other indirect taxes — across 76 countries in a single API call. You send a customer and a list of line items — your own supplier side is optional and auto-filled from your entity's master data; Clearvo resolves the applicable jurisdiction, classifies each product, applies the correct rate band, and returns a fully broken-down tax result. (seller is a deprecated alias for supplier — see Quickstart.)

Key capabilities

• 76 countries — EU multi-band VAT (standard, middle, reduced, super-reduced, special), US sales tax (all 50 states, 13k+ jurisdictions), Canadian GST/HST/PST, and more (see Supported Jurisdictions)
• AI-powered product classification — describe a product in plain language; no HS codes or custom slug mapping required
• Jurisdiction resolution — determines where tax is owed based on shipping address, billing address, IP geolocation, or card BIN country (2-of-3 rule for B2C digital goods)
• B2B reverse charge and EU IOSS — applies the correct treatment automatically based on seller and buyer tax IDs
• EN16931 tax codes — output maps directly to Clearvo e-invoicing fields with no additional transformation
• Flexible input — send country names, ISO alpha-3 codes, currency names, US state names, or informal customer type labels; all normalised server-side before validation
• Graceful degradation — never errors on rate-service failures; returns a result with degraded: true and a zero rate
• Recorded by default, preview on request — every calculation is persisted to your audit trail unless you send "commit": false for a quote/preview that shouldn't count toward usage or thresholds (see Calculate)

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 possible calculation: a B2C digital product sold to a customer in Germany. Clearvo classifies the product, resolves the jurisdiction, and returns the German VAT rate (19%) with an EN16931 tax code ready for e-invoicing. This example pins amountIncludesTax: false for clarity — non-US accounts default to tax-inclusive pricing (defaultPriceIncludesTax, see Account Settings) unless overridden per line or per account, as shown here.

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": "DE" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 100.00,
        "amountIncludesTax": false,
        "productName": "Annual SaaS subscription"
      }
    ]
  }'

{
  "calculationId": "cl_calc_01j4...",
  "entityId": "ent_01hx...",
  "apiVersion": "2026-01-01",
  "resolvedAt": "2026-07-08T10:00:00.000Z",
  "sandbox": true,
  "committed": true,
  "jurisdiction": {
    "country": "DE",
    "resolutionMethod": "BILLING_ADDRESS",
    "resolutionPrecision": "COUNTRY",
    "conflicts": []
  },
  "entityRole": "supplier",
  "supplier": {
    "country": "IE",
    "taxId": "IE1234567T",
    "isEntity": true
  },
  "customer": {
    "country": "DE",
    "isEntity": false,
    "b2bOverride": false,
    "taxIdValidated": false
  },
  "sellerRegistration": {
    "status": "REGISTERED",
    "canCollectTax": true,
    "pricingModel": "TAX_EXCLUSIVE"
  },
  "taxTreatment": "STANDARD",
  "taxCode": "S",
  "transactionType": "invoice",
  "lineItems": [
    {
      "id": "line-1",
      "taxCategory": "digital_services",
      "taxCode": "S",
      "rate": 0.19,
      "taxableAmount": 100.00,
      "taxAmount": 19.00,
      "totalAmount": 119.00,
      "classificationStatus": "APPROVED",
      "classificationConfidence": 0.97
    }
  ],
  "totalTax": 19.00,
  "summary": {
    "totalAmount": 100.00,
    "totalDiscount": 0.00,
    "totalTax": 19.00,
    "totalAmountWithTax": 119.00
  }
}

The rate: 0.19 on each line item flows directly into a Clearvo e-invoice submission as taxRate: 19 — no category mapping required (the invoice line never carries a taxCode). See E-Invoicing Integration.

This example uses a csk_test_* sandbox key, so it's safe to copy-paste and run before you're ready to touch production — sandbox calculations never count toward usage or Compliance Radar totals. Note that commit was not sent in this request either way: an omitted commit defaults to true, so it was still recorded ("committed": true) to your sandbox audit trail exactly as it would be in production. Run the identical request with a csk_live_* key and it is recorded for real — see the Calculate section below for what a recorded calculation does and how to opt out with "commit": false.

Changelog

Behavioural and breaking changes across Clearvo's API. Entries 1 and 2 are corrections to POST /v1/tax/calculate's place-of-supply logic and tax-code selection, not new opt-in features — they change the output for the specific transaction shapes described. Entry 3 changes POST /v1/tax/calculate's default recording behaviour for any call that omits commit. Entry 4 is E-Invoicing's buyer → customer vocabulary rename and is still in draft — see its own status marker.

Input Formats

Clearvo normalises incoming field values server-side before validation runs. You can send data in the format your billing system or platform already produces — no pre-processing or mapping layer needed on your end.

Countries

The country field on any address accepts ISO 3166-1 alpha-2, alpha-3, or an English country name. All forms are resolved to alpha-2 internally.

Currencies

The currency and reportingCurrency fields accept ISO 4217 codes or English currency names.

Regions (US states and Canadian provinces)

The region field on US and Canadian addresses accepts full state or province names as well as the standard 2-letter codes.

B2B override

By default, Clearvo infers B2B treatment from a valid customer.taxId — no additional flag is needed for standard B2B checkouts. For cases where you know the buyer is a business but don't have their VAT number at checkout time, set customer.b2bOverride: true.

Platform integration examples

These patterns work without any field transformation on your side.

// Google Play Orders API returns buyerCountry (alpha-2) + buyerState (full name)
{
  "currency": "USD",
  "customer": {
    "billingAddress": {
      "country": "US",
      "region": "California"
    }
  },
  "lineItems": [{ "id": "1", "amount": 9.99, "productName": "App subscription" }]
}
// no taxId/b2bOverride → B2C treatment (the default); "California" → "CA" resolved before validation

// Apple StoreKit 2 returns storefront as ISO 3166-1 alpha-3
{
  "currency": "USD",
  "customer": {
    "billingAddress": { "country": "GBR" }
  },
  "lineItems": [{ "id": "1", "amount": 4.99, "productName": "In-app purchase" }]
}
// "GBR" → "GB" — UK VAT (20%) applied

Calculate

Calculates tax for a single transaction. As of 2026-09-12, the result is recorded by default — persisted, counted toward your usage, and folded into Compliance Radar's threshold totals — unless you send "commit": false to calculate an ephemeral preview instead. See the alert above for the full list of what recording controls.

Endpoint

POST https://api.clearvo.io/v1/tax/calculate

Request body

Two request shapes below: a recorded calculation (the default — commit simply isn't sent) and a preview one (commit: false, for quoting). Both use the real request shape: supplier is optional (auto-filled from your entity's own registered address and VAT number when omitted), nested as supplier.billingAddress.country (seller/seller.address.country is a deprecated alias, see the field table below); the customer's address is customer.billingAddress / customer.shippingAddress (customer has no plain address field on this endpoint); ipAddress/binCountry live under a separate top-level evidence object, not on customer.

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "idempotencyKey": "order-abc-123",
    "supplier": {
      "billingAddress": { "country": "IE" },
      "taxId": "IE1234567T"
    },
    "customer": {
      "taxId": "DE987654321",
      "billingAddress": {
        "country": "DE",
        "postalCode": "10115"
      }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 500.00,
        "quantity": 5,
        "productName": "Enterprise software licence",
        "taxCategory": "digital-services"
      },
      {
        "id": "line-2",
        "amount": 120.00,
        "quantity": 2,
        "productName": "Printed user manual"
      }
    ],
    "vatUnverifiableFallback": "conservative"
  }'

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "commit": false,
    "customer": {
      "billingAddress": { "country": "DE" }
    },
    "lineItems": [
      { "id": "cart-line-1", "amount": 500.00, "productName": "Enterprise software licence" }
    ]
  }'

The preview response has the identical shape (same jurisdiction, taxTreatment, lineItems fields) but "committed": false — nothing is persisted, and it makes no contribution to your Compliance Radar totals. idempotencyKey has no effect on a preview call — it is only ever consulted when the resolved commit is true.

Full field-by-field shape, for reference (every field on the single-item schema — not every field would appear together on a real call):

{
  "currency": "EUR",
  "reportingCurrency": "USD",
  "date": "2026-09-01",
  "commit": true,
  "idempotencyKey": "order-abc-123",
  "vatUnverifiableFallback": "conservative",
  "vatValidation": "full",
  "merchantRef": "order-abc-123",
  "paymentMethod": "card",
  "isMarketplaceFacilitatedSale": false,
  "transactionType": "invoice",
  "transactionDirection": "sale",
  "supplier": {
    "name": "Acme Ireland Ltd",
    "taxId": "IE1234567T",
    "billingAddress": { "country": "IE" }
  },
  "customer": {
    "name": "Beispiel GmbH",
    "taxId": "DE987654321",
    "b2bOverride": false,
    "exemptionRef": "cert_01j4...",
    "ref": "crm-cust-9001",
    "billingAddress": { "country": "DE", "postalCode": "10115" },
    "shippingAddress": { "country": "DE", "postalCode": "10117" }
  },
  "shipFrom": { "country": "IE" },
  "shipTo": { "country": "DE", "postalCode": "10117" },
  "incoterms": "DDP",
  "importerOfRecord": "SELLER",
  "evidence": {
    "ipAddress": "203.0.113.42",
    "binCountry": "DE"
  },
  "lineItems": [
    {
      "id": "line-1",
      "productName": "Enterprise software licence",
      "productDescription": "Annual subscription, 5 seats",
      "productCode": "SKU-1001",
      "taxCategory": "digital-services",
      "classificationCodes": [{ "system": "stripe", "code": "txcd_10103000" }],
      "amount": 500.00,
      "quantity": 5,
      "amountIncludesTax": false,
      "discount": 50.00,
      "discountAmount": 50.00,
      "exempt": false,
      "taxTreatmentOverride": "STANDARD"
    },
    {
      "id": "line-2",
      "productName": "Standard shipping",
      "taxCategory": "shipping_handling",
      "amount": 12.00,
      "shippingCarrier": "common",
      "chargeAvoidable": false,
      "actualCostOfShipment": true
    },
    {
      "id": "line-3",
      "productName": "Children's cotton t-shirt",
      "amount": 45.00,
      "commodityCode": "6109100010"
    }
  ]
}

Request fields

Transaction

Parties — seller, customer

Addresses — shipFrom, shipTo, incoterms

Evidence

Line items

Purchase Mode

Every example so far has been a sale — the entity is the supplier. Set "transactionDirection": "purchase" to calculate the input tax on something your entity bought instead — an AP/procurement invoice. Party roles invert: supplier becomes the required counterparty field — the actual vendor on the purchase invoice (same shape as customer) — and your entity moves to customer, which is now optional: omit it to auto-fill from your entity's own master data, or supply it and its taxId must be one of the entity's own registered tax IDs, any country (422 CUSTOMER_TAX_ID_MISMATCH on a mismatch — see Registrations). A supplier.ref that does not resolve to a saved supplier of this entity is rejected with 422 SUPPLIER_REF_NOT_FOUND — create it with POST /suppliers, or send the vendor's taxId/billingAddress directly. seller (the deprecated alias for supplier) has no meaning on a purchase and is rejected outright with 422 SELLER_ALIAS_NOT_ALLOWED_FOR_PURCHASE. The response's top-level entityRole tells you which response block (supplier or customer) is your own entity — "customer" for a purchase, "supplier" for a sale.

Purchase-direction calculations are recorded/metered exactly like a sale (the same commit default applies), but are excluded from your own selling-side Compliance Radar thresholds and auto-discovery — transactionDirection: 'sale' is what those queries filter on. A purchase resolving to a US jurisdiction is rejected as 422 us_jurisdiction_purchase_unsupported (no use-tax self-assessment computation exists yet); a genuinely cross-border GOODS purchase is not a whole-calculation rejection — it is computed per line instead, with the per-line import/intra-community-acquisition/own-goods treatment surfaced in lineItems[].movement/.outcome (see Response Reference).

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "transactionDirection": "purchase",
    "supplier": {
      "name": "Acme Cloud Services Ltd",
      "taxId": "DE123456789",
      "billingAddress": { "country": "DE" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "productName": "Cloud hosting — September",
        "amount": 800.00,
        "supplyType": "SERVICES",
        "statedTaxAmount": 152.00
      },
      {
        "id": "line-2",
        "productName": "Office furniture",
        "amount": 300.00,
        "supplyType": "GOODS",
        "recoverablePercentOverride": 50
      }
    ]
  }'

Commodity & Tariff Classification

Two optional line-item fields — taxTreatmentOverride and commodityCode — sit above the ordinary rate-band resolution described in Tax Treatments. Neither changes any upstream B2B/reverse-charge/exemption decision, and neither changes how a line's taxCategory is classified — for rate-band purposes they only replace the tail, B2C-default rate-band step with a caller-supplied or tariff-derived one. commodityCode has one further effect outside rate-band resolution: on an IOSS-treated calculation it also drives the response's customsDuty item count, regardless of whether taxTreatmentOverride is also present on that line — see Response Reference.

Band-only, never a raw rate. taxTreatmentOverride takes one of STANDARD, MIDDLE, REDUCED, SUPER_REDUCED, SPECIAL, ZERO, or EXEMPT — the same closed set a naturally-resolved band can take. You are naming which band applies, not a percentage; Clearvo still resolves the actual rate for that band in the line's own jurisdiction. If no researched rate exists for that band in that jurisdiction, the line degrades the same way an unresolved band always does (see degraded / degradedReason in Response Reference) — this never invents a numeric rate.

Per-country code scoping. commodityCode keys into Clearvo's internal tariff-rate data the same way taxCategory keys into category rate data — that backing data is not itself a retrievable resource; there is no GET endpoint that exposes it. Codes are jurisdiction-scoped nomenclatures, never assumed shared across countries: GB is classified under the UK Trade Tariff, EU member states under CN/TARIC. There is no separate scheme field to set — HS, CN, and UK Trade Tariff codes all extend the same WCO Harmonized System numbering for their shared leading digits, so matching is driven entirely by the line's own resolved country/region, not by which nomenclature label the code happens to use. A code is looked up hierarchy-aware: its own digit precision is tried first, then progressively shorter standard prefixes (10 → 8 → 6 → 4 digits), each scoped to the line's own resolved country/region, taking the first level with a matching rate. A total miss at every level never invents a rate — the line re-enters the ordinary taxCategory/classification cascade exactly as if commodityCode had never been supplied.

The confidence signal is unaffected. classificationStatus and classificationConfidence on each response line item (see Response Reference) describe how Clearvo resolved the line's tax category — classification runs unconditionally, before jurisdiction and rate-band resolution. That is true even when taxTreatmentOverride or commodityCode later determined the line's actual rate band: a line can carry a high-confidence AI-classified category and still have its rate band overridden by a tariff code, or vice versa. Never infer anything about band provenance from classificationConfidence — check sourcingRationale and the applied rate/taxCode instead.

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "customer": {
      "billingAddress": { "country": "GB", "postalCode": "SW1A 1AA" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 45.00,
        "quantity": 1,
        "productName": "Children'"'"'s cotton t-shirt",
        "commodityCode": "6109100010"
      },
      {
        "id": "line-2",
        "amount": 12.00,
        "quantity": 3,
        "productName": "Promotional sample — always zero-rated",
        "taxTreatmentOverride": "ZERO"
      }
    ]
  }'

Line 1 has no taxTreatmentOverride, so the UK Trade Tariff code resolves the rate band. Line 2's taxTreatmentOverride takes precedence over any commodityCode that line might also carry — it is always checked first.

Successful response

See the Quickstart for a full response example. For the complete field reference, see Response Reference.

Error responses

Credit Notes & Refunds

Clearvo supports two distinct patterns for reversing a committed transaction, chosen based on how your billing or ERP system models reversals.

Credit notes (B2B / ERP path)

ERP systems such as SAP, NetSuite, and Oracle issue a formal credit note document when a sale is reversed. Submit this as a new calculation with transactionType: "credit_note". Clearvo negates all line item amounts before the calculation pipeline runs — the same jurisdiction, treatment, and rate logic applies unchanged, but every amount comes out negative. This keeps the credit note fully audit-traceable as its own document with its own calculationId.

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "transactionType": "credit_note",
    "relatedCalculationId": "cl_calc_01j4...",
    "supplier": { "billingAddress": { "country": "IE" }, "taxId": "IE1234567T" },
    "customer": {
      "taxId": "DE987654321",
      "billingAddress": { "country": "DE" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 500.00,
        "amountIncludesTax": false,
        "productName": "Enterprise software licence"
      }
    ]
  }'

The response is identical in shape to a regular calculation — all amounts are negative (e.g. taxableAmount: -500.00, taxAmount: -95.00). The response includes transactionType: "credit_note" and relatedCalculationId.

Refunds (B2C / billing system path)

B2C billing systems such as Stripe, Chargebee, and Recurly process a payment refund without issuing a separate credit note document. Use the refund endpoint to mark the original calculation as refunded.

Endpoint

POST https://api.clearvo.io/v1/tax/calculate/{id}/refund

curl https://api.clearvo.io/v1/tax/calculate/cl_calc_01j4.../refund \
  -X POST \
  -H "x-api-key: csk_live_..."

{
  "ok": true,
  "calculationId": "cl_calc_01j4...",
  "refundedAt": "2026-06-24T10:30:00.000Z"
}

Error responses

Compliance threshold impact

Both a recorded credit note and a recorded original invoice are, themselves, recorded calculations — reversing one never deletes or un-records the other:

• Credit notes — the negative amount nets out the original invoice's contribution to your Compliance Radar threshold total for that entity and country as soon as it's recorded.
• Refunds — marking a calculation refunded does not durably reduce your Compliance Radar threshold total. It is applied immediately, but the total is periodically recalculated from every recorded calculation regardless of refund status, so a refunded amount counts toward the threshold again once that recalculation next runs. There is currently no way to permanently exclude a refunded calculation from your threshold total — a refund is the correct step for your own records, but do not rely on it to bring a threshold back below APPROACHING/BREACH.

Neither path deletes anything — there is no way to un-record a calculation once it has been persisted. If a calculation was recorded in error with no corresponding real sale, contact support@clearvo.io rather than attempting to work around it client-side.

Exemptions

Store tax exemption records for specific customers. Use these endpoints to log that a customer holds a valid exemption certificate for a jurisdiction and product category. To apply an exemption in a calculation, pass "taxCode": "E" on the relevant line items — the engine processes it as exempt. Automated certificate matching during calculation is on the roadmap.

Endpoints

curl https://api.clearvo.io/v1/tax/exemptions \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "region": "TX",
    "customerTaxId": "12-3456789",
    "taxCategorySlug": "software",
    "reason": "Non-profit exemption certificate",
    "certificateRef": "TX-NPO-2026-00123",
    "validFrom": "2026-01-01",
    "validTo": "2026-12-31"
  }'

Exemption fields

Tax Obligations

Track where your entity has a tax registration obligation — based on economic nexus thresholds, physical presence, or a manual override. The calculation engine uses obligation records to determine whether to apply seller-not-registered treatment.

Endpoints

curl https://api.clearvo.io/v1/tax/obligations/oblig_01j4... \
  -X PATCH \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "registrationStatus": "REGISTERED",
    "registrationNumber": "DE987654321",
    "obligationStatus": "COMPLIANT"
  }'

Obligation fields

Product Catalogue

/v1/tax/calculate never runs a live AI classification — see Product Classification for the deterministic lookup it uses instead. The Product Catalogue endpoints below are how you build that catalogue up front: classify products with AI assistance, inspect AI-assigned slugs, approve or correct them, and bulk-load classifications from an ERP export — so a real transaction resolves to a correct, reviewed category via productCode/productName lookup instead of falling through to your account default.

Endpoints

curl https://api.clearvo.io/v1/tax/products \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "PLAN-BIZ-ANNUAL",
    "productName": "Business plan — annual subscription",
    "productDescription": "Cloud software subscription, B2B"
  }'

curl https://api.clearvo.io/v1/tax/products/bulk \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: text/csv" \
  --data-binary 'product_code,product_name,product_description,tax_category
PLAN-BIZ,Business plan,,saas_business
EBOOK-01,EU Tax Guide 2026,Comprehensive EU VAT reference,
CONSULT-HR,HR transformation workshop,Half-day onsite session,'

Classification fields

Tax Categories

The Tax Categories endpoint returns the complete, live taxonomy of product category slugs — the same set the engine uses to classify line items. Call this endpoint to discover valid values for taxCategory on calculate requests and defaultTaxCategorySlug in account settings.

Endpoint

GET https://api.clearvo.io/v1/tax/categories

Accepts both entity-scoped and account-scoped API keys.

curl https://api.clearvo.io/v1/tax/categories \
  -H "x-api-key: csk_live_..."

{
  "object": "list",
  "count": 48,
  "categories": [
    {
      "slug": "api_data_services",
      "name": "API Access / Data Feeds / Integrations",
      "defaultTaxCode": "S",
      "eligibleSchemes": ["STANDARD", "OSS_UNION", "OSS_NON_UNION", "SIMPLIFIED"]
    },
    {
      "slug": "ebooks",
      "name": "eBooks / Digital Publications",
      "defaultTaxCode": "AA",
      "eligibleSchemes": ["STANDARD", "OSS_UNION", "OSS_NON_UNION", "SIMPLIFIED"]
    },
    {
      "slug": "saas_business",
      "name": "SaaS / Cloud Software (Business Use)",
      "defaultTaxCode": "S",
      "eligibleSchemes": ["STANDARD", "OSS_UNION", "OSS_NON_UNION", "SIMPLIFIED"]
    },
    "..."
  ]
}

Response fields

Supported Jurisdictions

GET /v1/tax/jurisdictions returns every jurisdiction the engine can calculate tax for, plus any announced jurisdictions that are not yet live. Use it to discover coverage programmatically — for example, to decide which countries to route through Clearvo, or to self-heal after a country_not_supported error. This endpoint returns coverage only — it never returns rates or rate bands.

curl https://api.clearvo.io/v1/tax/jurisdictions \
  -H "x-api-key: csk_live_..."

{
  "object": "list",
  "jurisdictions": [
    { "country": "AE", "name": "United Arab Emirates", "comingSoon": false },
    { "country": "AL", "name": "Albania", "comingSoon": false },
    { "country": "AR", "name": "Argentina", "comingSoon": false }
  ],
  "count": 76
}

Truncated for readability — the live response lists all 76 jurisdictions in the jurisdictions array (the full set appears in the tables below).

An announced jurisdiction — one with a published go-live date that is not yet live — appears in the same array with comingSoon: true and an availableFrom date. There are none announced today, so the entry below is illustrative (how Qatar would appear if it enacted its VAT law):

{ "country": "QA", "name": "Qatar", "comingSoon": true, "availableFrom": "2027-01-01" }

Response fields

Freshness and caching

This endpoint reads coverage live on every request, but the calculation pipeline caches coverage for up to 30 minutes. Two consequences:

• A jurisdiction newly appearing in this list can take up to 30 minutes to be accepted by POST /v1/tax/calculate.
• A comingSoon jurisdiction whose availableFrom date arrives normally goes live in calculate immediately — the go-live date is evaluated per call, not cached. If the go-live is postponed, this list keeps reporting comingSoon: true and calculate keeps returning 422 — the two never disagree.

Recommended client pattern: cache this list on your side and refresh it every 30–60 minutes, and re-fetch it whenever you receive a 422 country_not_supported — the error means your cached view of coverage is stale or the country is genuinely unsupported.

Unsupported jurisdiction error

When a calculation resolves to a jurisdiction not in this list, POST /v1/tax/calculate returns 422 rather than guessing a rate:

{
  "error": "country_not_supported",
  "country": "QA",
  "message": "Tax calculations for QA are not currently supported. Call GET /v1/tax/jurisdictions for the list of supported jurisdictions.",
  "hint": "If you believe this country should be supported, contact support@clearvo.io."
}

Supported countries

The 76 jurisdictions live today, grouped by region. These tables are generated from the same coverage data the endpoint serves — the endpoint remains the live source of truth between site deploys. Qatar is deliberately not supported: its 2016 VAT framework law has never been enacted, so there is no live Qatar VAT to calculate.

European Union (27)

Rest of Europe (11)

Americas (10)

Asia-Pacific (15)

Middle East (7)

Africa (6)

Registrations

Registrations tell the calculation engine where your entity is authorised to collect tax. A jurisdiction with no registration record defaults to REGISTERED (tax collected). Set a jurisdiction to NOT_REGISTERED and the engine returns tax code O (outside scope, 0%) for all transactions there. Adding an IOSS number enables IOSS treatment for qualifying EU B2C shipments ≤ €150.

Endpoints

Collection status

When Tax Calculations is enabled for your account, each registration carries a collectionStatus that controls whether Clearvo applies tax for that jurisdiction.

The list response also includes two top-level flags: taxCalcEnabled (boolean — whether the product is active) and taxCalcSetupRequired (boolean — true when any registration is in SETUP_NEEDED state).

curl https://api.clearvo.io/v1/tax/registrations \
  -X POST \
  -H "x-api-key: csk_live_ent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "VAT",
    "country": "DE",
    "taxNumber": "DE123456789"
  }'

# Start collecting immediately
curl https://api.clearvo.io/v1/tax/registrations/<id> \
  -X PATCH \
  -H "x-api-key: csk_live_ent_..." \
  -H "Content-Type: application/json" \
  -d '{ "collectFromDate": null }'

# Defer to a future date
curl https://api.clearvo.io/v1/tax/registrations/<id> \
  -X PATCH \
  -H "x-api-key: csk_live_ent_..." \
  -H "Content-Type: application/json" \
  -d '{ "collectFromDate": "2026-07-01" }'

Registration types

Account Settings

Account-level defaults that apply to every calculation made with your API key. All three settings can be overridden per-request — the cascade is: request field → product cache → account setting → hardcoded default.

Endpoints

New accounts default to defaultPriceIncludesTax: true for every jurisdiction other than the US, matching common non-US B2C convention — a US-resolved line always stays exclusive regardless of this setting. The example below explicitly opts a non-US account out of that default (tax-exclusive prices, added on top).

curl https://api.clearvo.io/v1/tax/settings \
  -X PATCH \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vatValidationMode": "format",
    "vatUnverifiableTreatment": "consumer",
    "defaultPriceIncludesTax": false,
    "defaultTaxCategorySlug": "saas_business"
  }'

Settings fields

Response Reference

Full field reference for the TaxCalculateResponse object returned by the calculation endpoint.

Top-level fields

jurisdiction

supplier / customer / entityRole (response)

Present on every calculation — distinct from the request's own supplier/customer input objects. entityRole ("supplier" for a "sale", "customer" for a "purchase") tells you which of the two blocks below is your own entity; the other is the counterparty. Only the counterparty block carries the B2B/B2C validation fields.

sellerRegistration

Whether and how your entity is registered to collect tax in the resolved jurisdiction. Also present per-line as lineItems[].sellerRegistration for a request spanning categories with different registration coverage.

ioss (when applicable)

customsDuty (when applicable)

Present only on an IOSS-treated calculation for a low-value consignment, for the EU's temporary (2026-07-01 to 2028-06-30) per-item customs duty. This is an estimate of the duty that will be assessed when the consignment is declared for import — owed by the IOSS holder or their indirect customs representative, not VAT, not collected from the buyer, and never included in totalTax/totalAmountWithTax. It is counted per distinct tariff classification (6-digit level), assuming the order ships as a single consignment; the actual figure may differ if the carrier lodges a more detailed declaration, splits the order into several parcels, or the declaration is accepted outside the measure's window. It is not refunded when goods are returned — a credit note instead carries customsDutyNote: "NOT_REVERSED_ON_CREDIT_NOTE" and omits customsDuty. If you choose to recharge this amount to the buyer at the time of sale, that recharge becomes part of the VAT-taxable amount of the sale itself — the recharge is VAT-able, this field is not. When you also request duties (duties.include), the same €3 appears in the consignment's duty (source fee_rule): customsDuty is that one fee and consignments[] is the whole landed-cost estimate, so never add the two together. See Customs duties and landed cost.

Three IOSS goods lines, two sharing one tariff classification and one with no usable commodityCode — two duty items, €6.00 total:

{
  "calculationId": "cl_calc_01j4...",
  /* … full TaxCalculateResponse … */
  "ioss": {
    "number": "IM2760000123",
    "registrationCountry": "IE",
    "totalGoodsValue": 90.00,
    "currency": "EUR"
  },
  "customsDuty": {
    "feeCode": "EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY",
    "currency": "EUR",
    "amount": 6.00,
    "perItemAmount": 3.00,
    "itemCount": 2,
    "classificationDigits": 6,
    "items": [
      { "classificationCode": "610910", "lineIds": ["line-1", "line-2"] },
      { "classificationCode": null, "lineIds": ["line-3"] }
    ],
    "linesMissingCommodityCode": ["line-3"],
    "includedInTotals": false,
    "payableBy": "DECLARANT",
    "estimate": true,
    "effectiveFrom": "2026-07-01"
  },
  "totalTax": 17.10,
  /* customsDuty.amount (€6.00) is never folded into totalTax/totalAmountWithTax */
  "summary": { "totalAmount": 90.00, "totalDiscount": 0.00, "totalTax": 17.10, "totalAmountWithTax": 107.10 }
}

The same invoice, credited — the duty is not reversed:

{
  "calculationId": "cl_calc_01j5...",
  "transactionType": "credit_note",
  /* … full TaxCalculateResponse … */
  "customsDutyNote": "NOT_REVERSED_ON_CREDIT_NOTE"
  /* no "customsDuty" key on a credit note — the €6.00 already assessed on the original invoice is not refunded */
}

summary

lineItems[]

Tax Treatments

Clearvo selects a tax treatment for each transaction using a priority-ordered decision tree. The treatment determines the EN16931 tax code and effective rate applied to line items.

Jurisdiction Resolution

Clearvo determines which tax authority's rules apply to a transaction using a rule-based resolution chain. The resolved jurisdiction, resolution method, and any conflicting signals are all returned in the response.

When the resolution chain cannot determine the jurisdiction from available signals, Clearvo falls back to the seller's country and marks the result as degraded: true with a degradedReason of "jurisdiction_unresolved".

Sourcing matrix

Every line item is classified into one of three place-of-supply regimes (placeOfSupplyRule in the response — see Product Classification) before jurisdiction and tax code are resolved. The tables below are the complete, current sourcing behaviour per regime, including which rules are EU-specific versus applied by Clearvo for any seller/buyer country. A category classified UNSUPPORTED (e.g. real estate, restaurant/catering, passenger transport, event admission) never reaches sourcing at all — the calculation is rejected with a 422 category_not_supported error.

GOODS — tangible products, destination-of-goods sourcing.

DIGITAL_SERVICE — electronically supplied (TBE) services: SaaS, streaming, downloads, online courses, etc. Customer-location sourcing for both B2B and B2C.

GENERAL_SERVICE — non-digital services: consulting, legal, accounting, financial services, insurance, healthcare. B2B sourcing matches DIGITAL_SERVICE; B2C sourcing does not.

B2G (government) customers are treated identically to B2B throughout the tables above.

Product Classification

Clearvo classifies each line item into a product category to determine the correct VAT rate band — for example, whether a digital product is taxed at the standard rate or a reduced "cultural goods" rate. No HS codes are required.

Classification pipeline

/v1/tax/calculate never makes a live AI call — every line resolves through a deterministic, low-latency cascade so a large cart is never slowed down by an unrecognised product name. AI-assisted classification is available separately, for building your product catalogue in advance — see Product Catalogue below.

Common category slugs

A representative sample — call GET /v1/tax/categories for the complete live list.

E-Invoicing Integration

Tax Calculation 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

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 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 }
}