Duty and tariff rate lookup by HS code with customer-specific overrides
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/wove:wove-tariffs-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Wove External Tariffs API
version: 1.0.0
description: '# Wove External API Documentation
The Wove External API allows you to programmatically access document processing, shipment management, and validation capabilities.'
contact:
name: Wove API Support
email: api-support@wove.com
url: https://docs.wove.com
license:
name: Proprietary
url: https://wove.com/terms
servers:
- url: https://api.wove.com
description: Production server
- url: https://staging-api.wove.com
description: Staging server
- url: http://localhost:4000
description: Development server
security:
- bearerAuth: []
tags:
- name: Tariffs
description: Duty and tariff rate lookup by HS code with customer-specific overrides
paths:
/api/v1/external/tariffs/lookup:
get:
tags:
- Tariffs
summary: Look up duty rates by HS code
description: '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`.'
security:
- bearerAuth: []
parameters:
- name: hsCode
in: query
required: true
schema:
type: string
description: HS/HTS code to look up (e.g., "6209205000" or "6209.20.50.00")
example: '8471609050'
- name: originCountry
in: query
required: true
schema:
type: string
pattern: ^[A-Z]{2}$
description: Origin country code (2-letter ISO)
example: CN
- name: destinationCountry
in: query
required: true
schema:
type: string
pattern: ^[A-Z]{2}$
description: Destination country code (2-letter ISO)
example: US
- name: customsValue
in: query
required: false
schema:
type: number
description: Customs value for duty calculation
example: 10000
- name: currency
in: query
required: false
schema:
type: string
default: USD
description: Currency code for calculations
example: USD
- name: entryDate
in: query
required: false
schema:
type: string
format: date
description: Entry date for historical rate lookup (ISO date)
example: '2024-01-15'
- name: dateOfLoading
in: query
required: false
schema:
type: string
format: date
description: Date of loading for historical rate lookup (used if entryDate not provided)
- name: transportMode
in: query
required: false
schema:
type: string
enum:
- ocean
- air
- land
- rail
default: ocean
description: Transport mode for customs fee calculations
- name: componentValues
in: query
required: false
schema:
type: string
description: 'JSON object of component values for Section 232 calculations (e.g., ''{"aluminum": 30}'' for 30% aluminum content)
'
example: '{"aluminum": 30}'
- name: exclusionCodes
in: query
required: false
schema:
type: string
description: JSON array of Chapter 99 exclusion codes to apply (e.g., '["9903.01.21"]')
example: '["9903.01.21"]'
- name: includeFtaOptions
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
description: Whether to include FTA options in the response
- name: applyFtaProgram
in: query
required: false
schema:
type: string
description: FTA program code to apply (e.g., 'US_AU_FTA')
example: US_AU_FTA
- name: weightKg
in: query
required: false
schema:
type: number
description: Weight in kilograms for per-kg fee calculations
responses:
'200':
description: Tariff lookup successful
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
tariffLine:
type: object
properties:
id:
type: string
code:
type: string
example: 8471.60.90.50
description:
type: string
example: Other data processing equipment
fullDescription:
type: string
hs6:
type: string
example: '847160'
uomPrimary:
type: string
example: 'NO'
applicableRate:
type: object
properties:
regime:
type: string
example: MFN
programCode:
type: string
example: US_MFN
rateType:
type: string
example: AD_VALOREM
adValoremRate:
type: number
example: 0
formulaDescription:
type: string
example: Free
baseRate:
type: object
description: Base MFN/preferential rate without additional duties
mfnRate:
type: number
description: MFN rate percentage
example: 0
additionalDuties:
type: array
description: Additional duties (Section 301, 232, etc.)
items:
type: object
properties:
programCode:
type: string
programName:
type: string
rate:
type: number
rateType:
type: string
calculation:
type: object
description: Duty calculation breakdown (when customsValue provided)
properties:
dutyAmount:
type: number
baseDutyAmount:
type: number
additionalDutyAmount:
type: number
currency:
type: string
effectiveRate:
type: number
ftaOptions:
type: array
description: Available FTA programs
items:
type: object
properties:
program:
type: string
programName:
type: string
rate:
type: number
customsFees:
type: object
description: Customs fees breakdown
properties:
totalFees:
type: number
fees:
type: array
items:
type: object
landedCost:
type: object
description: Total landed cost breakdown
properties:
customsValue:
type: number
totalDuties:
type: number
totalFees:
type: number
grandTotal:
type: number
example:
success: true
data:
tariffLine:
id: '12345'
code: 8471.60.90.50
description: Other data processing equipment
hs6: '847160'
uomPrimary: 'NO'
applicableRate:
regime: MFN
programCode: US_MFN
rateType: AD_VALOREM
adValoremRate: 0
formulaDescription: Free
mfnRate: 0
additionalDuties: []
'400':
description: Bad request - invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_hs_code:
summary: Missing HS code
value:
success: false
error:
code: VALIDATION_ERROR
message: Query parameter "hsCode" is required
invalid_hs_code:
summary: Invalid HS code format
value:
success: false
error:
code: VALIDATION_ERROR
message: Invalid HS code format. Expected 4-12 digit code.
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Insufficient permissions - requires tariffs:read scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Tariff line not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: NOT_FOUND
message: No tariff line found for HS code 1234567890
operationId: getApiV1ExternalTariffsLookup
x-operation-id-source: derived
/api/v1/external/tariffs/search:
get:
tags:
- Tariffs
summary: Search tariffs by product description
description: 'Search for tariff lines using semantic search on product descriptions.
This endpoint uses AI-powered semantic search to find relevant HS codes
based on natural language product descriptions. Results are ranked by
relevance to the search query.
**Note**: This endpoint excludes Chapter 99 codes (9903.xx.xx) as they
are administrative tariff codes, not product classifications.'
security:
- bearerAuth: []
parameters:
- name: q
in: query
required: true
schema:
type: string
description: Product description to search for
example: laptop computer
- name: country
in: query
required: true
schema:
type: string
pattern: ^[A-Z]{2}$
description: Destination country code (2-letter ISO)
example: US
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 10
description: Maximum number of results (max 50)
- name: entryDate
in: query
required: false
schema:
type: string
format: date
description: Entry date for historical rate lookup (ISO date)
- name: dateOfLoading
in: query
required: false
schema:
type: string
format: date
description: Date of loading for historical rate lookup
responses:
'200':
description: Search results retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
code:
type: string
example: 8471.30.01.00
description:
type: string
example: Portable automatic data processing machines
fullDescription:
type: string
similarity:
type: number
description: Relevance score (0-1)
example: 0.89
example:
success: true
data:
results:
- id: '12345'
code: 8471.30.01.00
description: Portable automatic data processing machines, weighing not more than 10 kg
similarity: 0.92
- id: '12346'
code: 8471.41.01.00
description: Other automatic data processing machines comprising in the same housing at least a CPU and an input and output unit
similarity: 0.85
'400':
description: Bad request - invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Insufficient permissions - requires tariffs:read scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getApiV1ExternalTariffsSearch
x-operation-id-source: derived
/api/v1/external/tariffs/batch-lookup:
post:
tags:
- Tariffs
summary: Batch look up duty rates for multiple HS codes, origins, destinations, or entry…
description: 'Look up import duty rates for a batch of items in a single request.
Each item is a self-contained query carrying its own `hsCode`, `originCountry`,
`destinationCountry`, and (optionally) `entryDate`, so callers can mix and match
any combination of dimensions in a single request.
**Behaviour**:
- Items are processed independently; a failure on one item does not abort the batch.
- Results are returned in request order and matched to each item by the caller-provided `id`.
- Each item counts toward OAuth rate limits as one request.
**Limits**:
- Maximum 100 items per request.
- Item `id` values must be unique within a request.
For per-item parameter semantics (HS code format, country codes, FTA programs,
component values, exclusion codes, etc.) see `POST /api/v1/external/tariffs/lookup`.'
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- id
- hsCode
- originCountry
- destinationCountry
properties:
id:
type: string
description: Caller-provided identifier echoed back in the response. Must be unique within the request.
example: q1
hsCode:
type: string
description: HS/HTS code (e.g., "6209205000" or "6209.20.50.00")
example: '8471609050'
originCountry:
type: string
pattern: ^[A-Za-z]{2}$
description: Origin country code (2-letter ISO)
example: CN
destinationCountry:
type: string
pattern: ^[A-Za-z]{2}$
description: Destination country code (2-letter ISO)
example: US
customsValue:
type: number
example: 10000
currency:
type: string
default: USD
example: USD
entryDate:
type: string
format: date
description: Entry date for historical rate lookup (ISO date)
example: '2024-01-15'
dateOfLoading:
type: string
format: date
transportMode:
type: string
enum:
- ocean
- air
- land
- rail
default: ocean
componentValues:
type: object
additionalProperties:
oneOf:
- type: number
- type: boolean
description: 'Component values for Section 232 calculations (e.g., {"aluminum": 30} for 30% aluminum content)'
example:
aluminum: 30
exclusionCodes:
type: array
items:
type: string
description: Chapter 99 exclusion codes to apply
example:
- 9903.01.21
includeFtaOptions:
type: boolean
applyFtaProgram:
type: string
example: US_AU_FTA
weightKg:
type: number
examples:
mixed_origins:
summary: Same HS code across multiple origins
value:
items:
- id: cn
hsCode: '8471609050'
originCountry: CN
destinationCountry: US
customsValue: 10000
- id: mx
hsCode: '8471609050'
originCountry: MX
destinationCountry: US
customsValue: 10000
- id: de
hsCode: '8471609050'
originCountry: DE
destinationCountry: US
customsValue: 10000
mixed_dates:
summary: Same HS code/origin across historical entry dates
value:
items:
- id: '2024'
hsCode: '6209205000'
originCountry: CN
destinationCountry: US
entryDate: '2024-06-01'
- id: '2025'
hsCode: '6209205000'
originCountry: CN
destinationCountry: US
entryDate: '2025-06-01'
mixed_codes:
summary: Multiple HS codes from one origin
value:
items:
- id: a
hsCode: '6209205000'
originCountry: CN
destinationCountry: US
- id: b
hsCode: '8471609050'
originCountry: CN
destinationCountry: US
responses:
'200':
description: Batch lookup processed. Per-item status is reported via the `success` flag on each result.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
description: Caller-provided id from the matching request item
success:
type: boolean
data:
type: object
description: Tariff lookup result (same shape as `GET /api/v1/external/tariffs/lookup`). Present when success is true.
error:
type: string
description: Error message. Present when success is false.
status:
type: integer
description: HTTP-style status code for the per-item failure (e.g., 400, 404, 500). Present when success is false.
example:
success: true
data:
results:
- id: cn
success: true
data:
tariffLine:
code: 8471.60.90.50
description: Other data processing equipment
applicableRate:
regime: MFN
adValoremRate: 0
additionalDuties: []
- id: mx
success: false
error: No tariff line found for HS code 8471609050
status: 404
'400':
description: Bad request - request body invalid, items array empty, too many items, or duplicate ids
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
empty_items:
summary: Empty items array
value:
success: false
error:
code: VALIDATION_ERROR
message: '"items" array must not be empty'
too_many_items:
summary: Over 100 items
value:
success: false
error:
code: VALIDATION_ERROR
message: Maximum 100 items allowed per batch
duplicate_id:
summary: Duplicate item id
value:
success: false
error:
code: VALIDATION_ERROR
message: Duplicate item id "q1" in request
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Insufficient permissions - requires tariffs:read scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postApiV1ExternalTariffsBatchLookup
x-operation-id-source: derived
components:
schemas:
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
message:
type: string
example: Invalid input parameters
details:
type: object
description: Additional error context
required:
- success
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 Bearer token obtained from /auth/token endpoint