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

Calculate

Calculates tax for a single transaction: send who is buying, what they are buying and where it ships, and get back the rate, the tax amount and the reasoning for each line.

Endpoint

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

Request structure

A request is one JSON object. Three things are nested objects: the customer (who is buying), the supplier (who is selling) and each entry of lineItems. Addresses live inside the party they belong to, and evidence is a separate top-level object.

Request shape (not valid JSON: comments and ... are illustrative)
{
  "currency": "USD",  // required
  "commit": false,  // optional, default true
  "customer": {  // required for a sale
    "billingAddress": { "country": "US", "region": "CA", "postalCode": "94105" },
    "shippingAddress": { ... },  // optional, same shape
    "taxId": "...",  // optional, B2B
    "b2bOverride": true,  // optional
    "exemptionRef": "...", "ref": "..."  // optional
  },
  "supplier": {  // optional for a sale: defaults to your business
    "billingAddress": { "country": "US", "region": "TX" },
    "taxId": "..."
  },
  "shipFrom": { "country": "US", "region": "TX", "postalCode": "78701" },
  "evidence": { "ipAddress": "..." },
  "lineItems": [  // required, at least one
    { "id": "1", "amount": 100.00, "taxCategory": "physical_goods_general" }
  ]
}

Only currency, customer.billingAddress.country (plus region for the US) and one line item with an id and amount are required. Everything else refines the result. Country, currency and region values are normalised as described in Input formats.

Recording (commit)

By default every calculation is recorded: it is stored in your audit trail, shown in the dashboard, counted towards usage, and added to the Compliance Radar totals for its jurisdiction. The response confirms this with "committed": true.

Send "commit": false for anything that is not a real sale, such as a quote or cart estimate. A preview is not stored, not counted and ignores idempotencyKey.

  • A recorded calculation cannot be deleted. The way to reverse one is a credit note or refund.
  • A credit_note that is recorded needs relatedCalculationId, otherwise the call fails with 422.
  • With a recorded call, a repeated idempotencyKey that is still in flight returns 409, and a later repeat replays the stored response.
  • The request is retained for the audit-retention period in the Privacy Policy.

Request fields

Transaction

