sorted.REACT logo

Updating Shipments

This page explains how to use REACT’s Update Shipment and Delete Shipment endpoints to keep your registered shipment data up to date.

On This Page


Updating Shipments

To update a registered shipment, send a PUT request to https://api.sorted.com/react/shipments/{id}, where {id} is the REACT ID of the shipment you want to update.

The body of the request should be a Shipment resource. This resource will to a large extent overwrite the existing shipment details.

Note:

You must include the shipment’s tracking_reference in the body of every Update Shipment request you make. If you send a request with no tracking_reference, or an amended tracking_reference property, then REACT returns a 400 - Validation error.

All other Shipment properties are optional when making Update Shipment requests. For more information on available properties, see the Update Shipment API reference.

REACT follows the below rules when updating shipments:

PropertyConsideration
idYou must include the id of the shipment in the URL so that REACT can identify the shipment to be updated. However, id is a read-only property and cannot be changed manually.
tracking_referencesYou must include the shipment’s tracking_reference in the body of the request so that REACT can identify the shipment to be updated. However, tracking_reference is a read-only property and cannot be changed manually. If you send a new tracking_reference , or add additional tracking_reference values, then REACT returns a 400 - Validation error.
custom_referencesYou can update custom references at any point. REACT replaces all existing reference data with data sent in the Update Shipment request. As such, you should include all required references when making an update request, not just new references. To delete all references, send an empty custom_references array. If REACT receives a null custom_references property, no changes are made.
tagsYou can update tags at any point. REACT replaces all existing tags with those tags sent in the Update Shipment request. As such, you should include all required tags when making an update request, not just new ones. To delete all tags, send an empty tags array.

If REACT receives a null tags property, no changes are made. You can add up to 20 tags to a shipment, and each tag must be between three and 30 characters long. If you attempt to add more than 20 tags then only the first 20 are stored. Tags are not case-sensitive, and you cannot add duplicate tags within the same shipment.
carrierYou can update the shipment’s carrier at any point. However, REACT will overwrite the carrier property if it receives a tracking event that contains a different carrier name. This property is a label only, and does not have any impact on the shipment itself.
carrier_serviceYou can update the shipment’s carrier service at any point. This field is a label only, and does not have any impact on the shipment itself.
shipped_dateYou can update the shipped date at any point.
order_dateYou can update the order date at any point.
promised_dateYou can update the promised date at any point. If you change this property then REACT recalculates any properties that are derived from the promised date (for example, lateness ).
expected_delivery_dateYou can update the expected delivery date at any point. However, REACT will overwrite this property if it later receives an event that contains a change in expected date.
addressesYou can update addresses at any point. REACT replaces all existing address data with data sent in the Update Shipment request. As such, you should include all required addresses when making an update request, not just new addresses. To delete all addresses, send an empty addresses array. If REACT receives a null addresses property, no changes are made.
shipment_typeYou can update the shipment type at any point.
consumerYou can update consumer details at any point.
metadataYou can update metadata at any point. REACT replaces all existing metadata with data sent in the Update Shipment request. As such, you should include all required metadata when making an update request, not just new metadata. To delete all metadata, send an empty metadata array. If REACT receives a null metadata property, no changes are made.
retailerYou can update retailer details at any point.

Once the shipment has been updated, REACT returns a confirmation response:

{
  "id": "sp_1234567890",
  "message":
    "Shipment record 'sp_1234567890' with tracking reference ['QWERTYUIOP'] updated successfully.",
  "tracking_references": ["QWERTYUIOP"],
  "_links": [
    {
      "href": "https://api.sorted.com/react/shipment/sp_1234567890",
      "rel": "self"
    }
  ]
}

Example Update Shipment confirmation response.

Deleting Shipments

To delete a shipment, send a DELETE request to https://api.sorted.com/react/shipments/{id}, where {id} is the REACT ID of the shipment you want to delete. You do not need to include any data in the body of the request.

You can only delete shipments that belong to your organisation. Deleting a shipment means that REACT will no longer track that shipment, and you will no longer be able to use REACT’s APIs and Dashboard to get information on it.

Once the request has been validated, REACT returns a code 202 - Accepted with the following confirmation response in its body:

{
  "id": "sp_1234567899900",
  "message":
    "Shipment record 'sp_1234567899900' with tracking reference ['QWERTYUIOOP'] deleted successfully.",
  "tracking_references": ["QWERTYUIOOP"]
}

Example Delete Shipment confirmation response.

More Information:

For a more information on the properties returned by the Delete Shipment confirmation message, see the API Reference.

Next Steps

Learn more about integrating with REACT: