How to extract HTS-eligible fields from commercial invoices with Tandom Document Intelligence

TL;DR

• A commercial invoice carries every field CBP needs for entry under 19 USC 1481 and 19 CFR 141.86: parties, country of origin per line, detailed description, quantity, unit price, currency, charges, and any HS or HTS hint the exporter wrote in.
• Tandom Document Intelligence (closed beta) at POST /v1/extract/invoice returns the structured field set per line, plus per-field confidence scores. Chain into /v1/classify to get a verified 10-digit HTS code, then /v1/duty/calculate to get the full landed-duty stack in ACE reporting order.
• The pipeline cuts entry preparation from ~15 minutes per shipment of manual rekey to a single API round trip plus human review on flagged fields. Confidence scores route the low-certainty lines to a broker; everything else clears straight through.
• The Duty Calculator at tariffs.tandom.ai/calculator is available now. Document Intelligence and the HTS Classifier are closed beta as of May 2026.

The HTS-eligible field set

The list below is the practical superset of fields the extractor must surface. Some come straight from the invoice header; some live on each line; a few rarely appear on the invoice itself and must be flagged when missing.

Header fields

• Invoice number, date, currency. Required by 19 USC 1481(a)(1) and (a)(2). Currency drives the FX-rate lookup for customs valuation.
• Importer of record, exporter, ship-to, manufacturer. Required by 19 USC 1481(a)(3) and (a)(4). The manufacturer identifier (MID) is needed for Section 301 and AD/CVD scope checks, not just Customs entry.
• INCOTERMS. Drives whether freight, insurance, and additional charges are included in the invoice price or invoiced separately. EXW means the buyer adds freight to customs value; DDP means duties are inside the quoted price (and have to be backed out).
• Total invoice value, currency, payment terms. Cross-checked against the line-item sum and against the buyer's purchase order if attached.

Per-line fields

• Detailed description. The commercial description, the marketing name, the SKU, and any specs (material, gauge, dimensions, end-use). Per 19 USC 1481(a)(5), descriptions vague enough to obscure tariff treatment are grounds for refusing entry.
• Quantity per net unit. Pieces, kilograms, liters, dozens, and so on. Drives quantity-based duty rates, AD/CVD per-unit deposits, and PGA reporting.
• Unit price and extended value. In invoice currency. Extended value is unit price times quantity, line-by-line, before discounts or charges.
• Country of origin. Per 19 CFR 134.1, the country where substantial transformation last occurred, not the country the goods last shipped from. Origin on the invoice is the starting point; the broker confirms.
• HS or HTS hint. The exporter often codes the line at 6-digit HS or 10-digit US HTS. The 6-digit HS subheading transfers across countries; the US stat-suffix often does not. Treat exporter codes as a hint.
• End-use code. Drives PGA flagging (FDA product code, EPA code, FCC code, ATF code, CPSC certification). Sometimes pre-coded; often inferred from description.

Often-missing fields the extractor flags

• Country of melt-and-pour (steel) and country of smelt-and-cast (aluminum). Required for Section 232 derivative classification across HTS Chapters 73, 76, 82, 83, 84, 85, and 87. Rarely on the invoice itself; usually on a mill-certificate attachment. When neither shows them, the line must be flagged for the broker to request a mill certificate before filing.
• Assists, royalties, selling commissions, proceeds. Per 19 USC 1401a additions to transaction value. The extractor cannot find what is not on the document; the broker fills these in from the buyer's side data.
• Section 301 exclusion certificate. If the importer holds an active product-specific exclusion, the certificate's effective dates and the named importer must be verified against the line and the entry date. The extractor captures any cited Chapter 99 exclusion subheading; the broker confirms certificate validity against the source FRN.

The extraction pipeline

Extraction is one stage of three. Run them in order; each stage's output becomes the next stage's input.

1. Extract

POST the invoice file to /v1/extract/invoice. The endpoint accepts PDF (image-based or text), JPEG, PNG, and HEIC. The response contains a header object, a parties object, an array of lineItems, a totals object, and a confidenceByField map. Image-based PDFs run through OCR before the structured pass; output looks identical to a text-PDF response.

2. Classify each line

Send each lineItem through /v1/classify with the description, country of origin, the exporter's HS hint (if any), quantity, unit, and unit value. The classifier runs General Rules of Interpretation reasoning and returns the verified 10-digit HTS code, a confidence band, plus any cross-rulings or contested headings. For lines where the exporter coded a 10-digit US HTS and the description supports the code, the classifier confirms and returns immediately. For lines where the description contradicts the code, the classifier returns the corrected code with reasoning.