currencystringRequired
ISO 4217 currency code for all amounts in the request (e.g. "EUR", "USD", "GBP"). Exactly 3 characters. (Request-only — there is no top-level currency field on the response; see Response Reference.)
taxReportingCurrencystringOptional
ISO 4217 currency code to additionally convert the calculation's totals into — e.g. your group reporting currency when currency is the transaction's local currency. Adds taxReporting to the response (see Response Reference).
datestringOptional
ISO 8601. Selects which rules, rates, and registrations were in force on that date — it does not affect which Compliance Radar period this calculation is windowed into. A committed calculation always counts toward the period containing its real receipt time (resolvedAt), regardless of a back-dated date — to load genuinely historical transactions into Compliance Radar's own threshold history, use its historical-import route, not a back-dated calculation call.
commitbooleanOptional
Default: true. When the resolved value is true (sent explicitly, or omitted), the calculation is persisted to your audit trail, appears in the dashboard, counts toward your calculation usage, and contributes to Compliance Radar's nexus-threshold totals. A recorded calculation cannot be un-recorded — see Credit Notes & Refunds for the only reversal path (a credit note or refund, which nets its effect on totals but does not delete the row). Send "commit": false explicitly for a preview/quote that should not be recorded, billed, or counted toward any threshold.
idempotencyKeystringOptional
A unique key you provide (e.g. your order ID) — only ever consulted when the resolved commit is true; has no effect on a preview call. The first request for a given (account, key) pair wins the claim and runs the calculation; a concurrent duplicate while that first request is still in flight gets 409 idempotency_key_in_progress; once the first request completes, every later request with the same key replays its stored response verbatim, regardless of what request body it sends — there is no request-body comparison. Use a fresh key for a genuinely different transaction.
vatUnverifiableFallback"conservative" | "permissive"Optional
Default: "conservative". Controls behaviour when VIES cannot verify a customer's VAT ID within the timeout. "conservative" treats the customer as B2C (applies standard local rate). "permissive" applies B2B reverse charge rules anyway and marks the result as degraded: true.
vatValidation"full" | "format" | "none"Optional
Controls how a B2B customer's VAT ID is validated. No request-level default — an omitted value falls back to your account's own setting (Account Settings, itself "full" unless changed). "full" — live VIES lookup with a 300ms timeout. "format" — format check only, no network call; a structurally valid ID is trusted without a degraded flag. "none" — no validation at all; the VAT ID is trusted entirely.
merchantRefstringOptional
Merchant-of-Record reference to differentiate end customers, max 100 characters. Stored against the calculation and echoed back.
paymentMethod"card" | "bank_transfer" | "digital_wallet" | "cash" | "other"Optional
Informational only — echoed on the response, does not affect the calculation.
isMarketplaceFacilitatedSalebooleanOptional
Set when this whole order was sold through a marketplace facilitator (e.g. TikTok Shop, Amazon) that collects and remits tax on your behalf. Excludes the transaction from a Compliance Radar nexus-threshold rule's revenue sum in the US states that exclude marketplace-facilitated sales from the seller's own economic-nexus threshold. Does not change the calculated tax itself. Omit (or false) for a direct sale.
transactionType"invoice" | "credit_note"Optional
Default: "invoice". Set to "credit_note" when issuing a credit note against a prior invoice. The engine negates all line item amounts before calculation. See Credit Notes & Refunds.
relatedCalculationIdstringConditional
The calculationId of the original invoice being reversed. Required when transactionType is "credit_note" and the resolved commit is true (the default, unless you send commit: false) — omitting both fields on a credit note now returns a 422. The referenced calculation must belong to the same entity. Maximum 50 characters.
transactionDirection"sale" | "purchase"Optional
Default: "sale". Set to "purchase" for an incoming, input-tax transaction — see Purchase Mode below.
clientTaxCodestringOptional
Your own ERP tax code (e.g. a SAP two-digit code) for the whole invoice, forward-resolved against your own configured client tax codes and applied to every line lacking its own lineItems[].clientTaxCode/taxCode/taxTreatmentOverride. An unresolvable code rejects the whole calculation as one atomic 422.

Customer object

customer is the buyer on a sale (required, otherwise 422 CUSTOMER_REQUIRED). On a purchase it is your own business and can be omitted. Its shape:

customer object
{
  "customer": {
    "billingAddress": { "country": "US", "region": "CA", "postalCode": "94105" },
    "shippingAddress": { "country": "US", "region": "NY", "postalCode": "10001" },
    "taxId": "DE987654321",
    "b2bOverride": false,
    "exemptionRef": "cert-2026-0042",
    "ref": "crm-1001"
  }
}

Address fields are listed under addresses below; customer has no plain address field.

customerobjectRequired Yes, for a "sale" — optional for a "purchase"
The counterparty on a sale (required — 422 CUSTOMER_REQUIRED if missing). On a "purchase", this is instead your own entity: 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 Purchase Mode. This object has no plain address field on this endpoint — use billingAddress/shippingAddress below.
customer.billingAddress.countrystringRequired
ISO 3166-1 alpha-2 country code of the customer's billing address — the primary jurisdiction signal for B2B and most B2C transactions.
customer.billingAddress.regionstringRequired Yes (US)
State code (e.g. "CA", "TX"). Required whenever the resolved country is "US" — no country-level US rate exists. For Canada, optional; supply the province code for accurate provincial rate lookup.
customer.billingAddress.postalCodestringOptional
Used for special-territory detection — e.g. Canary Islands postal codes (35xxx–38xxx) are treated as outside the EU VAT area despite an ES country code.
customer.shippingAddressobjectOptional
Same shape as billingAddress. Takes precedence over billingAddress for physical goods when both are supplied.
customer.taxIdstringOptional
Customer's VAT number. When supplied, Clearvo verifies it against VIES and applies B2B treatment — reverse charge, intra-community zero-rating, or export zero-rating — based on the seller and buyer locations.
customer.b2bOverridebooleanOptional
When true, applies B2B treatment immediately without requiring a VAT number. Use when the buyer is a known business but their VAT ID is not available at request time.
customer.exemptionRefstringOptional
Reference (certificate_ref) to an exemption certificate stored in Clearvo ECM. Applies the exemption to eligible line items when an active matching certificate exists.
customer.refstringOptional
Your own reference for this customer (e.g. CRM ID). Does not resolve any stored customer master data — it only auto-looks up active ECM exemption certificates for this customer and applies them to eligible US line items. Contrast supplier.ref above, which on a purchase does fill name/taxId/address from the Suppliers master.
ℹ
A type field on customer (e.g. "B2B") is not read by this endpoint. Use b2bOverride and/or taxId instead.

