border.bot
Docs menu

API reference

Get started

Quickstart

Create a border.bot API key, classify a product, then calculate its landed cost, with curl.

1. Create an API key#

Sign in to the dashboard and open Developers → API keys. Create a key for your workspace. It starts with bb_live_ and is shown once, so put it in your secrets manager straight away.

bash
export BORDERBOT_API_KEY=bb_live_...

Check the key works. GET /v1/me is free and returns the workspace, the key's scopes and the credit balance:

bash
curl https://api.border.bot/v1/me \
  -H "Authorization: Bearer $BORDERBOT_API_KEY"

2. Classify a product#

Send a description or a product URL with the destination country. Add the origin if you know it.

bash
curl -X POST https://api.border.bot/v1/classify \
  -H "Authorization: Bearer $BORDERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"description":"Men'\''s cotton crew-neck t-shirt, knitted","destinationCountry":"US","originCountry":"PT"}'

The response has the code in the destination's format, the official description at each level, a confidence score, the reasoning and alternatives. The X-Credits-Charged and X-Credits-Remaining headers say what the call cost.

3. Calculate landed cost#

Pass the code, the origin and destination, the goods value and the shipping cost:

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

You get every duty, tax and fee line with its legal basis and the total landed cost. The reference for this endpoint lists every field, including shipping terms, preferential rates and seller-collected taxes.

Next#

Last updated