Update Shipment Status (Cancel / Resend)

Update the status of an existing shipment. This endpoint allows users to cancel an active shipment (triggering a wallet refund) or resend/reschedule a previously canceled shipment (triggering a wallet deduction).

---

Endpoint

PATCH/v1/shipments/status

Required permission: shipments:status:update

---

Request Body

Field	Type	Required	Description
id	String	✅	The internal ID of the shipment (e.g. SHP_Z8F9A2B3C4).
status	String	✅	The target status. Must be one of PENDING (to resend/reschedule) or CANCELED (to cancel).

---

Wallet Adjustments & Rules

Canceling or resending shipments affects your workspace prepaid wallet balance atomically:

• Cancel Shipment (CANCELED):
  • The shipment status is changed to CANCELED.
  • The full shipment cost (totalCost) is refunded back to your workspace wallet balance immediately.
• Resend Shipment (PENDING):
  • The shipment status is reset back to PENDING to make it available for delivery again.
  • The shipment cost (totalCost) is deducted from your workspace wallet balance.
  • If your wallet balance is lower than totalCost, the request will fail with a 400 Bad Request error.

---

Response

On success, returns the updated shipment record with a status transition event appended to the history.

Field	Type	Description
id	String	Internal shipment ID.
status	String	The updated status (PENDING or CANCELED).
events	Array	Appended event list (e.g. "Shipment Canceled" or "Shipment Rescheduled").

---

{
"id": "SHP_Z8F9A2B3C4",
"status": "CANCELED"
}