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

# Customs Rulings

> Find published US customs rulings showing how similar goods were classified.

Searches rulings published by US Customs and Border Protection, closest match first, with ruling numbers you can cite, dates, tariff numbers and revocation status. A ruling binds only the goods it describes. The rate itself comes from Duty Rate.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**query** `string` *required*

Search words, for example bluetooth speaker. 2 to 200 characters.

**tariff\_number** `string`

Keep rulings with a tariff number starting with this prefix, for example 8518, 8518.22 or 8518.22.0000.

**limit** `integer`

The most rulings to fetch before the optional tariff filter. From 1 to 20. Defaults to `10`.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `record_customs_rulings_find`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US Customs and Border Protection`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

The newest ruling date in the returned rulings; null when none has a known date.

## Result

Nested under `data.result`.

**data.result.total** `number`

Number of matches at the source before the optional tariff filter.

**data.result.rulings** `object[]`

Matching rulings in source relevance order.

**data.result.rulings\[].ruling\_number** `string`

The ruling number identifying this public record.

**data.result.rulings\[].subject** `string`

The subject of the ruling.

**data.result.rulings\[].date** `string | null`

The ruling date in US Eastern calendar time, YYYY-MM-DD; null when unknown.

**data.result.rulings\[].collection** `string`

The issuing collection: New York or Headquarters.

**data.result.rulings\[].categories** `string`

The source category of the ruling.

**data.result.rulings\[].tariff\_numbers** `string[]`

Tariff numbers listed in the ruling.

**data.result.rulings\[].related\_rulings** `string[]`

Related ruling numbers.

**data.result.rulings\[].modified\_by** `string[]`

Rulings that modified this ruling.

**data.result.rulings\[].revoked\_by** `string[]`

Rulings that revoked this ruling.

**data.result.rulings\[].revoked** `boolean`

Whether another ruling revoked it or the source marks it operationally revoked.

**data.result.rulings\[].usmca** `boolean`

Whether the source marks the ruling as USMCA related.

**data.result.rulings\[].url** `string`

The ruling page at the source.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/find/record-customs-rulings \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "query": "bluetooth speaker",
    "limit": 1
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/find/record-customs-rulings", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "query": "bluetooth speaker",
    "limit": 1
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('find/record-customs-rulings', {
  query: 'bluetooth speaker',
  limit: 1
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "record_customs_rulings_find",
    "result": {
      "total": 126,
      "rulings": [
        {
          "ruling_number": "N326117",
          "subject": "The tariff classification of a Bluetooth Party Speaker from China",
          "date": "2022-05-20",
          "collection": "ny",
          "categories": "Classification",
          "tariff_numbers": [
            "8518.22.0000",
            "9903.88.15"
          ],
          "related_rulings": [],
          "modified_by": [],
          "revoked_by": [],
          "revoked": false,
          "usmca": false,
          "url": "https://rulings.cbp.gov/ruling/N326117"
        }
      ]
    },
    "evidence": {
      "source": "US Customs and Border Protection",
      "source_kind": "public",
      "retrieved_at": "2026-10-25T07:26:53.389Z",
      "calls": [
        {
          "retrieved_at": "2026-10-25T07:26:53.389Z"
        }
      ],
      "as_of": "2022-05-20"
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* New rulings are added daily as issued. Each answer includes the ruling date and a link to the ruling page.
* The optional tariff\_number prefix filters the returned page. Fewer than limit rulings may remain; total is the source match count before filtering.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.