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).
​
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).
​
string
Own-template parcel labels at create: sync renders one label per parcel from your default parcel label template before responding (URLs ride the 201 in data.labels), async renders them in the background after flows — poll the consignment, list GET /labels, or subscribe to the label.generated webhook. Omitted (or none) = generate on demand via POST /labels/generate. Carrier labels are unaffected — they book via shipping rules / flows as before, and async skips parcels a flow already labelled.
​
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
required
The shipper: country_code (ISO alpha-2, required — customs origin and routing depend on it), plus optional code, company_name, address_1–address_3, city, state_province, post_code, contact (name, phone, email), and tax/duty registrations eori_id, ioss_id, vat_id, tax_id, manufacturer_id.
​
object
required
The consignee — same shape as sender, plus time_zone and type (Business | Residential). Required within it: country_code (ISO alpha-2), address_1, city, and at least one of contact.name / company_name. post_code is required when the destination country uses postal codes.

​
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, and currency_code whenever declared_value is given. 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, 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 (required) — ISO 4217, the currency of unit_value
  • order_ref — links the item to a consignment-level order (must exist in orders[])
  • sku — your item reference (stored as item_ref)
  • title, description — at least one is required (the customs goods description)
  • harmonised_code / hs_code — declared HS code, if known; hs_code_source records where it came from (audit only)
  • customs_description — short plain goods wording (≤255) for declarations and carrier labels; title stays the full commercial name for audit. Falls back to title when omitted.
  • product_type — free-text product type (Shopify-style), stored verbatim. GET /v1/reference/product-types lists suggestions; anything is accepted.
  • catalogue_item_id — the catalogue item the line was filled from (provenance only; the line’s own values are what is declared).
  • country_of_origin — ISO alpha-2 country of manufacture
  • product_url — the item’s listing page (usable by AI classification)
  • weight
  • abv — alcohol by volume, percentage 0–100 (e.g. 13.5)
  • volume — per-unit volume, in the consignment’s volume_unit
  • fabric_content — textile composition (e.g. 80% cotton 20% polyester)
  • Export controls: export_reference_number, export_license_number
  • battery_chem_code — battery chemistry code (e.g. LIION)
  • 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, tracking_number, status, sender, receiver, created_at, …) including its customer when one was linked. tracking_number is generated from the tracking-number structure configured under Settings → Defaults (null when none is configured).
​
array
The parcels, each with its orders and items nested. Each parcel carries an identifiers array — the canonical list of every code the parcel is known by ({ code, kind, owner, carrier_code, role, status, source }): the sender’s barcode, the generated barcode, carrier labels (piece + master tracking numbers), pre-applied labels and printed own-label barcodes. Scanning any of them resolves the parcel. The flat fields (barcode, generated_barcode, carrier_tracking_number) remain as conveniences.
​
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 labels: "sync" was requested — one entry per rendered parcel label: { parcel_id, label_url, barcode_value }. Each parcel’s label_url is also set. Failures (e.g. no template) report in data.label_errors without failing the create.
​
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