Customs declaration data

nutrab2b.logistics.customs_data.v2 · Logistics & customs

Purpose: Pre-filled data for import/export filing: HS and national codes, origin, preference, values, licences, prior notice.
When to send: Before export / import filing.
Sender → receiver: Exporter / importer of record → Broker, buyer
Expected responses: ACK
Equivalent standards: EDIFACT: CUSDEC · X12: 309/350 (US ACE)
Scenarios using it: Full order-to-cash · India → EU → US re-export

Fields and mappings

Field	Type	Req	Description	Code list / format
declaration_ref	string	yes	Reference
asn_id	string	yes	Shipment
procedure	string	yes	Customs procedure	customs_procedure
export_country	string	yes	Export country	country
import_country	string	yes	Import country	country
filing_date	date	yes	Planned filing dateNB-R017
importer_eori	string		Importer EORI / IOR number
fda_prior_notice	string		US FDA prior notice confirmation
items	array<object>	yes	Declared items
line_no	integer	yes	Line
hs_code	string	yes	HS (6)NB-R005 NB-R017	^\d{4}(\.\d{2}){1,2}$\|^\d{6,10}$
national_code	string	yes	Import country national tariff lineNB-R005	^\d{8,10}$
description	string	yes	Goods description
origin	string	yes	Country of origin	country
preference	string		Preferential origin basis	origin_preference
net_quantity	object	yes	Net quantity
value	number	yes	Quantity
uom	string	yes	Unit of measure	uom
customs_value	object	yes	Customs value
amount	number	yes	Amount in major units, decimals ≤ currency minor unitsNB-R011
currency	string	yes	Currency	currency
form	string		Product formNB-R017	product_form

Business rules

NB-R005 HS / national code mismatch, national tariff code does not start with the HS code, or is not a national line for the destination.
NB-R011 Currency precision, amount has more decimals than the currency's ISO 4217 minor units.
NB-R017 HS 2028 reclassification, from 2028-01-01, dietary supplements in measured doses classify in 2107.10, not 2106.90.

Example

{
  "specversion": "2.0",
  "id": "evt-customs-ASN-9001-1",
  "type": "nutrab2b.logistics.customs_data.v2",
  "source": "urn:gln:0614141000012:erp",
  "subject": "ASN-9001",
  "time": "2026-11-02T09:00:00Z",
  "datacontenttype": "application/json",
  "dataschema": "https://nutrab2b.org/schemas/2.0/CUSTOMS.json",
  "sender": {
    "gln": "0614141000012"
  },
  "receiver": {
    "gln": "4012345000009"
  },
  "correlationid": "CONV-RFQ-1001",
  "idempotencykey": "CUSTOMS:ASN-9001:1",
  "sequence": 1,
  "env": "test",
  "data": {
    "declaration_ref": "CD-2026-881",
    "asn_id": "ASN-9001",
    "procedure": "IM4",
    "export_country": "IN",
    "import_country": "US",
    "filing_date": "2026-11-29",
    "fda_prior_notice": "PN-88123",
    "items": [
      {
        "line_no": 1,
        "hs_code": "1302.19",
        "national_code": "1302194000",
        "description": "Ashwagandha root extract",
        "origin": "IN",
        "preference": "NONE",
        "net_quantity": {
          "value": 500,
          "uom": "KGM"
        },
        "customs_value": {
          "amount": 29000,
          "currency": "USD"
        },
        "form": "EXTRACT_DRY"
      }
    ]
  }
}

Mapping checklist

Every required field populated from your system of record
Coded fields mapped to the Bodylia OpenB2B code lists
GLN, GTIN and SSCC check digits validated
Rules above pass in the validator
Idempotency key and per-subject sequence generated
Expected responses, including rejections, handled