3. Calculate the landed duty

Send each verified line through /v1/duty/calculate with HTS code, country of origin, customs value (in USD; the extractor handles the FX conversion), entry date, and metals-content fields when applicable (steel %, melt-and-pour, aluminum %, smelt-and-cast). The response carries the full layer stack in ACE reporting order: MFN base, Section 232, Section 301, Section 122, AD/CVD advisory matches, MPF, HMF, and any matched preference program. Sum the per-line amounts for the entry total, applying MPF and HMF at the entry-summary level rather than per line.

Server-side stitching

The Tandom Customs App at app.tandom.ai stitches the three steps server-side. Upload the invoice, get back an ACE-ready entry packet (CBP Form 7501 layout, AD/CVD flags, PGA flags, total duty preview). For brokers building their own pipelines, the three endpoints can be called directly with a Tandom API key.

What Tandom returns

The shape below is the closed-beta GA-target schema for POST /v1/extract/invoice. Field names and types may shift slightly before GA; the structure is stable.

Request

POST https://api.tandom.ai/v1/extract/invoice
Authorization: Bearer tk_live_<your-key>
Content-Type: multipart/form-data

file=@invoice.pdf
language=en           # optional, default 'en'

Response (excerpt)

{
  "documentType": "commercial_invoice",
  "header": {
    "invoiceNumber": "SH-2026-04812",
    "invoiceDate": "2026-04-22",
    "currency": "USD",
    "incoterms": "FOB Shanghai",
    "paymentTerms": "Net 30"
  },
  "parties": {
    "exporter": { "name": "Shanghai Trade Co., Ltd.", "address": "...", "country": "CN" },
    "importer": { "name": "Acme Imports LLC", "address": "...", "country": "US" },
    "manufacturer": { "name": "Suzhou Plant 7", "mid": "CNSHATRA123SHA", "country": "CN" },
    "shipTo": { "name": "Acme Distribution Center", "address": "...", "country": "US" }
  },
  "lineItems": [
    {
      "lineNumber": 1,
      "description": "15.6\" laptop, 8GB RAM, model X-220 (no battery weight 1.4 kg)",
      "sku": "X220-CN",
      "quantity": 50,
      "unit": "EA",
      "unitPrice": 100.00,
      "extendedValue": 5000.00,
      "countryOfOrigin": "CN",
      "hsCodeHint": "8471.30",
      "endUseCode": null
    }
    // ... 9 more line items
  ],
  "totals": {
    "subtotal": 34500.00,
    "freight": null,
    "insurance": null,
    "total": 34500.00,
    "currency": "USD"
  },
  "confidenceByField": {
    "header.invoiceNumber": 0.99,
    "header.currency": 0.99,
    "parties.manufacturer.mid": 0.74,
    "lineItems[0].countryOfOrigin": 0.97,
    "lineItems[3].description": 0.91,
    "lineItems[7].countryOfMeltAndPour": null
  },
  "flags": [
    { "type": "missing_field", "field": "lineItems[7].countryOfMeltAndPour", "severity": "must_resolve" },
    { "type": "low_confidence", "field": "parties.manufacturer.mid", "severity": "review" }
  ]
}

Chaining into the classifier and the calculator

Node.js example. Per-line, the classifier returns a verified 10-digit HTS code; the calculator returns the layered duty stack.

import fs from "node:fs";

const KEY = process.env.TANDOM_API_KEY;
const BASE = "https://api.tandom.ai/v1";

