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

Response Reference

Full field reference for the TaxCalculateResponse object returned by the calculation endpoint.

Top-level fields

calculationIdstring
Unique ID for this calculation (cl_calc_* prefix, cl_calc_test_* in sandbox). Present whether the calculation was recorded or previewed.
entityIdstring
The entity (fiscal identity) that processed this calculation. Confirms which entity-scoped API key was used — useful for Merchant of Record setups where multiple entities share an account.
apiVersionstring
Always "v1" today. The X-Clearvo-Api-Version request header, if you sent one, is echoed back as a response header (not in this body field) — no request behaviour currently branches on it.
resolvedAtstring
ISO 8601 timestamp of when this calculation actually ran. For a recorded calculation, this — not the request's own optional date field — is what windows it into a Compliance Radar threshold period.
sandboxboolean
True when the request was made with a csk_test_* key. A sandbox calculation never counts toward usage or Compliance Radar totals, whatever committed below is.
committedboolean
Whether the resolved commit was true for this calculation — true for a recorded calculation, false for a preview. Since commit defaults to true (2026-09-12), this is the field to check if you need to confirm synchronously whether a given call was actually persisted, without inferring it from whether you happened to send commit yourself.
merchantRefstring
Echoes the request's merchantRef, when supplied.
paymentMethodstring
Echoes the request's paymentMethod, when supplied.
incotermsstring
Echoes the request's incoterms, when supplied.
taxTreatmentstring
The tax treatment applied to the transaction as a whole. See Tax Treatments for all possible values and their meanings. The effective rate and rate band are returned per line item (lineItems[].rate below), not here — a single calculation can span multiple bands when its lines fall into different categories.
taxCodestring
EN16931 tax code for the transaction as a whole: S, AA, AE, E, K, G, Z, or O.
transactionType"invoice" | "credit_note"
Echoed from the request (defaults to "invoice"). Credit note responses have negative amounts on all line items and totals.
relatedCalculationIdstring | undefined
The calculationId of the original invoice this credit note reverses. Only present when transactionType is "credit_note" and the field was provided in the request.
refundedAtstring | undefined
ISO 8601 timestamp. Set when POST /v1/tax/calculate/{id}/refund has been called. Absent for non-refunded calculations.
totalTaxnumber | undefined
Top-level convenience alias for summary.totalTax below.
degradedboolean | undefined
True when the engine encountered a partial failure (e.g. rate service timeout, VIES unreachable). The calculation still succeeds but a fallback rate may have been used.
degradedReasonstring | undefined
Human-readable explanation of why the result is degraded. Only present when degraded: true.
staleCacheReasonstring | undefined
Present only when degraded was caused specifically by a rate-service outage papered over with a static backup rate rather than left at 0% — a machine-readable sub-cause of degradedReason (e.g. "cch_unavailable_using_state_fallback").
taxReportingobject | undefined
Present only when the request supplied taxReportingCurrency: { currency, taxTotal, total, fxRate, fxRateAsOf } — the same totals converted into that currency.
jurisdictionBreakdownarray | undefined
Present only when the resolved jurisdiction has a multi-level tax structure (e.g. a US state + county + city + district stack). Each entry: { name, level, rate, taxableAmount, taxAmount }.
lineItems[].jurisdictionBreakdownarray | undefined
Every taxed line, in every jurisdiction: the line tax split into components, each { level, name, taxType, rate, taxAmount }. One component for most jurisdictions (VAT 20% in FR, HST 13% in ON, GST 5% in AB, YT, NT and NU) and several where a real split exists: Quebec GST 5% + QST 9.975%, British Columbia GST 5% + PST 7%, Manitoba GST 5% + RST 7%, Saskatchewan GST 5% + PST 6%; in the US one per taxing authority. The component rates add up to the line rate and the amounts to the line taxAmount, to the cent (negative on a credit note). Canadian taxes are separate taxes: each is rounded to the cent on its own and the line taxAmount is their sum. A merchant registered for the federal tax only gets just the federal component. Absent on a line with no tax. A rule that replaced the rate marks the components overridden.
pendingCertificatesarray | undefined
Present only when an inline lineItems[].exempt claim had no matching active ECM certificate. Each entry: { certId, certRef, ecmUrl } — see Exemptions.
lineResultsarray
Alias for lineItems below — identical data, both fields are always present together.

