CSV import for the HTS watchlist — format spec & batch upload guide (2026)

Why importers watch a portfolio of HTS codes

A U.S. importer of anything more complex than a single-SKU consumer product almost never sits at just one 10-digit HTSUS code. A mid-sized apparel brand may sit on 40 tariff items across Chapters 61 and 62; a housewares importer routinely spans Chapters 39 (plastics), 44 (wood), 69 (ceramics), 70 (glass), 73 (iron/steel articles), and 76 (aluminum articles); a consumer-electronics brand touches Chapters 84 (machinery), 85 (electrical), and 90 (precision instruments). Each of those 10-digit codes is a separate exposure surface for the 2026 tariff cycle: any of them can be swept into a Federal Register inclusion notice, a Bureau of Industry and Security (BIS) Section 232 derivative-articles list, a USITC Chapter 99 update, or a CBP Cargo Systems Messaging Service (CSMS) enforcement guidance without direct notice to the importer.

The traditional workaround was a staff compliance analyst reading the Federal Register table of contents every morning, scanning the BIS site weekly, and checking CSMS feeds by hand. That workflow scales to portfolios of 5 or 10 codes and collapses at 40. The TariffWatch watchlist replaces the manual scan with a 15-minute polling loop across all four primary-source feeds, per-row alert thresholds, and one-click deep-links into the matching inclusion-rebuttal draft when a swept code has a defensible carve-out argument. But the watchlist only works if the initial portfolio is loaded correctly, and for portfolios above 10 or so codes the only sane loading mechanism is a CSV upload. This guide is the specification for that CSV.

The CSV format specification

The TariffWatch watchlist CSV parser is intentionally strict: strict schema means fewer silent errors and faster diagnostic when an upload rejects. The full specification:

• File encoding. UTF-8 required. A leading UTF-8 BOM is silently stripped. Non-UTF-8 files (ISO-8859-1, Windows-1252, UTF-16 with any BOM) return a 422 with the offending byte offset.
• Line endings. LF (Unix) preferred. CRLF (Windows) accepted and normalized. CR-only (classic Mac) rejected with a specific error.
• Header row. Required. Must contain exactly these five column names in this order, case-sensitive, lowercase: hts_code,description,annual_customs_value_usd,alert_threshold_pct,notes. No extra columns permitted; extra columns return a schema-mismatch error naming the unexpected column.
• Delimiter. Comma. Semicolons (common in European Excel locales) are rejected; export from Excel-DE requires the Save As → Tools → Web Options workflow or a plain-text editor to convert.
• Quoting. Fields containing commas, double-quotes, or newlines must be enclosed in ASCII double-quotes; embedded double-quotes are escaped by doubling (RFC 4180 quoting). Curly quotes ("smart quotes" from Microsoft Word) are rejected with a specific error pointing to the offending character.
• Row terminator. The final row must end with a line terminator; parsers that omit the trailing newline occasionally lose the final row on some pipelines.
• Whitespace. Leading and trailing whitespace within a field is stripped for hts_code and alert_threshold_pct; preserved for description and notes; forbidden inside numeric fields (embedded spaces in annual_customs_value_usd return a parse error).

Field-by-field validation rules

• hts_code. Required. Must match the regex ^\d4\.?\d2\.?\d4$ after whitespace strip: a 10-digit string with optional dot separators at positions 4 and 6. Both 6205202016 and 6205.20.2016 parse to the same canonical form. The parser rejects codes that are not exactly 10 digits after removing dots. It also cross-references the code against the current USITC HTSUS dataset (refreshed weekly); codes not present in the current HTSUS trigger a warning but not a rejection (out-of-schedule codes are permitted because the importer may be watching a historical or newly-proposed code).
• description. Optional. Free text up to 200 characters. Used only for display in the watchlist dashboard; not sent to any external system. Unicode permitted.
• annual_customs_value_usd. Required. Numeric, integer or decimal to two places. No thousands separators (12345.67 not 12,345.67). No currency symbols. Range: 0 to 9,999,999,999.99. Zero is permitted (row will still be watched but ranked lower in alert priority).
• alert_threshold_pct. Required. Numeric, integer or decimal to two places. Range: 0 to 100 inclusive. Represents the percentage-point change in ad valorem duty exposure at which the row triggers an alert (10.00 means a 10-percentage-point change fires an alert; a change from 2.5% to 5% ad valorem is a 2.5-point change and would not fire at threshold 10.00 but would fire at threshold 2.00).
• notes. Optional. Free text up to 500 characters. Used only for internal customer tracking (broker case IDs, PO numbers, supplier codes). Not sent to any external system, not surfaced in alerts, and searchable within the watchlist dashboard.

