Changing Shipment States Manually
This page explains how to use the Change Shipment State endpoint to make manual alterations to a shipment's
Using the Change Shipment State Endpoint
This endpoint is intended to enable you to change the state of a shipment due to exceptional circumstances, rather than as part of a standard workflow.
Ship only allows certain manual state transitions. For instance, you cannot transition a shipment from a state of
allocated – this state change can only be carried out by the application itself as a result of a successful allocation.
To call Change Shipment State, send a
PUT request to
https://api.sorted.com/pro/shipments/state. The body of the request should contain the unique
reference of the shipment whose state you want to edit, the
state that you want that shipment to be placed into, and a free text
reason property detailing the reason for the change.
reason property does not affect the request itself, but instead forms part of the shipment's audit trail. Ship logs audit messages for all state transitions, including details of the change initiator.
Once it has received a valid Change Shipment State request, Ship places the specified shipment into the requested state and returns a standard Resource Result object.
Example Change Shipment State Call
The example below shows a request to put shipment sp_00874350842266620068172088868864 into a state of
ready_to_ship. Ship responds with a message confirming that the shipment was placed into the requested state.
"state": "ready_to_ship ",
"reason": "For reasons"
For full reference information on the Change Shipment State endpoint, see the Ship API reference.