jurisdiction

jurisdiction.countrystring
ISO country code of the resolved tax jurisdiction.
jurisdiction.regionstring | undefined
State or province of the resolved jurisdiction. Present for US/Canadian transactions where sub-national rates apply.
jurisdiction.resolutionMethodstring
How the jurisdiction was determined: SHIPPING_ADDRESS, BILLING_ADDRESS, IP_GEOLOCATION, BIN_COUNTRY, VAT_ID, or SELLER_ADDRESS (B2C general services sourced to the seller's own country).
jurisdiction.resolutionPrecisionstring
Confidence in the resolved jurisdiction: EXACT, POSTAL, REGION, or COUNTRY.
jurisdiction.addressPrecisionstring | undefined
US transactions only. The address resolution tier used to look up the rate: ROOFTOP (street address resolved to a zip+4 code), ZIP (postal code only), or STATE (region only).
jurisdiction.sourcingMethod"ORIGIN" | "DESTINATION" | undefined
US TX/CA/IL only. Which address local tax was sourced to. Absent for every other state/country, which always destination-source.
jurisdiction.sourcingAddressstring | undefined
Companion to sourcingMethod — which address it resolved to (SELLER_PLACE_OF_BUSINESS or BUYER_ADDRESS).
jurisdiction.sourcingCitationstring | undefined
Statute/regulation citation backing sourcingMethod.
jurisdiction.localityOverrideobject | undefined
US only — present only when a self-administered ("home-rule") locality's own rate row (not the state default) was applied, e.g. Boulder, CO: { locality, region, taxAuthorityId, reason }.
jurisdiction.conflictsarray
Non-empty when multiple jurisdiction signals disagree (e.g. billing address says DE, IP geolocation says FR). Each entry describes the conflicting signal and its country. The winning signal is indicated by resolutionMethod.
ℹ
Rate format — decimal fractions throughout. Every rate, standardRate, reducedRate, and slugRate field across all Tax Calculations endpoints uses a decimal fraction: 0.19 means 19%, 0.07 means 7%, 0 means zero-rated. Never multiply or divide rates received from the API — use them directly in tax calculations (taxAmount = taxableAmount × rate).

supplier / customer / entityRole (response)

Present on every calculation — distinct from the request's own supplier/customer input objects. entityRole ("supplier" for a "sale", "customer" for a "purchase") tells you which of the two blocks below is your own entity; the other is the counterparty. Only the counterparty block carries the B2B/B2C validation fields.

entityRole"supplier" | "customer"
Which party block is your own entity.
supplier.countrystring | undefined
This party's resolved country.
supplier.regionstring | undefined
State/region code, when resolved (e.g. US).
supplier.postalCodestring | undefined
—
supplier.taxIdstring | undefined
This party's tax/VAT ID, when known.
supplier.isEntityboolean
true when this block is your own entity; false when it is the counterparty.
supplier.b2bOverrideboolean | undefined
Counterparty block only (a purchase). Echoes the request's supplier.b2bOverride.
supplier.taxIdValidatedboolean | undefined
Counterparty block only (a purchase). Whether the supplied supplier.taxId was successfully verified.
supplier.taxIdValidationStatusstring | undefined
Counterparty block only (a purchase). More detail on the validation outcome.
customer.countrystring | undefined
This party's resolved country.
customer.regionstring | undefined
State/region code, when resolved (e.g. US).
customer.postalCodestring | undefined
—
customer.taxIdstring | undefined
This party's tax/VAT ID, when known.
customer.isEntityboolean
true when this block is your own entity; false when it is the counterparty.
customer.b2bOverrideboolean | undefined
Counterparty block only (a sale). Echoes the request's customer.b2bOverride.
customer.taxIdValidatedboolean | undefined
Counterparty block only (a sale). Whether the supplied customer.taxId was successfully verified (VIES, or format-only under vatValidation: "format").
customer.taxIdValidationStatusstring | undefined
Counterparty block only (a sale). More detail on the validation outcome (e.g. why an ID could not be verified).

sellerRegistration

Whether and how your entity is registered to collect tax in the resolved jurisdiction. Also present per-line as lineItems[].sellerRegistration for a request spanning categories with different registration coverage.

sellerRegistration.status"REGISTERED" | "PENDING" | "NOT_REGISTERED" | "MONITORING"
Registration state for this jurisdiction.
sellerRegistration.canCollectTaxboolean
Whether tax was actually collected on this calculation.
sellerRegistration.pricingModel"TAX_EXCLUSIVE" | "TAX_INCLUSIVE" | "TAX_INCLUSIVE_PENDING"
Your configured pricing model for this registration.
sellerRegistration.registrationNumberstring | undefined
The registration/VAT number on file, when one exists.
sellerRegistration.schemestring | undefined
The registration scheme matched, e.g. "OSS_UNION", "SIMPLIFIED".
sellerRegistration.matchLevel"country" | "region" | "locality" | undefined
Specificity of the registration row that matched (relevant for CA federal/provincial splits).
sellerRegistration.reasonstring | undefined
Free-form, customer-safe explanation of why canCollectTax is false despite a registration existing. Never machine-parseable — use reasonCode instead.
sellerRegistration.reasonCode"program-covered" | "registration-needed" | "not-obligated" | undefined
Closed, machine-readable classification, present only on a NOT_REGISTERED/$0 outcome.
sellerRegistration.requiresRegistrationToCollectboolean
Whether the destination jurisdiction itself requires seller registration to collect tax at all — a fact about the destination, independent of your own registration status there.

ioss (when applicable)

ioss.numberstring
The IOSS registration number used for this transaction.
ioss.registrationCountrystring
The EU member state where the IOSS number is registered.
ioss.totalGoodsValuenumber
Nominal total value of goods in the transaction currency (used to determine the ≤€150 threshold eligibility).
ioss.currencystring
Currency of the totalGoodsValue.

customsDuty (when applicable)

Present only on an IOSS-treated calculation for a low-value consignment, for the EU's temporary (2026-07-01 to 2028-06-30) per-item customs duty. This is an estimate of the duty that will be assessed when the consignment is declared for import — owed by the IOSS holder or their indirect customs representative, not VAT, not collected from the buyer, and never included in totalTax/totalAmountWithTax. It is counted per distinct tariff classification (6-digit level), assuming the order ships as a single consignment; the actual figure may differ if the carrier lodges a more detailed declaration, splits the order into several parcels, or the declaration is accepted outside the measure's window. It is not refunded when goods are returned — a credit note instead carries customsDutyNote: "NOT_REVERSED_ON_CREDIT_NOTE" and omits customsDuty. If you choose to recharge this amount to the buyer at the time of sale, that recharge becomes part of the VAT-taxable amount of the sale itself — the recharge is VAT-able, this field is not. When you also request duties (duties.include), the same €3 appears in the consignment's duty (source fee_rule): customsDuty is that one fee and consignments[] is the whole landed-cost estimate, so never add the two together. See Customs duties and landed cost.

customsDuty.feeCodestring
Always "EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY" today.
customsDuty.currencystring
Always "EUR" — the duty is never converted into the calculation's own currency.
customsDuty.amountnumber
Total duty owed this calculation — perItemAmount × itemCount.
customsDuty.perItemAmountnumber
The per-distinct-classification rate the rule charges (currently €3.00).
customsDuty.itemCountinteger
Distinct qualifying classification groups counted this calculation.
customsDuty.classificationDigitsinteger
Tariff-code digit-length used to group lines (6 = HS6/H7).
customsDuty.itemsarray
One entry per distinct classification code, plus one per missing/malformed-code line. Each entry: { classificationCode, lineIds }.
customsDuty.linesMissingCommodityCodestring[] | undefined
lineIds of qualifying lines whose commodityCode was missing or unusable — each still counts as its own item, never silently dropped.
customsDuty.includedInTotalsfalse
Always false — never folded into totalTax/totalAmountWithTax.
customsDuty.payableBy"DECLARANT"
Always "DECLARANT" — the IOSS holder or their indirect customs representative, never the buyer.
customsDuty.estimatetrue
Always true — customs assesses the actual debt on release; this is a forecast.
customsDuty.effectiveFromstring
ISO date — the resolved fee rule's own effective-from date.
customsDutyNote"NOT_REVERSED_ON_CREDIT_NOTE" | undefined
Present instead of customsDuty on a credit note whose original invoice would otherwise have owed one — the duty is never reversed on a return.

Three IOSS goods lines, two sharing one tariff classification and one with no usable commodityCode — two duty items, €6.00 total:

JSON Response — IOSS with customsDuty
{
  "calculationId": "cl_calc_01j4...",
  /* … full TaxCalculateResponse … */
  "ioss": {
    "number": "IM2760000123",
    "registrationCountry": "IE",
    "totalGoodsValue": 90.00,
    "currency": "EUR"
  },
  "customsDuty": {
    "feeCode": "EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY",
    "currency": "EUR",
    "amount": 6.00,
    "perItemAmount": 3.00,
    "itemCount": 2,
    "classificationDigits": 6,
    "items": [
      { "classificationCode": "610910", "lineIds": ["line-1", "line-2"] },
      { "classificationCode": null, "lineIds": ["line-3"] }
    ],
    "linesMissingCommodityCode": ["line-3"],
    "includedInTotals": false,
    "payableBy": "DECLARANT",
    "estimate": true,
    "effectiveFrom": "2026-07-01"
  },
  "totalTax": 17.10,
  /* customsDuty.amount (€6.00) is never folded into totalTax/totalAmountWithTax */
  "summary": { "totalAmount": 90.00, "totalDiscount": 0.00, "totalTax": 17.10, "totalAmountWithTax": 107.10 }
}

The same invoice, credited — the duty is not reversed:

JSON Response — credit note
{
  "calculationId": "cl_calc_01j5...",
  "transactionType": "credit_note",
  /* … full TaxCalculateResponse … */
  "customsDutyNote": "NOT_REVERSED_ON_CREDIT_NOTE"
  /* no "customsDuty" key on a credit note — the €6.00 already assessed on the original invoice is not refunded */
}

summary

summary.totalAmountnumber
Sum of all taxableAmount values across line items (tax-exclusive).
summary.totalDiscountnumber
Sum of all discounts applied across line items.
summary.totalTaxnumber
Sum of all taxAmount values across line items. Also aliased at the top level as totalTax. Never includes customsDuty.amount — the EU per-item customs duty estimate, when present, is not included in this total.
summary.totalAmountWithTaxnumber
Sum of all totalAmount values across line items (totalAmount + totalTax). Never includes customsDuty.amount — see customsDuty above.
summary.retailDeliveryFeesarray | undefined
Present only when a state retail-delivery fee applies (CO, MN) — flat per-delivery fees already included in totalTax/totalAmountWithTax. Each entry: { state, name, amount }.

lineItems[]

idstring
Your line item ID, echoed from the request.
taxCodestring
EN16931 tax code for this line item.
ratenumber
Effective tax rate for this line item as a decimal fraction (0.19 = 19%, 0 = zero-rated).
taxableAmountnumber
Amount on which tax is calculated (always tax-exclusive, regardless of the seller's pricing model).
taxableBasisnumber | undefined
Present (< 1) only when a statute taxes just a fixed share of the charge (e.g. Texas information services, 20% exempt). rate is already the effective rate, so taxAmount = taxableAmount × rate still holds.
taxAmountnumber
Tax amount for this line item.
totalAmountnumber
Total including tax (taxableAmount + taxAmount).
taxCategorystring
Product category slug resolved for this line item (e.g. digital_services).
classificationStatus"APPROVED" | "NEEDS_REVIEW" | "MANUAL" | "PENDING" | undefined
APPROVED — used with confidence; NEEDS_REVIEW — low confidence, recommend manual override; MANUAL — explicit taxCategory supplied; PENDING — classification failed, fallback used.
classificationConfidencenumber | undefined
Confidence score (0–1) carried over from when this catalogue entry was originally classified. 1.0 when an explicit taxCategory was provided on this call.
classificationFallbacktrue | undefined
Present and true only when the category was resolved via the account default (no productCode/productName catalogue match found). Omitted otherwise.
classificationSource"EXPLICIT" | "CODE_MAP" | "CACHED" | "CACHED_BY_NAME" | "DEFAULT" | undefined
HOW this line's tax category was resolved this call — see Product Classification. No live AI classification ever occurs on this endpoint. Always populated alongside the other classification* fields, even when taxTreatmentOverride/commodityCode later determined the actual rate band.
classificationSystemstring | undefined
Present only when classificationSource is "CODE_MAP": which code system decided this line (stripe, shopify, hs, …).
classificationMatchedCodestring | undefined
Present only when classificationSource is "CODE_MAP": the code in the map that actually decided. It can be a parent of the code you sent, for example a Shopify category that fell back to its nearest mapped parent.
sourcingRationale.rateBandstring
This line's resolved rate band (STANDARD/MIDDLE/REDUCED/SUPER_REDUCED/SPECIAL/ZERO/EXEMPT/etc.). Always present.
sourcingRationale.bandTierstring
Which resolution tier decided rateBand above — OVERRIDE confirms taxTreatmentOverride was honoured, COMMODITY_CODE confirms commodityCode matched a row; any other value means the band came from the ordinary taxCategory-driven chain instead.
jurisdictionobject | undefined
This line's own resolved jurisdiction — same shape as the top-level jurisdiction object above. Present on every non-degraded line.
placeOfSupplyRule"GOODS" | "DIGITAL_SERVICE" | "GENERAL_SERVICE" | "UNSUPPORTED" | undefined
This line's classified place-of-supply regime.
movement"local" | "intra_community" | "export" | "distance_sale" | "import" | "own_goods_movement" | undefined
This line's EU-VAT-Directive movement classification. Present whenever the line reached full derivation, for both sale and purchase.
exemptionobject | undefined
Present when an exemption certificate was applied: { certificateId, certificateRef, certificateType, effectiveTo }.
clientTaxCodestring | undefined
Your own ERP tax code for this line — either an echo of a resolved input (lineItems[].clientTaxCode/header clientTaxCode), or a reverse lookup handing back your own code for this line's resolved treatment when no input was supplied. Absent when no client tax code matches, or more than one does (an allowed but ambiguous duplicate).
outcomeobject | undefined
The headline per-line resolution verdict — check this first. { status, reasonCode?, label?, nextStep? }. status is "RESOLVED" (complete, the default), "NO_TAX_CODE" (treatment fully determined but no client tax code matched — informational only, not an error), or "UNKNOWN_TREATMENT" (a required input signal is missing, e.g. purchase-mode missing_supply_type — always carries a reasonCode, label, and nextStep). Never causes a request-level 4xx.
recoverabilityobject | undefined
Purchase mode only — absent on every sale line. { recoverablePercent, recoverableAmount, blockedAmount, recoverabilityRate, allocationSource, status, selfAssessedOutputTax? } — the input-tax recoverable/blocked split for this purchase line. See Purchase Mode.
taxVerificationobject | undefined
Purchase mode only — present only when you supplied lineItems[].statedTaxAmount for this line and it isn't a border-paid import. { statedTaxAmount, calculatedTaxAmount, delta, verdict, recoverableBase }, where verdict is "MATCH", "OVERCHARGED", or "UNDERCHARGED". See Purchase Mode.