border.bot
Esc
  • Loading…
↑ ↓ to move↵ to openEsc to close
Docs menu

Products

Calculate

Calculate duties, taxes, fees and the landed cost of a parcel or a whole order with the border.bot API, with every line's legal basis, de minimis and the additional duties that stack.

Calculate works out what a parcel pays on arrival: the customs duty, additional duties (US Section 301, 232 and the like), import VAT or sales tax, and the fees, each with its legal basis and source, and the landed cost. The Calculate page explains how it works.

Endpoints#

Endpoint What it does
POST /v1/calculate One line: a code, origin, destination and value (or a catalogue product by sku)
POST /v1/calculate/shipment A cart or order of up to 50 lines, with freight and insurance shared out by value and one de minimis check
POST /v1/calculate/stacking Which duty lines apply to a code from an origin on a date, without a shipment
GET /v1/countries Which destinations calculate (landedCost)

Calculate a line#

curl -X POST https://api.border.bot/v1/calculate \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "hsCode": "6109.10.00.12",
    "originCountry": "CN",
    "destinationCountry": "US",
    "value": 100,
    "currency": "USD",
    "shippingCost": 15
  }'

The response lists every duty, tax and fee line with its rate, amount, legal basis and source, the de minimis decision, the exchange rate used and the totals (duty, fees, taxes, landed cost). For the US, the additional duties come with their Chapter 99 numbers, in the order CBP wants them declared, and the claims you could file to remove one.

JSON
{
  "data": {
    "hsCode": "6109100012",
    "hsCodeFormatted": "6109.10.00.12",
    "originCountry": "CN",
    "destinationCountry": "US",
    "currency": "USD",
    "exchangeRate": 1,
    "transportMode": "air",
    "shipmentChannel": "courier",
    "shippingTerms": null,
    "deMinimis": null,
    "customsValue": 100,
    "lines": [
      {
        "kind": "duty",
        "name": "Customs duty",
        "type": "CUSTOMS_DUTY",
        "code": "61091000",
        "rate": "16.5%",
        "amount": 16.5,
        "agreement": null
      },
      {
        "kind": "duty",
        "name": "Section 301 forced labour, China (12.5%)",
        "type": "S301_FORCED_LABOUR",
        "code": "9903.05.31",
        "rate": "12.5%",
        "amount": 12.5,
        "agreement": null,
        "legalBasis": "Section 301 (failure to prohibit imports made with forced labour, 60 economies); USTR notice 91 FR 47318 (FR 2026-15181); CBP CSMS 69326983; HTSUS ch. 99 subch. III U.S. note 52",
        "sourceUrl": "https://www.federalregister.gov/d/2026-15181"
      },
      {
        "kind": "duty",
        "name": "Section 301 China, list 4A (7.5%)",
        "type": "S301_CN",
        "code": "9903.88.15",
        "rate": "7.5%",
        "amount": 7.5,
        "agreement": null,
        "legalBasis": "Section 301 (China: technology transfer, IP and innovation); continued by USTR on 2026-10-07 (91 FR 64212, FR 2026-20510); HTSUS ch. 99 subch. III U.S. notes 20 and 31",
        "sourceUrl": "https://www.federalregister.gov/d/2026-20510"
      }
    ],
    "totals": {
      "goods": 100,
      "shipping": 15,
      "insurance": 0,
      "duties": 36.5,
      "fees": 0,
      "taxes": 0,
      "dutiesTaxesFees": 36.5,
      "landedCost": 151.5
    },
    "notes": [],
    "upstreamRequestId": null,
    "dataSource": {
      "version": "HTS 2026 Revision 7",
      "importedAt": "2026-10-14T18:04:08.512Z",
      "datasets": [
        {
          "dataset": "US:hs",
          "seq": 42,
          "releaseId": "01a1502a-2fb3-7e6b-8e4d-a46e75afb07b",
          "version": "HTS 2026 Revision 7",
          "liveSince": "2026-10-14T18:04:08.512Z"
        }
      ]
    },
    "engine": "borderbot",
    "schedule": "US",
    "region": null,
    "entryDate": "2026-10-20",
    "entryType": "informal",
    "declaration": {
      "type": "simplified",
      "term": "informal entry"
    },
    "filing": {
      "method": "electronic",
      "preparedBy": "declarant"
    },
    "estimated": false,
    "needs": [],
    "sources": [
      {
        "label": "USITC Harmonized Tariff Schedule (HTSUS)",
        "url": "https://hts.usitc.gov/"
      },
      {
        "label": "Section 301 forced labour, China (12.5%)",
        "url": "https://www.federalregister.gov/d/2026-15181"
      },
      {
        "label": "Section 301 China, list 4A (7.5%)",
        "url": "https://www.federalregister.gov/d/2026-20510"
      }
    ],
    "sellerTaxes": 0,
    "flatDuty": null,
    "validation": [],
    "regulatory": [],
    "tradeAgreement": null,
    "rateFound": true,
    "availableExemptions": [
      "9903.05.91",
      "9903.05.92"
    ],
    "options": [],
    "claims": {
      "available": [
        {
          "code": "9903.05.91",
          "name": "Donations to relieve human suffering",
          "affects": "Section 301 forced labour, China (12.5%)",
          "affectsCode": "9903.05.31",
          "kind": null,
          "legalBasis": null,
          "sourceUrl": "https://www.federalregister.gov/d/2026-15181",
          "proof": null,
          "condition": "Only if the goods are donations of articles, such as food, clothing and medicine, intended to be used to relieve human suffering (50 U.S.C. 1702(b)(2))."
        }
      ],
      "applied": []
    },
    "entryCodes": [
      {
        "code": "9903.05.31",
        "role": "additional",
        "name": "Section 301 forced labour, China (12.5%)",
        "type": "S301_FORCED_LABOUR",
        "lines": [
          "9903.05.31"
        ]
      },
      {
        "code": "9903.88.15",
        "role": "additional",
        "name": "Section 301 China, list 4A (7.5%)",
        "type": "S301_CN",
        "lines": [
          "9903.88.15"
        ]
      },
      {
        "code": "6109100012",
        "role": "tariff",
        "name": "Customs duty",
        "type": "CUSTOMS_DUTY",
        "lines": [
          "61091000"
        ]
      }
    ],
    "entryCodeOrder": {
      "label": "CBP CSMS #69668138: order of reporting multiple HTS numbers",
      "url": "https://content.govdelivery.com/bulletins/gd/USDHSCBP-4270d2a"
    }
  },
  "credits": {
    "charged": 1,
    "remaining": 97,
    "usageId": "usg_01m5dc29tdkdmpffnd43jmg1w5"
  },
  "replayed": false
}

8 or 10 digits#

Duty rates are set at the national line. In the US the general rate sits at 8 digits, so 6109.10.00 and 6109.10.00.12 give the same duty. The 10-digit statistical suffix is what you declare, and agency flags (such as CPSC's eFiling list) and some exclusions are set at 10 digits, so send the full code when you have it.

Costs and limits#

A line costs 1 credit (GET /v1/pricing); a shipment costs 1 credit per line. Duty stacking is free unless your pricing says otherwise. A destination border.bot doesn't calculate returns 422 unsupported_country without charging. See credits and retries.

Also from#

  • MCP: calculate_landed_cost and calculate_cart (see MCP).
  • No code yet? Classify first, or calculate a catalogue product by sku to use its approved code.

Last updated