--- title: "Look up duty rates by HS code" method: GET path: "/api/v1/external/tariffs/lookup" tags: ["Tariffs"] --- # Look up duty rates by HS code `GET /api/v1/external/tariffs/lookup` ## Request - Base URL: `https://api.wove.com` - URL: `https://api.wove.com/api/v1/external/tariffs/lookup` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Look up import duty rates for a specific HS/HTS code. **Features**: - Supports US, EU, Canada, and Australia tariff schedules - Returns MFN rates, preferential rates, and additional duties (Section 301, 232, etc.) - Calculates landed cost including customs fees - Supports FTA program selection - Customer-specific tariff overrides are automatically applied **HS Code Format**: - US: 10-digit HTS code (e.g., "6209205000" or "6209.20.50.00") - Other countries: 4-12 digit HS code **Additional Duties**: For products subject to Section 232 tariffs (steel/aluminum derivatives), you may need to provide component percentages via `componentValues`. ## Query parameters - `hsCode` string, required - `originCountry` string, required - `destinationCountry` string, required - `customsValue` number - `currency` string - `entryDate` string, date - `dateOfLoading` string, date - `transportMode` 'ocean' | 'air' | 'land' | 'rail' - `componentValues` string - `exclusionCodes` string - `includeFtaOptions` 'true' | 'false' - `applyFtaProgram` string - `weightKg` number ## Response `200` Tariff lookup successful - object - `success` boolean - `data` object - `tariffLine` object - `id` string - `code` string - `description` string - `fullDescription` string - `hs6` string - `uomPrimary` string - `applicableRate` object - `regime` string - `programCode` string - `rateType` string - `adValoremRate` number - `formulaDescription` string - `baseRate` object: Base MFN/preferential rate without additional duties - `mfnRate` number: MFN rate percentage - `additionalDuties` object[]: Additional duties (Section 301, 232, etc.) - `programCode` string - `programName` string - `rate` number - `rateType` string - `calculation` object: Duty calculation breakdown (when customsValue provided) - `dutyAmount` number - `baseDutyAmount` number - `additionalDutyAmount` number - `currency` string - `effectiveRate` number - `ftaOptions` object[]: Available FTA programs - `program` string - `programName` string - `rate` number - `customsFees` object: Customs fees breakdown - `totalFees` number - `fees` object[] - `landedCost` object: Total landed cost breakdown - `customsValue` number - `totalDuties` number - `totalFees` number - `grandTotal` number - `importProhibitions` ImportProhibition[]: Bans on importing these goods from this origin at all — see the `ImportProhibition` schema. Omitted when none applies; an absent field means no ban was found, never that the goods were cleared for entry. Read this BEFORE the duty figures. An entry carrying an unconditional prohibition cannot be made, whatever `calculation` reports alongside it. - `description` string, required: Human-readable statement of what may not be imported. - `effectiveFrom` string, date, required: Date the ban takes effect. Note these run on goods IMPORTED on or after the date, not entered for consumption, unlike most Chapter 99 effective dates. - `authority` string: Statutory authority for the exclusion. - `sourceReference` string, uri: URL of the proclamation or notice imposing the ban. - `condition` string: Present when the ban reaches only PART of the subheading and the classification alone cannot settle whether these goods fall inside it. `packaged` — only alcohol in bottles, cans, boxes, kegs or other similar direct-to-consumption containers is excluded; bulk shipments under the same subheading remain importable and remain dutiable. When this field is present the finding is a WARNING, not a determination: the duties in the same response still stand, and the importer must decide whether the goods meet the stated limitation. - `supersededDuties` string[]: Chapter 99 headings this ban replaced, and which have therefore been omitted from `additionalDuties`. The proclamations move a product OUT of the additional duty and INTO the ban rather than stacking the two. Empty for a conditional ban, which supersedes nothing. - `appliedCh98Provision` object: How a claimed Chapter 98 provision was applied. Present only when one was sent in `exclusionCodes`. `unresolved: true` means the claim was NOT applied and duty is on the full entered value. - `code` string - `dutyBasis` 'full_value' | 'foreign_value_add' | 'repair_value' | 'duty_equivalent' | 'ordinary_rate' | 'zero' - `dutiableValue` number - `unresolved` boolean - `attestations` string[] - `warnings` object[]: Caveats on this answer (US destination). Omitted when none applies. The figures are correct for the request as sent; a `warning` means they are probably not what the importer will pay. - `us_origin_no_chapter_98_claim`: origin is the US and no Chapter 98 provision is claimed, so the ordinary duty rate was charged. US-origin goods are duty-free only when entered under `9801.00.10`. - `us_goods_returned_claim`: `9801.00.10` is claimed; what the claim rests on (proof of US origin, no improvement abroad). - `section_232_on_us_goods_returned`: a Section 232 duty on steel, aluminum or copper is still charged on a `9801.00.10` claim for goods declared with a foreign origin, and may not be owed. (US-origin goods carry no additional duty at all.) - `code` 'us_origin_no_chapter_98_claim' | 'us_goods_returned_claim' | 'section_232_on_us_goods_returned' - `severity` 'warning' | 'info' - `message` string - `suggestedClaimCode` string: A code to send in `exclusionCodes` to act on the warning. ## Other responses - `400`: Bad request - invalid parameters - `401`: Authentication required - `403`: Insufficient permissions - requires tariffs:read scope - `404`: Tariff line not found --- [API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)