recordShipmentStatus

Requires permission sales:shipment:update.

Records a shipment status by hand, for a custom courier only. A courier that reports its own status is refused: use refreshShipmentTracking instead. Only statuses staff may set by hand are accepted (awaiting pickup, picked up, in transit, out for delivery, delivered, failed attempt, exception, returned to sender and lost), and the move must be allowed from the shipment's current status. Marking an order's outbound shipment DELIVERED also needs the sales order deliver permission, because it can mark the order delivered. Needs the delivery partners feature on your plan and the shipment update permission.

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

mutation RecordShipmentStatus($id: ID!, $input: RecordShipmentStatusInput!) {
  recordShipmentStatus(id: $id, input: $input) {
    id
    serviceLevelCode
    shipmentNumber
    trackingNumber
    carrierName
    serviceLevelName
    costSplit {
      changedByName
      changedAt
      courierCharge
      currency
      customerPaid
      plannedCost
    }
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "mutation RecordShipmentStatus($id: ID!, $input: RecordShipmentStatusInput!) {\n  recordShipmentStatus(id: $id, input: $input) {\n    id\n    serviceLevelCode\n    shipmentNumber\n    trackingNumber\n    carrierName\n    serviceLevelName\n    costSplit {\n      changedByName\n      changedAt\n      courierCharge\n      currency\n      customerPaid\n      plannedCost\n    }\n  }\n}",
  "variables": {
    "id": "id",
    "input": {
      "status": "AWAITING_PICKUP"
    }
  }
}
EOF

Variables:

{
  "id": "id",
  "input": {
    "status": "AWAITING_PICKUP"
  }
}

Response:

{
  "data": {
    "recordShipmentStatus": {
      "id": "id",
      "serviceLevelCode": "string",
      "shipmentNumber": "string",
      "trackingNumber": "string",
      "carrierName": "string",
      "serviceLevelName": "string",
      "costSplit": {
        "changedByName": "string",
        "changedAt": "2025-01-15T00:00:00Z",
        "courierCharge": "string",
        "currency": "string",
        "customerPaid": "string",
        "plannedCost": "string"
      }
    }
  }
}

recordShipmentStatus(
  id: ID!
  input: RecordShipmentStatusInput!
): ShipmentGql!

Arguments

recordShipmentStatus.id ● ID! non-null scalar

The ID of the shipment.

recordShipmentStatus.input ● RecordShipmentStatusInput! non-null input

The details of the record shipment status request.

Type

ShipmentGql object

A shipment as staff see it. It includes the seller's cost and is never returned to buyers.