Supplier object

supplier is the seller. On a sale it is optional: when omitted it is filled in from your business profile's registered address and tax number. On a purchase it is the vendor and is required (422 SUPPLIER_REQUIRED; see Purchases). Its shape:

supplier object
{
  "supplier": {
    "name": "Acme Inc.",
    "billingAddress": { "country": "US", "region": "TX", "postalCode": "78701" },
    "taxId": "...",
    "ref": "vendor-77"
  }
}
supplierobjectRequired Yes, for a "purchase" — optional for a "sale"
The actual vendor on a purchase (required — 422 SUPPLIER_REQUIRED if missing; see Purchase Mode for its field meanings there). On a "sale", this is instead your own entity: 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 SUPPLIER_TAX_ID_MISMATCH on a mismatch).
supplier.billingAddress.countrystringRequired Yes, if supplier is sent
ISO 3166-1 alpha-2 country code of the supplier's address — on a purchase, the vendor's; on a sale, your own entity's registered address.
supplier.taxIdstringOptional
On a purchase, the vendor's VAT number/tax ID — used to determine reverse-charge/import treatment. On a sale, validated against the entity's own registered tax IDs (see above).
supplier.namestringOptional
Free-text display name, informational only.
supplier.refstringOptional
Purchase only. Your own reference for this vendor (e.g. ERP vendor ID) — resolves saved supplier master data (POST/GET /suppliers), filling in name/taxId/billingAddress you omit here (explicit fields win). A ref that does not resolve to a saved supplier of this entity returns 422 SUPPLIER_REF_NOT_FOUND. Ignored when supplier is the entity side (a sale).

Ship-from, ship-to and shipment details

