API
Duty calculations and usage as JSON, for partners who run CustomsGenius inside their own product. Every call is served from https://app.customsgenius.com.
A partner holds one key (cgp_...), issued under the partner agreement. The key is a server secret: it mints short-lived tokens and reads usage, and it never reaches a browser. The token does the calculating, bound to one of your users. To get a key, write to team@customsgenius.com.
1. Mint a token
POST/api/partner/embed-token with the key as the bearer. Once per user session, from your server.
POST /api/partner/embed-token
Authorization: Bearer cgp_...
Content-Type: application/json
{ "userId": "your-user-id", "userLabel": "optional, for support", "userClass": "staff" }
{ "token": "eyJhbGciOi...", "expiresAt": "2026-10-14T12:25:49.000Z",
"embedUrl": "https://app.customsgenius.com/embed/calculator?token=eyJhbGciOi..." }
The token lives 12 hours. userId is your own opaque id (1 to 128 characters, not starting with demo-link-, which names our demo visitors); usage is reported per userId. embedUrl frames the full calculator in your colors if you want the screen rather than the numbers.
userClass is optional: "staff" for your own people, "customer" for your customers. Staff see the bulk upload in the frame and may call the bulk upload endpoint (/api/embed/tariff-simulator-bulk, the same form the frame posts); customers get the single calculator, and that endpoint answers 403 for their tokens. A token minted without the field takes the default agreed for your key.
2. Calculate
POST/api/embed/tariff-simulate with the token as the bearer.
POST /api/embed/tariff-simulate
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
{ "htsCode": "8479.89.9597", "originCountry": "DE", "value": 25000,
"transportMode": "ocean", "entryDate": "2026-10-13" }
| Field | Meaning |
|---|---|
htsCode | The HTS code, dots optional. At least 8 digits; a partner account may require the full 10. |
originCountry | Country of origin, ISO 3166-1 two letters. Origin, not country of export. |
value | Customs value in US dollars. Omit it for rates only (every amount is null). |
transportMode | ocean, air, rail or truck. Decides the harbor maintenance fee. |
entryDate | YYYY-MM-DD. The duties in force on that date, past dates included. |
The calculator's further inputs (metal content, a USMCA qualification, SPI claims, AD/CVD deposits, the attestations behind each election) ride on the same body; ask us for the list when a screen needs one.
A real answer, trimmed to what a duty display needs:
{
"dutyLines": [
{ "code": "8479.89.9597", "description": "Other", "ratePct": 2.5, "amount": 625 },
{ "code": "9903.05.39", "description": "Section 301 Forced Labor", "program": "Section 301 Forced Labor",
"ratePct": 0, "amount": 0, "preExclusionRatePct": 7.5, "preExclusionAmount": 1875,
"exclusionNote": "Excluded: subject to Section 232 action (9903.05.90, U.S. note 52(f))",
"exclusionClaimCode": "9903.05.90" },
{ "code": "9903.82.10", "description": "Combined 232", "program": "Combined 232", "ratePct": 12.5, "amount": 3125 }
],
"mpf": 86.6, "hmf": 31.25, "totalDuty": 3867.85, "landedCost": 28867.85,
"warnings": [],
"pgaFlags": [ { "flag_code": "FD1", "agency_code": "FDA", "requirement": "may_be_required",
"description": "FDA CLEARANCE MAY BE REQUIRED" } ],
"adCvdWarnings": [],
"ch99DisplayNames": { "9903.82.10": "Section 232 Metals - Derivatives Floor (15%)" }
}
| Field | Meaning |
|---|---|
dutyLines | One row per duty: the HTS line's general rate, then each Chapter 99 program that applies. ratePct is a percent of the customs value, amount is dollars. A program another program excludes stays listed at 0 with exclusionNote, the pre-exclusion figures and the heading the filer claims. |
mpf, hmf | Merchandise processing fee and harbor maintenance fee for the line as its own entry. hmf is null off the water. |
totalDuty | Every duty line plus the two fees. |
landedCost | value plus totalDuty. |
warnings | Sentences worth showing beside the number. Empty when there is nothing to say. |
pgaFlags | Partner government agency flags on the code: agency, requirement (required, may_be_required, informational) and ACE's description. |
adCvdWarnings | Antidumping and countervailing duty orders that may cover the code and origin, with case numbers. A deposit is priced only when the body names the case. |
elections | Claims that would change the duty (a US-content attestation, an FTA claim), each with its code and amount; the default is what dutyLines priced. |
ch99DisplayNames | A display name for each Chapter 99 code in the answer. |
Other fields serve the calculator's own screen (eligibleSpis, mfnAncestorPath, quota and a few more). Ignore them.
3. Email a result
POST/api/embed/send-results with the token as the bearer. The frame's Send control calls it; your backend may too. The message carries your name and logo and the priced table, and no CustomsGenius link. A token from a demo link cannot send (403): only a user your backend named may.
POST /api/embed/send-results
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
{ "to": "buyer@example.com", "sendKey": "a UUID v4 your side mints per send",
"htsCode": "8479.89.9597", "originCountry": "DE", "value": 25000,
"transportMode": "ocean", "entryDate": "2026-10-13",
"rows": [["Code", "Description", "Rate", "Amount"],
["8479.89.9597", "Other", "2.5%", "625.00"],
["Total", "", "", "3,867.85"]] }
rows is the table as shown, header first, four cells a row, at most 80 rows of 240 characters a cell, inside a 64 KB body (413 above it). sendKey is a UUID your side mints per send: a retry with the same key sends once. { "ok": true } on success. An address that opted out of our mail answers 400 with the reason.
4. Saved runs
A user keeps a priced run with the Save glyph on the result; the frame lists the kept runs under the calculator and a click prices them again. Your backend may read and write the same list with the user's token: GET/api/embed/sim-runs answers { "rows": [...] }, newest first, at most 50; POST/api/embed/sim-runs with the calculation's inputs plus totalDuty and landedCost keeps one (the frame also sends the whole form it priced as form, an object under 16 KB, so a replay restores every field; your backend may leave it out); DELETE/api/embed/sim-runs?id=... removes one. Rows are per userId and go with your key; a save past 50 removes the oldest. A token from a demo link has no saved runs (403 with "reason": "demo-link"). Each call spends the user's lookup budget.
5. Usage
GET/api/partner/usage?month=2026-10 with the key as the bearer, or ?from=2026-11-02&to=2026-11-08 for a span of UTC days (to inclusive; a weekly report is Monday to Sunday). One UTC month by default, the current one: one row per userId (calculations, lookups, bulk rows and files, rejected and failed requests, emailed results, first and last seen), token mints, totals, each key's limits, and a breakdown by day.
What your users look up is yours. By default the calculator records that a calculation happened and nothing about what was priced, and the breakdown's detail is false. If you want the ten codes and ten origins priced most in the report, ask us to turn the detail on for your key; detail is then true and topCodes and topOrigins fill.
Errors
| Status | Meaning |
|---|---|
| 400 | An input the engine cannot price. The error sentence names the field. |
| 401 | Missing, invalid or expired token, or an unknown key. Mint again. |
| 403 | The key was revoked, or a customer token called the bulk upload endpoint (error says Staff only; single calculations still work). |
| 429 | A budget is spent. Retry-After says when. |
| 503 | Ours. Retry later. |
Limits
| Budget | Default |
|---|---|
| Token mints | 60 per minute per key |
| Calculations, per partner | 300 per minute |
Calculations, per userId | 30 per minute |
| Usage reads | 30 per minute per key |
Emailed results, per userId | 5 per minute, 50 per day |
| Emailed results, per partner | 500 per day |
Saved runs, per userId | 50 kept; reads and writes on the lookup budget |
| Monthly calculations | uncapped unless agreed |
Every calculation is real and metered, in staging as in production. Cache the answer per line and recompute when an input or the entry date changes. For a batch job, tell us the volume before you build it.