API endpoints and SDKs

API endpoints and SDKs

The LandedFees /v1 API exposes five endpoints that map directly to the four product pillars: /v1/calc for single-shipment landed-cost calculations, /v1/calc/bulk for batches, /v1/classify for semantic HS lookup, /v1/compare for side-by-side lane comparison, and /v1/rates for looking up duty rates by country and HS code. Everything is JSON in, JSON out, with API-key authentication and a 60-requests-per-minute rate limit per key.

Full reference documentation with per-endpoint schemas, request examples, and SDK usage lives on docs.landedfees.com, hosted on Mintlify.

The five endpoints

POST /v1/calc runs one landed-cost calculation. Same output shape as the marketing calculator, cited to primary sources.

POST /v1/calc/bulk runs a batch. Synchronous for small batches, async with a job ID for larger runs. The async pattern is documented at /developers alongside the streaming job callback.

POST /v1/classify returns the same three ranked HS code candidates as the calculator's inline semantic lookup.

GET /v1/compare returns a side-by-side lane comparison for two origin-destination-HS combinations.

GET /v1/rates/:country/:hs returns the current duty rate for the country and HS code. Historical rate history is available at GET /v1/rates/history/:country/:hs.

SDKs

TypeScript / JavaScript: pnpm add @landedfees/sdk. Python: pip install landedfees. Both SDKs are thin wrappers over the same JSON API with typed request and response shapes.

Every SDK release maps one-to-one to a live /v1 API version. Breaking changes only ship in a major version bump.

Rate limits

60 requests per minute per API key. Bursts of up to 100 are absorbed if the sliding average stays under 60. Exceeding the limit returns 429 with a Retry-After header. See the 429 rate limit troubleshooting guide.

Tier gate

API access is a Growth tier feature. The api_keys table constraint rejects inserts on Free and Pro. Upgrade to Growth or above to create keys.

Frequently asked questions

Where is the full API reference

docs.landedfees.com. Every endpoint has its own page with request examples in curl, Python, and TypeScript.

Can I use the API without an SDK

Yes. The API is plain JSON over HTTPS. Any HTTP client works. See the curl examples on the docs site.

Is the API stable

/v1 is stable. Fields may be added; existing fields never rename or remove without a version bump.

What is the rate limit for async bulk jobs

Async submission counts as one request. The bulk executor is capped at 10,000 lines per job. Larger runs split into multiple jobs.