shipFrom.countrystringOptional
Physical dispatch country for goods, when different from supplier.billingAddress.country. Relevant to Art. 138 (intra-Community) vs. Art. 146 (export) classification for cross-border goods.
shipFrom.region, shipFrom.postalCodestringOptional
State and ZIP code of the dispatch address. For a US dispatch, region decides the rate on in-state sales in Texas, California and Illinois (local tax is sourced to the seller's own location there). When you omit it, the state (and ZIP code, if none sent) of your own business address is used. The address used is echoed on the response as shipFrom, shipFromRegion and shipFromPostalCode.
shipToobjectOptional
Physical receiving address, same shape as shipFrom. Accepted, persisted, and echoed back — not yet used to determine the tax result for either sale or purchase. customer.shippingAddress remains the field jurisdiction resolution actually consumes for a sale.
incotermsstringOptional
Incoterms® 2020 rule for the shipment (e.g. "DDP", "EXW"). Does not gate IOSS eligibility: IOSS applies whenever ship-from is non-EU, destination is EU, and value is ≤€150, regardless of the incoterms supplied. Above that threshold, this determines who is liable for import VAT: omitting it, or supplying "DDP" (seller is importer of record), leaves the ordinary registration-based treatment unchanged. Any other value — EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU (buyer is importer of record) — makes that line outside the scope of Clearvo tax calculation (taxCode: "O", tax charged: 0). Never affects B2B transactions.
importerOfRecord"SELLER" | "BUYER"Optional
Explicit override for who is the importer of record. Accepted, persisted, and echoed back — contract-only in this release, not yet consumed by jurisdiction/treatment resolution.
shipFrom.customsStatus"free_circulation" | "bonded"Optional
Read only when duties are requested. "bonded" marks stock held under customs control, so leaving it is a customs crossing even within one territory. Also accepted on a per-line shipFrom.
insuranceobjectOptional
{ amount, currency? }. Consignment insurance, a customs-value component under CIF. Read only when duties are requested.
dutiesobjectOptional
{ include, collectDeposit?, defaultCountryOfOrigin?, ratePolicyForHs6? }. Estimated import duty, import VAT/GST and customs fees. include overrides the account dutiesEnabled setting either way. Never changes a tax figure. See Customs duties and landed cost and POST /v1/duties/quote.
ℹ
On every address object (supplier.billingAddress, customer.billingAddress/shippingAddress, shipFrom, shipTo) country, region, and postalCode determine the jurisdiction and the rate. For a US address, line1, line2, and city are also sent to the address check, which finds the ZIP+4 for rooftop-precision rates (see the precision tiers below); without a street the rate is ZIP-level. Outside the US they never influence the tax. A committed calculation keeps the request as sent, including city and street lines, for as long as the calculation needs them. They are removed only on request: POST /v1/tax/address-erasure (or the erase_customer_address_data MCP tool) takes a calculationId or the order reference, removes the address lines and the customer display name (at level: "full" also the city), and leaves the amounts, tax, jurisdiction, region, postal code and country untouched. Repeating it changes nothing.

Evidence

evidence.ipAddressstringOptional
Customer's IP address — a top-level object, not nested under customer. Used as a secondary jurisdiction signal for B2C digital services under the EU 2-of-3 evidence rule (CIR (EU) 282/2011 Art. 24b/24f).
evidence.binCountrystringOptional
ISO country code derived from the customer's card BIN. Used as a third corroborating signal under the same 2-of-3 rule. Advanced/payment-processor use only.

Line items

lineItems[].idstringRequired
Your identifier for this line item. Echoed back in the response.
lineItems[].amountnumberRequired
Line item amount in the transaction currency. Whether this is tax-exclusive or tax-inclusive is resolved by lineItems[].amountIncludesTax if set, else the product's own configured pricing, else your account's defaultPriceIncludesTax setting (Account Settings) — exclusive by default for a US-resolved line regardless of your account setting, inclusive by default everywhere else.
lineItems[].quantitynumberOptional
Default: 1. Informational only — amount should already be the total line amount, not a per-unit price.
lineItems[].productNamestringOptional
Plain-language product name, max 200 characters. Used to classify the product when no explicit taxCategory is supplied and none of the classificationCodes map. Not required — an omitted name with no other classification signal falls back to a generic goods category (see Product Classification).
lineItems[].productDescriptionstringOptional
Additional descriptive text, max 500 characters, stored for your records only.
lineItems[].productCodestringOptional
Your own product/SKU code, max 40 characters, stored for your records and used to key the per-account classification cache.
lineItems[].amountIncludesTaxbooleanOptional
Explicitly marks this line's amount as tax-inclusive (true) or tax-exclusive (false), for every jurisdiction including the US. Omit to fall through to the account's defaultPriceIncludesTax setting.
lineItems[].taxCategorystringOptional
Explicit product category slug, skipping catalogue lookup entirely (e.g. "digital-services", "books"). See Product Classification for available slugs.
lineItems[].classificationCodesarrayOptional
Up to 5 outside product codes for this line, each { "system": "stripe" | "shopify" | "hs" | …, "code": "…" }. Tried in the order given; the first one that maps to a tax category is authoritative, ahead of the per-account product catalogue lookup. system is lowercase letters, digits or underscore (1–30 characters). See Product Classification for how the code map works.
lineItems[].taxCodestringOptional
EN16931 escape hatch — directly forces the output taxCode for this line. Rare; prefer taxTreatmentOverride or clientTaxCode.
lineItems[].discountnumberOptional
Reduces the taxable base: taxableAmount = amount − discount.
lineItems[].discountAmountnumberOptional
Audit-trail/display only — stored verbatim, never affects taxableAmount/taxAmount. Distinct from discount above, which does reduce the taxable base.
lineItems[].exemptbooleanOptional
Claims exemption for this line. If no active ECM certificate matches, a PENDING_CERTIFICATE record is created (see pendingCertificates[] in Response Reference) — you remain liable until it's substantiated.
lineItems[].taxTreatmentOverridestringOptional
Caller-forced rate band — one of STANDARD, MIDDLE, REDUCED, SUPER_REDUCED, SPECIAL, ZERO, EXEMPT. A band only, never a raw percentage. Rejected (422) for a US-resolved line except ZERO/EXEMPT — see Commodity & Tariff Classification for the full precedence contract.
lineItems[].commodityCodestringOptional
Tariff/customs classification code (HS/CN/UK Trade Tariff). Two uses: (1) may set this line's rate band, consulted only when taxTreatmentOverride is absent; (2) on an IOSS-treated calculation, drives the response's customsDuty object regardless of any override — lines sharing the same normalised classification count as one duty item. See Commodity & Tariff Classification.
lineItems[].commodityCodeScheme"HS6" | "CN8" | "TARIC10" | "UK10" | "HTS10"Optional
Scheme of this line's commodityCode, read only when duties are requested. Omitted: inferred from the digit count and the destination. Not the rules-engine fact customProperties.commodityCodeScheme.
lineItems[].countryOfOriginstringOptional
ISO 3166-1 alpha-2 country the goods were made in, read only when duties are requested. Never inferred from shipFrom.
lineItems[].weightobjectOptional
{ value, unit } (kg, g, lb, oz), per unit; the line weight is value × quantity. Read only when duties are requested.
companyCodestringOptional
Enterprise only. A division of the entity, such as an SAP company code (max 50 characters, matched without regard to case). Omitted: the entity's default company code, else none. An unknown or archived code is 422 company_code_unknown before anything is calculated; a code that is not valid on the transaction's own invoice or tax-point date (outside its validFrom/validTo window) is 422 company_code_not_valid_on_date, while an entity default outside its window is simply not applied; a plan without company codes is 403 company_codes_not_included. When a code resolved or the entity uses company codes, the response echoes companyCode and companyCodeSource (request, entity_default or none), and company-code rules fire only for it. Manage codes with GET/POST /v1/company-codes and PATCH /v1/company-codes/{id} (optional validFrom/validTo dates, YYYY-MM-DD, both inclusive, null = no limit; validTo must not be before validFrom); set the default with defaultCompanyCode in PATCH /v1/tax/settings.
lineItems[].clientTaxCodestringOptional
Your own ERP tax code for this line only — wins over the invoice-header clientTaxCode for this line specifically.
lineItems[].shippingCarrier"common" | "seller_vehicle"Optional
US shipping_handling lines only, ignored elsewhere. Omitted resolves conservatively to "seller_vehicle" — there is deliberately no request-level default that would grant an unattested carrier-conditioned exemption. If you have set a default shipping rule (the default_shipping_carrier template) it fills an omitted value first; a value on the line always wins and the shipping rules always decide.
lineItems[].chargeAvoidablebooleanOptional
US shipping_handling lines only. Whether the customer could have avoided this shipping charge (e.g. in-store pickup). Omitted resolves conservatively to false, unless your default shipping rule fills it.
lineItems[].actualCostOfShipmentbooleanOptional
US shipping_handling lines only. Whether the charge passes through your actual shipment cost rather than a flat/marked-up fee. Omitted resolves conservatively to false, unless your default shipping rule fills it.
ℹ
Request limits. The request body must be under 512KB (524288 bytes); a larger body is rejected with 413 and { "error": "Request body too large", "hint": "Body must be under 524288 bytes." }. Line item string fields are capped: lineItems[].id at 200 characters, taxCategory and taxCode at 100 characters each, and commodityCode at 40 characters.

Examples

A recorded calculation (the default, commit not sent), a preview (commit: false) and a full request using every common field.

curl — recorded (commit omitted)
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 — preview (commit: false)
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):

