CBP Customs Rulings Search (CROSS)

Search the U.S. Customs and Border Protection CROSS (Customs Rulings Online Search System) database for tariff classification rulings. Enter a product description or ruling number and get back structured ruling records with HTS tariff codes, ruling status, full ruling text, and ruling relationship chains showing revocations, modifications, and related decisions.

CBP Customs Rulings Search queries the official rulings.cbp.gov API, which contains over 220,000 searchable rulings dating back decades. Results include the ruling number, subject line, HTS codes, commodity grouping, USMCA/NAFTA applicability, and the complete ruling text. The actor also tracks ruling status (active, revoked, or modified) and provides the full chain of related rulings so you can trace how a classification decision has evolved.

What data can you extract?

Why use CBP Customs Rulings Search?

Researching customs classifications by hand on the CBP website means paginating through search results, opening each ruling individually, and manually tracking which rulings have been revoked or modified. For trade compliance professionals handling hundreds of product classifications, this process does not scale.

This actor automates the entire workflow: search by keyword or ruling number, paginate through all results, fetch full ruling text, and output structured records with status tracking and relationship chains.

Built on the Apify platform, CBP Customs Rulings Search gives you capabilities you won't get from a simple script:

• Scheduling -- run daily or weekly to monitor new rulings in your product categories
• API access -- trigger runs programmatically from Python, JavaScript, or any HTTP client
• Monitoring -- get notified when runs fail or produce unexpected results
• Integrations -- connect directly to Zapier, Make, Google Sheets, or webhooks

Features

• Keyword search across the full CROSS database with support for Boolean operators
• Direct ruling lookup by ruling number for instant access to a specific decision
• Full ruling text retrieval with concurrent batch fetching (5 at a time) and polite rate limiting
• Ruling status tracking -- automatically determines whether each ruling is active, revoked, or modified based on the ruling relationship chain
• Ruling relationship chains -- includes related rulings, modifications, revocations, and the rulings they revoke or modify
• Collection filtering -- search across all rulings or limit to Headquarters (HQ) or New York (NY) collections
• Commodity group filtering -- narrow results by category (Agriculture, Electronics, Automotive, Textiles, etc.)
• Date range filtering -- restrict results to rulings issued within a specific time window
• HTS tariff code extraction -- every ruling includes its associated HTS codes for direct use in import/export classification
• USMCA and NAFTA flags -- identifies rulings relevant to North American trade agreements
• Pagination -- automatically pages through large result sets up to your configured maximum

Use cases for searching customs rulings

Import/export compliance

Customs brokers and trade compliance teams search for rulings on specific product types to determine the correct HTS classification before filing import declarations, reducing the risk of misclassification penalties.

Product classification research

Manufacturers launching new products research existing rulings for similar goods to predict how CBP will classify them and estimate duty rates before importing.

Trade dispute preparation

Legal teams compile ruling histories and revocation chains to build arguments for customs classification protests or petitions for new rulings.

Tariff impact analysis

Trade policy analysts search for all rulings within a commodity group to assess how many product categories are affected by proposed tariff changes.

Compliance monitoring

Companies set up scheduled runs to monitor new rulings in their product categories and get alerted when CBP issues a ruling that could affect their classifications.

Academic and policy research

Researchers analyze classification patterns across thousands of rulings to study trends in customs enforcement, trade policy, and tariff application.

How to search customs rulings

1. Enter a search term -- Type a product description, commodity name, or HTS code in the search field. Boolean operators are supported for complex queries.
2. Configure filters -- Optionally narrow results by collection (HQ/NY), commodity group, or date range. Choose your preferred sort order.
3. Run the actor -- Click "Start" to begin the search. The actor will paginate through results and optionally fetch full ruling text for each match.
4. Download results -- Once finished, download your data as JSON, CSV, or Excel from the Dataset tab. Each row contains one complete ruling record.

Input parameters

*Either searchTerm or rulingNumber is required.

Input examples

Search for electronics rulings:

{
    "searchTerm": "electronics",
    "maxResults": 25
}

Look up a specific ruling:

{
    "rulingNumber": "N082097"
}

Search with filters and date range:

{
    "searchTerm": "lithium battery",
    "collection": "HQ",
    "commodityGrouping": "Electronics",
    "fromDate": "2023-01-01",
    "toDate": "2024-12-31",
    "sortBy": "DATE_DESC",
    "maxResults": 100
}

Quick search without full text (faster):

{
    "searchTerm": "automotive sensors",
    "includeFullText": false,
    "maxResults": 200
}

Input tips

• Start without full text for large searches -- Setting includeFullText to false skips individual ruling detail fetches, making searches with hundreds of results much faster.
• Use specific commodity groups -- Filtering by commodity group reduces noise and returns more relevant results for your product category.
• Combine date filters with keywords -- When monitoring for new rulings, use fromDate with sortBy: DATE_DESC to surface the most recent decisions first.

Output example

Each item in the output dataset represents one customs ruling:

{
    "rulingNumber": "N082097",
    "subject": "The tariff classification of electronic fitness trackers from China",
    "categories": ["Electrical Machinery", "Consumer Electronics"],
    "rulingDate": "2023-06-15",
    "collection": "NY",
    "htsTariffCodes": ["8517.62.0090"],
    "commodityGrouping": "Electronics",
    "status": "active",
    "isUsmca": false,
    "isNafta": false,
    "relatedRulings": ["N081234", "N083456"],
    "modifiedBy": [],
    "modifies": [],
    "revokedBy": [],
    "revokes": [],
    "fullText": "Dear Sir or Madam:\n\nIn your letter dated May 10, 2023...",
    "documentUrl": "https://rulings.cbp.gov/ruling/N082097.pdf",
    "sourceUrl": "https://rulings.cbp.gov/ruling/N082097"
}