Sample CSV (5 real HTSUS codes)

The following 5-row example uses real 10-digit HTSUS codes drawn from Chapters 73 (iron and steel articles), 76 (aluminum articles), and 83 (miscellaneous articles of base metal), the three chapters most affected by the 2026 Section 232 derivative-articles proposal. Save the block below as watchlist.csv (UTF-8, LF endings) and upload directly to the watchlist:

hts_code,description,annual_customs_value_usd,alert_threshold_pct,notes
7326.90.8688,"Other articles of iron or steel, other",1250000.00,5.00,"PO-2026-Q4-fasteners"
7616.99.5190,"Other articles of aluminum",840000.00,5.00,"broker case CB-88421"
8302.30.3060,"Base metal mountings for motor vehicles",620000.00,10.00,"Tier-1 auto supplier"
7318.15.8065,"Other threaded articles of iron/steel screws",410000.00,2.50,"Section 232 exposure high"
7616.99.5160,"Other cast articles of aluminum",295000.00,5.00,"quarterly review"

Every code in the sample is present in the current USITC HTSUS at hts.usitc.gov and can be looked up individually for the corresponding duty rate and any current Section 232 or Section 301 additional-tariff status. The notes column shows the recommended pattern: link each row to whatever internal identifier your broker or ERP already uses (purchase order number, broker case ID, supplier code) so alerts tie back to your operational systems without ambiguity.

Seven common CSV import errors and fixes

1. Excel autoformatting truncating leading zeros. A code such as 0202.30.0000 (frozen boneless beef, Chapter 2) becomes 202.30.0000 when Excel autoformats the column as a number. Fix: format the hts_code column as Text before pasting codes, or use Excel’s Get Data → From Text/CSV wizard with explicit column-type control. Never double-click a CSV to open it on Windows without the wizard.
2. UTF-8 BOM causing header mismatch on strict parsers. Excel on Windows exports CSV with a UTF-8 BOM (bytes EF BB BF) at the start of the file. Our parser strips this silently, but strict downstream parsers (Python’s csv.DictReader without utf-8-sig) will read the first column header as hts_code and reject the file. Fix on our end: nothing needed. Fix if you are pre-validating: use utf-8-sig instead of utf-8 for the file read.
3. Curly quote replacement from Word or Google Docs. If any description or notes value contains a straight double-quote and the file was authored in Microsoft Word, Word converts the straight quotes to curly quotes (U+201C and U+201D). RFC 4180 requires ASCII double-quotes for quoting; curly quotes are rejected. Fix: author CSVs in a plain-text editor (VS Code, Sublime, Notepad++) or turn off smart-quote replacement in Word before authoring.
4. Non-UTF-8 encoding from legacy ERP exports. SAP GTS on older installations exports as Windows-1252 by default. Fix: change the export encoding to UTF-8 in the SAP GUI, or run iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv on the command line before uploading.
5. Semicolon delimiter from European Excel locale. Excel on European installations (Germany, France, Spain, and others) uses the semicolon as the default CSV delimiter because comma is the decimal separator. Fix: change the delimiter in Excel’s Web Options (Save As → Tools → Web Options → Encoding), or run tr ';' ',' < in.csv > out.csv after export.
6. Embedded thousands separators in the value column. Values like 1,250,000.00 in annual_customs_value_usd are rejected because the embedded commas confuse the CSV field parser (even when quoted, the numeric regex requires clean digits with optional single decimal point). Fix: strip thousands separators before export. In Excel, format the column as Number with zero thousands separators.
7. Duplicate hts_code rows silently overwriting. The parser accepts duplicate codes within a file but applies last-write-wins: the final row for a given code overwrites all earlier rows for the same code. This is a common source of "why is my description wrong?" support tickets. Fix: deduplicate the hts_code column in Excel (Data → Remove Duplicates) or with sort -u on the command line before upload.

Batch size limits and rate rules

