POST
/
v1
/
shipments
/
:id
/
cancel
curl --location --request POST 'https://api.stateset.com/v1/shipments/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "reason": "order_cancelled",
    "notes": "Customer requested cancellation before shipment"
}'

{
  "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "shipment",
  "status": "cancelled",
  "cancelled_at": "2024-01-19T17:00:00Z",
  "cancellation": {
    "reason": "order_cancelled",
    "notes": "Customer requested cancellation before shipment",
    "cancelled_by": "user_123"
  },
  "refund": {
    "status": "processed",
    "amount": 1250,
    "currency": "USD",
    "processed_at": "2024-01-19T17:00:15Z",
    "reference": "REF-SHIP-001"
  },
  "tracking_number": "1Z999AA10123456784",
  "carrier": "ups",
  "metadata": {
    "cancellation_reference": "CANCEL-2024-001"
  }
}
This endpoint cancels a shipment and voids the shipping label. Refunds are processed automatically based on carrier policies.

​
Authentication

This endpoint requires a valid API key with shipments:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The unique identifier of the shipment to cancel

​
Request Body

​
reason
string
required
Cancellation reason: “order_cancelled”, “incorrect_address”, “changed_shipping_method”, “duplicate”, “other”
​
notes
string
Additional notes about the cancellation

​
Response

Returns the cancelled shipment with refund information. 
curl --location --request POST 'https://api.stateset.com/v1/shipments/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "reason": "order_cancelled",
    "notes": "Customer requested cancellation before shipment"
}'

{
  "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "shipment",
  "status": "cancelled",
  "cancelled_at": "2024-01-19T17:00:00Z",
  "cancellation": {
    "reason": "order_cancelled",
    "notes": "Customer requested cancellation before shipment",
    "cancelled_by": "user_123"
  },
  "refund": {
    "status": "processed",
    "amount": 1250,
    "currency": "USD",
    "processed_at": "2024-01-19T17:00:15Z",
    "reference": "REF-SHIP-001"
  },
  "tracking_number": "1Z999AA10123456784",
  "carrier": "ups",
  "metadata": {
    "cancellation_reference": "CANCEL-2024-001"
  }
}