> ## Documentation Index
> Fetch the complete documentation index at: https://traddal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate stacking

> The full duty-rate stack for a code and origin — no shipment values needed.

Requires the `calculate:read` scope. Answers "which tariff lines stack for
this code from this origin, on this date?" — base duty plus additional
measures (Section 301/232, reciprocal, …), which Chapter 99 exclusion codes
suppressed what, and which claim codes *could* be filed — without needing
values or weights.

<ParamField body="hs_code" type="string" required>
  2–10 digit HS code (dots and spaces allowed).
</ParamField>

<ParamField body="origin_country" type="string" required>
  ISO alpha-2 origin (case-insensitive).
</ParamField>

<ParamField body="destination_country" type="string" default="US">
  ISO alpha-2 destination.
</ParamField>

<ParamField body="entry_date" type="string">
  `YYYY-MM-DD` — the stack as of this date (defaults to today).
</ParamField>

## Response

<ResponseField name="rate_found" type="boolean">
  Whether a general (MFN) rate exists for this code.
</ResponseField>

<ResponseField name="tariffs" type="array">
  The stack, base rate first. Each line:
  `{ name, rate, type, code? }`, plus — when an exclusion fired —
  `exempted: true` with `exclusion_code` / `exclusion_name` (the line's
  rate shows as zeroed).
</ResponseField>

<ResponseField name="potential_exclusion_codes" type="array">
  Present when claimable Chapter 99 codes overlap the applied stack:
  `{ code, name, applied: false, reason }` — codes the importer could file.
</ResponseField>

<ResponseField name="conditional_measures" type="array">
  Present when measures exist that need shipment facts (metal content /
  weight / manual claim): stack lines plus a `condition` string. Never
  auto-applied here.
</ResponseField>

<ResponseField name="data_source" type="object | null">
  Which tariff publication answered: `{ version, source, imported_at }`.
</ResponseField>

<ResponseField name="request_id" type="string | null">
  Log id — appears in `GET /usage-history/calculate`.
</ResponseField>

## Bulk stacking

For up to 500 codes at once, POST `{ "items": [...] }` to
`/calculate/stacking/bulk` — each item is the same shape plus an optional
`ref` (echoed back). The response is
`{ "results": [...], "execution_time": … }`, each result tagged with its
`index`, `ref`, and `success`; a failed item carries `error` instead of a
stack.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://{partner}.mytraddal.com/admin/api/v1/calculate/stacking \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {access_token}' \
    -d '{
      "hs_code": "7326.90",
      "origin_country": "CN",
      "destination_country": "US"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "",
    "hs_code": "732690",
    "origin_country": "CN",
    "destination_country": "US",
    "entry_date": "2026-07-30",
    "rate_found": true,
    "tariffs": [
      { "name": "Customs duty (general)", "rate": "2.9%", "type": "general" },
      { "name": "Section 301 List 3", "rate": "25%", "type": "section_301", "code": "9903.88.03" }
    ],
    "potential_exclusion_codes": [
      {
        "code": "9903.88.69",
        "name": "Section 301 exclusion",
        "applied": false,
        "reason": "Eligible claim — file this Chapter 99 code to exempt the affected duty"
      }
    ],
    "conditional_measures": [
      {
        "name": "Section 232 steel derivative",
        "rate": "25%",
        "type": "section_232",
        "code": "9903.81.91",
        "condition": "Applies to the steel content value"
      }
    ],
    "data_source": { "version": "2026 Rev 7", "source": "hts_rates_2026_rev7.csv", "imported_at": "2026-06-30T08:11:02.000Z" },
    "request_id": "5b1f7a2e-9c0d-4f3b-8a67-0e2d4c6f8a12"
  }
  ```
</ResponseExample>