API for calculating US Customs and Border Protection (CBP) duties against the Harmonized Tariff Schedule of the United States (HTSUS).
\nThe endpoints available are:
\nPOST /api/v1/duties/calculate — compute the total duty owed for a single product line, broken down per duty layer (base rate, Ch. 99 supplemental surcharges) and per component (compound and content-based rates).
GET /api/v1/hts-codes — look up a single HTS entry and return its full hierarchical description, accepted units of measure, and the components it requires (if any).
The authentication flow is OAuth 2.0 client-credentials. All requests require Authorization: Bearer .
POST /api/v1/duties/calculate — Calculate dutiesResolves the request's htsCode against the HTSUS data (including chapter 98 replacements and chapter 99 supplementals), and calculates the duties owed based on input data, returning the following information:
htsClassification — the resolved HTS entry.
baseCalculations[] — one entry per base duty layer that contributed to the total.
componentCalculations[] — when the product carries components (compound rates or content-based rates), one entry per component with its HTS code, per-component duty layers, and the component's total duty.
totalDutiesOwed — sum of all baseCalculations[].dutiesOwed and componentCalculations[].dutiesOwed in USD.
Special-case routing: when the request's HTS code falls under Chapter 76 (aluminum articles), the calculator switches to the Section 232 split-duty strategy, which requires the request to supply aluminumSmelt (single-unit aluminum content value, weight in kg, primary country of smelt). When the HTS code resolves to a sliding-duty entry in heading 1701 (raw sugar), the request must supply sugarPolarizationDegree.
GET /api/v1/hts-codes?htsCode={code} — HTS code lookupReference lookup for client integrations to discover what an HTS code resolves to before submitting a calculation request. Accepts the HTS code in either dotted (9101.11.40) or undotted (91011140) form; both are accepted, and returns the following information:
htsCode — the normalized HTS code in canonical dotted format.
text — the full hierarchical description (heading + subheading + tariff line + statistical suffix, concatenated).
unitsOfMeasure — the accepted units of measure for the entry (e.g. [\"Number\"], [\"Kg\"]).
requiredComponents — the components a duty calculation request must supply for this code. Each entry has the component's HTS code and its leaf-level description (not the full path). Empty list when no components are required.
OAuth 2.0 client-credentials flow. Token endpoint:
\nhttps://auth.dutycollection-sandbox.safepackage.com/realms/SafePackage/protocol/openid-connect/tokenSubmit the resulting JWT as Authorization: Bearer on each request.
All 400 Bad Request responses follow the shape { \"errors\": [{ \"code\", \"propertyName\", \"errorMessage\", \"attemptedValue\" }] }. Codes are stable and prefixed V_ for validation failures (e.g. V_InvalidHtsCode, V_HtsCodeNotFound, V_UnitOfMeasureMismatch, V_MissingRequiredComponents, V_CountryNotFound). 404 Not Found is returned without a body for HTS lookups against unknown codes. 401 Unauthorized and 403 Forbidden are returned by the auth middleware before the handler runs.
API access provisioning: api-access@safepackage.com
Technical support: support@safepackage.com
Resolves the request's HTS code against the HTSUS tariff tree and returns the total duty owed for a single product line, broken down by duty layer.
\nproductInfo.htsCode (string, required) — HTS tariff code. Dotted (9101.11.40) or undotted (91011140) — both are accepted.
productInfo.quantity (object, required) — { amount: number > 0, unitOfMeasure: enum }. unitOfMeasure must match the unit required by the resolved tariff entry; mismatches return V_UnitOfMeasureMismatch.
productInfo.singleUnitDeclaredValue (number, required) — declared customs value of a single unit in USD, > 0.
\nproductInfo.countryOfOrigin (string, required) — ISO 3166-1 alpha-2.
\nproductInfo.entryDate (string, required) — ISO 8601 date (YYYY-MM-DD). Determines which HTSUS revision and Ch. 99 supplementals apply.
productInfo.components (array, optional) — required for compound rates (e.g. watches: case, movement, strap, battery) and content-based rates (e.g. lead content in copper ore). Each component carries its own HTS code, optional singleUnitDeclaredValue, and a required quantity representing the quantity per single unit of the parent product (total component count is computed as component.quantity \\* parent.quantity).
productInfo.sugarPolarizationDegree (number 0..100, conditionally required) — required only for Ch. 17 raw sugar sliding rates (heading 1701).
\nproductInfo.aluminumSmelt (object, conditionally required) — required only for Ch. 76 aluminum articles. Carries the aluminum content value per unit, content weight in kg, and the primary country of smelt.
\nhtsClassification — resolved HTS entry: matched HTS code (may differ from the request when the tariff resolves to a parent or a Ch. 98 replacement) and its full hierarchical description.
\nbaseCalculations[] — duty layers driving the base rate, additional duties, and Ch. 99 supplemental surcharges. Each layer: sourceHtsCode, description (leaf-level), dutiesOwed in USD.
componentCalculations[] — per-component duty layers when the product carries components. Each entry: component HTS code, leaf-level description, per-component duty calculations, and the component's dutiesOwed.
totalDutiesOwed — sum of all baseCalculations[].dutiesOwed + componentCalculations[].dutiesOwed in USD.
Validation is assertable by error code (all prefixed V_):
V_ValueEmpty, V_InvalidHtsCode, V_HtsCodeNotFound — HTS code missing, malformed, or unknown.
V_UnitOfMeasureMismatch — the supplied unit does not match the tariff's required unit.
V_InvalidCountryCode, V_CountryNotFound — bad ISO2 or unknown country.
V_ValueMustBeGreaterThanZero — singleUnitDeclaredValue or quantity.amount is zero or negative.
V_DuplicateComponentsNotAllowed, V_InvalidComponentHtsCode, V_MissingRequiredComponents — components list problems.
V_AluminumSmeltDataRequired, V_SugarPolarizationDegreeRequired — Ch. 76 / heading 1701 entries without their required side data.
Reference lookup for a single HTS code. Accepts both dotted (9101.11.40) and undotted (91011140) forms; the request is normalized server-side to the canonical dotted representation before the lookup runs.
^(\\d{4}\\.\\d{2}\\.\\d{2}(\\.\\d{2})?|\\d{8}(\\d{2})?)$.[\"Number\"], [\"Kg\"]).htsCode of the required component and its leaf-level text (not the full hierarchical path). Empty list when no components are required.200 OK — HTS entry resolved.400 Bad Request (V_InvalidHtsCode) — htsCode does not match the regex.404 Not Found — htsCode is well-formed but has no corresponding entry in the tariff tree.401 Unauthorized — missing or invalid bearer token.403 Forbidden — token lacks hts-codes#view permission.