Set and read shipping dates and track & trace#

This guide explains how to set the suggested shipping date and expected delivery date on order items, how to read the actual shipping date once a delivery has been processed, and how to retrieve track & trace information from a parcel.

Overview#

Fetch the order to get its delivery and inventory item IDs
Set the suggested shipping date with setShipAtForOrderItems
Set the expected delivery date with setExpectedAtForOrderItems
Read the actual shipping date from delivery.handled_at after the delivery is processed
Read track & trace from parcel.track_trace

Step 1 — Fetch the order deliveries and item IDs#

Query the order to get the delivery details (including dates) and the item IDs you will update.

query GetOrderDeliveries($orderId: String!) {
  order(id: $orderId) {
    id
    number
    deliveries {
      id
      status
      handle_at
      handled_at
      expected_at
      parcels {
        id
        number
        status
        track_trace {
          number
          url
        }
      }
    }
    items {
      label
      sku
      quantity
    }
  }
}

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

Then fetch the physical inventory item IDs using the items query:

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

{
  "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.

Step 2 — Set the suggested shipping date#

setShipAtForOrderItems sets the planned ship date on a set of inventory items. This is the date your warehouse intends to dispatch the goods — it appears as delivery.handle_at when you query the order.

Input: SetShipAtForOrderItemsInput!

Name	Type	Required	Description
`ship_at`	Int64!	Required	Unix timestamp (milliseconds) of the planned shipping date.
`items`	[String!]!	Required	List of CollectionItem IDs (UUIDs) to set the date on.

Returns: SetShipAtForOrderItemsPayload

Name	Type	Required	Description
`items`	[CollectionItem!]!▾	Required	Items whose suggested ship date was updated

mutation SetShipAt($input: SetShipAtForOrderItemsInput!) {
  setShipAtForOrderItems(input: $input) {
    items {
      id
      sku
    }
  }
}

{
  "input": {
    "ship_at": 1748822400000,
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345"
    ]
  }
}

Note:The timestamp 1748822400000 equals 2025-06-02 00:00:00 UTC. Use Date.now() or your language's equivalent to compute the value from a date object.

Step 3 — Set the expected delivery date#

setExpectedAtForOrderItems sets the date the customer expects to receive the goods. This is stored as delivery.expected_at on the delivery.

Input: SetExpectedAtForOrderItemsInput!

Name	Type	Required	Description
`expected_at`	Int64!	Required	Unix timestamp (milliseconds) of the expected delivery date.
`items`	[String!]!	Required	List of CollectionItem IDs (UUIDs) to set the date on.

Returns: SetExpectedAtForOrderItemsPayload

Name	Type	Required	Description
`items`	[CollectionItem!]!▾	Required	Items whose expected delivery date was updated

mutation SetExpectedAt($input: SetExpectedAtForOrderItemsInput!) {
  setExpectedAtForOrderItems(input: $input) {
    items {
      id
      sku
    }
  }
}

{
  "input": {
    "expected_at": 1749081600000,
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345"
    ]
  }
}

Step 4 — Read the actual shipping date#

The actual shipping date is recorded automatically by the platform when a delivery is processed. Query delivery.handled_at to retrieve it:

query GetDeliveryDates($orderId: String!) {
  order(id: $orderId) {
    deliveries {
      id
      handle_at
      handled_at
      expected_at
      status
    }
  }
}

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

| Field | Description | |---|---| | handle_at | Suggested shipping date — set via setShipAtForOrderItems | | handled_at | Actual shipping date — set by the platform when the delivery is processed | | expected_at | Expected delivery date — set via setExpectedAtForOrderItems |

Note:handled_at is null until the delivery has been processed. Poll or use webhooks to detect when a delivery status changes to determine when this date is set.

Step 5 — Read track & trace#

Track & trace information is stored on the parcel level. After creating a parcel (see Create a parcel and add track & trace), query the delivery's parcels to retrieve the tracking details:

query GetTrackTrace($orderId: String!) {
  order(id: $orderId) {
    deliveries {
      id
      status
      parcels {
        id
        number
        status
        track_trace {
          number
          url
        }
      }
    }
  }
}

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

The track_trace.url is the direct link to the carrier's tracking page that you can share with your customer.