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
The delivery option the buyer chose at checkout, as your channel names it (e.g. Express Shipping). Shipping rules can match on it (condition “Shipping method”), so storefront shipping options route to carrier services. The Shopify app sends the order’s shipping line title here automatically.
​
string
The shipping/delivery profile the goods belong to in your channel (e.g. the Shopify delivery profile name USA Bottle Sale). Several profiles on one order are sent comma-separated. Shipping rules can match on it (condition “Shipping profile”). The Shopify app sends it automatically.
​
string
Machine code of that option when your channel has one (Shopify shipping line code).
​
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, type (Business | Residential), 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 (including type), plus time_zone. 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