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

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

MethodPathDescription
GET/v1/tax/exemptionsList all exemptions. Filter by country, customerTaxId, or taxCategorySlug.
POST/v1/tax/exemptionsCreate a new exemption.
GET/v1/tax/exemptions/{id}Retrieve a single exemption.
DELETE/v1/tax/exemptions/{id}Delete an exemption (e.g. when a certificate expires).
curl — create exemption
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

countrystringRequired
ISO country code the exemption applies to.
regionstringOptional
State or province code. Leave null for a country-wide exemption.
customerTaxIdstringRequired
The customer's tax ID that this exemption is issued to.
taxCategorySlugstringOptional
Limit the exemption to a specific product category. If null, the exemption applies to all categories in the jurisdiction.
reasonstringOptional
Human-readable description for your records (e.g. "Non-profit exemption certificate").
certificateRefstringOptional
Your reference number for the exemption certificate. Stored for audit purposes.
validFromstringRequired
YYYY-MM-DD. Date from which the exemption is valid.
validTostringOptional
YYYY-MM-DD. Expiry date. If omitted, the exemption does not expire.
Tax Calculations

Tax Obligations

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

Endpoints

MethodPathDescription
GET/v1/tax/obligationsList all obligations. Filter by country and status (the obligation status).
PATCH/v1/tax/obligations/{id}Update registration status, registration number, or obligation status.
curl — update obligation
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

countrystring
ISO country code this obligation applies to.
regionstring | null
State or province. Null for country-level obligations.
registrationStatus"REGISTERED" | "PENDING" | "NOT_REGISTERED"
Current registration status with the tax authority in this jurisdiction. Controls whether the engine applies local tax rates or seller-not-registered treatment.
registrationNumberstring | null
The tax registration number issued by the authority. Set when registrationStatus is REGISTERED.
obligationStatus"COMPLIANT" | "MONITORING" | "ACTION_REQUIRED"
Overall compliance posture. ACTION_REQUIRED surfaces in the dashboard as a priority item.
thresholdAmountnumber | null
The economic nexus threshold for this jurisdiction (in local currency). Informational only — Clearvo does not automatically track sales against this threshold.
currentPeriodAmountnumber | null
Your current period sales amount in this jurisdiction. Update this via PATCH to keep the obligation status current.
estimatedExposurenumber | null
Estimated tax exposure if registered (computed field — not updateable directly).
Tax Calculations

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

MethodPathDescription
GET/v1/tax/productsList classified products. Filter by status (APPROVED | NEEDS_REVIEW), entityId (account-scoped keys only), page, limit (max 100).
POST/v1/tax/productsClassify a single product. Providing taxCategory bypasses AI and saves immediately as APPROVED.
PATCH/v1/tax/products/{id}Approve or correct a classification. Accepts slug and status (APPROVED | NEEDS_REVIEW | MANUAL).
DELETE/v1/tax/products/{id}Soft-delete a product. Sets deleted_at and hides it from all reads — classification history is preserved. Use the restore endpoint to reactivate.
POST/v1/tax/products/{id}/restoreReactivate a soft-deleted product. Body: { "reason": "string" } (required — logged to audit trail).
POST/v1/tax/products/bulkClassify up to 500 products in one call. Accepts text/csv or application/json.
curl — classify a product
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 — bulk classify (CSV)
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

productCodestring
Your SKU or ERP code. Used as the cache key — the same product is classified at most once per account.
productNamestring
Plain-language product name, used for an exact-match catalogue lookup when productCode isn't supplied or doesn't match. Required unless productCode is supplied.
productDescriptionstring
Additional context for the classifier. Include when the product name alone is ambiguous.
taxCategorystring
Explicit slug override (e.g. "saas_business", "ebooks"). Bypasses AI — confidence is set to 1.0 and status is APPROVED immediately.
classificationCodesarray
Up to 5 outside product codes, each { "system": "stripe" | "shopify" | "hs" | …, "code": "…" }. Tried in order; the first that maps to a tax category is used, the same way as on a calculation line. Ambiguous, unmapped or unknown codes are skipped.
statusAPPROVED | NEEDS_REVIEW
AI confidence ≥ 0.85 → APPROVED automatically. Below 0.85 → NEEDS_REVIEW until approved via PATCH or the dashboard.
Tax Calculations

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.

ℹ
Slugs are an open string taxonomy — new categories are added non-breakingly as the engine is updated. Fetch this endpoint rather than hardcoding slug strings to ensure your integration handles new additions gracefully.

Endpoint

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

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

curl
curl https://api.clearvo.io/v1/tax/categories \
  -H "x-api-key: csk_live_..."