// 1. Extract
const form = new FormData();
form.set("file", new Blob([fs.readFileSync("./invoice.pdf")]), "invoice.pdf");
const extractRes = await fetch(`${BASE}/extract/invoice`, {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}` },
  body: form,
});
const invoice = await extractRes.json();

// 2. Classify each line
const classified = await Promise.all(
  invoice.lineItems.map(async (li) => {
    const r = await fetch(`${BASE}/classify`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        items: [
          {
            description: li.description,
            country: li.countryOfOrigin,
            hsCodeHint: li.hsCodeHint,
            qty: li.quantity,
            unit: li.unit,
            value: li.extendedValue,
          },
        ],
      }),
    });
    const out = await r.json();
    return { ...li, htsCode: out.items[0].suggestedHtsCode };
  })
);

// 3. Calculate landed duty per line
const priced = await Promise.all(
  classified.map(async (li) => {
    const u = new URL(`${BASE}/duty/calculate`);
    u.searchParams.set("hts", li.htsCode);
    u.searchParams.set("origin", li.countryOfOrigin);
    u.searchParams.set("value", String(li.extendedValue));
    u.searchParams.set("date", invoice.header.invoiceDate);
    const r = await fetch(u, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    return { ...li, duty: (await r.json()).dutyInfo };
  })
);

// priced[i] now carries: htsCode, generalRate, chapter99Sources,
// totalDutyAmount, mpf, hmf, landedCost. ACE-ready.

Worked example

A 10-line commercial invoice, China origin, ocean, $34,500 declared value, entry date May 1, 2026.

The extractor returns ten line items with the field set above. The classifier verifies each exporter HS hint against the description and returns a 10-digit HTS code. The calculator returns the per-line duty stack. Below is the consolidated per-line output, exactly as the calculator emits it.

Total declared value: $34,500. Total duty across all 10 lines: $4,823.80, an effective duty rate of 14.0%. Section 301 dominates the bill on furniture, t-shirts, pillows, connectors, and the power adapter; smartphones and laptops clear at $0 under the Section 122 Annex II exception. MPF and HMF are computed at the entry-summary level (0.3464% and 0.125% of $34,500) and are additive to the per-line duty.

Where the extractor saved time

On Lines 4 (cotton t-shirts) and 5 (cotton pillows), the exporter hinted 6109.10 and 9404.90; the classifier resolved to 6109.10.00.40 (women's knitted cotton t-shirts) and 9404.90.10.30 (cotton-shell foam-filled pillow). On Line 8 (steel furniture), the description carried "frame: cold-rolled steel," which forced the calculator to attach a Section 232 advisory check; the smelt-and-cast and melt-and-pour fields were null on the invoice, and the extractor flagged them for broker follow-up.

Where the extractor flagged review

The manufacturer MID came back at confidence 0.74. CBP requires the MID for AD/CVD risk and post-entry audit; below 0.85, Document Intelligence routes the field to manual review. The broker checks the manufacturer block on the invoice against the buyer's vendor master and either confirms the parsed MID or corrects it. The line passes with no other AD/CVD risk flags; the steel-furniture line resolved to advisory only at the heading level (9403), not at the order-scope level.

Common pitfalls

The mistakes that bite on extracted-invoice pipelines:

Trusting the exporter's 10-digit US HTS

The exporter's customs broker on the export side may have used a different stat suffix from the one the US importer should use. The 6-digit subheading is reliable; the last four digits are not. Always pass the exporter's code through the classifier and let GRI reasoning confirm or correct it.

Treating "shipped from" as country of origin

A shipment leaving Vietnam from a Chinese factory is China origin, not Vietnam origin, regardless of the invoice's ship-from. CBP audits trans-shipment aggressively. The extractor captures whatever the invoice declares; the broker confirms against the substantial-transformation test in 19 CFR 134.1.

Ignoring missing metals fields

The country of melt-and-pour or smelt-and-cast rarely appears on the invoice. The extractor flags the field as missing, and the line cannot be priced for Section 232 until the broker requests a mill certificate. Aluminum derivatives entered with smelt-and-cast unknown pay 200% by default since June 28, 2025.

Skipping the parties block on related parties

Related-party transactions still use transaction value if the relationship did not influence the price, per 19 CFR 152.103(j). The extractor flags shared-address or shared-parent signals; the broker tests circumstance-of-sale before committing the customs value. Defaulting to transaction value without testing is a CBP audit target.

Using the invoice currency at the wrong date

The customs value uses the FX rate for the day of export, not the invoice date and not the entry date. 19 CFR 159.31 through 159.38 set the conversion mechanics. Document Intelligence uses the export date when present in the parties or shipping block; otherwise the broker confirms.

Treating quantity per the invoice as quantity per HTS

The invoice may list quantity in pieces; the HTS may require dozens, kilograms, or square meters. The classifier returns the required HTS unit; the extractor converts when the conversion factor is unambiguous and flags otherwise. Specific-rate items (mostly agriculture, textiles, footwear) collapse if the unit is wrong.

Dropping discounts and price adjustments

The dutiable value is the price paid or payable. Trade discounts shown on the invoice reduce the dutiable value when they are unconditional and apply at the time of the sale. Other discounts (volume rebates after the fact, settlement discounts) often do not. The extractor surfaces every discount line; the broker decides which apply.

Missing the Section 301 exclusion certificate window

A Section 301 exclusion certificate is product-specific and time-bounded. The certificate's effective dates must bracket the entry date. The extractor captures any cited Chapter 99 exclusion subheading; the broker re-verifies against the source FRN and the named-importer condition where the exclusion has one.

Missing PGA flags on FDA-regulated lines

FDA, EPA, FCC, ATF, USDA, and CPSC requirements gate entry. They are not duties, but they will hold or refuse the goods. The extractor captures the description and any end-use code; the classifier flags PGA-relevant headings. Skipping the PGA check on food, drugs, devices, cosmetics, electronics, pesticides, firearms, or children's products produces a held entry.

Treating low-confidence fields as committed

Per-field confidence scores are the audit control. Below the configured threshold (default 0.85), the field is held for review. Committing low-confidence fields straight through is the classic ML-pipeline failure mode: the median entry looks fine, and the 5% with broken extractions blow up months later as Notice of Action assessments.

Glossary

Commercial invoice

The seller's billing document for goods sold for export to the US. Required for CBP entry under 19 USC 1481 and 19 CFR 141.86. Distinct from a proforma invoice (pre-shipment quote) and a customs invoice (occasionally a parallel form for specific jurisdictions).

Document Intelligence

Tandom's structured-extraction layer for trade documents. Closed beta as of May 2026. Endpoints under /v1/extract/* cover commercial invoice, packing list, B/L, proforma, arrival notice, booking, and inbound email.

HTS Classifier

Tandom's classifier that takes a description plus optional hints and returns a verified 10-digit HTS code with GRI reasoning. Closed beta. Endpoint: /v1/classify, with conversational refinement at /v1/classify/chat.

MID (Manufacturer Identification Code)

CBP's identifier for the manufacturer, constructed from country, name segments, and city per 19 CFR 102.23. Required on entry summary for AD/CVD risk and post-entry audit. Format: country prefix + first three letters of each of two name words + first three letters of the city, with a numeric segment for disambiguation. Document Intelligence parses or constructs the MID from the manufacturer block.

Confidence score

Per-field probability that the extracted value matches what the document actually says. Returned in the confidenceByField map. Brokers configure a threshold (default 0.85) below which the field is held for human review.

HS hint vs HTS code

HS (Harmonized System) is the 6-digit international code; HTS is the 10-digit US-specific extension. Exporters often code at 6 digits (transferable across markets) or pre-code at 10 (often using their export-side broker's stat suffix). The first six digits transfer; the last four require US-side classification.

INCOTERMS

International commercial terms (Incoterms 2020) defining who bears freight, insurance, risk, and duty. EXW, FOB, CIF, DDP, and DAP are the most common. Drives whether freight and insurance are included in the invoice price for customs value.

Customs value

The dutiable value per 19 USC 1401a. Default is transaction value: the price actually paid or payable for the goods sold for export to the US, plus required additions, minus permitted deductions. Document Intelligence parses the invoice; the broker fills in additions (assists, royalties, commissions) and confirms.

Melt-and-pour

For steel, the country where the raw steel was first solidified into slab, billet, or ingot. Drives Section 232 country-specific rates. Rarely on the commercial invoice; lives on the mill certificate.

Smelt-and-cast

For aluminum, the country where the metal was last liquefied and cast. Drives the 200% Russia-aluminum rate at 9903.85.67 and 9903.85.68. Aluminum derivatives entered with this field unknown pay 200% by default since June 28, 2025.

Substantial transformation

The case-by-case test CBP applies to determine non-preferential country of origin: did processing in country X result in a new article with a different name, character, and use? Defined in 19 CFR 134.1. Distinct from the stricter tariff-shift or regional-value-content tests under preference programs.

ACE

Automated Commercial Environment, CBP's entry-filing platform. Document Intelligence output maps directly to ACE's required fields, including Chapter 99 secondary classifications and PGA message sets.

Closed beta

A Tandom endpoint state where the schema is stable but not yet generally available. Pilot-customer access only, by request. /v1/extract/* and /v1/classify are closed beta as of May 2026. /v1/duty/calculate is available now.

FAQ

The questions brokers and forwarders ask before piping their invoice queue through Tandom.