Tax Calculations

The Tax Calculation API determines the correct tax amount for any transaction — VAT, GST, sales tax, and other indirect taxes — across 100+ countries in a single API call. You send a seller, a customer, and a list of line items; Clearvo resolves the applicable jurisdiction, classifies each product, applies the correct rate band, and returns a fully broken-down tax result.

Key capabilities

• 100+ countries — EU multi-band VAT (standard, reduced, second-reduced, super-reduced), US sales tax (all 50 states, 13k+ jurisdictions), Canadian GST/HST/PST, and more
• 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
• Ephemeral and committed calculations — calculate without recording (for quoting), or commit the result to your audit trail

Authentication

All Tax Calculation endpoints require an x-api-key header. Both entity-scoped and account-scoped keys are accepted on all endpoints. Account-scoped keys must include an X-Entity-Id header on every request to identify the target entity — entity-scoped keys do not require this header.

x-api-key: csk_live_...

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.

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "seller": {
      "country": "IE",
      "taxId": "IE1234567T"
    },
    "customer": {
      "address": { "country": "DE" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 100.00,
        "productName": "Annual SaaS subscription"
      }
    ]
  }'

{
  "calculationId": "cl_calc_01j4...",
  "committed": false,
  "sandbox": false,
  "degraded": false,
  "currency": "EUR",
  "jurisdiction": {
    "country": "DE",
    "region": null,
    "method": "BILLING_ADDRESS",
    "precision": "COUNTRY",
    "conflicts": []
  },
  "treatment": {
    "taxTreatment": "STANDARD",
    "taxCode": "S",
    "rate": 0.19,
    "rateBand": "STANDARD"
  },
  "lineItems": [
    {
      "id": "line-1",
      "taxCode": "S",
      "rate": 0.19,
      "taxableAmount": 100.00,
      "taxAmount": 19.00,
      "totalAmount": 119.00,
      "rateBand": "STANDARD",
      "classification": {
        "slug": "digital-services",
        "confidence": 0.97,
        "status": "APPROVED",
        "fromCache": false
      }
    }
  ],
  "totals": {
    "subtotal": 100.00,
    "totalTax": 19.00,
    "total": 119.00
  },
  "rateSource": {
    "provider": "CLEARVO",
    "asOf": "2026-06-21",
    "cacheHit": true
  }
}

The taxCode: "S" and rate: 0.19 on each line item flow directly into a Clearvo e-invoice submission — no mapping required. See E-Invoicing Integration.

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": {
    "type": "consumer",
    "billingAddress": {
      "country": "US",
      "region": "California"
    }
  },
  "lineItems": [{ "id": "1", "amount": 9.99, "productName": "App subscription" }]
}
// "consumer" → B2C, "California" → "CA" — both 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. By default the result is ephemeral — not recorded in your account. Set "commit": true to persist it to your audit trail and expose it in the dashboard.

Endpoint

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

Request body

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": true,
    "idempotencyKey": "order-abc-123",
    "seller": {
      "country": "IE",
      "taxId": "IE1234567T"
    },
    "customer": {
      "taxId": "DE987654321",
      "address": {
        "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"
  }'

Request fields

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",
    "commit": true,
    "transactionType": "credit_note",
    "relatedCalculationId": "cl_calc_01j4...",
    "seller": { "country": "IE", "taxId": "IE1234567T" },
    "customer": {
      "taxId": "DE987654321",
      "address": { "country": "DE" }
    },
    "lineItems": [
      {
        "id": "line-1",
        "amount": 500.00,
        "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 patterns exclude the reversed amount from your compliance obligation totals immediately:

• Credit notes — the negative total_amount reduces the threshold SUM automatically, because the SUM aggregates all committed amounts for the entity and country.
• Refunds — the refunded calculation is excluded from the threshold SUM as soon as refunded_at is set. The Compliance Radar reflects this in real time.

Batch Calculation

Calculate tax for up to 50 transactions in one request. Each item in the batch is processed independently and in parallel — an error on one item does not affect the others. Per-item errors are returned inline at the item's index.

Endpoint

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

curl https://api.clearvo.io/v1/tax/calculate/batch \
  -X POST \
  -H "x-api-key: csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "currency": "EUR",
        "seller": { "country": "IE", "taxId": "IE1234567T" },
        "customer": { "address": { "country": "DE" } },
        "lineItems": [{ "id": "l1", "amount": 100.00, "productName": "SaaS subscription" }]
      },
      {
        "currency": "GBP",
        "seller": { "country": "GB", "taxId": "GB123456789" },
        "customer": { "address": { "country": "GB" } },
        "lineItems": [{ "id": "l1", "amount": 49.99, "productName": "Printed guidebook" }]
      }
    ]
  }'