A single CSV upload accepts up to 500 rows. Portfolios larger than 500 codes must be split into multiple files and uploaded sequentially, with at least a 2-minute gap between uploads to respect the per-account rate limit (documented in the API reference as 500 rows per 2 minutes for the interactive upload endpoint). The 2-minute window is not a rolling window; it resets on each successful upload response. There is no monthly cap on total rows watched on the $29/mo plan; the 500-row-per-upload cap is a request-shape constraint not a portfolio-size cap.

Large customs-brokerage accounts watching 5,000+ codes across many client importers can request access to the enterprise batch endpoint, which accepts a signed S3 presigned URL to a CSV of any size and processes it asynchronously with a webhook callback on completion. The async endpoint has no row cap but is rate-limited at 100 files per account per day. Enterprise accounts are also given a dedicated hourly quota for the interactive endpoint to avoid noisy-neighbor rate-limit collisions.

What the watchlist actually monitors

The watchlist queries four primary-source feeds every 15 minutes. Every alert cites the exact primary-source URL and a timestamped snapshot of the source document at the moment the alert fired, so the alert is independently verifiable by the importer or the importer’s customs counsel:

• Federal Register public-inspection and daily-issue feeds. Every notice published or made available for public inspection is scanned for any mention of any HTS code on the account’s watchlist, plus any mention of the section/chapter/heading level that encompasses the watched code. Source: federalregister.gov.
• Bureau of Industry and Security Section 232 pages. The BIS derivative-articles list and Section 232 investigation pages are re-fetched every 15 minutes; any change to the list of covered HTS headings fires an alert on any watched code that falls under a newly-covered heading. Source: bis.doc.gov/232-investigations.
• USITC Chapter 99 dataset. Chapter 99 is the U.S.-specific chapter for temporary tariff legislation (Section 301 China tariffs, IEEPA measures, safeguard actions, and so on). Any addition, removal, or duty-rate change in Chapter 99 that references a watched code fires an alert. Source: hts.usitc.gov/current.
• CBP Cargo Systems Messaging Service (CSMS). CSMS is CBP’s operational feed for entry-processing changes (new PGA flags, rate updates, enforcement guidance, ACE downtime). Any CSMS message referencing a watched code fires an alert. Source: CBP CSMS subscription page.

ERP and customs-broker export patterns

The five-column watchlist CSV maps cleanly onto the standard export shapes of every major global-trade-management (GTM) system and the two customs-filing standards (ABI and ACE). Below is the recommended field-mapping for each source:

• SAP GTS (Global Trade Services). Export the Product Master with the fields NUMMR (product number, map to notes), TARIF (tariff number, map to hts_code, strip dots), TXZ01 (short text, map to description), and a joined annual-import-value from the Customs Value report (map to annual_customs_value_usd). Alert threshold is set uniformly in the CSV; SAP GTS does not carry a per-material alert-threshold field natively.
• Oracle GTM (Global Trade Management). Use the standard Item Master Extract with the columns ITEM_XID, HTS_CLASSIFICATION_10, ITEM_DESCRIPTION, ANNUAL_IMPORT_VALUE. Map ITEM_XID to notes (so alerts back-reference the Oracle item), HTS_CLASSIFICATION_10 to hts_code, ITEM_DESCRIPTION to description, and ANNUAL_IMPORT_VALUE to annual_customs_value_usd.
• NetSuite (SuiteAnalytics saved search export). Build a saved search on the Item record with columns Item Name (notes), Custom HTS Code (hts_code), Description (description), and a summary column for cumulative sales/purchase amount at the item level from the last 12 months (annual_customs_value_usd). Export to CSV from the saved-search results page.
• ABI (Automated Broker Interface) filings. The customs broker’s ABI system carries the HTS code on every entry summary (CATAIR record I40). A broker export of the past 12 months of entry summaries, aggregated by 10-digit HTS code with sum of Customs Value, produces a portfolio CSV that maps directly onto the watchlist schema. Ask the broker for a "12-month entry-summary rollup by HTS code" CSV.
• ACE (Automated Commercial Environment) reports. The importer’s own ACE Portal account has the Reports module with the standard "ES-002 Entry Summary Line" report, exportable to CSV with columns HTS Number and Line Customs Value that map directly onto hts_code and annual_customs_value_usd. Run the report for the past 12 months, aggregate in Excel by HTS Number, and upload.

Sample end-to-end workflow