JSON — full request shape
{
  "currency": "EUR",
  "taxReportingCurrency": "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"
    }
  ]
}

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

Enterprise only. Purchase mode (transactionDirection: "purchase"), the purchase_order documentStage, the direction=purchase and documentStage=purchase_order filters on GET /v1/tax/calculate, the Coupa Tax Call Out, and the AP-only supplier fields (trusted, toleranceOverride) and settings (apTolerance, apPoDisposition) are the Purchases (AP) sub-solution of Tax Calculations. It needs the Enterprise plan and Purchases (AP) switched on for the business under Settings > Solutions (Tax Calculations must be on first). Without the Enterprise plan the API answers 403 ap_not_included (with an upgradeUrl); on Enterprise with the switch off it answers 403 ap_not_enabled (with a hint). Sales calculations are never affected, and nothing stored is deleted if a plan changes.

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 delivered to a US state that is not enabled for use tax is rejected as 422 us_jurisdiction_purchase_unsupported (the whole calculation); a purchase delivered to an enabled state is calculated as US consumer's use tax, see US consumer's use tax; 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).

US consumer's use tax (purchases)

A purchase delivered to a US state enabled for use tax is calculated as consumer's use tax. Send where the goods or service are delivered in shipTo (request level) or lineItems[].shipTo (per line, wins); a US address needs region. With neither, your own entity address is used and the line says so (assumptions contains USE_LOCATION_ASSUMED_ENTITY_ADDRESS, useLocation.basis is ENTITY_ADDRESS). A shipTo in your own country refines a goods line's destination; a shipTo in any other country is not used and the response warns with ship_to_country_not_supported. A purchase with no shipTo is unchanged.

