---
title: "Batch look up duty rates for multiple HS codes, origins, destinations, or entry dates"
method: POST
path: "/api/v1/external/tariffs/batch-lookup"
tags: ["Tariffs"]
---

# Batch look up duty rates for multiple HS codes, origins, destinations, or entry dates

`POST /api/v1/external/tariffs/batch-lookup`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/tariffs/batch-lookup`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/tariffs/batch-lookup/post.ts> (a function with typed inputs; its response is checked against the schema)

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`.

## Request body

- object
  - `items` object[], required
    - `id` string, required: Caller-provided identifier echoed back in the response. Must be unique within the request.
    - `hsCode` string, required: HS/HTS code (e.g., "6209205000" or "6209.20.50.00")
    - `originCountry` string, required: Origin country code (2-letter ISO)
    - `destinationCountry` string, required: Destination country code (2-letter ISO)
    - `customsValue` number
    - `currency` string
    - `entryDate` string, date: Entry date for historical rate lookup (ISO date)
    - `dateOfLoading` string, date
    - `transportMode` 'ocean' | 'air' | 'land' | 'rail'
    - `componentValues` object: Component values for Section 232 calculations (e.g., {"aluminum": 30} for 30% aluminum content)
    - `exclusionCodes` string[]: Importer-claimed codes to apply: Chapter 99 exclusion codes, or a Chapter 98 provision such as `9801.00.10` (American goods returned). See the `exclusionCodes` parameter of `GET /lookup`.
    - `includeFtaOptions` boolean
    - `applyFtaProgram` string
    - `weightKg` number

## Response `200`

Batch lookup processed. Per-item status is reported via the `success` flag on each result.

- object
  - `success` boolean
  - `data` object
    - `results` object[]
      - `id` string: Caller-provided id from the matching request item
      - `success` boolean
      - `data` object: Tariff lookup result (same shape as `GET /api/v1/external/tariffs/lookup`). Present when success is true. This includes `importProhibitions`. A batch item can carry a ban while reporting `success: true` — the lookup succeeded, the goods just may not be imported. Check the field per item; do not infer admissibility from the batch status.
      - `error` string: Error message. Present when success is false.
      - `status` integer: HTTP-style status code for the per-item failure (e.g., 400, 404, 500). Present when success is false.

## Other responses

- `400`: Bad request - request body invalid, items array empty, too many items, or duplicate ids
- `401`: Authentication required
- `403`: Insufficient permissions - requires tariffs:read scope

---

[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)