The change shipment state endpoint

This page explains how to use the Change Shipment State endpoint to make manual alterations to a shipment’s state.

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.

The reason property does not affect the request itself, but instead forms part of the shipment’s audit trail. The Shipments platform logs audit messages for all state transitions, including details of the change initiator.

Once it has received a valid Change Shipment State request, Shipments 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. Shipments responds with a message confirming that the shipment was placed into the requested state.

Change shipment state request

PUT https://api.sorted.com/pro/shipments/state

  {
    "reference": "sp_00874350842266620068172088868864",
    "state": "ready_to_ship	",
    "reason": "For reasons"
}

Change shipment state response

  {
    "reference": "sp_00874350842266620068172088868864",
    "message": "Shipment sp_00874350842266620068172088868864 has changed state to ready_to_ship",
    "_links": [
        {
            "href": "https://api-int.sorted.com/pro/shipments/sp_00874350842266620068172088868864",
            "rel": "shipment",
            "reference": "sp_00874350842266620068172088868864",
            "type": "shipment"
        }
    ]
}

Next steps