Response Reference
Full field reference for the TaxCalculateResponse object returned by the calculation endpoint.
Top-level fields
calculationIdstringcl_calc_* prefix, cl_calc_test_* in sandbox). Present whether the calculation was recorded or previewed.entityIdstringapiVersionstring"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.resolvedAtstringdate field — is what windows it into a Compliance Radar threshold period.sandboxbooleancsk_test_* key. A sandbox calculation never counts toward usage or Compliance Radar totals, whatever committed below is.committedbooleancommit 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.merchantRefstringmerchantRef, when supplied.paymentMethodstringpaymentMethod, when supplied.incotermsstringincoterms, when supplied.taxTreatmentstringlineItems[].rate below), not here — a single calculation can span multiple bands when its lines fall into different categories.taxCodestringS, AA, AE, E, K, G, Z, or O.transactionType"invoice" | "credit_note""invoice"). Credit note responses have negative amounts on all line items and totals.relatedCalculationIdstring | undefinedcalculationId of the original invoice this credit note reverses. Only present when transactionType is "credit_note" and the field was provided in the request.refundedAtstring | undefinedPOST /v1/tax/calculate/{id}/refund has been called. Absent for non-refunded calculations.totalTaxnumber | undefinedsummary.totalTax below.degradedboolean | undefineddegradedReasonstring | undefineddegraded: true.staleCacheReasonstring | undefineddegraded 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 | undefinedtaxReportingCurrency: { currency, taxTotal, total, fxRate, fxRateAsOf } — the same totals converted into that currency.jurisdictionBreakdownarray | undefined{ name, level, rate, taxableAmount, taxAmount }.lineItems[].jurisdictionBreakdownarray | undefined{ 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 | undefinedlineItems[].exempt claim had no matching active ECM certificate. Each entry: { certId, certRef, ecmUrl } — see Exemptions.lineResultsarraylineItems below — identical data, both fields are always present together.jurisdiction
jurisdiction.countrystringjurisdiction.regionstring | undefinedjurisdiction.resolutionMethodstringSHIPPING_ADDRESS, BILLING_ADDRESS, IP_GEOLOCATION, BIN_COUNTRY, VAT_ID, or SELLER_ADDRESS (B2C general services sourced to the seller's own country).jurisdiction.resolutionPrecisionstringEXACT, POSTAL, REGION, or COUNTRY.jurisdiction.addressPrecisionstring | undefinedROOFTOP (street address resolved to a zip+4 code), ZIP (postal code only), or STATE (region only).jurisdiction.sourcingMethod"ORIGIN" | "DESTINATION" | undefinedjurisdiction.sourcingAddressstring | undefinedsourcingMethod — which address it resolved to (SELLER_PLACE_OF_BUSINESS or BUYER_ADDRESS).jurisdiction.sourcingCitationstring | undefinedsourcingMethod.jurisdiction.localityOverrideobject | undefined{ locality, region, taxAuthorityId, reason }.jurisdiction.conflictsarrayresolutionMethod.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"supplier.countrystring | undefinedsupplier.regionstring | undefinedsupplier.postalCodestring | undefinedsupplier.taxIdstring | undefinedsupplier.isEntitybooleantrue when this block is your own entity; false when it is the counterparty.supplier.b2bOverrideboolean | undefinedsupplier.b2bOverride.supplier.taxIdValidatedboolean | undefinedsupplier.taxId was successfully verified.supplier.taxIdValidationStatusstring | undefinedcustomer.countrystring | undefinedcustomer.regionstring | undefinedcustomer.postalCodestring | undefinedcustomer.taxIdstring | undefinedcustomer.isEntitybooleantrue when this block is your own entity; false when it is the counterparty.customer.b2bOverrideboolean | undefinedcustomer.b2bOverride.customer.taxIdValidatedboolean | undefinedcustomer.taxId was successfully verified (VIES, or format-only under vatValidation: "format").customer.taxIdValidationStatusstring | undefinedsellerRegistration
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"sellerRegistration.canCollectTaxbooleansellerRegistration.pricingModel"TAX_EXCLUSIVE" | "TAX_INCLUSIVE" | "TAX_INCLUSIVE_PENDING"sellerRegistration.registrationNumberstring | undefinedsellerRegistration.schemestring | undefined"OSS_UNION", "SIMPLIFIED".sellerRegistration.matchLevel"country" | "region" | "locality" | undefinedsellerRegistration.reasonstring | undefinedcanCollectTax is false despite a registration existing. Never machine-parseable — use reasonCode instead.sellerRegistration.reasonCode"program-covered" | "registration-needed" | "not-obligated" | undefinedNOT_REGISTERED/$0 outcome.sellerRegistration.requiresRegistrationToCollectbooleanioss (when applicable)
ioss.numberstringioss.registrationCountrystringioss.totalGoodsValuenumberioss.currencystringtotalGoodsValue.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"EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY" today.customsDuty.currencystring"EUR" — the duty is never converted into the calculation's own currency.customsDuty.amountnumberperItemAmount × itemCount.customsDuty.perItemAmountnumbercustomsDuty.itemCountintegercustomsDuty.classificationDigitsintegercustomsDuty.itemsarray{ classificationCode, lineIds }.customsDuty.linesMissingCommodityCodestring[] | undefinedcommodityCode was missing or unusable — each still counts as its own item, never silently dropped.customsDuty.includedInTotalsfalsefalse — never folded into totalTax/totalAmountWithTax.customsDuty.payableBy"DECLARANT""DECLARANT" — the IOSS holder or their indirect customs representative, never the buyer.customsDuty.estimatetruetrue — customs assesses the actual debt on release; this is a forecast.customsDuty.effectiveFromstringcustomsDutyNote"NOT_REVERSED_ON_CREDIT_NOTE" | undefinedcustomsDuty 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:
{
"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:
{
"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.totalAmountnumbertaxableAmount values across line items (tax-exclusive).summary.totalDiscountnumbersummary.totalTaxnumbertaxAmount 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.totalAmountWithTaxnumbertotalAmount values across line items (totalAmount + totalTax). Never includes customsDuty.amount — see customsDuty above.summary.retailDeliveryFeesarray | undefinedtotalTax/totalAmountWithTax. Each entry: { state, name, amount }.lineItems[]
idstringtaxCodestringratenumber0.19 = 19%, 0 = zero-rated).taxableAmountnumbertaxableBasisnumber | undefinedrate is already the effective rate, so taxAmount = taxableAmount × rate still holds.taxAmountnumbertotalAmountnumbertaxableAmount + taxAmount).taxCategorystringdigital_services).classificationStatus"APPROVED" | "NEEDS_REVIEW" | "MANUAL" | "PENDING" | undefinedAPPROVED — used with confidence; NEEDS_REVIEW — low confidence, recommend manual override; MANUAL — explicit taxCategory supplied; PENDING — classification failed, fallback used.classificationConfidencenumber | undefined1.0 when an explicit taxCategory was provided on this call.classificationFallbacktrue | undefinedtrue 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" | undefinedclassification* fields, even when taxTreatmentOverride/commodityCode later determined the actual rate band.classificationSystemstring | undefinedclassificationSource is "CODE_MAP": which code system decided this line (stripe, shopify, hs, …).classificationMatchedCodestring | undefinedclassificationSource 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.rateBandstringSTANDARD/MIDDLE/REDUCED/SUPER_REDUCED/SPECIAL/ZERO/EXEMPT/etc.). Always present.sourcingRationale.bandTierstringrateBand 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 | undefinedjurisdiction object above. Present on every non-degraded line.placeOfSupplyRule"GOODS" | "DIGITAL_SERVICE" | "GENERAL_SERVICE" | "UNSUPPORTED" | undefinedmovement"local" | "intra_community" | "export" | "distance_sale" | "import" | "own_goods_movement" | undefinedsale and purchase.exemptionobject | undefined{ certificateId, certificateRef, certificateType, effectiveTo }.clientTaxCodestring | undefinedlineItems[].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{ 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 | undefinedsale line. { recoverablePercent, recoverableAmount, blockedAmount, recoverabilityRate, allocationSource, status, selfAssessedOutputTax? } — the input-tax recoverable/blocked split for this purchase line. See Purchase Mode.taxVerificationobject | undefinedlineItems[].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.