REST API for calculating US Customs and Border Protection (CBP) duties against the Harmonized Tariff Schedule of the United States (HTSUS).
\nThe authentication flow is OAuth 2.0 client-credentials. All requests require Authorization: Bearer .
Three endpoints are exposed under /api/v1. See each operation's own description for its request/response contract and validation behavior.
Duties are calculated at the full 10-digit statistical-suffix level. Every HTS code submitted as input — the calculation item's code, its component codes, and the lookup endpoint's code — must be a full 10-digit code, dotted (6201.40.50.11) or plain (6201405011). The single exception: an 8-digit tariff line is accepted for component-rated classifications (e.g. watches, 9101.11.40), where the statistical suffixes identify the article's components rather than the article itself. A broader code is rejected with V_TenDigitHtsCodeRequired.
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\": [{ \"fieldName\", \"rejectedValue\", \"code\", \"message\" }] }. Codes are stable and prefixed V_ for validation failures (e.g. V_InvalidHtsCode, V_HtsCodeNotFound, V_TenDigitHtsCodeRequired, V_DeclaredValueRequired, V_QuantityRequired, V_MutuallyExclusiveProperties, V_MissingRequiredComponents, V_AluminumSmeltDataRequired, V_SteelMeltAndPourDataRequired, V_CountryNotFound). 404 Not Found is returned without a body for HTS lookups against unknown codes. 401 Unauthorized is returned when the bearer token is missing or invalid, and 403 Forbidden when the caller is not permitted to access the resource.
API access provisioning: api-access@safepackage.com
Technical support: support@safepackage.com
Calculates the duty owed for each requested item, broken down by duty layer, plus the grand total across all items. All duty amounts leave the calculator rounded to whole cents (half away from zero); every aggregate is the exact sum of its rounded lines.
\nentryDate (string, conditionally required) — ISO 8601 date (YYYY-MM-DD) for the whole request; selects the tariff rows in effect. Falls back to each item's own deprecated entryDate when omitted; one of the two must be present or the request is rejected with V_ValueEmpty.
items (array, required) — one or more product lines to calculate. Each item carries the fields below.
\nitems[].htsCode (string, required) — full 10-digit HTS tariff code, dotted (6201.40.50.11) or plain (6201405011). An 8-digit tariff line is accepted only for component-rated classifications (e.g. watches, 9101.11.40); any other broader code returns V_TenDigitHtsCodeRequired.
items[].reference (string, optional) — client correlation reference echoed back in the matching itemCalculations[] entry. If omitted, the server assigns a new GUID.
items[].totalDeclaredValue (number, conditionally required) — total transaction value of the goods across the whole line in USD, >= 0. The basis for ad valorem rates; required when any resolved rate is value-based (V_DeclaredValueRequired).
items[].quantities (array, conditionally required) — declared quantities across the whole line, each { amount: number > 0, unitOfMeasure: enum }, at most one per unit of measure. The basis for per-unit rates: a rate that bills per unit requires a quantity in (or convertible to) that unit, otherwise V_QuantityRequired. Mass units (kg, g, t) are converted automatically.
items[].countryOfOrigin (string, required) — ISO 3166-1 alpha-2 uppercase country of origin code.
\nitems[].tradeProgramCode (string, optional) — special program indicator (SPI) from HTSUS general note 3(c)(i) claiming preferential treatment, e.g. 'R' (CBTPA), 'D' (AGOA), 'S+' (USMCA TRQ). Claims only apply when the country of origin is a beneficiary of the claimed program.
\nitems[].components (array, conditionally required) — 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:
\nhtsCode (string, required) — full 10-digit statistical suffix code of the component.
\ndeclaredValue (number, optional) — declared value of this component across the parent item's whole quantity in USD.
\nitems[].sugarPolarizationDegree (number 0..100, conditionally required) — required only for Ch. 17 raw sugar sliding rates (heading 1701), otherwise V_SugarPolarizationDegreeRequired.
items[].aluminumSmelt (object, conditionally required) — required for Ch. 76 aluminum articles and derivative aluminum products (V_AluminumSmeltDataRequired). Section 232 aluminum duties are assessed on the aluminum content value and qualify on the smelt country rather than the country of origin. Fields:
aluminumContentValue (number, required) — declared value of the aluminum content across the whole line in USD.
\naluminumContentWeightKg (number, required) — weight of the aluminum content in kilograms.
\nprimaryCountryOfSmelt (string, required) — ISO2 code for the primary country of smelt.
\nsecondaryCountryOfSmelt (string, optional) — ISO2 code for the secondary country of smelt.
\ncountryOfCast (string, optional) — ISO2 code for the country where the aluminum was cast.
\nitems[].steelMeltAndPour (object, conditionally required) — required for Ch. 72/73 steel articles and derivative steel products (V_SteelMeltAndPourDataRequired); Section 232 steel duties qualify on the country of melt and pour. Fields:
Accepted for backward compatibility; new integrations should not send them:
\nitems[].quantity (object) — single declared quantity; superseded by quantities (ignored when quantities is populated).
items[].singleUnitDeclaredValue (number) — per-unit value; the line total is derived as singleUnitDeclaredValue x quantity.amount. Mutually exclusive with totalDeclaredValue (V_MutuallyExclusiveProperties).
items[].entryDate (string) — per-item entry date; superseded by the request-level entryDate.
items[].components[].singleUnitDeclaredValue / components[].quantity — per-unit component pricing; superseded by the component's line-total declaredValue.
itemCalculations[] — one entry per requested item, in request order. Each entry carries the fields below.
\nitemCalculations[].reference — the item's correlation reference: the client-supplied value, or the server-generated GUID when none was provided.
\nitemCalculations[].htsClassification — the resolved HTS entry: the matched HTS code (which may differ from the submitted code) and its full hierarchical description.
\nitemCalculations[].baseCalculations[] — the base duty layers (base rate plus any additional duties and surcharges). Each layer: sourceHtsCode, description, dutiesOwed in USD, rounded to whole cents.
itemCalculations[].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.
itemCalculations[].totalDutiesOwed — sum of that item's baseCalculations[].dutiesOwed + componentCalculations[].dutiesOwed in USD.
totalDutiesOwed — sum of every item's totalDutiesOwed in USD.
Validation is stable and assertable by error code (all prefixed V_):
V_ValueEmpty, V_InvalidHtsCode, V_HtsCodeNotFound, V_TenDigitHtsCodeRequired — HTS code or entry date missing, code malformed, unknown, or not specific enough.
V_DeclaredValueRequired, V_QuantityRequired — the resolved tariff bills on a value or on a unit the request did not declare.
V_DuplicateQuantityUnitsNotAllowed — a repeated unit of measure in quantities.
V_MutuallyExclusiveProperties — totalDeclaredValue combined with singleUnitDeclaredValue.
V_InvalidCountryCode, V_CountryNotFound — bad ISO2 or unknown country.
V_ValueMustBeGreaterThanZero, V_ValueMustBeGreaterThanOrEqualToZero — a value or quantity amount out of range.
V_DuplicateComponentsNotAllowed, V_InvalidComponentHtsCode, V_MissingRequiredComponents — components list problems.
V_AluminumSmeltDataRequired, V_SteelMeltAndPourDataRequired, V_SugarPolarizationDegreeRequired — Ch. 76 / Ch. 72-73 / heading 1701 entries without their required side data.
Paged search over the HTS codes that are valid as the main HTS code of a duty calculation request. Use it to discover the full 10-digit code when only a partial code or a product description is known.
\n6201, 6201.40 and 620140 are equivalent.{ htsCode, text } with the code in canonical dotted form and the full hierarchical description.Digits-only prefix filter; dots are ignored.
\n","type":"text/plain"},"key":"code","value":"6201"},{"description":{"content":"Case-insensitive full-text filter over the hierarchical description.
\n","type":"text/plain"},"key":"text","value":"overcoats"},{"description":{"content":"1-based page number.
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Items per page, max 200.
\n","type":"text/plain"},"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"28c8dfd2-3366-4f2d-983c-71048f2e34ad","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: oauth2","key":"Authorization","value":"Reference lookup for a single HTS code. Accepts both dotted (6201.40.50.11) and plain (6201405011) forms.
Lets client integrations discover what an HTS code resolves to before submitting a calculation request — in particular which units of measure a duty calculation must declare quantities in, and which components a component-rated classification requires.
\n9101.11.40); any other broader code returns 400 with V_TenDigitHtsCodeRequired.[\"Number\"], [\"Kg\"]).htsCode of the required component and its leaf-level text (not the full hierarchical path). Empty list when no components are required.totalDeclaredValue): true when any of the entry's rates is value-based (ad valorem or compound).aluminumSmelt data (Ch. 76 aluminum articles and derivative aluminum products).steelMeltAndPour data (Ch. 72/73 steel articles and derivative steel products).200 OK — HTS entry resolved.400 Bad Request (V_InvalidHtsCode, V_TenDigitHtsCodeRequired) — htsCode malformed, or not a 10-digit code (and not component-rated).404 Not Found — htsCode is well-formed but no matching HTS entry exists.401 Unauthorized — missing or invalid bearer token.403 Forbidden — the caller is not permitted to access this resource.