Skip to main content
POST
Requires the consignments:write scope. Creating a consignment runs your workspace’s validation rules synchronously (an error-severity hit rejects the create with 422; warnings ride the response) and then dispatches your consignment.created automation flows. Two payload shapes are accepted and can be mixed:
  • Consignment-level orders — commercial orders in the top-level orders[] (no items), physical items in parcels[].items[], linked back by order_ref.
  • Nested orders — orders under their parcel in parcels[].orders[], each carrying its own items[].
Every request on this surface is audited: the response carries an X-Request-Id header (a ULID) you can quote to support and look up later.

​
Consignment

​
string
required
Your reference for the shipment (1–100 chars). The only required top-level field.
​
integer
The customer this consignment belongs to. A customer-scoped API key pins its own customer and ignores this field; omitted otherwise, the consignment has no customer.
​
string
default:"delivery"
delivery, return, or exchange.
​
string
Your product/plan code — shipping rules and flows match on it.
​
string
Incoterm (e.g. DDP, DAP).
​
string
YYYY-MM-DD.
​
string
sea, air, road, or rail.
​
string
kg, g, lb, or oz — the unit for every weight in the payload.
​
string
cm, mm, or inch — the unit for parcel dimensions.
​
string
b2b, b2c, c2b, or c2c.
​
object
Shipment-level freight: { amount, currency_code } (currency required when given).
​
object
Shipment-level insurance: { amount, currency_code }.
​
array
Free-text tags.
​
object
Carrier custom references: external_item_code, external_order_code, special_provision, sender_ukims_number, receiver_ukims_number.
​
object
Supporting addresses keyed return, pudo, importer_of_record, billing — each a slim address (company_name, address_1, address_2, city, state_province, post_code, country_code, type, contact).
​
object
Explicit carrier selection — always wins over shipping rules: { org_carrier_id, service_id?, additional_service_ids? }.
Additional optional fields: nature_type (UPU CL136 code), shipping_date, invoice_number, invoice_url, office_of_origin, windsor_not_at_risk, picking_ref, contract_condition, total_discount ({ amount, currency_code }), attributes (cash_on_delivery, notification_type, flexible_delivery, pod_required, content_type), committed_delivery_window ({ from, to }), and volume_unit (ml | l).

​
Sender and receiver

​
object
The shipper: code, company_name, address_1–address_3, city, state_province, post_code, country_code (ISO alpha-2), contact (name, phone, email), plus tax/duty registrations eori_id, ioss_id, vat_id, tax_id, manufacturer_id.
​
object
The consignee — same shape as sender, plus time_zone and type (Business | Residential).

​
Orders

​
array
Consignment-level commercial orders (up to 200). Each requires order_ref (unique across the consignment), plus optional amount, currency_code, order_date, invoice_number, shipping_charge / insurance_charge / other_charge (each { amount, currency_code }).

​
Parcels

​
array
Each parcel requires weight_value. Optional: sender_ref, barcode (your own parcel barcode — never overwritten by carrier labelling), packaging_type (BAG | BOX | ENVELOPE | PALLET | TUBE, default BOX), height, width, depth, declared_value, currency_code, plus its contents in items[] and/or legacy nested orders[].
​
array
The declared item lines. Per item:
  • quantity (required) — positive integer
  • unit_value (required) — per-unit price, not the line total
  • currency_code — ISO 4217
  • order_ref — links the item to a consignment-level order (must exist in orders[])
  • sku — your item reference (stored as item_ref)
  • title, description
  • harmonised_code / hs_code — declared HS code, if known; hs_code_source records where it came from (audit only)
  • country_of_origin — ISO alpha-2 country of manufacture
  • product_url — the item’s listing page (usable by AI classification)
  • weight
  • Section 232 metals traceability: country_of_melt_pour, primary_country_of_smelt, secondary_country_of_smelt, country_of_cast
  • CN23/ITMATT: nature_type, certificate_number
  • compliance — agency certs keyed by scheme (e.g. cpsc)
  • dangerous_goods — structured DG declaration (un_id, shipping_name, product_class, packaging_group, …)
International consignments (sender and receiver in different countries) must carry at least one item, and every item must have a country_of_origin — customs declarations and the commercial invoice are built from the item lines. Domestic consignments are exempt. Items must live inside a parcel (parcels[].items[]) or a nested order — top-level items are rejected.

​
Response

Returns 201 with data containing the created tree:
​
object
The consignment (id, shipment_ref, status, sender, receiver, created_at, …) including its customer when one was linked.
​
array
The parcels, each with its orders and items nested.
​
array
The consignment-level orders (commercial view, items included).
​
array
Documents attached during creation — only populated when an inline flow (e.g. generate_invoice) ran; background flows attach later.
​
array
Present when warning-severity validation rules matched — the consignment was created.
By default, consignment.created flows run in the background. A flow action marked “Wait and include in API response” runs inline: the response then carries fresh label/tracking/invoice data on the parcels and consignment, and a failed wait-flow (with no side effects) rolls the create back and returns 422 with the error message(s).
422