1. Extract 12 months of entry data. Pull either the ACE ES-002 report (importer-side) or the ABI 12-month entry-summary rollup (broker-side). This is the source of the portfolio of 10-digit HTS codes and the annual customs value per code.
2. Aggregate to unique 10-digit HTS codes. Use Excel’s Data → Remove Duplicates or the command line to collapse the export to one row per unique 10-digit code, with sum of customs value.
3. Map to the watchlist column schema. Rename columns to hts_code, description, annual_customs_value_usd, alert_threshold_pct (add uniformly if not present), notes.
4. Validate encoding and formatting. Format the hts_code column as Text before saving. Save As → CSV UTF-8. Open the resulting file in a plain-text editor and verify the header row and first 3 rows look correct with dots or without, no BOM issues, no smart quotes.
5. Upload the CSV. Go to the watchlist dashboard → Import CSV. If >500 rows, split and upload with 2-minute spacing.
6. Verify the row count and spot-check a few rows. The upload response reports the accepted-row count and any warnings (out-of-schedule codes). Spot-check three or four rows in the dashboard against the source data.
7. Set per-row alert thresholds if needed. The CSV sets a uniform threshold on load; per-row thresholds can be adjusted in the dashboard or by re-uploading with row-level threshold values.
8. Subscribe to email or webhook alerts. Configure the account’s alert channel (email, webhook to Slack or the broker’s system). Alerts fire within 15 minutes of the primary-source publication.

Security, encryption, and retention

Uploaded CSV files are transmitted over TLS 1.3, parsed in-memory (never written to disk in the original CSV form), stored row-by-row in a Postgres database with per-row AES-256 encryption at rest via Supabase Vault, and access-logged for every read via row-level Postgres policies that prevent cross-account reads. The original CSV file is deleted from the ingest pipeline after successful parse; only the structured row data persists. Deletion of the watchlist (via the UI or the DELETE API endpoint) triggers immediate soft-delete followed by hard-delete after a 30-day retention window during which the account owner can restore. SOC 2 Type II attestation is in progress with a Big-Four auditor; full data-processing terms are in the TariffWatch DPA available on request from the account dashboard.

None of the uploaded HTS codes or customs values are shared with any third party, aggregated, anonymized-and-resold, or used to train any model. The row data is used exclusively to run the four primary-source polling loops for the account that uploaded it. Account termination triggers a 30-day soft-delete followed by hard-delete of all row data, backups included, and an emailed deletion certificate.

FAQ

Start a $29/mo HTS watchlist Run the free BIS-14 HTS checker

References and primary sources

1. U.S. International Trade Commission — Harmonized Tariff Schedule (HTSUS).
2. U.S. International Trade Commission — Current HTSUS (Chapter 99 for temporary legislation).
3. U.S. Customs and Border Protection — Cargo Systems Messaging Service (CSMS) subscription.
4. U.S. Customs and Border Protection — Customs Rulings Online Search System (CROSS).
5. Federal Register — Daily issue and public-inspection feed.
6. Bureau of Industry and Security — Section 232 investigations and derivative-articles pages.
7. 19 CFR Part 141 — Entry of merchandise.
8. 19 CFR Part 111 — Customs brokers.
9. 15 CFR Part 30 — Foreign trade regulations (statistical reporting).
10. RFC 4180 — Common format and MIME type for CSV files.
11. Related reading — HTS classification guide for beginners (2026).
12. Related reading — TariffWatch $29/mo HTS watchlist.
13. Related reading — Free BIS-14 HTS checker.
14. Related reading — Section 232 inclusion-rebuttal drafting ($99).

TariffWatch is a data and workflow tool that estimates Section 232 tariff exposure from publicly available Federal Register, USITC, and CBP data. TariffWatch is NOT a licensed customs broker under 19 CFR 111, NOT a filer of record, and NOT a legal-advice service. This is not customs classification advice. Compliance decisions remain the responsibility of the importer and their customs broker or trade attorney. TariffWatch does not guarantee that any classification, exposure estimate, or comment letter will be accepted by CBP, BIS, or Commerce.

TariffWatch is not affiliated with the U.S. Department of Commerce, the Bureau of Industry and Security (BIS), U.S. Customs and Border Protection (CBP), or the U.S. International Trade Commission (USITC).

Digital Empire Holdings LLC, 30 N Gould St Ste N, Sheridan WY 82801