Customs Duty API

Pricing

Simple, transparent pricing. No per-transaction fees. No annual contracts.

Quick Start

Get your API key by signing up at customs-compliance.ai/app, then start making requests:

# Get landed cost for importing smartphones (HS 8517) from China to India
curl -X POST https://epytgmksddhvwziwxhuq.supabase.co/functions/v1/tariff-lookup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity_code": "85171400",
    "import_country": "IN",
    "export_country": "CN",
    "customs_value": 10000,
    "currency": "USD"
  }'

# Python
import requests

response = requests.post(
    "https://epytgmksddhvwziwxhuq.supabase.co/functions/v1/tariff-lookup",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "commodity_code": "85171400",
        "import_country": "IN",
        "export_country": "CN",
        "customs_value": 10000,
        "currency": "USD"
    }
)
print(response.json())

// JavaScript (Node.js / browser)
const response = await fetch(
  "https://epytgmksddhvwziwxhuq.supabase.co/functions/v1/tariff-lookup",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      commodity_code: "85171400",
      import_country: "IN",
      export_country: "CN",
      customs_value: 10000,
      currency: "USD"
    })
  }
);
const data = await response.json();
console.log(data);

Authentication

All requests require an API key in the X-API-Key header:

X-API-Key: ci_live_your_key_here

Get your key by signing up at customs-compliance.ai/app. Free accounts get 50 lookups per month.

1. Tariff Lookup — Landed Cost

Returns the complete landed cost breakdown for any commodity imported into any of 51 countries. Includes customs duty, VAT/GST, anti-dumping duties, exemptions, drawback rates, and required import documents.

Request Parameters

