DELETE /shipments/{orderId}

Cancel (void) a shipment: request cancellation with the carrier, update order status, and sync the linked rate request when applicable.

Scope: shipments:cancel

Path parameters

Name	Required	Description
orderId	Yes	Order UUID from ship metadata.orderId

Request body

None.

Preconditions

1. Order exists and order.companyId matches the API key organization.
2. Order transitStatus is not already void, canceled, or cancelled (otherwise 409).

Success response (200)

The response is wrapped in data:

{
  "data": {
    "status": "success",
    "title": {
      "en": "Order canceled",
      "fr": "Commande cancelée"
    },
    "messages": []
  }
}

When the carrier cancel API fails but the order is voided locally, the title may be Order voided / Commande annulée and transitStatus is set to void. When the carrier accepts cancellation, transitStatus is set to canceled.

For credit-card–billed orders, void may also trigger a refund; an informational message may appear in messages (e.g. credit card refunded).

Always check data.status === "success" before treating the call as successful.

Business / carrier failure (200 with error payload)

Cancel returns HTTP 200 even when cancellation fails:

{
  "data": {
    "status": "error",
    "title": {
      "en": "Cancel order failed",
      "fr": "Cancellation échouée"
    },
    "messages": [
      {
        "message": "Error detail",
        "severity": "error"
      }
    ]
  }
}

Error responses

HTTP	Condition
400	Missing orderId
401	API key auth failure
403	Missing shipments:cancel scope, or order belongs to another company
404	Order not found
409	Shipment is already canceled (CONFLICT)
500	Server error