customerTrackShipment

Requires a customer (portal or buyer app) session.

The in-app tracking view for one of the buyer's shipments (an order shipment this buyer may see, or the company's own return pickup): the shipment, its progress steps and when the carrier was last asked. Opening it asks the carrier (the answer is reused for 60 s); refresh: true asks again unless the last ask was under 30 s ago. A carrier failure sets updateDelayed and still returns the saved timeline. Another company's shipment is not found. Shaped by the store's customer tracking setting: progress-only hides the courier, number and link; order-status-only returns null for an order shipment (show no shipment section).

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

GraphQL

query CustomerTrackShipment($shipmentId: ID!) {
  customerTrackShipment(shipmentId: $shipmentId) {
    canAskCarrier
    checkedAt
    problemStatus
    updateDelayed
    progress {
      at
      state
      step
    }
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "query CustomerTrackShipment($shipmentId: ID!) {\n  customerTrackShipment(shipmentId: $shipmentId) {\n    canAskCarrier\n    checkedAt\n    problemStatus\n    updateDelayed\n    progress {\n      at\n      state\n      step\n    }\n  }\n}",
  "variables": {
    "shipmentId": "id"
  }
}
EOF

Variables:

{
  "shipmentId": "id"
}

Response:

{
  "data": {
    "customerTrackShipment": {
      "canAskCarrier": true,
      "checkedAt": "2025-01-15T00:00:00Z",
      "problemStatus": "AWAITING_PICKUP",
      "updateDelayed": true,
      "progress": [
        {
          "at": "2025-01-15T00:00:00Z",
          "state": "CURRENT",
          "step": "BOOKED"
        }
      ]
    }
  }
}

customerTrackShipment(
  refresh: Boolean = false
  shipmentId: ID!
): CustomerShipmentTracking

Arguments

customerTrackShipment.refresh ● Boolean scalar

True to fetch fresh tracking from the courier instead of using the stored status.

customerTrackShipment.shipmentId ● ID! non-null scalar

The ID of the shipment.

Type

CustomerShipmentTracking object

A buyer's tracking view of one of their shipments: the shipment, its progress steps, any problem it is in, and when the carrier was last asked. Never carries the carrier's error text.