FreightUtils Customs API
The Customs API from FreightUtils — 1 operation(s) for customs.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/freightutils-com:freightutils-com-customs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: FreightUtils Customs API
description: 'The neutral freight reference layer for AI agents: reference and calculation APIs for dangerous goods, customs, locations and freight math that agents can call and cite. No freight to sell, no carrier to push. Anon 25/day per IP, free key 100/day, Pro 50k/month — freightutils.com/pricing.'
version: 1.0.0
contact:
name: FreightUtils
url: https://www.freightutils.com
email: contact@freightutils.com
license:
name: Free to use
url: https://www.freightutils.com/api-docs
servers:
- url: https://www.freightutils.com
description: Production
security:
- {}
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Customs
paths:
/api/duty:
post:
summary: UK import duty and VAT estimator
description: 'Estimate UK import duty and VAT from the live GOV.UK Trade Tariff. Only ad valorem duties are computed: a specific or compound duty (sugar 1701991000: "35.00 GBP / 100 kg") is answered duty_status "unsupported" with the HMRC expression quoted and figures null, never 0.'
operationId: estimateDuty
tags:
- Customs
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
required:
- commodity_code
- origin_country
- customs_value
properties:
commodity_code:
type: string
pattern: ^(?:\s*\d){6,10}\s*$
description: UK commodity code. A declarable code is 10 digits; a 6- or 8-digit code is refused with HTTP 400 and declarable_codes — the 10-digit codes beneath it in the UK Trade Tariff — never padded with zeros.
example: '6204430000'
origin_country:
type: string
example: CN
customs_value:
type: number
example: 10000
description: Goods value in GBP, greater than 0 — a number, or its digits as text. Anything else is refused with 400.
freight_cost:
type: number
example: 500
minimum: 0
description: Freight cost in GBP, 0 or more (default 0). A negative or non-numeric cost is refused with 400 — it would change the CIF value duty is charged on.
insurance_cost:
type: number
example: 50
minimum: 0
description: Insurance cost in GBP, 0 or more (default 0). A negative or non-numeric cost is refused with 400 — it would change the CIF value duty is charged on.
incoterm:
type: string
example: FOB
- type: object
required:
- lines
additionalProperties: false
description: 'Batch: up to 10 lines, each a single-call body, answered as results[] in input order (each line its own receipt). One call against the daily budget, N against Pro monthly.'
properties:
lines:
type: array
minItems: 1
maxItems: 10
items:
type: object
responses:
'200':
description: Duty and VAT estimate. duty_status "ok" (ad valorem, figures computed) or "unsupported" (duty_form specific | compound | other, duty_expression quoted, figures null).
headers:
X-FreightUtils-Upstream:
$ref: '#/components/headers/X-FreightUtils-Upstream'
'400':
description: 'Invalid parameters: a commodity_code that is not 10 digits (a 6- or 8-digit code is refused with declarable_codes, the 10-digit codes beneath it in the UK Trade Tariff), an origin_country that is not ISO 3166-1, a customs_value not above 0, or a negative cost.'
'404':
description: 'HMRC answered 404: the 10-digit commodity code is not in the UK Trade Tariff (with a hint naming declarable codes under it where there are any).'
'424':
description: 'Only with ?if_stale=refuse: a dataset of the answer missed its upstream window.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/StaleUpstreamProblem'
'429':
$ref: '#/components/responses/RateLimited'
'503':
description: 'The UK Trade Tariff (HMRC) did not answer (network failure, timeout, 5xx or 429). {error:"upstream_unavailable", message, retryable:true, upstream, upstream_status}; Retry-After: 60. The commodity code was not checked — this is never a "not found". Envelope: UPSTREAM_UNAVAILABLE.'
parameters:
- $ref: '#/components/parameters/Envelope'
- $ref: '#/components/parameters/ClientLabel'
- $ref: '#/components/parameters/IfStale'
components:
schemas:
StaleUpstreamProblem:
type: object
description: HTTP 424 problem details, only for a caller who sent ?if_stale=refuse while a dataset of the answer missed its upstream window. Not retryable in seconds. Without the parameter the same request is answered, marked stale.
required:
- type
- title
- status
- code
- detail
- datasets
properties:
type:
type: string
title:
type: string
status:
type: integer
enum:
- 424
code:
type: string
enum:
- stale_upstream
detail:
type: string
datasets:
type: array
items:
type: object
properties:
dataset:
type: string
state:
type: string
last_success:
type:
- string
- 'null'
window_days:
type:
- number
- 'null'
editions_held:
type: array
items:
type: string
state_read_at:
type:
- string
- 'null'
instance:
type: string
RateLimitError:
type: object
required:
- error
- message
properties:
error:
type: string
example: rate_limited
message:
type: string
tier:
type: string
example: anon
limit:
type: integer
window:
type: string
example: 1d
reset_at:
type: string
description: UTC time the allowance resets.
upgrade_url:
type: string
signup_url:
type: string
docs_url:
type: string
retry_after_seconds:
type: integer
parameters:
Envelope:
name: envelope
in: query
required: false
description: 'Response envelope: 1 (byte-stable), 1.1, or 1.2 (adds status, missing_inputs, edition, as_of). Omit for the plain body.'
schema:
type: string
enum:
- '1'
- '1.1'
- '1.2'
ClientLabel:
name: client
in: query
required: false
description: Optional caller label (up to 40 characters of A-Za-z0-9._-) so your calls are recognisable in our usage figures. Changes no answer. The X-FreightUtils-Client header does the same.
schema:
type: string
maxLength: 40
pattern: ^[A-Za-z0-9._-]{1,40}$
IfStale:
name: if_stale
in: query
required: false
description: 'refuse: answer HTTP 424 (stale_upstream) instead of serving stale while a dataset of this answer missed its upstream check window. Omit it (the default) to be served from the last verified edition with stale: true.'
schema:
type: string
enum:
- refuse
headers:
X-FreightUtils-Upstream:
description: 'The upstream state of the datasets this answer was drawn from: the UpstreamMeta object as compact JSON, on every REST answer of a record lookup and of a calculator that read a served dataset (absent when it read none, e.g. a container check digit).'
schema:
type: string
responses:
RateLimited:
description: 'Rate limited: the daily (or monthly) allowance or a burst window is spent. Retry after Retry-After seconds, or send a key.'
headers:
Retry-After:
schema:
type: integer
X-RateLimit-Limit:
schema:
type: integer
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: 'Free or Pro API key (fu_…). Optional: without one a call is anonymous (25/day per address).'
BearerAuth:
type: http
scheme: bearer
description: 'The same key as Authorization: Bearer fu_…'