Show / Hide Table of Contents

    Updating Shipments

    • 29/05/2020
    • ~4 minutes to read
    • 29/05/2020
    • ~4 minutes to read
    • andy.walton@sorted.com
    • michael.rose@sorted.com
    • react
    • api
    • shipments
    • updating

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


    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:

    Property Rule
    id You 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_references You 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_references You 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.
    tags You 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.
    carrier You 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_service You 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_date You can update the shipped date at any point.
    order_date You can update the order date at any point.
    promised_date You 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_date You 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.
    addresses You 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_type You can update the shipment type at any point.
    consumer You can update consumer details at any point.
    metadata You 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.
    retailer You can update retailer details at any point.

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

    • Update Shipment 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"
        }
      ]
    }
    

    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:

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

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

    Next Steps

    Learn more about integrating with REACT:

    • Registering Shipments
    • Retrieving Shipment and Event Data
    • Error Codes
    Back to top Copyright © Sorted Group 2021. Generated by DocFX