Build production trade
infrastructure.

The TariffOS API is a JSON over HTTPS interface for tariff intelligence, landed-cost computation, and trade compliance. It is the same engine that powers our dashboards, AI assistant, and enterprise integrations — exposed as primitives you can wire into any quoting engine, ERP, or freight platform.

All requests are made against https://api.tariffos.com and require a Bearer token. Responses are JSON, latencies are sub-100ms p95, and the surface area is versioned via the URL.

The console below executes against an in-browser sandbox using mocked responses modeled on the production schema. Swap the placeholder API key for a real sk_test_… sandbox key to hit sandbox.api.tariffos.com directly.

Try it · Sandbox TOSMock

MockLive

Enter Sandbox→

EndpointGET /v2/tariff/lookupPOST /v2/landed-costPOST /v2/classifyGET /v2/fta/eligibilityGET /v2/origin/rulesPOST /v2/scenarios/simulateGET /v2/changes/since

GEThttps://sandbox.api.tariffos.com/v2/tariff/lookup?hs=8703.80&origin=CN&destination=US

API key (placeholder)

Demo only. Production keys grant per-workspace scope.

Query string

▶ Send mock requestCopy as cURL

Response

[ awaiting request ]

Configure inputs and press Send request.

1. Request a key from enterprise sales or hit our self-serve sandbox.
2. Export it as TARIFFOS_KEY.
3. Call POST /v2/landed-cost with an HS code and shipment value.
4. Subscribe to tariff.changed webhooks for ongoing intelligence.

curl https://api.tariffos.com/v2/landed-cost \
  -H "Authorization: Bearer $TARIFFOS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shp_4kJ29fA" \
  -d '{
    "hs_code": "8703.80",
    "origin": "CN",
    "destination": "US",
    "value_usd": 48000,
    "incoterm": "FOB"
  }'

Major versions live in the URL (/v2/…). Field additions and new enum values are non-breaking. Removals or rename ship as /v3 with a 12-month overlap and deprecation headers.

TariffOS supports three auth modes. Use API keys for server-side integrations, OAuth 2.0 for third-party apps acting on behalf of a tenant, and request signing when calling from untrusted edges.

Keys are scoped to an environment and a workspace. Live keys are prefixed sk_live_; sandbox keys are sk_test_. Treat keys as secrets — store them in your platform's secret manager, never in source control.

GET /v2/tariff/lookup?hs=8703.80&origin=CN&destination=US HTTP/1.1
Host: api.tariffos.com
Authorization: Bearer sk_live_REPLACE_ME
Accept: application/json

For partner apps acting on behalf of a TariffOS tenant. Standard OAuth 2.1 with PKCE; access tokens expire in 1 hour, refresh tokens in 60 days.

For environments where a key cannot be embedded (browser SDK, partner edge), sign each request with a short-lived signing secret derived server-side.

{timestamp}.{method}.{path}.{sha256(body)}

X-TariffOS-Signature: t=1714694400,v1=4f2e…c0a1

Subscribe an HTTPS endpoint to receive event notifications. Deliveries are signed with HMAC-SHA256 over the raw request body and a per-endpoint signing secret. Retries follow exponential backoff (1m → 24h) for up to 72 hours.

curl https://api.tariffos.com/v2/alerts/subscribe \
  -H "Authorization: Bearer $TARIFFOS_KEY" \
  -d '{
    "url": "https://hooks.acme.com/tariffos",
    "events": ["tariff.changed", "shipment.recommendation"],
    "filters": { "lanes": ["CN>US", "VN>US"] }
  }'

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req: { headers: Record<string,string>, rawBody: string }, secret: string) {
  const sig = req.headers["x-tariffos-signature"]; // t=...,v1=...
  const parts = Object.fromEntries(sig.split(",").map(p => p.split("=")));
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${req.rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

For low-latency dashboards, stream the same events over Server-Sent Events on GET /v2/stream. Authenticate with a short-lived stream token issued by POST /v2/stream/token.

const es = new EventSource(`https://api.tariffos.com/v2/stream?token=${streamToken}`);
es.addEventListener("tariff.changed", (e) => {
  const change = JSON.parse(e.data);
  console.log("New rate:", change.to_pct);
});

Errors return a stable shape. The code field is the contract — do not branch on message, which is for humans.

{
  "error": {
    "code": "tariff_not_found",
    "message": "No tariff schedule for HS 9999.99 on lane XX>US.",
    "request_id": "req_01HZ…",
    "doc_url": "https://docs.tariffos.com/errors#tariff_not_found"
  }
}

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. On 429, respect Retry-After.

All POST endpoints accept an Idempotency-Key header (UUID v4 recommended). Replays within 24 hours return the original response, including status code. Different payloads under the same key return 409 idempotency_conflict.

List endpoints use cursor pagination. Pass ?limit=100&cursor=… — responses include next_cursor when more pages exist. Maximum page size is 500.

Import the live collection — every endpoint, pre-request scripts for HMAC signing, and example sandbox keys.

https://docs.tariffos.com/postman/tariffos.postman_collection.json

The full machine-readable spec — generate clients, mock servers, or contract tests directly from it.

https://api.tariffos.com/v2/openapi.json
sha256: 9f4c…1ab2

• 2025-04-12ADDEDReciprocal tariff component

  Tariff lookup and landed cost now decompose the new reciprocal-tariff component. Existing fields are unchanged.

• 2025-03-30ADDEDEU residency endpoint

  eu.api.tariffos.com — all data plane traffic stays within EU regions.

• 2025-02-18CHANGEDStable webhook signing v1

  x-tariffos-signature now uses the stable t=…,v1=… format. Legacy x-signature is deprecated for removal 2025-08-01.

• 2025-01-04ADDEDScenario simulate endpoint

  POST /v2/scenarios/simulate — model tariff, FX, and sourcing overrides across portfolios.