Generates a CN22/CN23 postal customs declaration from a commercial-invoice

payload (the form is chosen by goods value). Emits a signed edi.postal_declaration.generated event.

POST /v1/customs/postal/{partner_id}

cURL

curl --request POST \
  --url 'https://edi.stateset.com/v1/customs/postal/{partner_id}' \
  --header "Authorization: Bearer $STATESET_EDI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "buyer": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "currency": "USD",
  "freight": "string",
  "incoterms": "string",
  "incoterms_place": "string",
  "insurance": "string",
  "invoice_date": "2026-08-31T14:22:05Z",
  "invoice_number": "ORD-10042",
  "lines": [
    {
      "country_of_origin": "US",
      "description": "Two-person tent, green — replacement for damaged pole set.",
      "hs_code": "string",
      "net_weight_kg": "string",
      "quantity": "string",
      "sku": "SKU-TENT-2P-GRN",
      "unit_price": "49.00",
      "uom": "string"
    }
  ],
  "po_number": "ORD-10042",
  "reason_for_export": "string",
  "seller": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "ship_to": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}'

payload (the form is chosen by goods value). Emits a signed edi.postal_declaration.generated event.

Path parameters

partner_id · string · required

Partner ID

Request body

CommercialInvoice

buyer · CustomsParty · required

currency · string

ISO currency code the values are expressed in.

freight · string

Freight charge added to the customs value (when DDP/CIF style terms).

incoterms · string

Incoterms 2020 three-letter rule, e.g. DAP, DDP, EXW.

incoterms_place · string

Named place for the incoterm, e.g. Rotterdam.

insurance · string

Insurance charge added to the customs value.

invoice_date · string · required

invoice_number · string · required

lines · CustomsLine[] · required

po_number · string

reason_for_export · string

Why the goods are being exported (sale, sample, return, gift) — a CN22/23 and many national customs forms require it.

seller · CustomsParty · required

ship_to · object

Response

No response body. Postal declaration (structured + HTML).

Status codes

Code	Meaning
200	Postal declaration (structured + HTML)
403	Not this credential’s partner
422	Invalid payload

cURL

curl --request POST \
  --url 'https://edi.stateset.com/v1/customs/postal/{partner_id}' \
  --header "Authorization: Bearer $STATESET_EDI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "buyer": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "currency": "USD",
  "freight": "string",
  "incoterms": "string",
  "incoterms_place": "string",
  "insurance": "string",
  "invoice_date": "2026-08-31T14:22:05Z",
  "invoice_number": "ORD-10042",
  "lines": [
    {
      "country_of_origin": "US",
      "description": "Two-person tent, green — replacement for damaged pole set.",
      "hs_code": "string",
      "net_weight_kg": "string",
      "quantity": "string",
      "sku": "SKU-TENT-2P-GRN",
      "unit_price": "49.00",
      "uom": "string"
    }
  ],
  "po_number": "ORD-10042",
  "reason_for_export": "string",
  "seller": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "ship_to": {
    "address_lines": [
      "548 Market St"
    ],
    "city": "San Francisco",
    "country": "US",
    "name": "Two-Person Tent",
    "postal_code": "94107",
    "state": "CA",
    "tax_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}'