JSON Response
{
  "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

slugstring
The category identifier to use in taxCategory on line items, or as defaultTaxCategorySlug in account settings.
namestring
Human-readable description of the category.
defaultTaxCodestring
The EN16931 tax code most commonly applied to this category (S = standard, AA = reduced, E = exempt). The actual code used in a calculation may differ depending on country-specific rules.
eligibleSchemesstring[]
OSS/IOSS schemes this category qualifies for: STANDARD, OSS_UNION, OSS_NON_UNION, IOSS, SIMPLIFIED (e.g. Norway VOEC). Physical goods include IOSS; location-specific services include STANDARD only.
Tax Calculations

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 tell a country we do not cover from one you have misconfigured after a country_not_supported warning. This endpoint returns coverage only — it never returns rates or rate bands.

curl
curl https://api.clearvo.io/v1/tax/jurisdictions \
  -H "x-api-key: csk_live_..."
JSON Response
{
  "object": "list",
  "jurisdictions": [
    { "country": "AE", "name": "United Arab Emirates", "comingSoon": false },
    { "country": "AL", "name": "Albania", "comingSoon": false },
    { "country": "AR", "name": "Argentina", "comingSoon": false }
  ],
  "count": 80
}

Truncated for readability — the live response lists all 80 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):

JSON — illustrative announced entry
{ "country": "QA", "name": "Qatar", "comingSoon": true, "availableFrom": "2027-01-01" }

Response fields

objectstring
Always "list".
jurisdictions[]array
One entry per jurisdiction, sorted alphabetically by ISO country code. Unsupported jurisdictions are omitted entirely — absence from this list means POST /v1/tax/calculate returns a 200 with totalTax: 0 and taxTreatment: "UNSUPPORTED_JURISDICTION" for that country (not an error).
jurisdictions[].countrystring
ISO 3166-1 alpha-2 country code (uppercase), e.g. "DE".
jurisdictions[].namestring
English display name of the jurisdiction, e.g. "Germany".
jurisdictions[].comingSoonboolean
false — live now: calculate accepts this jurisdiction. true — announced but not yet live: calculate still returns the 200 zero-tax UNSUPPORTED_JURISDICTION result until the availableFrom date, at which point the jurisdiction normally goes live automatically. If a go-live is postponed, the entry simply remains comingSoon: true — treat this field, not the date, as authoritative for whether calculate accepts the jurisdiction.
jurisdictions[].availableFromstring
Present only when comingSoon is true — the announced go-live date (YYYY-MM-DD). Omitted entirely on live jurisdictions.
countinteger
Total number of entries in jurisdictions (live plus coming soon).

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 a response carries unsupportedJurisdiction or a country_not_supported warning — it means your cached view of coverage is stale or the country is genuinely unsupported. The response is never an error, so checkout is not blocked.

Unsupported jurisdiction

When a calculation resolves to a well-formed country that is not in this list (for example JE, GG, IM or QA), POST /v1/tax/calculate does not fail and does not guess a rate. It returns 200 with totalTax: 0, taxTreatment: "UNSUPPORTED_JURISDICTION" (tax code O), a top-level unsupportedJurisdiction field and a country_not_supported warning. Each affected line carries outcome: { status: "UNKNOWN_TREATMENT", reasonCode: "unsupported_jurisdiction" }. Test for unsupportedJurisdiction: it tells you the 0 tax is because we do not cover the country, not because no tax is due. The transaction is stored (when commit is true) and shown in the dashboard as an unsupported country. party is seller when the place of supply was the seller's own address, otherwise customer.

JSON Response — 200 (abridged)
{
  "totalTax": 0,
  "taxTreatment": "UNSUPPORTED_JURISDICTION",
  "taxCode": "O",
  "unsupportedJurisdiction": { "country": "JE", "party": "customer" },
  "warnings": [{
    "ruleCode": "country_not_supported",
    "scopeLevel": "PLATFORM",
    "country": "JE",
    "party": "customer",
    "message": "Tax calculations for JE are not currently supported; 0 tax was returned.",
    "hint": "Call GET /v1/tax/jurisdictions for the list of supported jurisdictions."
  }]
}

A country code that is not a valid ISO 3166-1 alpha-2 code (XX, Narnia, UK) is a different case: it returns 422 with error: "invalid_country", code: "INVALID_COUNTRY", the field that carried it (for example customer.shippingAddress.country) and the value you sent.

To see demand for countries we do not yet cover, list your unsupported calculations from the ledger: GET /v1/tax/calculation-ledger?outcome=unsupported_country&summary=country groups them by destination country.

Supported countries

The 80 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)

CodeCountryCodeCountryCodeCountry
ATAustriaFIFinlandLVLatvia
BEBelgiumFRFranceMTMalta
BGBulgariaGRGreeceNLNetherlands
CYCyprusHRCroatiaPLPoland
CZCzechiaHUHungaryPTPortugal
DEGermanyIEIrelandRORomania
DKDenmarkITItalySESweden
EEEstoniaLTLithuaniaSISlovenia
ESSpainLULuxembourgSKSlovakia

Rest of Europe (11)

CodeCountryCodeCountryCodeCountry
ALAlbaniaISIcelandRSSerbia
BABosnia & HerzegovinaMEMontenegroTRTürkiye
CHSwitzerlandMKNorth MacedoniaUAUkraine
GBUnited KingdomNONorway

Americas (11)

CodeCountryCodeCountryCodeCountry
ARArgentinaCOColombiaUSUnited States
BRBrazilECEcuadorUYUruguay
CACanadaMXMexicoVIU.S. Virgin Islands
CLChilePEPeru

