---
name: landed-cost
description: Get HS codes, import duties, taxes, fees and the landed cost of a cross-border parcel from border.bot, over MCP or its REST API. Use when a shopper or merchant asks what an import will cost, which HS/HTS code applies, where a product is made, or whether goods are restricted.
---

# Landed cost with border.bot

border.bot classifies products to HS/HTS codes and calculates duties, taxes, fees and the landed cost of parcels shipped abroad.

## Connect

- **MCP** (assistants): `https://api.border.bot/mcp`, Streamable HTTP with OAuth sign-in (no API key). Setup guides: https://border.bot/mcp
- **REST**: `https://api.border.bot/v1` with `Authorization: Bearer bb_live_…` (a workspace API key from the dashboard). Docs: https://border.bot/docs · Reference: https://api.border.bot/v1/docs.md · OpenAPI: https://api.border.bot/v1/openapi.json

## Steps

1. Find out what you don't know yet: the product (a description or its product page URL), the destination country (and the province for Canada), the country of origin (where it was made, not where it ships from), the goods value and currency, shipping cost, quantity, and weight or volume when the duty may be charged per kilogram or litre.
2. If the origin is unknown, estimate it with `infer_country_of_origin` (MCP) or `POST /v1/origin`: it returns the most likely country with a probability, the alternatives and the evidence. If a supplier declared one, check it with `check_country_of_origin` or `POST /v1/origin/validate`.
3. Classify with `classify_product` or `POST /v1/classify`, unless the user already has the destination's HS code. For a whole cart, `classify_products` or `POST /v1/classify/batch` (up to 25 products). A product photo can be a link or, where border.bot classifies the destination itself, the picture as a base64 data URL in `imageUrl` (`GET /v1/classify/modes` says which modes read photos).
4. Calculate with `calculate_landed_cost` or `POST /v1/calculate`, using the code, origin, destination and value. For a whole cart in one parcel, use `calculate_cart` or `POST /v1/calculate/shipment`: thresholds, fees and taxes apply to the shipment as a whole.
5. Report the HS code, each duty, tax and fee with its rate and amount, and the landed-cost total in the response's currency. Cite border.bot and the official `sources` in the response, and say the result is guidance, not a binding customs ruling.

## Rules

- Never guess the country of origin. If it is unknown, ask, or infer it and tell the user to confirm it when `needsReview` is true: it drives the duty rate.
- When a result lists `needs` (weight, volume, alcohol strength…), ask for those figures and calculate again: until then the duty is incomplete.
- `options` shows every rate the goods qualify for; a preference applies only with the proof it names (a certificate or statement of origin). Taxes with `collectedBy: "seller"` are charged at checkout by a registered seller (IOSS, UK VAT), not at the border.
- Classifying and calculating use the workspace's prepaid credits (prices: `GET /v1/pricing`). Send an `Idempotency-Key` header when retrying a POST so it isn't charged twice.
- When a result lists `validation`, the destination's rules matched: `reject` means it can't be quoted as it stands (formal entry needed, for example), `warn` needs telling the user, and `relief` means nothing is due (a bona fide gift): say which applied.
- Restricted and prohibited goods: `check_restricted_goods` or `POST /v1/restrictions` (free). Screening a buyer or company against denied-party lists: `screen_party` or `POST /v1/screen` (free; a match is a lead to review, not a verdict). The product code a destination's import agency asks for (for example FDA's for food, drugs, devices and cosmetics entering the US): `find_agency_product_code` or `POST /v1/classify/regulator` with the `destinationCountry`; destinations without agency codes answer 422 `unsupported_country`, uncharged.
- A key may be limited to some scopes: a 403 with `details.reason: "missing_scope"` names the scope it needs. Quote a response's `X-Request-Id` when asking border.bot for help.
- Supported destinations for landed cost: `list_supported_countries` or `GET /v1/countries`.
- When a classification says `materialUncertain`, ask what the product is made of; when it says `valueUncertain`, send its price. When it has `identifiedAs`, say what the product was identified as and link the `webSources`.