A customs declaration is the legal statement of what is crossing a border, who is sending and receiving it, and what it is worth — and Docyield's parser reads it into structured fields you can file, audit, or feed into a trade system. It captures the declaration number, the date, the exporter and importer, the countries of origin and destination, the incoterms and currency, each declared line with its HS code, quantity, and value, plus the total value and the total duties. Upload a declaration as a PDF or photo and get JSON, CSV, or Excel back.
Declarations are unforgiving documents: the HS code drives the duty rate, the declared value drives the tax, and an error invites a hold or a penalty. Docyield reads the form line by line and keeps each commodity code tied to its quantity and value, so the data lands accurately enough to check against an entry rather than as loose text that has to be re-sorted by hand.
What a customs declaration states
A customs declaration is the formal submission to a customs authority describing goods being imported or exported. It identifies the exporter and importer, the country the goods originate from and the country they are bound for, the terms of sale through incoterms, and the currency of the transaction. Crucially, it lists each item with its Harmonised System (HS) code, quantity, and declared value, and it totals the value of the consignment and the duties and taxes assessed against it.
In the trade flow, the declaration is prepared from the commercial invoice, packing list, and transport documents, then lodged with customs before goods can clear. Brokers compile it, customs assess it, and importers are liable for the duties it carries. Because the HS code and value determine the money owed, the declaration is the document where accuracy translates most directly into cost and compliance risk.
Why structured extraction beats manual entry
Compiling and checking declarations means handling HS codes, values, and country fields across many lines — exactly the data that is painful and risky to rekey. A mistyped HS code can land goods in the wrong duty bracket, and a transposed value misstates the tax. Pulling the fields structurally captures each line's code, quantity, and value in one read, so they can be checked against the source invoice automatically instead of by eye.
OCR alone returns the text but leaves the interpretation to you — which figure is the declared value, which the duties, which code belongs to which line. Docyield returns named fields and keeps each declared item as its own record, so a trade or audit system can rely on 'hsCode', 'value', and 'dutiesTotal' meaning the same thing on every declaration it ingests.
Who uses a customs declaration parser
- Customs brokers and freight forwarders capturing declaration data for filing and audit.
- Importers and exporters reconciling declarations against commercial invoices and HS classifications.
- Trade-compliance teams checking declared values and duties for accuracy.
- Finance teams reconciling assessed duties and taxes against landed-cost estimates.
- Logistics and ERP integrations that need declaration data captured structurally.
- Auditors building a searchable record of past declarations and their HS codes.
Accuracy, blanks, and review
We make no claim of perfect extraction, and on a compliance document that honesty matters more than usual. Docyield is built to be accurate on clear declarations and transparent about the hard ones. Where a field — an HS code, a duty figure, an incoterm — is genuinely absent, it returns empty rather than a guess, because a fabricated commodity code or value on a customs document carries real legal and financial consequences.
Image quality shapes the result, particularly for HS codes and values packed into a multi-line table. A clean PDF reads well; a stamped, faxed, or photographed declaration is harder. Given what rides on these figures, a review step is genuinely warranted: the source sits beside the extracted data so a broker or compliance reviewer can confirm the codes and values before the declaration is relied upon.
HS codes, values, and duties
Docyield returns each declared line as a structured record carrying its goods description, HS or commodity code, quantity, and declared value, so the classification stays bound to the item it describes. That line-level detail is what lets you verify a declaration against the underlying invoice and catch a mismatched code or value before it becomes a query.
At the document level, the total declared value and the total duties and taxes come back as their own numeric fields, distinct from the per-line values. That separation supports reconciliation — summing the line values and checking them against the stated total, or comparing assessed duties against a landed-cost estimate — without any manual untangling of summary from detail.
Output formats, API, and batch
Every parse exports as JSON, CSV, Excel, or XML from the same result. JSON suits feeding declarations into a trade or compliance system; CSV and Excel suit teams reconciling values and duties in a spreadsheet; XML fits older customs-adjacent or ERP feeds. The free tool handles one declaration at a time, which covers an ad-hoc check or filing.
For brokers and forwarders processing declarations in volume, the same extraction runs through the Docyield API and batch dashboard, with webhook delivery and your own validation rules — for instance, flagging any line missing an HS code. The schema in the free tool is what the API returns, so a compliance workflow built on these fields carries over to an automated pipeline unchanged.
How a declaration differs from a commercial invoice
A commercial invoice is the seller's statement of the goods sold and their prices; it is the commercial basis for the transaction. A customs declaration is the regulatory statement made to a customs authority, built from that invoice but adding HS classifications, duties, and the country and incoterm detail customs require. They share data but serve different masters — one the buyer and seller, the other the state. A dedicated declaration parser keeps the focus on the HS codes, declared values, and duties that drive a customs assessment rather than the sale-oriented fields of an invoice.
What the customs declaration parser extracts
Each declaration is returned against a fixed schema. Fields not present on a document come back empty rather than guessed.
- Declaration number
- The customs declaration number.
- Date
- The date of the declaration.
- Exporter
- The exporter or consignor.
- Importer
- The importer or consignee.
- Country of origin
- The country the goods originate from.
- Country of destination
- The country the goods are bound for.
- Incoterms
- The incoterms or delivery terms of the transaction.
- Currency
- The ISO currency code or symbol used.
- Items
- Each declared line, with description, HS code, quantity, and value.
- Total value
- The total declared value of the consignment.
- Duties total
- The total duties and taxes assessed.
How to convert a customs declaration to JSON, CSV, or Excel
- 1Upload your declaration — drop a PDF, PNG, JPG, or WEBP onto the box above, or click to choose a file.
- 2Wait a few seconds while Docyield reads the form and extracts the declared lines and totals.
- 3Review the result and confirm the HS codes, values, and duties against the original.
- 4Choose your output tab — JSON, CSV, Excel, or XML.
- 5Copy the result or download the file, ready to file or import into your trade system.
Frequently asked questions
Processing documents at scale?
Batch upload, an extraction API, and webhooks for 100+ documents a month.