CBP AD/CVD + HTS Duty Alert

Monitor CBP antidumping and countervailing duty AD/CVD public messages and turn case, country, product, supplier, message-type, and optional HTS watchlists into structured compliance-risk events for customs brokers, import teams, consultants, and AI agents.

What This Actor Does

• Fetches the latest public CBP AD/CVD messages from the CBP AD/CVD public portal.
• Matches new messages against user-provided watchlists.
• Normalizes matches into event records with source URLs, dates, entities, match terms, confidence, and raw source payloads.
• Persists event fingerprints in a named key-value store so repeat runs do not re-emit the same event.
• Supports pay-per-event charging with a safe no-op fallback for local or unpublished runs.

Inputs

• caseNumbers: AD/CVD case numbers such as A-570-983 or A570983.
• countries: country names such as China, Kazakhstan, or Canada.
• productKeywords: product phrases such as silicon metal or wind towers.
• supplierNames: supplier, exporter, importer, or company terms when present in source data.
• messageTypes: CBP message type prefixes or labels such as CD or ALI.
• htsPrefixes: HTS prefixes such as 7308 or 8502.31. In v1, HTS matching requires caseReferenceUrl.
• sinceDate: optional ISO date. If empty, the Actor uses a 7-day lookback.
• maxEvents: safety cap for one run.
• caseReferenceUrl: optional public CSV or JSON case table containing case number and HTS fields. Use this to enable HTS matching in v1; a built-in Federal Register source is planned for v1.1.
• stateStoreName: named key-value store for dedupe and case snapshots. Default: cbp-adcvd-state.

Output

Each dataset item uses this event shape:

{
  "source_url": "https://trade.cbp.dhs.gov/ace/adcvd/adcvd-public/#/message/6183414",
  "source_api_url": "https://trade.cbp.dhs.gov/ace/adcvd/service-messages/messages/public/getLatestMessages",
  "event_type": "high_confidence_catalog_hit",
  "entities": {
    "case_number": "C463811",
    "normalized_case_number": "C463811",
    "message_number": "6183414",
    "product": "Silicon Metal",
    "countries": ["The Republic of Kazakhstan"],
    "hts_numbers": []
  },
  "match_terms": ["country:Kazakhstan", "product:silicon metal"],
  "confidence": 0.85
}

Event Pricing Plan

The code is ready for pay-per-event pricing, but monetization must be configured manually in Apify Console before publication.

• adcvd_message_match: $0.03
• case_status_change: $0.04
• high_confidence_catalog_hit: $0.05

Use all-inclusive pay-per-event pricing. Do not enable pay-per-event plus usage unless the margin model changes.

Local Development

npm install
npm run build
npm test
npm run lint
npm run canary
apify run --purge

The local smoke input lives at storage/key_value_stores/default/INPUT.json.

Data Sources

• CBP AD/CVD public portal: https://trade.cbp.dhs.gov/ace/adcvd/adcvd-public/
• Latest messages API discovered from the public app shell: https://trade.cbp.dhs.gov/ace/adcvd/service-messages/messages/public/getLatestMessages
• Data.gov AD/CVD case metadata: https://catalog.data.gov/dataset/cbp-active-dumping-and-active-countervailing-ad-cvd-cases
• Federal Register API for planned v1.1 case-to-HTS mapping: https://www.federalregister.gov/api/v1/documents.json

Limitations

• In v1, default matching covers case number, country, product keyword, supplier, message type, and date. HTS-prefix matching is active only when you provide a public caseReferenceUrl table.
• The Data.gov AD/CVD case record exposes metadata but no downloadable distribution. Authenticated CBP /service-cases endpoints are intentionally out of scope.
• Built-in HTS-prefix matching is planned for v1.1 using public Federal Register order notices.
• HTS matches are indicative only. AD/CVD scope is controlled by the written scope language in the order notice and related official instructions, not by HTSUS codes alone.
• This Actor reports source facts and watchlist matches. It is not legal advice and does not determine whether merchandise is in scope for an AD/CVD order.
• This Actor is not affiliated with, endorsed by, or sponsored by CBP, DHS, Data.gov, or the U.S. government.

Maintenance

Run the canary daily:

$npm run canary

Open a fix ticket if the endpoint returns login HTML, records are empty twice, required fields disappear, or known-token matching stops producing one normalized event.

Kill / Scale Gate

After 60 days listed on Apify, continue only if the Actor reaches at least 5 paid-plan users or about $25 in charged events. Otherwise archive/freeze and move to the next finalist.