Output fields

How much does it cost to search customs rulings?

CBP Customs Rulings Search uses compute-based pricing on the Apify platform. Costs depend on memory allocation (512 MB default) and run time.

Apify Free Tier: New Apify accounts receive $5 of free platform credits each month, enough for hundreds of ruling searches.

Search customs rulings using the API

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/cbp-customs-rulings").call(run_input={
    "searchTerm": "lithium battery",
    "commodityGrouping": "Electronics",
    "sortBy": "DATE_DESC",
    "maxResults": 50,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['rulingNumber']}: {item['subject']}")
    print(f"  HTS: {', '.join(item['htsTariffCodes'])} | Status: {item['status']}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/cbp-customs-rulings").call({
    searchTerm: "lithium battery",
    commodityGrouping: "Electronics",
    sortBy: "DATE_DESC",
    maxResults: 50,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log(`${item.rulingNumber}: ${item.subject}`);
    console.log(`  HTS: ${item.htsTariffCodes.join(", ")} | Status: ${item.status}`);
}

cURL

# Start the actor run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~cbp-customs-rulings/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerm": "lithium battery",
    "commodityGrouping": "Electronics",
    "maxResults": 50
  }'

# Fetch results (replace DATASET_ID from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"

How the CBP customs rulings search works

The actor operates in two modes depending on the input:

Mode 1: Direct ruling lookup

When a rulingNumber is provided, the actor calls the CROSS API detail endpoint directly for that ruling number. The full ruling record -- including text, tariff codes, and relationship chains -- is returned as a single output record.

Mode 2: Keyword search with pagination

When a searchTerm is provided, the actor queries the CROSS search API with the specified filters. Results are paginated in batches of 100, with a polite 100ms delay between pages, until the maxResults limit or total hit count is reached.

If includeFullText is enabled, the actor then enriches each search result by fetching the full ruling detail. This is done in concurrent batches of 5 requests with a 200ms delay between batches to respect the CROSS API's rate limits.

Each ruling is then transformed into the clean output format: dates are normalized to YYYY-MM-DD, categories are parsed from the comma/semicolon-delimited string, HTS codes are extracted from the tariffs array, and the status is determined from the revocation and modification chains.

Status determination logic

• Revoked: The ruling has operationallyRevoked set to true, isRevokedByOperationalLaw is true, or the revokedBy array is non-empty.
• Modified: The modifiedBy array is non-empty (and not revoked).
• Active: Neither revoked nor modified.

Commodity groups

The CROSS database organizes rulings into these commodity groups for filtering:

Limitations

• CROSS API availability -- The actor depends on the rulings.cbp.gov API. If the CROSS system is down for maintenance, searches will fail.
• Search syntax -- The search term is passed directly to the CROSS API's search engine. Complex Boolean queries may behave differently than expected.
• Full text fetching is slow -- Retrieving ruling text requires individual API calls per ruling (batched at 5 concurrent). Large searches with full text enabled can take several minutes.
• No full-text search within ruling bodies -- The keyword search operates on the CROSS index, not the full ruling text. To search within ruling text, fetch results first, then filter locally.
• Historical coverage -- While the database contains ~220,000 rulings dating back decades, older rulings may have incomplete metadata or missing text.
• Rate limiting -- The actor uses polite delays (100-200ms between requests) to avoid overwhelming the CROSS API. This is not configurable.

Integrations

• Zapier -- Trigger workflows when new rulings are found matching your search criteria.
• Make -- Build automated classification monitoring pipelines with 1,500+ app integrations.
• Google Sheets -- Export rulings directly to Google Sheets for team review and collaboration.
• Apify API -- Call the actor programmatically. Start runs, poll for completion, and download results in JSON, CSV, XML, or Excel.
• Webhooks -- Get notified when a search run completes, then process results in your compliance system.

FAQ

How many rulings are in the CROSS database? The database contains approximately 220,000 searchable rulings. The actor reports the exact count from the API's statistics endpoint at the start of each search run.

Can I search by HTS code? Yes. Enter the HTS code as your search term. The CROSS search engine indexes tariff codes, so queries like 8517.62 will return rulings classified under that heading.

What is the difference between HQ and NY collections? HQ rulings are issued by CBP Headquarters in Washington, D.C. and typically address more complex or precedent-setting classification questions. NY rulings are issued by the National Commodity Specialist Division in New York and handle the majority of routine classification requests.

How do I know if a ruling is still valid? Check the status field. Rulings with status active are still in effect. Rulings marked revoked have been superseded -- check the revokedBy array to find the replacement ruling. Rulings marked modified have been partially changed -- check modifiedBy for the modifying ruling.

Can I monitor for new rulings automatically? Yes. Use Apify Schedules to run the actor daily or weekly with sortBy: DATE_DESC and a fromDate filter set to your last check date. Combine with webhooks to get notified when new rulings appear.

What format are the ruling dates in? All dates in the output are normalized to ISO YYYY-MM-DD format regardless of how they appear in the source data.

Is this the same data as on rulings.cbp.gov? Yes. The actor queries the same internal JSON API that powers the rulings.cbp.gov website. The data is identical -- just structured for programmatic access.

Related actors

Support

Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page. For custom compliance solutions or enterprise integrations, reach out through the Apify platform.