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
| Method | Path | Description |
|---|---|---|
| GET | /v1/tax/exemptions | List all exemptions. Filter by country, customerTaxId, or taxCategorySlug. |
| POST | /v1/tax/exemptions | Create 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 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
countrystringRequiredregionstringOptionalcustomerTaxIdstringRequiredtaxCategorySlugstringOptionalreasonstringOptional"Non-profit exemption certificate").certificateRefstringOptionalvalidFromstringRequiredvalidTostringOptionalTax 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
| Method | Path | Description |
|---|---|---|
| GET | /v1/tax/obligations | List all obligations. Filter by country and status (the obligation status). |
| PATCH | /v1/tax/obligations/{id} | Update registration status, registration number, or obligation status. |
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
countrystringregionstring | nullregistrationStatus"REGISTERED" | "PENDING" | "NOT_REGISTERED"registrationNumberstring | nullregistrationStatus is REGISTERED.obligationStatus"COMPLIANT" | "MONITORING" | "ACTION_REQUIRED"ACTION_REQUIRED surfaces in the dashboard as a priority item.thresholdAmountnumber | nullcurrentPeriodAmountnumber | nullestimatedExposurenumber | nullProduct 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
| Method | Path | Description |
|---|---|---|
| GET | /v1/tax/products | List classified products. Filter by status (APPROVED | NEEDS_REVIEW), entityId (account-scoped keys only), page, limit (max 100). |
| POST | /v1/tax/products | Classify 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}/restore | Reactivate a soft-deleted product. Body: { "reason": "string" } (required — logged to audit trail). |
| POST | /v1/tax/products/bulk | Classify up to 500 products in one call. Accepts text/csv or application/json. |
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
productCodestringproductNamestringproductCode isn't supplied or doesn't match. Required unless productCode is supplied.productDescriptionstringtaxCategorystring"saas_business", "ebooks"). Bypasses AI — confidence is set to 1.0 and status is APPROVED immediately.classificationCodesarray{ "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_REVIEWTax 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
slugstringtaxCategory on line items, or as defaultTaxCategorySlug in account settings.namestringdefaultTaxCodestringS = standard, AA = reduced, E = exempt). The actual code used in a calculation may differ depending on country-specific rules.eligibleSchemesstring[]STANDARD, OSS_UNION, OSS_NON_UNION, IOSS, SIMPLIFIED (e.g. Norway VOEC). Physical goods include IOSS; location-specific services include STANDARD only.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 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": 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):
{ "country": "QA", "name": "Qatar", "comingSoon": true, "availableFrom": "2027-01-01" }
Response fields
objectstring"list".jurisdictions[]arrayPOST /v1/tax/calculate returns a 200 with totalTax: 0 and taxTreatment: "UNSUPPORTED_JURISDICTION" for that country (not an error).jurisdictions[].countrystring"DE".jurisdictions[].namestring"Germany".jurisdictions[].comingSoonbooleanfalse — 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[].availableFromstringcomingSoon is true — the announced go-live date (YYYY-MM-DD). Omitted entirely on live jurisdictions.countintegerjurisdictions (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
comingSoonjurisdiction whoseavailableFromdate 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 reportingcomingSoon: trueand calculate keeps returning422— 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.
{
"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)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| AT | Austria | FI | Finland | LV | Latvia |
| BE | Belgium | FR | France | MT | Malta |
| BG | Bulgaria | GR | Greece | NL | Netherlands |
| CY | Cyprus | HR | Croatia | PL | Poland |
| CZ | Czechia | HU | Hungary | PT | Portugal |
| DE | Germany | IE | Ireland | RO | Romania |
| DK | Denmark | IT | Italy | SE | Sweden |
| EE | Estonia | LT | Lithuania | SI | Slovenia |
| ES | Spain | LU | Luxembourg | SK | Slovakia |
Rest of Europe (11)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| AL | Albania | IS | Iceland | RS | Serbia |
| BA | Bosnia & Herzegovina | ME | Montenegro | TR | Türkiye |
| CH | Switzerland | MK | North Macedonia | UA | Ukraine |
| GB | United Kingdom | NO | Norway |
Americas (11)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| AR | Argentina | CO | Colombia | US | United States |
| BR | Brazil | EC | Ecuador | UY | Uruguay |
| CA | Canada | MX | Mexico | VI | U.S. Virgin Islands |
| CL | Chile | PE | Peru |
Asia-Pacific (18)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| AS | American Samoa | ID | Indonesia | NZ | New Zealand |
| AU | Australia | IN | India | PH | Philippines |
| BD | Bangladesh | JP | Japan | SG | Singapore |
| CN | China | KR | South Korea | TH | Thailand |
| GU | Guam | MP | Northern Mariana Islands | TW | Taiwan |
| HK | Hong Kong SAR China | MY | Malaysia | VN | Vietnam |
Middle East (7)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| AE | United Arab Emirates | JO | Jordan | SA | Saudi Arabia |
| BH | Bahrain | KW | Kuwait | ||
| IL | Israel | OM | Oman |
Africa (6)
| Code | Country | Code | Country | Code | Country |
|---|---|---|---|---|---|
| EG | Egypt | KE | Kenya | NG | Nigeria |
| GH | Ghana | MA | Morocco | ZA | South Africa |
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
| Method | Path | Description |
|---|---|---|
| GET | /v1/tax/registrations | List 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/registrations | Create 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.
| Status | Meaning |
|---|---|
COLLECTING | Tax is being collected — collectFromDate is set to today or a past date. |
DEFERRED | Collection starts on a future collectFromDate. No tax collected until that date. |
SETUP_NEEDED | Tax Calculations is enabled but no collectFromDate has been set. Set one via PATCH /v1/tax/registrations/{id}. |
null | Tax 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 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
| Type | Description | Engine effect |
|---|---|---|
| VAT | Standard national VAT registration | Sets obligation to REGISTERED; tax collected at local rate |
| IOSS | EU Import One-Stop Shop number | Writes registration_number on a tax_registrations row with scheme=IOSS; enables IOSS treatment for eligible B2C goods ≤ €150 shipped into the EU |
| UNION_OSS | EU One-Stop Shop (Union scheme) | Sets obligation to REGISTERED with OSS scheme flag |
| NON_UNION_OSS | EU One-Stop Shop (Non-Union scheme) | Sets obligation to REGISTERED with OSS scheme flag |
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
| Method | Path | Description |
|---|---|---|
| GET | /v1/tax/settings | Read current account settings. Returns defaults if no settings row has been written yet. |
| PATCH | /v1/tax/settings | Update 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 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"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"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 UStrue (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: nullproductCode/productName catalogue match is found. If null, the engine applies the standard physical-goods category.usAddressPrecision"rooftop" | "zip"Default: "rooftop"placeOfBusinessAddressobject | nullDefault: nullPOST /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: falseavailableTaxCategoriesarray