Each such line returns lineItems[].useTax: useLocation, taxDueAtUseLocation (also the line's taxAmount), taxChargedByVendor (your statedTaxAmount), taxExpectedFromVendor, creditAllowed, selfAssessedTaxAmount, toleranceWaived, a per-authority breakdown (state first; taxDue, creditApplied, selfAssessed), assumptions, vendorChargeStory and reviewRequired. The response header carries selfAssessedTaxAmount and selfAssessedKind: "USE_TAX"; both are stored and returned on list and detail and in Explore.

  • Use tax is owed on the delivery state's use rates. Illinois and Iowa have no local use tax on general purchases, so only the state rate applies; Nebraska, Minnesota and Texas include the local rates.
  • The vendor's charge is compared with the sales tax at the delivery address. Tax charged for the delivery state is credited and only the shortfall is self-assessed. A vendor that charged 0 is self-assessed in full. A charge that matches another state's rate, or none of the known cases, earns no credit: the full use tax is self-assessed and reviewRequired is true. The trusted supplier flag does not apply to use tax. A correct charge by an in-state vendor at its own location's rate (Illinois, Texas), or by a Texas remote seller at the single flat local rate, is not an overcharge.
  • On an invoice without a statedTaxAmount the vendor is assumed to have charged 0 (assumptions contains VENDOR_TAX_NOT_PROVIDED_ASSUMED_ZERO) and the usual verification runs. On a purchase_order no such assumption or verification is made: you get the expected use tax.
  • All use tax is self-assessed by default. A rule from the us_use_tax_tolerance template can waive small amounts (toleranceWaived).
  • Use tax is not recoverable: recoverability.allocationSource is US_USE_TAX_NOT_RECOVERABLE and blockedAmount is the self-assessed amount. taxVerification.outcome: UNDERCHARGED with reason USE_TAX_SELF_ASSESSED or USE_TAX_SHORTFALL_SELF_ASSESSED means you accrue the tax; the ap.decision webhook does not fire for these.
  • Buyer exemptions (certificates, intended use, direct-pay permits) are not applied: the purchase is taxable under the item's normal rules. Return filing is not part of this release; Explore (selfAssessedKind = USE_TAX, jurisdictionRegion, useTax) is the extract.
curl — purchase mode
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
      }
    ]
  }'