Parameter	Type		Description
commodity_code	string	Required	HS code (any length — auto-matched to the country's national format). Accepts 4, 6, 8, or 10 digits.
import_country	string	Required	2-letter ISO code of the importing country (e.g. IN, GB, US, BR)
export_country	string	Optional	2-letter ISO code of the exporting country. Required for preferential rates, anti-dumping, and origin-specific measures.
customs_value	number	Optional	CIF value in the specified currency. Omit for rates-only response (no monetary amounts calculated).
currency	string	Optional	Currency code. Default: USD. Supported: USD, EUR, GBP, INR, ZAR, BRL, CNY, JPY, AED.

Logistics Parameters (Optional)

Include any of these to get a full landed cost with freight, insurance, port handling, and brokerage. When omitted, only border costs (duties + taxes) are returned.

Parameter	Type		Description
incoterm	string	Optional	Incoterm code: EXW, FOB, CIF, DDP, CFR, DAP, etc. Default: FOB. Determines which logistics costs the buyer bears.
origin_port	string	Optional	Port of loading — UN/LOCODE (e.g. CNSHA = Shanghai, INNSA = Nhava Sheva). Gives port-to-port freight rates.
dest_port	string	Optional	Port of discharge — UN/LOCODE (e.g. GBFXT = Felixstowe, USLAX = Los Angeles).
container_type	string	Optional	20FT, 40FT (default), 40HC, LCL, or AIR_KG
transport_mode	string	Optional	SEA (default), AIR, RAIL, or ROAD
freight	number	Optional	Your actual freight cost in USD. Overrides the benchmark estimate.
insurance	number	Optional	Your actual insurance cost in USD. Overrides the auto-estimate.
goods_category	string	Optional	GENERAL (default), HAZMAT, REEFER, HIGH_VALUE, FRAGILE, PERISHABLE
weight_kg	number	Optional	Cargo weight in kg. Used for air freight calculations.
volume_cbm	number	Optional	Cargo volume in CBM. Used for LCL calculations.
inland_origin	number	Optional	Inland transport cost at origin (USD).
inland_dest	number	Optional	Inland transport cost at destination (USD).

Response — Rates Only

200 OK

{
  "status": "OK",
  "mode": "rates_only",
  "input": {
    "commodity_code": "85171400",
    "import_country_name": "India",
    "export_country_name": "China",
    "commodity_description": "Telephone sets, smartphones",
    "valuation_basis": "CIF"
  },
  "duty": {
    "mfn_rate_pct": 15.0,
    "effective_rate_pct": 15.0,
    "exemption_rate_pct": null,
    "sws_rate_pct": 1.5,
    "pref_rate_pct": null,
    "pref_agreement": null
  },
  "indirect_tax": {
    "taxes": [{
      "tax_type": "GST",
      "rate_pct": 18.0,
      "basis": "CUSTOMS_VALUE_PLUS_DUTY"
    }]
  },
  "trade_remedies": { "measures": [] },
  "drawback": {
    "drawback_rate_pct": 2.5,
    "drawback_cap_amt": 18.50,
    "drawback_cap_currency": "INR"
  },
  "import_conditions": [
    { "document_code": "BOE", "description": "Bill of Entry (ICEGATE)", "mandatory": true },
    { "document_code": "BIS-CRS", "description": "BIS Registration (Compulsory Registration Scheme)", "mandatory": true }
  ],
  "summary": {
    "effective_duty_rate_pct": 15.0,
    "sws_rate_pct": 1.5,
    "vat_rate_pct": 18.0,
    "total_border_rate_pct": 34.5
  }
}

Response — Full Calculation (with customs_value)

200 OK

// When customs_value is provided, summary includes monetary amounts:
"summary": {
  "mode": "full_calculation",
  "customs_value": 10000,
  "duty_amount": 1500.00,
  "sws_amount": 150.00,
  "vat_amount": 2097.00,
  "total_border_cost": 3747.00,
  "total_landed_cost": 13747.00,
  "border_cost_pct": 37.47,
  "currency": "USD"
}

Response — Full Calculation with Logistics

When logistics parameters are included, the response gains a logistics block and additional summary fields:

200 OK

// When incoterm, container_type, or other logistics params are included:
"summary": {
  "customs_value": 10000,
  "duty_amount": 400.00,
  "vat_amount": 0.00,
  "total_border_cost": 400.00,
  "total_landed_cost": 10400.00,
  // Logistics fields (only when logistics params provided):
  "freight_usd": 2500.00,
  "insurance_usd": 50.00,
  "port_handling_usd": 380.00,
  "brokerage_usd": 150.00,
  "logistics_cost_usd": 3130.00,
  "incoterm": "FOB",
  "is_logistics_estimate": true,
  "total_true_landed_cost": 13530.00
},
"logistics": {
  "status": "OK",
  "incoterm": "FOB",
  "buyer_bears": { "freight": true, "insurance": true, "import_duty": true, ... },
  "freight": {
    "amount_usd": 2500.00,
    "source": "FBX_BENCHMARK",
    "container_type": "40FT",
    "transit_days_min": 20,
    "transit_days_max": 25
  },
  "insurance": { "amount_usd": 50.00, "rate_pct": 0.35 },
  "port_handling_dest": { "amount_usd": 380.00 },
  "brokerage": { "amount_usd": 150.00 },
  "documentation": { "amount_usd": 50.00 },
  "total_logistics_usd": 3130.00,
  "cif_value_usd": 12550.00,
  "is_estimate": true,
  "disclaimer": "Freight rates are benchmark estimates..."
}

2. Classify — Product Description to HS Code

Given a product description in plain English, returns the best-matching HS code with confidence score and country-specific MFN rate. Uses a 3-stage pipeline: cache → vector search → Claude AI.

Request Parameters

Parameter	Type		Description
description	string	Required	Product description in plain English. More detail = better accuracy.
country	string	Optional	2-letter ISO code. Default: ZA. Returns the country-specific commodity code and MFN rate.

Response

200 OK

{
  "status": "ok",
  "suggestions": [
    {
      "commodity_code": "20041010",
      "subheading_code": "200410",
      "confidence": 0.94,
      "reasoning": "Frozen potato products, prepared or preserved",
      "mfn_rate": 30.0,
      "source": "VECTOR"
    }
  ]
}

Confirm a Classification

After the user selects the correct code, confirm it to cache for instant future lookups:

{
  "confirm_code": "20041010",
  "description": "Frozen potato chips, pre-cooked, in 25kg bags",
  "country": "IN"
}

3. Enrich PO — Purchase Order Customs Intelligence

Enriches a purchase order (or any list of line items) with full customs intelligence: auto-classifies HS codes, calculates landed costs, checks for trade remedies, lists required documents, and identifies savings opportunities. Optionally includes freight & logistics for true landed cost.

Request Parameters

Parameter	Type		Description
import_country	string	Required	2-letter ISO code of the importing country
export_country	string	Optional	2-letter ISO code of the default exporting country (can be overridden per line)
currency	string	Optional	Currency code. Default: USD
lines	array	Required	1-50 line items (see below)
incoterm	string	Optional	PO-level incoterm (e.g. FOB, CIF). Triggers logistics calculation.
origin_port	string	Optional	Port of loading UN/LOCODE
dest_port	string	Optional	Port of discharge UN/LOCODE
container_type	string	Optional	20FT, 40FT, 40HC, LCL, AIR_KG
freight	number	Optional	Your actual total freight cost (USD). Overrides benchmark.
insurance	number	Optional	Your actual insurance cost (USD).

Line Item Fields

Field	Type		Description
line_id	string	Required	Unique line identifier
description	string	Required*	Product description (used for AI HS classification)
hs_code	string	Optional	Pre-classified HS code. If provided, skips AI classification.
total_value	number	Optional	Line total value (for duty amount calculation)
supplier_country	string	Optional	Override export country for this specific line

Response

200 OK

{
  "status": "OK",
  "summary": {
    "total_lines": 3,
    "classified_lines": 3,
    "total_goods_value": 15000,
    "total_duty": 600.00,
    "total_tax": 0.00,
    "total_landed_cost": 15600.00,
    // When logistics params included:
    "freight_usd": 2500.00,
    "insurance_usd": 55.00,
    "logistics_cost_usd": 3185.00,
    "total_true_landed_cost": 18785.00,
    "documents_needed": ["Commercial Invoice", "Bill of Lading", "Certificate of Origin"],
    "sanctions_clear": true
  },
  "lines": [
    {
      "line_id": "1",
      "classification": { "hs_code": "0904120000", "confidence": 0.75, "source": "TEXT_MATCH" },
      "duty": { "mfn_rate_pct": 4.0, "effective_rate_pct": 4.0 },
      "amounts": { "goods_value": 5000, "duty_amount": 200, "total_landed_cost": 5200 },
      "logistics_allocation": { "freight_share": 833, "total_true_landed": 6261 },
      "documents_required": [...],
      "savings_opportunities": [...]
    }
  ],
  "declaration": { // WCO Data Model 3.0 aligned customs declaration JSON }
}

4. Opportunities — Trade Intelligence Feed

Returns personalised trade opportunities based on the tenant's product catalogue, trade routes, and ERP data. Includes FTA savings, duty reductions, new market signals, and competitor disadvantages.

200 OK

{
  "opportunities": [
    {
      "type": "NEW_FTA",
      "title": "FTA savings on flat-rolled steel to South Africa",
      "saving_pct": 10.0,
      "commodity_code": "7210",
      "route": "GB → ZA",
      "agreement": "SACU-EPA",
      "ai_insight": "Based on your Xero purchase history, you import £45K/year of steel from UK suppliers..."
    }
  ]
}

4. Alerts — Tariff Change Notifications

Returns active trade alerts: duty increases, new anti-dumping duties, expiring preferences, sanctions changes, and regulatory updates relevant to the tenant's trade profile.

Error Responses

404 Not Found

{
  "status": "error",
  "error": "Commodity code 99999999 not found for IN"
}

403 Sanctions Block

{
  "status": "BLOCKED",
  "blocked_reason": "SANCTIONS",
  "message": "This trade route is subject to active sanctions. Do not proceed."
}

Supported Countries

51 countries with national tariff data, preferential rates, and import conditions:

HS Code Resolution

You don't need the exact national code format. The API accepts any length and resolves to the best match:

Input	Resolves to	Example
4-digit heading	First leaf commodity	8517 → 85171400
6-digit subheading	Best national match	850511 → 85051110
8-digit code	Exact match	85051110 → 85051110
10-digit code	Trimmed to match	8505111000 → 85051110

Rate Limits

Plan	Lookups/month	Rate
Free	50	5 req/min
Pro	500	30 req/min
Business	2,000	60 req/min
Enterprise	Unlimited	120 req/min