Create a parcel and add track & trace#

This guide shows how to create a parcel for an order's delivery, assign specific inventory items to it, and attach a track & trace number so customers can follow their shipment.

Overview#

Fetch the order to get the delivery ID and item IDs
Create a parcel with createParcelForDelivery
Attach track & trace with addTrackTraceToItems

Step 1 — Fetch the delivery ID and item IDs#

An order has one or more deliveries. Query the order to get the delivery ID, then fetch the corresponding inventory items using the items query filtered by order_id.

query GetOrderForShipping($orderId: String!) {
  order(id: $orderId) {
    id
    number
    deliveries {
      id
      status
    }
    items {
      label
      sku
      quantity
    }
  }
}

{
  "orderId": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
}

Fetch the physical inventory items (with their IDs) using the items query:

query GetOrderItems($filters: CollectionItemFilterInput!) {
  items(filters: $filters) {
    id
    sku
    label
    is_allocated
  }
}

{
  "filters": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

ℹ

Tip:Use the id values from the items response as the items input in the mutations below. These are CollectionItem IDs (UUIDs).

Step 2 — Create a parcel#

Use createParcelForDelivery to create a parcel for a specific delivery and assign items to it.

Input: CreateParcelForDeliveryInput!

Name	Type	Required	Description
`delivery_id`	String!	Required	The ID of the delivery to create a parcel for (from `order.deliveries[].id`).
`items`	[String!]!	Required	List of CollectionItem IDs to include in this parcel.

Returns: CreateParcelForDeliveryPayload

Name	Type	Required	Description
`parcels`	[Parcel!]!▾	Required	Parcels created for the delivery
`items`	[CollectionItem!]!▾	Required	Items assigned to the new parcel

mutation CreateParcel($input: CreateParcelForDeliveryInput!) {
  createParcelForDelivery(input: $input) {
    parcels {
      id
      number
      status
      track_trace {
        number
        url
      }
    }
    items {
      id
      sku
    }
  }
}

{
  "input": {
    "delivery_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345"
    ]
  }
}

Step 3 — Add track & trace#

Once the parcel is created, attach a track & trace number and URL to the items using addTrackTraceToItems.

Input: AddTrackTraceToItemsInput!

Name	Type	Required	Description
`track_trace_number`	String!	Required	The carrier-issued tracking number (e.g. "3SPOST12345678").
`track_trace_url`	String!	Required	The full URL where the customer can track the shipment.
`items`	[String!]!	Required	List of CollectionItem IDs to assign the track & trace to.

Returns: AddTrackTraceToItemsPayload

Name	Type	Required	Description
`parcels`	[Parcel!]!▾	Required	Parcels carrying the updated track & trace
`items`	[CollectionItem!]!▾	Required	Items the track & trace was attached to

mutation AddTrackTrace($input: AddTrackTraceToItemsInput!) {
  addTrackTraceToItems(input: $input) {
    parcels {
      id
      number
      status
      track_trace {
        number
        url
      }
    }
    items {
      id
      sku
    }
  }
}

{
  "input": {
    "track_trace_number": "3SPOST12345678",
    "track_trace_url": "https://track.postnl.nl/3SPOST12345678",
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345"
    ]
  }
}

Notes#

A single order can have multiple deliveries — use the correct delivery_id matching the items you are shipping.
The same item IDs are used in both createParcelForDelivery and addTrackTraceToItems.
track_trace_url should be the direct tracking page URL, not just the carrier's homepage.
See Queries → parcel to fetch the full parcel details after creation.