border.bot
Docs menu

API reference

API reference

Calculate a whole shipment

POST https://staging-api.border.bot/v1/calculate/shipment

Requires an API key (Authorization: Bearer bb_live_…).

Duties, taxes, fees and the landed cost of a cart or order to one destination: up to 50 lines (by their facts, or catalogue products by sku), freight and insurance shared out by value, one de minimis check, and per-entry fees charged once. Costs 1 credit per line. Priced on border.bot’s own data: a destination it doesn’t cover yet returns 422 unsupported_country without charging.

API key scope: calculate.

Headers#

Name Type Required Description
idempotency-key string no Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).

Request body (JSON)#

Name Type Required Description
destinationCountry string yes Destination: one GET /countries marks landedCost. ISO 3166-1 alpha-2, case-insensitive.
currency string no ISO 4217 currency of value, shippingCost and insuranceCost.
shippingCost number no Shipping cost (affects CIF-based duty/VAT bases).
insuranceCost number no Insurance cost.
transportMode "air" | "sea" | "road" | "rail" no Transport mode (fees such as HMF apply to sea freight).
shippingTerms "EXW" | "FCA" | "FAS" | "FOB" | "CFR" | "CIF" | "CPT" | "CIP" | "DAP" | "DPU" | "DDP" no Incoterm of the price (Incoterms 2020). Under C and D terms (CFR, CIF, CPT, CIP, DAP, DPU, DDP) the price already carries the goods to the destination, so shippingCost isn’t added to the customs value again.
shipmentChannel "courier" | "postal" | "freight" no How the goods travel and clear: courier (an express consignment: DHL, UPS, FedEx…), postal (national post) or freight (cargo on its own entry). Omitted: from transportMode — air is courier, sea, road and rail are freight (sea cargo is never an express consignment, so courier by sea is priced as freight). Affects de minimis and fees (US: the informal-entry MPF, 19 CFR 24.23(b)(2), is charged on freight; express consignments pay the carrier’s per-waybill fee, 24.23(b)(4)). The result’s shipmentChannel says which was used.
entryDate string no Calculate with the rates in force on this date (YYYY-MM-DD). Default: today.
tradeAgreement string no Ignored. Preferential rates are applied automatically from the origin and destination; the agreement used is returned as tradeAgreement.
region string no State, province or territory, where import taxes differ inside the country. Canada needs one (ON, QC, BC…).
purpose "sale" | "gift" | "sample" | "return" no Why the goods are sent: some thresholds differ for gifts, samples and returns. Default: sale. A gift is a personal gift, not something bought: a free gift with a purchase is sale (or set giftInConjunctionWithPurchase).
sender "person" | "business" no Who sends the goods: a private person or a business. Gift exemptions are usually for gifts from a person (US: up to $100 per recipient per day, 19 CFR 10.152); a gift from a business qualifies only on the declaration the destination accepts, claimed in claims (US: gift_statement, the parcel clearly marked as a gift with a statement enclosed, 19 CFR 10.153(c)). Left out, a gift exemption limited to some senders is applied and the result is estimated.
giftInConjunctionWithPurchase boolean no The gift is given in conjunction with a purchase (a bonus or free article with an order). It isn’t a gift for customs (US 19 CFR 10.153(a)): gift exemptions don’t apply and the goods are treated as sold.
businessBuyer boolean no The buyer is a business: some taxes are reverse-charged or apply differently.
sellerRegistrations string[] no Tax schemes the seller is registered for (EU_IOSS, GB_VAT, AU_GST, NZ_GST, NO_VOEC…). Taxes the seller collects at checkout are returned with collectedBy: "seller".
preference string no best (default): the lowest preferential rate the origin qualifies for. none: the general rate only. Or a programme code (S for USMCA into the US). Every option is returned in options.
claims string[] no Exemption, relief and quota codes being claimed (US Chapter 99 exclusions such as 9903.88.69; an end-use authorisation such as TARIC document N990; a tariff quota order number such as 050331). Codes you could claim are returned in claims.available.
enforceValidation boolean no Refuse a shipment that matches one of the destination’s reject validation rules (400 invalid_input, details.reason: "validation_failed", refunded) instead of reporting it in validation.
declarationType "full" | "simplified" no The declaration the goods are entered on, when known: full (US formal entry) or simplified (US informal entry). Default: what the destination’s value rules require. A full declaration may always be chosen; a simplified one the value rules out is ignored (see notes). Fees differ by declaration (US MPF, the cotton assessment).
filing object no How the declaration is filed, when known: method electronic or paper, preparedBy declarant or authority (a customs officer). Default: the destination’s usual filing (electronic, by the declarant). The US informal-entry MPF differs by both.
items object[] yes The shipment’s lines (up to 50), each with its code, origin and line value, or a catalogue sku (or productId) and quantity. Freight and insurance are shared out by value.

Responses#

  • 200: The shipment’s landed cost, line by line, and the credits charged. (CalculateShipmentResponse)
  • 400: Invalid input (invalid_input). (Error)
  • 401: Missing, invalid, revoked or expired API key (unauthorized). (Error)
  • 402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
  • 403: Workspace suspended, action disabled, or the key lacks the scope (org_suspended, action_disabled, forbidden). (Error)
  • 409: A request with this Idempotency-Key is still in progress (conflict). (Error)
  • 422: Destination not covered by border.bot’s own data (unsupported_country). (Error)
  • 429: Rate limited (rate_limited). Retry after Retry-After seconds; RateLimit says which limit was hit (r=0, t seconds until its window ends) and RateLimit-Policy its quota. (Error)
  • 500: Unexpected error (internal). (Error)
  • 502: The engine failed (upstream_error). The credits are refunded automatically. (Error)
  • 504: The engine timed out (upstream_timeout). The credits are refunded automatically. (Error)

Example#

bash
curl -X POST 'https://staging-api.border.bot/v1/calculate/shipment' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"destinationCountry":"GB","currency":"USD","shippingCost":12,"items":[{"hsCode":"6109.10","originCountry":"CN","value":60,"quantity":3},{"hsCode":"6204.62","originCountry":"BD","value":45}]}'