CSV import and export

If you're tracking more than about fifteen HTS codes, the CSV import flow is the fastest way to build (or rebuild) your TariffWatch watchlist. This guide walks the schema, the validation gates, and the export path for archival or downstream analysis in your data warehouse.

Import CSVs use a strict header row. The seven columns:

• hts_code (required): 10-digit HTS code with no punctuation. 7304390056 not 7304.39.00.56.
• label (required): a short human name (usually the product line). Free text, up to 100 chars.
• country_of_origin (required): 2-letter ISO 3166-1 alpha-2 code. CN for China, MX for Mexico, DE for Germany. Full list at ISO 3166 at ISO.org and mirrored in the CBP entry documentation.
• typical_quantity_kg (optional, defaults 0): typical shipment quantity in kilograms. Used by the Section 232 exposure calculator for pre-computed exposure.
• typical_shipment_value_usd (optional, defaults 0): typical CIF value in USD. Same use as quantity.
• alert_threshold (optional, defaults any_change): any_change to alert on any rate change or notice, material_only to alert only on rate changes greater than 0.5 percentage points or notices flagged high-confidence.
• slack_webhook_url (optional): a Slack webhook to route alerts for this code. Overrides account default. Setup detail in webhook Slack setup.

On upload, TariffWatch parses the header, validates every row, and returns a per-row status report. Rows fail (and are excluded from the import) for these reasons:

• hts_code is not 10 digits or contains non-numeric characters.
• hts_code is not currently active in the CBP HTS. Retired codes fail; renumbered codes are auto-remapped and imported with a note. The current active list is mirrored from CBP's HTS revisions on cbp.gov.
• country_of_origin is not a valid ISO 3166-1 alpha-2 code.
• slack_webhook_url is present but does not match the Slack webhook URL pattern (a common source of silent Slack drops; validation now catches it).
• Duplicate hts_code + country_of_origin pair. If two rows for the same code + country appear, only the first is imported.

Rows that pass validation appear on your watchlist immediately.

The import endpoint accepts up to 5,000 rows per file. Larger imports should be split into multiple files. Firms tracking a full metals catalog often split by chapter (Chapter 72 iron and steel, Chapter 73 iron and steel articles, Chapter 76 aluminum, etc.).

From the Watchlist tab, click "Export watchlist as CSV." The download includes every column from the import schema plus three read-only fields: watchlist_id, added_at, and current_mfn_rate_percent. The MFN rate is fetched at export time from the current CBP HTS revision.

From the Digest tab, click "Export this week as CSV." The download contains one row per digest row (see understanding your weekly digest) with these columns: section (direct_hit, adjacent_hit, rate_delta, comment_period, exclusion_status_change), hts_code, notice_title, agency, federal_register_document_number, publication_date, confidence, summary, underlying_url. The underlying URL points to the source document at federalregister.gov or regulations.gov.

For long-window historical exports (last 12 months, last 24 months) the CSV export is available on the API rather than the UI, because the file sizes typically exceed the browser-download safe range. Use the TariffWatch API access reference to authenticate and hit the /api/tariffwatch/history.csv endpoint with your date range.

All CSVs are UTF-8 encoded with a BOM. If your downstream tool (older Excel on Windows especially) misreads the header row, the BOM is why. Open the CSV in a modern tool (Sheets, Numbers, or Excel 365) or strip the BOM in preprocessing.

• Adding HTS codes to your watchlist
• Understanding your weekly digest
• How to use the Section 232 exposure calculator
• TariffWatch API access
• TariffWatch product home

Can I schedule a recurring export? Not from the UI yet. From the API, cron a GET /api/tariffwatch/watchlist.csv on your side every Monday morning; the endpoint is idempotent and cheap.

What happens on re-import to an existing watchlist? The importer treats each (hts_code, country_of_origin) pair as the natural key: existing rows are updated in place, new rows are added, rows in the current watchlist but missing from the CSV are NOT deleted (safety default). To fully replace a watchlist, delete it in the UI first, then import.

Does the CSV export include archived (deleted) codes? No, current-watchlist export is current-only. Archived codes are available via the history API export.

Still stuck? Email support@digitalempireholdings.com or support@digitalempireholdings.com.