On this page

Create a shipment

Submit new shipment data with the create shipments endpoint and manage your shipments effortlessly with our flexible shipment management API requests.

Overview

In order for the Shipments platform to manage a shipment, you’ll need to record the details of that shipment on the system. This page explains how to use the Create Shipment endpoint to create a new shipment record.

Send a create shipment request

The Create Shipment endpoint enables you to create new shipment records within the Shipments platform. When you send a valid Create Shipment request, Shipments generates a new shipment record and returns a unique {reference} for that shipment. Many of Ship’s endpoints take this shipment {reference} as a parameter.

To create a shipment, send a POST request to https://api.sorted.com/pro/shipments. The body of the request should contain the shipment details, structured as per the Shipment API data contract.

warning

When registering a shipment, we recommend avoiding the use of special characters (e.g. delimiter symbols), especially in fields like address lines and contact information. These may be rejected by our systems or cause errors when transmitted to carriers.

Required shipment properties

As a minimum, the Create Shipments endpoint requires you to send:

shipment_type - Specifies whether the shipment is on_demand (i.e. will require an ad-hoc carrier collection to be booked) or scheduled (i.e. will be picked up as part of a regularly scheduled carrier collection).
contents - The contents of the shipment itself.
addresses - All shipments require both origin and destination addresses.

check_circle

The Shipments platform handles collection booking for on_demand shipments as a background process when the shipment is allocated to a carrier service. You do not need to specify on_demand booking details manually.

Specify shipment contents

The contents object replaces the package and item objects used in Shipment API’s version 1 consignments-based implementation. Contents objects are designed to nest within each other, and can be used at both package and item level.

As an example, suppose that a clothing retailer has received a customer order for a necklace, a bracelet, and a coat. As the necklace and bracelet are both physically small, the retailer elects to ship them in the same package. The resulting shipment would contain:

One contents object containing details of the coat and its accompanying package.
One contents object containing details of the package that the necklace and bracelet are shipping in.
One contents object containing details of the necklace, nested inside the object representing its package.
One contents object containing details of the bracelet, nested inside the object representing its package.

The example below shows how this shipment would be represented in JSON. This is a highly simplified example, with only the minimum properties given for each contents object. In practice, you would probably look to provide additional detail on the shipment contents by specifying optional properties.

Contents example

  "contents": [
    {
        "description": "Coat",
        "value": {
            "amount": 30,
            "currency": "GBP"
        },
        "shipping_terms": "fca",
        "contents": null
    },
    {
        "description": "Package",
        "value": {
            "amount": 40,
            "currency": "GBP"
        },
        "shipping_terms": "fca",            
        "contents": [
            {
                "description": "Necklace",
                "value": {
                    "amount": 20,
                    "currency": "GBP"
                },
                "shipping_terms": "fca",                    
                "contents": null
            },
            {
                "description": "Bracelet",
                "value": {
                    "amount": 20,
                    "currency": "GBP"
                },
                "shipping_terms": "fca",                        
                "contents": null
            }
        ]    
    }
]

Specify addresses

All shipments require both origin and destination addresses. In the Shipments API, addresses are represented by address objects, which must be specified as a list inside the shipments.addresses property. As a minimum, each address must include the following:

address_type - As well as origin and destination address types, Shipments enables you to specify return, sender, recipient, importer, and billing addresses.
shipping_location_reference - Each shipping location that you run scheduled shipments from should have a unique shipping location reference. The shipping_location_reference property is optional for on_demand shipments but required for scheduled shipments. Where provided, the value must be a valid shipping location reference for your organisation.
info
Shipping locations are configured in the UI. For information on managing your shipping locations, see the Managing Shipping Locations page of the Shipments Admin User Guide.
contact- Details of the contact at the address (for example, the name of the recipient). This property is only required where a shipping_location_reference is not provided.
address_line_1 - All addresses must have at least one line.
region - The state, county, or equivalent. This property is required for certain countries, such as the US, Australia, and Canada.
postal_code - Required for countries with official postcode systems, such as the UK.
country_iso_code - The ISO 3166 Alpha 2 code for the country.

In addition, the Shipments platform supports several optional address properties, including custom references, company details, and latitude / longitude. See the Shipment API reference for details.

Optional shipment properties

There are lots of optional properties you can send when creating a shipment, including:

Your own custom reference for the shipment.
Required shipping and delivery dates.
The order date.
Customs documentation for international shipments. For more information on using customs documentation, see the Get Shipment Documents page.
Shipment direction.
Custom label properties.
Tenant and channel.
Metadata. Enables you to use custom fields to record additional data about a shipment.
Tags. Allocation tags enable you to filter the list of carrier services that a particular shipment could be allocated to. For more information on allocation tags, see the Shipment Tags page.

Adding optional properties when you create a shipment can help you to ensure that your shipment is allocated to the most appropriate carrier service.

report

You should exercise caution when using the required_delivery_date and required_shipping_date parameters to specify dates for your shipment. These parameters limit delivery options for the shipment, meaning that it can only be allocated to those carrier services that would be able to ship it within the specified required_shipping_date range and / or deliver it by the specified required_delivery_date range. If the dates you specify are too restrictive, there may not be any carrier services available to take the shipment, which would result in a failed allocation. As such, you should only specify shipping and delivery dates where it is necessary to do so.

Example create shipment request

The example below shows a simple Create Shipment request containing only a shipment_type, contents, and addresses. For an example of a full Create Shipment request, see the Shipment API reference.

Create shipment request

POST https://api.sorted.com/pro/shipments

  