transactionDirection"purchase"Required Yes, to enter purchase mode
Persisted verbatim. Also narrows which of your client_tax_codes rows can reverse-match this calculation's lines to direction purchase (or direction-less) rows only.
supplierobjectRequired Yes, for "purchase" (optional, entity-side, for "sale")
The actual vendor on the purchase invoice — same shape as customer (name, taxId, billingAddress). taxId and billingAddress.country are the supplier's VAT ID and country; shippingAddress/b2bOverride/exemptionRef carry no meaning here and are ignored. ref resolves saved supplier master data (see GET/POST /suppliers), filling in any fields you omit here — an unresolvable ref returns 422 SUPPLIER_REF_NOT_FOUND. Unlike supplier.ref, customer.ref on a sale never resolves stored master data — it only auto-applies ECM exemption certificates.
lineItems[].supplyType"GOODS" | "SERVICES"Optional No (but see note)
Purchase-only; ignored for a sale line. A purchase line with no supplyType still returns a full computed treatment/rate, but is flagged lineItems[].outcome: { status: "UNKNOWN_TREATMENT", reasonCode: "missing_supply_type" } — see Response Reference.
lineItems[].recoverablePercentOverridenumber, 0–100Optional
Purchase-only; ignored for a sale line. Manual override of the recoverable share of this line's input tax (VAT Directive Art. 173–175 partial-exemption split) — a 0–100 percentage, not a 0–1 fraction. When supplied, wins over whatever recoverability your configured client tax code carries. Affects only the reported recoverable/blocked split, never the tax amount charged.
lineItems[].statedTaxAmountnumberOptional
Purchase-only; ignored for a sale line. The tax amount your supplier actually charged on their invoice, in decimal units. When supplied, Clearvo independently computes the legally-due tax and returns a verdict (MATCH/OVERCHARGED/UNDERCHARGED) rather than trusting the invoice at face value — see lineItems[].taxVerification in Response Reference. Skipped (no verdict computed, never defaulted to MATCH) for a genuine border-paid import line, where the real import-VAT base is customs value + duty + freight, not this line's invoice net.
lineItems[].glAccountstring, max 50Optional
Purchase-only. The general-ledger account this line is booked to. Free text. Rules can read and write it as glAccount; echoed on the response line after rules have run.
lineItems[].costCenterstring, max 50Optional
Purchase-only. The cost centre this line is booked to. Free text. Rules can read and write it as costCenter; echoed on the response line.
lineItems[].intendedUsestring, max 100Optional
Purchase-only. What you intend to use the goods or services for, free text (for example resale, manufacturing, raw material). Used to match a certificate you hold from the supplier to the line. Echoed on the response line.
lineItems[].accountAssignment"stock" | "expense" | "asset" | "project"Optional
Purchase-only. How the line is assigned in your books. A raw ERP code (a SAP account assignment category letter such as K, A or P, or a Coupa account type such as capital) is also accepted and mapped onto these four; a code with no mapping is dropped and the AP_ACCOUNT_ASSIGNMENT_UNKNOWN warning fires. The response always echoes one of the four. stock marks a resale line for certificate matching.

glAccount, costCenter, intendedUse and accountAssignment are regular line fields, not custom properties. Sending any of them, or commodityCode or commodityCodeScheme, inside customProperties is a 400 with code: "BUILT_IN_PROPERTY_AS_CUSTOM", and the message names the flat field to send instead (for example lineItems[1].glAccount). Use customProperties only for data that Clearvo's schema does not already have.

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.

ℹ
Precedence, highest first. (1) taxTreatmentOverride — a caller-forced band, honoured for the line's resolved jurisdiction (with one exception — see below). (2) commodityCode — consulted for rate-band purposes only when taxTreatmentOverride is absent, but always consulted for customsDuty item counting on an IOSS-treated line, regardless of taxTreatmentOverride. (3) The ordinary rate-band lookup described in Tax Treatments (explicit country/region rate research, then an EU/US/global scoped default, then the STANDARD floor).

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.

ℹ
Not supported for US lines. STANDARD, MIDDLE, REDUCED, SUPER_REDUCED, and SPECIAL have no meaning for a line that resolves to a US jurisdiction — US sales tax is a single combined state/county/city/district percentage per address, not a VAT-style banded rate table. Sending one of these five values on a US line returns a 422 us_tax_treatment_override_unsupported error rather than silently applying the ordinary calculated rate. ZERO and EXEMPT are rate-independent and work identically for every jurisdiction, including the US.

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 — commodity code override
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