Asia-Pacific (18)

CodeCountryCodeCountryCodeCountry
ASAmerican SamoaIDIndonesiaNZNew Zealand
AUAustraliaINIndiaPHPhilippines
BDBangladeshJPJapanSGSingapore
CNChinaKRSouth KoreaTHThailand
GUGuamMPNorthern Mariana IslandsTWTaiwan
HKHong Kong SAR ChinaMYMalaysiaVNVietnam

Middle East (7)

CodeCountryCodeCountryCodeCountry
AEUnited Arab EmiratesJOJordanSASaudi Arabia
BHBahrainKWKuwait
ILIsraelOMOman

Africa (6)

CodeCountryCodeCountryCodeCountry
EGEgyptKEKenyaNGNigeria
GHGhanaMAMoroccoZASouth Africa
Tax Calculations

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

MethodPathDescription
GET/v1/tax/registrationsList registrations for the entity. Account-scoped keys must supply ?entityId=. Returns collectionStatus, collectFromDate, and canCollectTax on each registration when Tax Calculations is enabled.
POST/v1/tax/registrationsCreate a registration. Account-scoped keys must include X-Entity-Id.
PATCH/v1/tax/registrations/{id}Set the collection start date for a registration. Pass collectFromDate: null to collect immediately, or an ISO date string to defer. Returns the updated collectionStatus.
DELETE/v1/tax/registrations/{id}Delete a tax number registration. Account-scoped keys must include X-Entity-Id.

Collection status

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

StatusMeaning
COLLECTINGTax is being collected — collectFromDate is set to today or a past date.
DEFERREDCollection starts on a future collectFromDate. No tax collected until that date.
SETUP_NEEDEDTax Calculations is enabled but no collectFromDate has been set. Set one via PATCH /v1/tax/registrations/{id}.
nullTax Calculations is not enabled for this account.

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 — add a VAT registration
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"
  }'
curl — set collection date
# 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

TypeDescriptionEngine effect
VATStandard national VAT registrationSets obligation to REGISTERED; tax collected at local rate
IOSSEU Import One-Stop Shop numberWrites registration_number on a tax_registrations row with scheme=IOSS; enables IOSS treatment for eligible B2C goods ≤ €150 shipped into the EU
UNION_OSSEU One-Stop Shop (Union scheme)Sets obligation to REGISTERED with OSS scheme flag
NON_UNION_OSSEU One-Stop Shop (Non-Union scheme)Sets obligation to REGISTERED with OSS scheme flag
Tax Calculations

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

MethodPathDescription
GET/v1/tax/settingsRead current account settings. Returns defaults if no settings row has been written yet.
PATCH/v1/tax/settingsUpdate one or more settings. Partial updates — omitted fields are unchanged.

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 — update settings
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

vatValidationMode"full" | "format" | "none"Default: "full"
Account-level default for VAT ID validation. Overridden per-request by the vatValidation request field. "full" — live VIES lookup (default). "format" — format check only, no VIES call. "none" — no validation; all VAT IDs trusted.
vatUnverifiableTreatment"consumer" | "business"Default: "consumer"
How to treat B2B transactions when the customer's VAT ID cannot be verified (only applies when vatValidationMode is "full"). "consumer" charges tax at B2C rates (conservative). "business" applies reverse charge and sets degraded: true.
defaultPriceIncludesTaxbooleanDefault: true (non-US) / n/a for US
Whether line item amounts already include tax by default, for every jurisdiction other than the US — defaults to true (inclusive), matching common non-US B2C convention. Always ignored for a US-resolved line, which is always treated as exclusive at this account-wide tier regardless of this value — US retail convention adds tax at checkout rather than folding it into the sticker price. A line item's own amountIncludesTax field is honoured for every jurisdiction including the US (e.g. a fixed-price digital subscription or a marketplace absorbing tax).
defaultTaxCategorySlugstring | nullDefault: null
Fallback product category slug when no productCode/productName catalogue match is found. If null, the engine applies the standard physical-goods category.
usAddressPrecision"rooftop" | "zip"Default: "rooftop"
How US sales tax jurisdiction is resolved. See Jurisdiction Resolution below.
placeOfBusinessAddressobject | nullDefault: null
Where your business is physically established — distinct from the per-transaction seller address sent to POST /v1/tax/calculate. Changing this can change which jurisdiction's rate applies to your intrastate US sales: Texas, California, and Illinois source some sales to the seller's own location rather than the buyer's. Review recent tax calculations after changing this field. Sub-fields: line1, line2, city, region, postalCode, country (2 or 3 letter code) — each independently nullable to clear just that field, or pass null for the whole object to clear the entire address.
isMarketplaceFacilitatorbooleanDefault: false
Whether the account is a marketplace facilitator (a platform that collects and remits tax on behalf of third-party sellers) rather than a direct seller. Currently only affects sourcing determination for Illinois — no other jurisdiction is affected by this flag today.
availableTaxCategoriesarray
Read-only. Full list of active category slugs and names available in your account (GET only).