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.
{
"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_notethat is recorded needsrelatedCalculationId, otherwise the call fails with422. - With a recorded call, a repeated
idempotencyKeythat is still in flight returns409, 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"EUR", "USD", "GBP"). Exactly 3 characters. (Request-only — there is no top-level currency field on the response; see Response Reference.)taxReportingCurrencystringOptionalcurrency is the transaction's local currency. Adds taxReporting to the response (see Response Reference).datestringOptionalresolvedAt), 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.commitbooleanOptionaltrue. 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.idempotencyKeystringOptionalcommit 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"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"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.merchantRefstringOptionalpaymentMethod"card" | "bank_transfer" | "digital_wallet" | "cash" | "other"OptionalisMarketplaceFacilitatedSalebooleanOptionalfalse) for a direct sale.transactionType"invoice" | "credit_note"Optional"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.relatedCalculationIdstringConditionalcalculationId 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"sale". Set to "purchase" for an incoming, input-tax transaction — see Purchase Mode below.clientTaxCodestringOptionallineItems[].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": {
"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"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.countrystringRequiredcustomer.billingAddress.regionstringRequired Yes (US)"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.postalCodestringOptionalcustomer.shippingAddressobjectOptionalbillingAddress. Takes precedence over billingAddress for physical goods when both are supplied.customer.taxIdstringOptionalcustomer.b2bOverridebooleanOptionaltrue, 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.exemptionRefstringOptionalcertificate_ref) to an exemption certificate stored in Clearvo ECM. Applies the exemption to eligible line items when an active matching certificate exists.customer.refstringOptionalsupplier.ref above, which on a purchase does fill name/taxId/address from the Suppliers master.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": {
"name": "Acme Inc.",
"billingAddress": { "country": "US", "region": "TX", "postalCode": "78701" },
"taxId": "...",
"ref": "vendor-77"
}
}
supplierobjectRequired Yes, for a "purchase" — optional for a "sale"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 sentsupplier.taxIdstringOptionalsupplier.namestringOptionalsupplier.refstringOptionalPOST/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.countrystringOptionalsupplier.billingAddress.country. Relevant to Art. 138 (intra-Community) vs. Art. 146 (export) classification for cross-border goods.shipFrom.region, shipFrom.postalCodestringOptionalregion 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.shipToobjectOptionalshipFrom. 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"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"OptionalshipFrom.customsStatus"free_circulation" | "bonded"Optional"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.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.ipAddressstringOptionalcustomer. 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.binCountrystringOptionalLine items
lineItems[].idstringRequiredlineItems[].amountnumberRequiredlineItems[].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[].quantitynumberOptionalamount should already be the total line amount, not a per-unit price.lineItems[].productNamestringOptionaltaxCategory 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[].productDescriptionstringOptionallineItems[].productCodestringOptionallineItems[].amountIncludesTaxbooleanOptionalamount 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"digital-services", "books"). See Product Classification for available slugs.lineItems[].classificationCodesarrayOptional{ "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[].taxCodestringOptionaltaxCode for this line. Rare; prefer taxTreatmentOverride or clientTaxCode.lineItems[].discountnumberOptionaltaxableAmount = amount − discount.lineItems[].discountAmountnumberOptionaltaxableAmount/taxAmount. Distinct from discount above, which does reduce the taxable base.lineItems[].exemptbooleanOptionalPENDING_CERTIFICATE record is created (see pendingCertificates[] in Response Reference) — you remain liable until it's substantiated.lineItems[].taxTreatmentOverridestringOptionalSTANDARD, 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[].commodityCodestringOptionaltaxTreatmentOverride 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"OptionalcommodityCode, read only when duties are requested. Omitted: inferred from the digit count and the destination. Not the rules-engine fact customProperties.commodityCodeScheme.lineItems[].countryOfOriginstringOptionalshipFrom.lineItems[].weightobjectOptional{ value, unit } (kg, g, lb, oz), per unit; the line weight is value × quantity. Read only when duties are requested.companyCodestringOptional422 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[].clientTaxCodestringOptionalclientTaxCode for this line specifically.lineItems[].shippingCarrier"common" | "seller_vehicle"Optionalshipping_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[].chargeAvoidablebooleanOptionalshipping_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[].actualCostOfShipmentbooleanOptionalshipping_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.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 https://api.clearvo.io/v1/tax/calculate \
-X POST \
-H "x-api-key: csk_live_..." \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"idempotencyKey": "order-abc-123",
"supplier": {
"billingAddress": { "country": "IE" },
"taxId": "IE1234567T"
},
"customer": {
"taxId": "DE987654321",
"billingAddress": {
"country": "DE",
"postalCode": "10115"
}
},
"lineItems": [
{
"id": "line-1",
"amount": 500.00,
"quantity": 5,
"productName": "Enterprise software licence",
"taxCategory": "digital-services"
},
{
"id": "line-2",
"amount": 120.00,
"quantity": 2,
"productName": "Printed user manual"
}
],
"vatUnverifiableFallback": "conservative"
}'
curl https://api.clearvo.io/v1/tax/calculate \
-X POST \
-H "x-api-key: csk_live_..." \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"commit": false,
"customer": {
"billingAddress": { "country": "DE" }
},
"lineItems": [
{ "id": "cart-line-1", "amount": 500.00, "productName": "Enterprise software licence" }
]
}'
The preview response has the identical shape (same jurisdiction, taxTreatment, lineItems fields) but "committed": false — nothing is persisted, and it makes no contribution to your Compliance Radar totals. idempotencyKey has no effect on a preview call — it is only ever consulted when the resolved commit is true.
Full field-by-field shape, for reference (every field on the single-item schema — not every field would appear together on a real call):
{
"currency": "EUR",
"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
0is 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 andreviewRequiredis 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
statedTaxAmountthe vendor is assumed to have charged 0 (assumptionscontainsVENDOR_TAX_NOT_PROVIDED_ASSUMED_ZERO) and the usual verification runs. On apurchase_orderno 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_tolerancetemplate can waive small amounts (toleranceWaived). - Use tax is not recoverable:
recoverability.allocationSourceisUS_USE_TAX_NOT_RECOVERABLEandblockedAmountis the self-assessed amount.taxVerification.outcome: UNDERCHARGEDwith reasonUSE_TAX_SELF_ASSESSEDorUSE_TAX_SHORTFALL_SELF_ASSESSEDmeans you accrue the tax; theap.decisionwebhook 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 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 modeclient_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")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)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–100OptionallineItems[].statedTaxAmountnumberOptionalMATCH/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 50OptionalglAccount; echoed on the response line after rules have run.lineItems[].costCenterstring, max 50OptionalcostCenter; echoed on the response line.lineItems[].intendedUsestring, max 100Optionalresale, 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"OptionalK, 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.
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.
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 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 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).| HTTP | When it occurs | How to fix |
|---|---|---|
| 422 | Missing 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. |
| 422 | currency is not exactly 3 characters, or lineItems is an empty array or exceeds 100 items | Supply a valid ISO 4217 currency code (e.g. "EUR") and between 1 and 100 line items. For larger carts, split into multiple calculate calls. |
| 422 | merchantRef exceeds 100 characters, lineItems[].productCode exceeds 40, lineItems[].productName exceeds 200, or lineItems[].productDescription exceeds 500 | Truncate the field to its limit. |
| 422 | customer.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. |
| 400 | An account-scoped key was used without an X-Entity-Id header | Add X-Entity-Id: <entityId> to identify the target entity, or use an entity-scoped key. |
| 403 | The entity in X-Entity-Id does not belong to this account | Check that the entity ID belongs to the account associated with this API key. |
| 401 | The x-api-key header is missing or the key is unrecognised | Include a valid x-api-key header on every request. |
| 409 | idempotency_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. |
| 422 | transactionType is "credit_note", the resolved commit is true (explicit or the default), but relatedCalculationId is absent | Supply the calculationId of the original invoice in relatedCalculationId, or send "commit": false if you only meant to preview the credit note amount. |
| 422 | relatedCalculationId is provided but the referenced calculation does not exist or belongs to a different entity | Verify the ID — it must be a recorded calculation for this entity. Preview (uncommitted) calculations are not valid targets. |
| 422 | A 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). |
Credit Notes & Refunds
Clearvo supports two distinct patterns for reversing a committed transaction, chosen based on how your billing or ERP system models reversals.
Credit notes (B2B / ERP path)
ERP systems such as SAP, NetSuite, and Oracle issue a formal credit note document when a sale is reversed. Submit this as a new calculation with transactionType: "credit_note". Clearvo negates all line item amounts before the calculation pipeline runs — the same jurisdiction, treatment, and rate logic applies unchanged, but every amount comes out negative. This keeps the credit note fully audit-traceable as its own document with its own calculationId.
curl https://api.clearvo.io/v1/tax/calculate \
-X POST \
-H "x-api-key: csk_live_..." \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"transactionType": "credit_note",
"relatedCalculationId": "cl_calc_01j4...",
"supplier": { "billingAddress": { "country": "IE" }, "taxId": "IE1234567T" },
"customer": {
"taxId": "DE987654321",
"billingAddress": { "country": "DE" }
},
"lineItems": [
{
"id": "line-1",
"amount": 500.00,
"amountIncludesTax": false,
"productName": "Enterprise software licence"
}
]
}'
The response is identical in shape to a regular calculation — all amounts are negative (e.g. taxableAmount: -500.00, taxAmount: -95.00). The response includes transactionType: "credit_note" and relatedCalculationId.
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 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
| HTTP | When it occurs | How to fix |
|---|---|---|
| 404 | The calculation does not exist or belongs to a different entity | Check that the ID is correct and the API key is for the entity that owns this calculation. |
| 409 | The calculation has already been marked as refunded | No action needed — the refund was already processed. The response body includes the original refundedAt timestamp. |
| 422 | The calculation is a sandbox calculation | Sandbox calculations cannot be marked as refunded — they never count toward usage or compliance thresholds in the first place. |
| 422 | The 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.