Customs duties and landed cost
POST /v1/duties/quote returns an estimate of the import duty, import VAT/GST and customs fees on a cross-border cart, without recording a calculation. The same estimate comes back on POST /v1/tax/calculate and POST /v1/tax/calculate/partner when you pass duties.include: true (or turn on the dutiesEnabled setting). Every measure is named, so a broker can reproduce the figure.
totalTax or totalAmountWithTax, and your tax figures are identical with duties off, on, or degraded. The one amount a checkout may add is summary.importChargesAtCheckout; summary.totalAmountDue, present only alongside it, is totalAmountWithTax plus that amount. Figures are estimates and are not guaranteed: reconcile any difference with the carrier or broker invoice.See also the Tax Calculations reference for the full calculate request and response.
What to send
The body is the POST /v1/tax/calculate body. duties.include is implied on a quote; commit, credit notes and transactionDirection: "purchase" are rejected with 422. A quote is stateless: nothing is stored and no idempotency key is read. A partner_calc key adds the same required sellerRegistrationContext and partnerMerchantId as POST /v1/tax/calculate/partner.
| Field | Type | Description |
|---|---|---|
| lineItems[].commodityCode | string | The tariff code the duty is priced at. The most important input: it decides the precision of the estimate. |
| lineItems[].commodityCodeScheme | "HS6" | "CN8" | "TARIC10" | "UK10" | "HTS10" | Scheme of that code. Omitted: inferred from the digit count and the destination (schemeInferred: true on the result). A national code is exact only in its own territory; anywhere else its first six digits are used and the result is HS6_EXACT or HS6_AMBIGUOUS, not an error. |
| lineItems[].countryOfOrigin | string | ISO 3166-1 alpha-2. Never inferred from shipFrom. Falls back to the product catalogue, then duties.defaultCountryOfOrigin, then the account default. |
| lineItems[].weight | object | { value, unit } with unit kg, g, lb or oz; per unit. Needed for per-kilogram duties. |
| shipFrom / lineItems[].shipFrom | object | Where goods are dispatched from; a different customs territory from the destination makes a customs crossing. customsStatus: "bonded" marks stock held under customs control. |
| incoterms / importerOfRecord | string | Who imports. importerOfRecord wins over incoterms (DDP is the seller, any other rule the buyer), which wins over the account defaultImporterOfRecord. |
| insurance | object | { amount, currency? }, part of the customs value where the destination values goods CIF. |
| shippingMode | "post" | "courier" | How the consignment travels (optional, also accepted on the partner endpoint). It selects the low-value regime: for Canada, courier from the US or Mexico is duty-free up to CAD 150 (GST/HST applies above CAD 40) while postal and courier from elsewhere are duty and tax free only up to CAD 20. Omitted means unknown: the stricter outcome is assumed and the estimate carries shipping_mode_assumed. |
| duties.collectDeposit | boolean | Ask for the estimate to be collected at checkout when the buyer is the importer. |
| duties.defaultCountryOfOrigin, duties.ratePolicyForHs6 | string | Per-request overrides of the account settings. ratePolicyForHs6 is modal or highest; a collected deposit always uses the highest rate. |
Mapping a Shopify product
| Shopify | Clearvo line item |
|---|---|
harmonizedSystemCode | commodityCode (scheme inferred, or set commodityCodeScheme) |
countryHarmonizedSystemCodes[] | The entry for the destination country is its commodityCode with that country's national commodityCodeScheme. |
countryCodeOfOrigin | countryOfOrigin |
weight and weightUnit | weight.value and weight.unit |
| Product taxonomy category | classificationCodes: [{ "system": "shopify", "code": "aa-1-13" }]. Used when no code is sent, so the line is priced from its category as a proxy and never collected. |
What to show at checkout
Decide by consignments[].responsibleParty and collectedAtCheckout. Every quoted consignment also carries collection.reason, which says why nothing is collected when you asked for a deposit.
responsibleParty | collectedAtCheckout | Typical case | Tax fields (unchanged) | Show the buyer |
|---|---|---|---|---|
seller | false | DDP registered seller; IOSS up to €150 (the €3 is the IOSS holder's cost) | Normal destination VAT/GST or IOSS at checkout, or US sales tax on the price | Nothing new. Use landedCost for pricing and margin. |
customer | false | DAP or buyer importer, no deposit | OUT_OF_SCOPE, tax code O, rate 0 | Optional notice: "Import duties and taxes of approximately X may be payable to the carrier on delivery." Not added to the total. |
customer | true | Deposit model (duties.collectDeposit, buyer is importer) | Same as above | Add summary.importChargesAtCheckout as its own line, "Estimated import charges"; charge totalAmountDue. Never label it tax. Refund any excess. |
| any | any | duties.status: "not_applicable": domestic, intra-EU, GB to GB | Normal | Nothing. |
Canada, Australia and New Zealand
These destinations use low-value regimes with their own thresholds and authority fees, all estimates. Canada: postal and courier up to CAD 20 are duty and tax free; courier from the US or Mexico is free of duty up to CAD 150 and of tax up to CAD 40 (send shippingMode); GST (5%) or HST (the province's rate, from the delivery province) is charged on value for duty plus duties. Australia: consignments up to AUD 1,000 pay no border duty or GST (the vendor collects GST at checkout); above that, duty, 10% GST, the Import Processing Charge (AUD 50, or AUD 152 from AUD 10,000) and the biosecurity charge apply. New Zealand: up to NZD 1,000 pay no border duty or GST (the offshore supplier collects 15% GST) plus the Customs and MPI goods levy; above NZD 1,000 duty, 15% GST and the higher goods levy apply. Chapter-level tariff data means precision is CHAPTER_PROXY and the quote is never collected as a deposit. Where the seller is unregistered at the destination and no incoterms or importerOfRecord is sent, border import VAT is estimated and flagged responsible_party_unresolved rather than shown as zero.
Reading an estimate
duties.statusisquoted,not_applicable,degradedordisabled. A duty failure is a 200 withdegradedand areason, never a 5xx, and it never changes the tax figures or the calculation's owndegradedflag.estimate: falsemeans no modelled source of variance (a flat or zero regime, or tariff-line precision with no origin-scoped measure and no static FX). It is never a guarantee: the declarant's classification, valuation, origin and declaration choices prevail.estimateReasonsis the closed list behindestimate: true.precisionrunsTARIFF_LINE,HS6_EXACT,HS6_AMBIGUOUS,PLATFORM_CODE,CATEGORY_PROXY,CHAPTER_PROXY,UNRESOLVED. The last three are never collected from a buyer.- Each measure carries its
rateExpression, a closed union:ad_valorem_pct,top_up_to_pct,flat,specific,compound,alternativeandmin_max. - Measures that exist but could not be evaluated (not yet in force, or origin unknown) are in
notEvaluatedand block collection. - The IOSS response may also carry
customsDuty. It is the same €3 per item as the consignment'sduty(sourcefee_rule):customsDutyis that one fee,consignments[]is the whole landed-cost estimate, so never add the two together. - Amounts using a static FX rate say so in
fx.sourceandfxSource; they are not live rates.
Turn duties on for the account with PATCH /v1/tax/settings: dutiesEnabled, dutyRatePolicyForHs6, defaultCountryOfOrigin. The quote_duties tool in the Clearvo MCP server and clearvo duties quote in the CLI call this endpoint; the TypeScript SDK exposes quoteDuties() and the DutiesResult type.
Example 1: $40 China-origin T-shirt, UK warehouse to Texas
{
"currency": "USD",
"date": "2026-10-03",
"supplier": {
"name": "Acme Apparel Ltd",
"billingAddress": {
"country": "GB",
"postalCode": "SW1A 1AA"
}
},
"customer": {
"name": "Jordan Lee",
"billingAddress": {
"country": "US",
"region": "TX",
"postalCode": "78701"
},
"shippingAddress": {
"country": "US",
"region": "TX",
"postalCode": "78701"
}
},
"shipFrom": {
"country": "GB",
"postalCode": "SW1A 1AA"
},
"lineItems": [
{
"id": "l1",
"amount": 40,
"quantity": 1,
"productName": "Cotton T-shirt",
"commodityCode": "6109100012",
"commodityCodeScheme": "HTS10",
"countryOfOrigin": "CN"
}
],
"duties": {
"include": true
}
}
{
"currency": "USD",
"duties": {
"status": "quoted",
"contentVersion": 1
},
"consignments": [
{
"id": "c1",
"lineIds": [
"l1"
],
"status": "quoted",
"dispatchTerritory": "GB",
"destinationTerritory": "US",
"customsStatus": "free_circulation",
"valuation": {
"basis": "FOB",
"goods": 40,
"freight": 0,
"insurance": 0,
"customsValue": 40,
"currency": "USD"
},
"regime": null,
"duty": {
"total": 9.6,
"source": "tariff",
"estimate": true
},
"importTax": {
"label": null,
"collection": "none",
"base": 40,
"rate": 0,
"amount": 0,
"baseIncludes": [
"customs_value"
],
"sellerRegistrationRequired": false,
"notes": []
},
"fees": [
{
"code": "US_MPF_INFORMAL",
"label": "Merchandise Processing Fee (informal entry)",
"amount": 2.77,
"currency": "USD",
"basis": "flat",
"entryType": "informal",
"entryTypeAssumed": true,
"incidence": "SELLER_COST"
}
],
"responsibleParty": "unresolved",
"responsiblePartySource": "unresolved",
"collectedAtCheckout": false,
"collection": {
"requested": false,
"collected": false,
"reason": "not_requested"
},
"landedCost": 52.37,
"importChargesAtCheckout": 0,
"sellerBorne": {
"duty": 0,
"importTax": 0,
"fees": 0,
"total": 0
},
"precision": "TARIFF_LINE",
"estimate": true,
"estimateReasons": [
"origin_measures_apply",
"measure_not_in_force",
"preference_not_considered",
"entry_type_assumed"
],
"notEvaluated": [
{
"familyCode": "US_301_BY_ORIGIN_CN",
"measureType": "SECTION_301_BY_ORIGIN",
"reason": "not_in_force",
"legalStatus": "announced"
}
],
"fxSource": null,
"sellerRegistrationGap": false
}
],
"lineItems": [
{
"id": "l1",
"duty": {
"consignmentId": "c1",
"commodityCode": "6109100012",
"scheme": "HTS10",
"codeSource": "request",
"precision": "TARIFF_LINE",
"origin": "CN",
"originSource": "request",
"customsValue": 40,
"amount": 9.6,
"measures": [
{
"type": "MFN",
"rate": 0.165,
"rateExpression": {
"type": "ad_valorem_pct",
"value": 16.5
},
"amount": 6.6,
"legalBasis": null,
"effectiveFrom": "2026-01-01"
},
{
"type": "SECTION_301_LIST_4A",
"rate": 0.075,
"rateExpression": {
"type": "ad_valorem_pct",
"value": 7.5
},
"amount": 3,
"legalBasis": "HTSUS 9903.88.15",
"effectiveFrom": "2026-01-01"
}
],
"notEvaluated": [
{
"familyCode": "US_301_BY_ORIGIN_CN",
"measureType": "SECTION_301_BY_ORIGIN",
"reason": "not_in_force",
"legalStatus": "announced"
}
],
"missingInputs": [],
"estimateReasons": [
"origin_measures_apply",
"measure_not_in_force",
"preference_not_considered"
]
}
}
],
"summary": {
"totalDuty": 9.6,
"totalImportTax": 0,
"totalImportFees": 2.77,
"totalLandedCost": 52.37,
"sellerBorneImportCosts": 0
}
}
How to read it
- Duty $9.60: 16.5% MFN ($6.60) plus 7.5% Section 301 List 4A ($3.00). The by-origin China measure is announced, not in force: it is listed in
notEvaluatedand never applied. - The informal-entry Merchandise Processing Fee of $2.77 applies (a $40 parcel is an informal entry,
entryTypeAssumed: true), not the $34.58 formal-entry minimum. A fee is a seller cost and is never added to what the buyer pays. - No importer of record is set, so
responsiblePartyisunresolvedand nothing is collected (collection.reason: not_requested). Texas sales tax on the $40 is unchanged.estimate: truebecause origin-scoped measures apply and one is not in force.
Example 2: €120 item, UK to France, IOSS-registered seller
{
"currency": "EUR",
"date": "2026-10-03",
"supplier": {
"name": "Acme Apparel Ltd",
"billingAddress": {
"country": "GB",
"postalCode": "SW1A 1AA"
}
},
"customer": {
"name": "Camille Martin",
"billingAddress": {
"country": "FR",
"postalCode": "75001"
},
"shippingAddress": {
"country": "FR",
"postalCode": "75001"
}
},
"shipFrom": {
"country": "GB",
"postalCode": "SW1A 1AA"
},
"importerOfRecord": "BUYER",
"lineItems": [
{
"id": "l1",
"amount": 120,
"quantity": 1,
"productName": "Cotton T-shirt",
"commodityCode": "61091000",
"commodityCodeScheme": "CN8",
"countryOfOrigin": "GB"
}
],
"duties": {
"include": true,
"collectDeposit": true
}
}
{
"currency": "EUR",
"duties": {
"status": "quoted",
"contentVersion": 1
},
"consignments": [
{
"id": "c1",
"lineIds": [
"l1"
],
"status": "quoted",
"dispatchTerritory": "GB",
"destinationTerritory": "EU",
"customsStatus": "free_circulation",
"valuation": {
"basis": "CIF",
"goods": 120,
"freight": 0,
"insurance": 0,
"customsValue": 120,
"currency": "EUR"
},
"regime": {
"code": "EU_IOSS_150",
"name": "EU_IOSS_150",
"basis": "intrinsic_value",
"thresholdAmount": 150,
"thresholdCurrency": "EUR",
"comparedValue": 120,
"nearThreshold": false,
"consequence": {
"vat": "checkout",
"duty": "flat_per_item"
},
"feeCode": "EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY",
"taxTreatmentMismatch": false,
"notes": []
},
"duty": {
"total": 3,
"source": "fee_rule",
"feeCode": "EU_LOW_VALUE_CONSIGNMENT_CUSTOMS_DUTY",
"estimate": false
},
"importTax": {
"label": "VAT",
"collection": "checkout",
"base": 123,
"rate": 0,
"amount": 0,
"baseIncludes": [
"customs_value",
"duty",
"freight"
],
"sellerRegistrationRequired": false,
"notes": []
},
"fees": [],
"responsibleParty": "seller",
"responsiblePartySource": "regime",
"collectedAtCheckout": false,
"collection": {
"requested": true,
"collected": false,
"reason": "regime_vat_at_checkout"
},
"landedCost": 123,
"importChargesAtCheckout": 0,
"sellerBorne": {
"duty": 3,
"importTax": 0,
"fees": 0,
"total": 3
},
"precision": null,
"estimate": false,
"estimateReasons": [],
"notEvaluated": [],
"fxSource": null,
"sellerRegistrationGap": false
}
],
"lineItems": [
{
"id": "l1",
"duty": {
"consignmentId": "c1",
"commodityCode": "61091000",
"scheme": "CN8",
"codeSource": "request",
"precision": null,
"origin": "GB",
"originSource": "request",
"customsValue": 120,
"amount": 3,
"measures": [
{
"type": "REGIME_FLAT",
"rate": null,
"rateExpression": {
"type": "flat",
"amount": 0,
"currency": "EUR"
},
"amount": 3,
"legalBasis": null,
"effectiveFrom": "2026-07-01"
}
],
"notEvaluated": [],
"missingInputs": [],
"estimateReasons": []
}
}
],
"summary": {
"totalDuty": 3,
"totalImportTax": 0,
"totalImportFees": 0,
"totalLandedCost": 123,
"sellerBorneImportCosts": 3
}
}
How to read it
- French VAT is collected at checkout under IOSS and sits in
totalTax, so import VAT is0withcollection: "checkout"and nothing is added to the buyer's total. - The EU €3 per-item customs duty is the IOSS holder's cost:
responsibleParty: "seller",collection.reason: "regime_vat_at_checkout",importChargesAtCheckout: 0,sellerBorne.duty: 3. - Asking for a deposit and naming the buyer as importer changes nothing: under IOSS the declarant is the seller.
estimate: falsemeans no modelled source of variance, not a guarantee.
Example 3: the same item at €200, China origin, DAP
{
"currency": "EUR",
"date": "2026-10-03",
"supplier": {
"name": "Acme Apparel Ltd",
"billingAddress": {
"country": "GB",
"postalCode": "SW1A 1AA"
}
},
"customer": {
"name": "Camille Martin",
"billingAddress": {
"country": "FR",
"postalCode": "75001"
},
"shippingAddress": {
"country": "FR",
"postalCode": "75001"
}
},
"shipFrom": {
"country": "GB",
"postalCode": "SW1A 1AA"
},
"incoterms": "DAP",
"lineItems": [
{
"id": "l1",
"amount": 200,
"quantity": 1,
"productName": "Cotton T-shirt",
"commodityCode": "61091000",
"commodityCodeScheme": "CN8",
"countryOfOrigin": "CN"
},
{
"id": "ship",
"amount": 12,
"productName": "Shipping",
"taxCategory": "shipping_handling"
}
],
"duties": {
"include": true,
"collectDeposit": true
}
}
{
"currency": "EUR",
"duties": {
"status": "quoted",
"contentVersion": 1
},
"consignments": [
{
"id": "c1",
"lineIds": [
"l1"
],
"status": "quoted",
"dispatchTerritory": "GB",
"destinationTerritory": "EU",
"customsStatus": "free_circulation",
"valuation": {
"basis": "CIF",
"goods": 200,
"freight": 12,
"insurance": 0,
"customsValue": 212,
"currency": "EUR"
},
"regime": null,
"duty": {
"total": 25.44,
"source": "tariff",
"estimate": false
},
"importTax": {
"label": "VAT",
"collection": "border",
"base": 237.44,
"rate": 0.2,
"amount": 47.49,
"baseIncludes": [
"customs_value",
"duty",
"freight"
],
"sellerRegistrationRequired": false,
"notes": []
},
"fees": [],
"responsibleParty": "customer",
"responsiblePartySource": "incoterms",
"collectedAtCheckout": true,
"collection": {
"requested": true,
"collected": true,
"reason": "collected"
},
"landedCost": 284.93,
"importChargesAtCheckout": 72.93,
"sellerBorne": {
"duty": 0,
"importTax": 0,
"fees": 0,
"total": 0
},
"precision": "TARIFF_LINE",
"estimate": false,
"estimateReasons": [],
"notEvaluated": [],
"fxSource": null,
"sellerRegistrationGap": false
}
],
"lineItems": [
{
"id": "l1",
"duty": {
"consignmentId": "c1",
"commodityCode": "61091000",
"scheme": "CN8",
"codeSource": "request",
"precision": "TARIFF_LINE",
"origin": "CN",
"originSource": "request",
"customsValue": 212,
"amount": 25.44,
"measures": [
{
"type": "MFN",
"rate": 0.12,
"rateExpression": {
"type": "ad_valorem_pct",
"value": 12
},
"amount": 25.44,
"legalBasis": null,
"effectiveFrom": "2026-01-01"
}
],
"notEvaluated": [],
"missingInputs": [],
"estimateReasons": []
}
}
],
"summary": {
"totalDuty": 25.44,
"totalImportTax": 47.49,
"totalImportFees": 0,
"totalLandedCost": 284.93,
"sellerBorneImportCosts": 0,
"importChargesAtCheckout": 72.93,
"totalAmountDue": 284.93
}
}
How to read it
- Above €150 no low-value regime applies. Duty €25.44 is 12% of a CIF customs value of €212 (200 goods + 12 freight). Import VAT €47.49 is 20% of customs value plus duty (€237.44).
incoterms: "DAP"makes the buyer the importer and a deposit was requested, socollectedAtCheckoutistrueandsummary.importChargesAtCheckoutis €72.93. Show it as its own line, "Estimated import charges"; chargetotalAmountDue.- With
incoterms: "DDP"the same cart is seller-borne and nothing is collected.
Estimate one product across destinations
POST /v1/duties/estimate prices one product for up to 20 destinations in a single call: use it to set delivered-duty-paid prices per market, or to answer “what would it cost to sell this into Australia”. It is the same engine, tariff content and estimate semantics as POST /v1/duties/quote: each destination is the one-line cart a quote call would take. Nothing is recorded: no calculation, no id, no idempotency key, no catalogue write, so a read-only API key is enough. Entity keys and partner_calc keys can call it (a partner key also sends supplier, sellerRegistrationContext and partnerMerchantId, as on POST /v1/tax/calculate/partner). It shares the rate-limit class of the quote.
Identify the product with at least one of commodityCode (with commodityCodeScheme), classificationCodes, productCode / sku (resolved through your catalogue) or taxCategory / slug, and price it with unitPrice (times quantity) or amount. Add countryOfOrigin, a per-unit weight, shipFrom, incoterms, importerOfRecord, insurance and freight to tighten the estimate.
{
"currency": "USD",
"shipFrom": { "country": "CN" },
"product": {
"commodityCode": "610910",
"commodityCodeScheme": "HS6",
"countryOfOrigin": "CN",
"unitPrice": 25,
"quantity": 4
},
"freight": { "amount": 12 },
"incoterms": "DDP",
"destinations": [
{ "country": "DE" },
{ "country": "AU" },
{ "country": "US", "region": "TX" }
]
}
The response has a top-level product block (the resolved commodityCode, scheme, codeSource and precision) and one entry per destination, in request order. Each entry has a status and the same duties, consignments and summary blocks the quote returns, plus the product line’s duty:
quoted: duties were estimated; readconsignments[].estimate,estimateReasonsandprecisionexactly as for a quote.not_applicable: nothing crosses a customs border for that destination (seereason).degraded: that destination could not be estimated (reasondestination_rejectedwith anerror, for example a US destination without aregion). One bad destination never fails the call.
The one non-2xx the engine can add is the fail-closed 503 tax_content_unavailable. Every figure is an estimate and none of it is tax.
Record what customs actually charged
After clearance, post the customs entry number and the actual duty, import VAT/GST and fees from the entry or the carrier’s duty-and-tax invoice with POST /v1/tax/calculate/{id}/import-settlement. It works on a committed calculation that carries a quoted duties block (request it with duties.include: true). The settlement is stored next to a snapshot of the estimate, and the variance is computed server-side.
{
"entryNumber": "EAD-2026-004411",
"entryDate": "2026-10-09",
"consignmentId": "c1",
"actual": { "duty": 14.00, "importTax": 20.10, "fees": 3.30, "currency": "GBP" },
"lines": [ { "lineId": "line-1", "duty": 14.00 } ],
"notes": "Carrier duty-and-tax invoice DT-9917"
}
consignmentIdis only needed when the calculation has more than one quoted consignment (422 consignment_requiredlists the ids).actual.currencymust equal the calculation’s currency. No conversion is performed: a different currency is422 currency_mismatch.- The response returns the stored settlement with
estimatedandactual(duty, importTax, fees, total), thevarianceamount and percent per component (actual minus estimated; positive means customs charged more), andwithinEstimate(true when the actual total did not exceed the estimate). - Idempotent on the calculation, consignment and
entryNumber: replaying the same actuals returns the stored settlement (200,replayed: true). Different actuals for the same entry are409 settlement_conflict: settlements are append-only, so record a correction under a newentryNumber. - Other refusals are
404(calculation not found for your entity) and422(credit note, not committed, no quoted duties block, unknown line). - Facts only. A settlement never changes the calculation, its tax figures or your tax obligations.
GET /v1/tax/calculate/{id}/import-settlement lists a calculation’s settlements with a summary (estimated against actual, and the variance, per currency). GET /v1/duties/settlement-variance?from=&to=&destination=&precision= aggregates your settlements by destination customs territory and precision tier: count, mean and median variance percent, and amounts per currency, so you can see how close the estimate runs to the entry for each corridor.
Data sources and attribution
- United Kingdom: Contains public sector information licensed under the Open Government Licence v3.0.
- European Union: Combined Nomenclature and TARIC data, source acknowledged in accordance with Commission Decision 2011/833/EU on the reuse of Commission documents.
- United States: Harmonized Tariff Schedule of the United States (HTSUS), a public-domain work of the US International Trade Commission.
Estimates only, with no guarantee of accuracy. Clearvo is not a customs broker and does not file entries.