cancelShipment

Requires permission sales:shipment:cancel.

Cancels a shipment with the carrier, with an optional reason. Stock is not returned: a return does that. A shipment the courier already holds (picked up, in transit or out for delivery) or one that has finished cannot be cancelled, and that is checked before the carrier is contacted. Needs the delivery partners feature on your plan and the shipment cancel 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 CancelShipment($id: ID!) {
  cancelShipment(id: $id) {
    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 CancelShipment($id: ID!) {\n  cancelShipment(id: $id) {\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"
  }
}
EOF

Variables:

{
  "id": "id"
}

Response:

{
  "data": {
    "cancelShipment": {
      "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"
      }
    }
  }
}

cancelShipment(
  id: ID!
  reason: String
): ShipmentGql!

Arguments

cancelShipment.id ● ID! non-null scalar

The ID of the shipment.

cancelShipment.reason ● String scalar

Why the shipment is cancelled.

Type

ShipmentGql object

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