Developers · Schemas
Schemas and the CN 23 field map
One JSON Schema for postal items. It follows the CN 22 and CN 23 customs declaration, which the UPU ITMATT message carries in electronic form.
Downloads
JSON Schema draft 2020-12. Use the SHA-256 value to check your copy.
JSON Schema 2020-12
postal-items.v1.jsonBatch, dispatch, item and contents.
- SHA-256:
- ddfdad6b61137e8e68298b39716200a95c2a577914c9bae8bca4b74b59d87884
- Size:
- 8,237 B
Example
postal-items.v1.example.jsonOne dispatch with one item. It passes the schema.
- SHA-256:
- 02cf9af6f851f2b89d658b9fe4cf82bdd2270f1739ef89b3e9b081ed783bec4a
- Size:
- 1,179 B
OpenAPI 3.1Planned
postal-api.v1.yamlThe API description, published with the sandbox.
CN 23 content, Allied field and ACE record
Postal items carry no master or house air waybill. The S10 item identifier plays that role (WCO-UPU Guidelines on Exchange of Electronic Advance Data, 2025).
| CN 22 / CN 23 content | Allied field | ACE, entry type 13 |
|---|---|---|
| S10 item identifier | item_id | SE15 bill (air: SFP + S10, issuer blank; truck, rail, ocean: issuer SFP); AE 23-record type M |
| Sender | sender | SE30 name and SE35 address (mandatory) |
| Addressee | addressee | SE30 consignee by name and address; Final Delivered To party |
| Category of item | nature_code (UPU code list 136) | Screening input |
| Quantity and detailed description | contents[].description, quantity | SE40 commercial description (mandatory) |
| Net weight | contents[].net_weight_kg | Quantity and weight when a specific duty rate applies |
| Value | contents[].value, currency | SE60 line value (mandatory); $2,500 limit (code 323) |
| HS tariff number | contents[].hs_code | 10-digit HTSUS number and Chapter 99 numbers (SE60), assigned by Allied |
| Country of origin | contents[].origin_country | Country of origin |
Item fields
The fields of one item.
| Field | Type | Required | Rule |
|---|---|---|---|
item_id | string | Yes | UPU S10: 2 letters, 8 digits, check digit, 2 letters. |
nature_code | integer | Yes | UPU code list 136. |
sender | object | Yes | Name and address (line 1, city, country). |
addressee | object | Yes | Name and U.S. address with a 5-digit ZIP code. |
contents[] | array | Yes | 1 to 99 lines. |
contents[].description | string | Yes | 3 to 200 characters, specific enough to classify. |
contents[].quantity | integer | Yes | 1 or more. |
contents[].net_weight_kg | number | Yes | More than 0. |
contents[].value | string | Yes | Decimal with 2 places, for example 45.00. |
contents[].hs_code | string | Yes | 6 to 10 digits. |
contents[].origin_country | string | Yes | ISO 3166-1 alpha-2 country code. |
currency | string | Yes | ISO 4217 currency code. |
gross_weight_kg | number | Yes | More than 0. |
postage_paid, insurance | string | No | Decimal with 2 places. |
receptacle_id | string | No | UPU S9 identifier of the bag that holds the item. |
Item nature codes
UPU code list 136.
| Code | Meaning |
|---|---|
| 11 | Sale of goods |
| 111 | Commercial sale of goods (business to business) |
| 21 | Returned goods |
| 31 | Gift |
| 32 | Commercial sample |
| 91 | Documents |
| 999 | Other |
Example batch
The file
postal-items.v1.example.json.postal-items.v1.example.json
{ "batch_ref": "POST-DISPATCH-2026-10-01-A", "sent_at": "2026-10-01T09:30:00Z", "dispatch": { "dispatch_id": "DISPATCH-0001", "mode": "AIR", "carrier": "EXAMPLE AIRLINE", "flight_or_trip": "XX123", "us_port_code": "4701", "expected_arrival_date": "2026-10-02" }, "items": [ { "item_id": "CP123456785CA", "nature_code": 11, "sender": { "name": "EXAMPLE SHOP LTD", "address": { "line1": "100 EXAMPLE ST", "city": "TORONTO", "region": "ON", "postal_code": "M5V1A1", "country": "CA" } }, "addressee": { "name": "JANE SAMPLE", "address": { "line1": "100 MAIN ST", "city": "NEWARK", "state": "NJ", "zip5": "07102" } }, "contents": [ { "description": "WOMEN'S KNITTED COTTON SWEATER", "quantity": 1, "net_weight_kg": 0.4, "value": "45.00", "hs_code": "611020", "origin_country": "CA" } ], "currency": "CAD", "gross_weight_kg": 0.5, "postage_paid": "18.50" } ]}Start with a data test
Send us a sample dispatch in JSON, CSV or Excel. We report each gap in the data before the first entry. Quote on request.
Call (908) 291-8001 or email mail@alliedchb.com