{
  "results": [
    {
      "index": 0,
      "calculationId": "cl_calc_01j4...",
      "totals": { "subtotal": 100.00, "totalTax": 19.00, "total": 119.00 },
      /* … full TaxCalculateResponse … */
    },
    {
      "index": 1,
      "error": "invalid_country: 'ZZ' is not a valid ISO country code"
    }
  ],
  "processedAt": "2026-06-21T12:00:00.000Z"
}

Each result includes an index matching its position in the items array. Successful items contain the full TaxCalculateResponse shape. Items that failed contain only index and error. The top-level HTTP status is always 200 if the batch request itself was valid — check each item's error field individually.

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

Every product that passes through /v1/tax/calculate is classified by AI and cached per account. The Product Catalogue endpoints let you pre-classify your full product catalogue, inspect AI-assigned slugs, approve or correct them, and bulk-load classifications from an ERP export — all before go-live, so the first real transaction is never slowed by an AI round-trip.

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", "VOEC"]
    },
    {
      "slug": "ebooks",
      "name": "eBooks / Digital Publications",
      "defaultTaxCode": "AA",
      "eligibleSchemes": ["STANDARD", "OSS_UNION", "OSS_NON_UNION", "VOEC"]
    },
    {
      "slug": "saas_business",
      "name": "SaaS / Cloud Software (Business Use)",
      "defaultTaxCode": "S",
      "eligibleSchemes": ["STANDARD", "OSS_UNION", "OSS_NON_UNION", "VOEC"]
    },
    "..."
  ]
}

Response fields

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

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 both the single and batch calculation endpoints.

Top-level fields

jurisdiction

treatment

lineItems[]

totals

ioss (when applicable)

rateSource

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".

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

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 taxCode and rate fields on each calculated line item match the fields expected by the POST /v1/send endpoint — no mapping layer is needed.

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 buyer fields …
  "lineItems": [{
    "description": "Annual SaaS subscription",
    "quantity": 1,
    "unitPrice": 100.00,
    "taxCode": "S",    // ← from calculation response
    "taxRate": 0.19,     // ← from calculation response
    "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 are not billed 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 (AI classifier and cache)
• Tax treatment determination (all rules, including IOSS and reverse charge)
• DB write when commit: true (written to sandbox DB, not production)
• Idempotency key enforcement (scoped to 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
• Billing — sandbox calculations do not count toward usage

curl https://api.clearvo.io/v1/tax/calculate \
  -X POST \
  -H "x-api-key: csk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "seller": { "country": "IE", "taxId": "IE1234567T" },
    "customer": { "address": { "country": "FR" } },
    "lineItems": [{ "id": "l1", "amount": 99.00, "productName": "SaaS subscription" }]
  }'

{
  "calculationId": "cl_calc_test_...",
  "committed": false,
  "sandbox": true,
  "degraded": false,
  "currency": "EUR",
  "jurisdiction": { "country": "FR", "method": "BILLING_ADDRESS" },
  "treatment": { "taxTreatment": "STANDARD", "taxCode": "S", "rate": 0.20 },
  "lineItems": [{
    "id": "l1",
    "taxCode": "S",
    "rate": 0.20,
    "taxableAmount": 99.00,
    "taxAmount": 19.80,
    "totalAmount": 118.80
  }],
  "totals": { "subtotal": 99.00, "totalTax": 19.80, "total": 118.80 }
}