{
    "shipment_type": "on_demand",
    "contents": [
        {
            "custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
            "package_size_reference": null,
            "weight": {
                "value": 2.40,
                "unit": "Kg"
            },
            "dimensions": {
                "unit": "Cm",
                "width": 15.0,
                "height": 15.5,
                "length": 20.0
            },
            "description": "Jeans",
            "value": {
                "amount": 8.99,
                "currency": "GBP"
            },
            "sku": "SKU09876",
            "model": "MOD-009",
            "country_of_origin": "PT",
            "harmonisation_code": "09021000",
            "shipping_terms": "fca",
            "quantity": 2,
            "unit": "Box",
            "metadata": [
                {
                    "key": "Category",
                    "value": "Menswear",
                    "type": "string"
                }
            ],
            "label_properties": null,
            "Contents": null
        }
    ],
    "addresses": [
        {
            "address_type": "Origin",
            "contact": {
                "reference": "co_9953035290535460864",
                "title": "Mr",
                "first_name": "Mark",
                "last_name": "Brunell",
                "contact_details": {
                    "mobile": "+447495747987",
                    "email": "mark@62-7.com"
                }
            },
            "property_number": "1",
            "property_name": "Frank's Place",
            "address_line1": "Zappa Avenue",
            "address_line2": "Off Rock Road",
            "address_line3": "Off Heavy Crescent",
            "locality": "Manchester",
            "region": "Greater Manchester",
            "postal_code": "M2 6LW",
            "country_iso_code": "GB"
        },
        {
            "address_type": "destination",
            "custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
            "contact": {
                "reference": "co_9953035290535460865",
                "title": "Mr",
                "first_name": "Gardner",
                "last_name": "Minshew",
                "middle_name": null,
                "position": null,
                "contact_details": {
                    "landline": null,
                    "mobile": "+447495747987",
                    "email": "gminshew@test.com"
                }
            },
            "property_number": "8",
            "property_name": null,
            "address_line1": "Norbert Road",
            "address_line2": "Bertwistle",
            "address_line3": null,
            "locality": "Preston",
            "region": "Lancashire",
            "postal_code": "PR4 5LE",
            "country_iso_code": "GB",
            "lat_long": null
        }
    ]
}

The create shipments response

Once it has received the shipment information, Shipments creates the shipment record and returns a link to the newly-created shipment, including its {reference}.

The {reference} is a unique identifier for that shipment and is a required parameter for many of Shipments API requests. Each shipment {reference} takes the format sp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, where x is a numerical digit.

In the example below, Shipments API has returned a shipment {reference} of sp_00595452779180472847666078547968.

Create shipment response

  {
  "reference": "sp_00595452779180472847666078547968",
  "message": "Shipment created successfully",
  "_links": [
    {
      "href": "https://api.sorted.com/pro/shipments/sp_00595452779180472847666078547968",
      "rel": "shipment",
      "reference": "sp_00595452779180472847666078547968",
      "type": "shipment"
    }
  ]
}

All shipments have a {state}, indicating the point in the delivery process that that particular shipment is at. Newly-created shipments have an initial state of Unallocated. For more information on shipment states, see the Shipment States page.

info

For full reference information on the Create Shipments endpoint, including the properties accepted and the structure required, see the Shipments API reference.

Update shipments

You can update an existing unallocated shipment via the Update Shipment endpoint. When you make an Update Shipment request, Shipments overwrites the specified shipment’s details with new details provided in the body of the request.

To call Update Shipment, send a PUT request to https://api.sorted.com/pro/shipments. You will need to specify the shipment reference in the body of the request, but the request should otherwise be structured in the same way as a Create Shipment request.

The Update Shipment endpoint uses the same validation as Create Shipment (that is, shipment_type, contents, and addresses are required and all other valid properties are optional).

When it has received the request, the Shipments platform replaces the entire shipment object for the specified shipment with the new details you provided, and returns a confirmation message.

You cannot update a shipment that has already been allocated, because Shipments uses a shipment’s current details to decide the carrier services that that shipment can be allocated to.

report

If you do not pass a value for an optional property when making an Update Shipment request then Shipments will not store any value for that property, even if that property had a value before you updated the shipment. You can only pass properties that would be accepted by a Create Shipment request when using Update Shipment. For example, you can update a shipment’s contents and custom_reference, but not its allocation details or state.

Update shipment example

The example shows a simple Update Shipment request for a shipment with a {reference} of sp_00595452779180472847666078547968. The request is successful, meaning that the Shipments platform has any previous details for that shipment with the details in the request.

Example update shipment request

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

  {
  "reference": "sp_00595452779180472847666078547968",
  "custom_reference": "MyCustomRef002",
  "shipment_type": "on_demand",
  "direction": "outbound",
  "contents": [
    {
      "value": {
        "amount": 2.99,
        "currency": "GBP"
      }
    }
  ],
  "addresses": [
    {
      "address_type": "origin",
      "shipping_location_reference": "myref"
    },
    {
      "address_type": "destination",
      "shipping_location_reference": "myref002"
    }
  ]
}

Example update shipment response

  {
  "reference": "sp_00595452779180472847666078547968",
  "custom_reference": "MyCustomRef002",
  "message": "Shipment sp_00595452779180472847666078547968 has been updated successfully",
  "_links": [
    {
      "href": "https://api.sorted.com/pro/shipments/sp_00595452779180472847666078547968",
      "rel": "shipment",
      "reference": "sp_00595452779180472847666078547968",
      "type": "shipment"
    }
  ]
}

info

For full reference information on the Update Shipment endpoint, see the Shipments API reference.

Next steps

Learn how to retrieve shipment data: Get Shipments
Learn how to cancel shipments: Cancel Shipments
Learn how to allocate shipments: Allocate Shipments

Create a shipment

Overview link

Send a create shipment request link

Required shipment properties link

Specify shipment contents link

Specify addresses link

Optional shipment properties link

Example create shipment request link

The create shipments response link

Update shipments link

Update shipment example link

Next steps link