trackShipment

Requires permission sales:shipment:read.

The in-app tracking view: 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 10 s ago. A carrier failure sets carrierError (the carrier's own words) and still returns the saved timeline. Rep-scoped: an out-of-scope shipment is not found.

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 TrackShipment($shipmentId: ID!) {
  trackShipment(shipmentId: $shipmentId) {
    canAskCarrier
    carrierError
    checkedAt
    problemStatus
    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 TrackShipment($shipmentId: ID!) {\n  trackShipment(shipmentId: $shipmentId) {\n    canAskCarrier\n    carrierError\n    checkedAt\n    problemStatus\n    progress {\n      at\n      state\n      step\n    }\n  }\n}",
  "variables": {
    "shipmentId": "id"
  }
}
EOF

Variables:

{
  "shipmentId": "id"
}

Response:

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

trackShipment(
  refresh: Boolean = false
  shipmentId: ID!
): ShipmentTracking!

Arguments

trackShipment.refresh ● Boolean scalar

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

trackShipment.shipmentId ● ID! non-null scalar

The ID of the shipment.

Type

ShipmentTracking object

Staff tracking view of a shipment: the shipment, its progress steps, any problem it is in, and the last time the carrier was asked for news (with the carrier's exact error when that ask failed).