ℹ
422 vs 400. Clearvo uses 422 Unprocessable Entity for request bodies that are valid JSON but fail field-level validation (missing fields, wrong types, constraint violations). The error field in the response body identifies the failing field and reason — e.g. "customer: Required" or "merchantRef: String must contain at most 100 character(s)". Fix the field named in error to resolve it. 400 Bad Request is reserved for scope-level errors (e.g. using an account-scoped key on an entity-only endpoint).
HTTPWhen it occursHow to fix
422Missing required field (customer, lineItems, currency, or a line item id / amount)Check the error field — it names the failing path (e.g. "customer: Required"). Add the missing field.
422currency is not exactly 3 characters, or lineItems is an empty array or exceeds 100 itemsSupply a valid ISO 4217 currency code (e.g. "EUR") and between 1 and 100 line items. For larger carts, split into multiple calculate calls.
422merchantRef exceeds 100 characters, lineItems[].productCode exceeds 40, lineItems[].productName exceeds 200, or lineItems[].productDescription exceeds 500Truncate the field to its limit.
422customer.billingAddress.region (or shippingAddress.region) is missing when country is "US"Supply the state code (e.g. "CA", "TX"). No country-level US tax rate exists — state is mandatory for all US addresses.
400An account-scoped key was used without an X-Entity-Id headerAdd X-Entity-Id: <entityId> to identify the target entity, or use an entity-scoped key.
403The entity in X-Entity-Id does not belong to this accountCheck that the entity ID belongs to the account associated with this API key.
401The x-api-key header is missing or the key is unrecognisedInclude a valid x-api-key header on every request.
409idempotency_key_in_progress — a previous request with this idempotencyKey is still being processed (only reachable when the resolved commit is true)Retry shortly. There is no request-body comparison on replay: once the first request for a key completes, every later request with the same key replays its stored response verbatim, whatever body it sends. Use a fresh key for a genuinely different transaction.
422transactionType is "credit_note", the resolved commit is true (explicit or the default), but relatedCalculationId is absentSupply the calculationId of the original invoice in relatedCalculationId, or send "commit": false if you only meant to preview the credit note amount.
422relatedCalculationId is provided but the referenced calculation does not exist or belongs to a different entityVerify the ID — it must be a recorded calculation for this entity. Preview (uncommitted) calculations are not valid targets.
422A country is not a valid ISO 3166-1 alpha-2 code (for example XX, Narnia or UK) — error: "invalid_country", code: "INVALID_COUNTRY", with field naming the offending request path (for example customer.shippingAddress.country), value (what you sent), message and hint. A valid country we do not support is not a 422: it returns 200 (see Unsupported jurisdiction).Fix the country value in the field the error names and resend. Use ISO 3166-1 alpha-2 codes (GB, not UK).
Tax Calculations

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 — credit note
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.

⚠
relatedCalculationId is required whenever a credit note is recorded. That includes a credit note where commit was simply omitted — the default is now true, so an omitted commit with no relatedCalculationId now fails with 422 where it previously succeeded as an unrecorded preview. Fix it either of two ways: supply relatedCalculationId (it must reference a previously recorded invoice calculation belonging to the same entity — a preview/uncommitted calculation cannot be referenced), or send "commit": false if you only meant to preview the credit note amount.

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 — refund
curl https://api.clearvo.io/v1/tax/calculate/cl_calc_01j4.../refund \
  -X POST \
  -H "x-api-key: csk_live_..."
JSON Response
{
  "ok": true,
  "calculationId": "cl_calc_01j4...",
  "refundedAt": "2026-06-24T10:30:00.000Z"
}

Error responses

HTTPWhen it occursHow to fix
404The calculation does not exist or belongs to a different entityCheck that the ID is correct and the API key is for the entity that owns this calculation.
409The calculation has already been marked as refundedNo action needed — the refund was already processed. The response body includes the original refundedAt timestamp.
422The calculation is a sandbox calculationSandbox calculations cannot be marked as refunded — they never count toward usage or compliance thresholds in the first place.
422The calculation is a credit note (not an invoice)Credit notes cannot be refunded. If the credit note was issued in error, issue a correcting invoice instead.

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.