Getting Shipments

  • Ship
  • api
  • retrieve shipments

This page explains how to retrieve shipment data by shipment reference.

Getting Shipments by Shipment Reference

The Get Shipment endpoint takes the {reference} of the shipment you want to view and returns details of that shipment. To call Get Shipment, send a GET request to https://api.sorted.com/pro/shipments/{reference}, where {reference} is the unique reference of the shipment you want to retrieve.

The information returned is structured in a broadly similar way to a Create Shipment request, but also contains additional properties (that is, properties that are managed by Ship rather than explicitly stated by the customer when a shipment is created). These properties include:

  • reference - The shipment's unique reference.
  • state - The shipment's current state. For a full list of shipment states, see the Shipment States page.
  • created - The date and time that the shipment was created.
  • updated - The date and time that the shipment was last updated, where applicable.
  • shipping_date - The assigned shipping date for the shipment based on the active allocation, where applicable.
  • expected_delivery_date - The expected date(s) for delivery based on the current active allocation, where applicable.
  • actual_delivery_date - The actual date and time that the shipment was delivered, where applicable.
  • allocation - Details of the active allocated carrier and service for the shipment, where applicable.
  • label_details - Links to retrieve labels for allocated and fields indicating whether labels have already been retrieved.
  • reservation - Details of any reservation for the shipment (for example, click and collect options), where applicable.
  • _links - Links to any related resources.
Note

For full reference information on the Get Shipment endpoint, see the Ship API reference.

Example Get Shipment Call

The example below shows a Get Shipment request for a shipment with a {reference} of sp_00792693789526132644358207963136.

GET https://api.sorted.com/pro/shipments/sp_9953035299125395456009822134452

Getting Shipments by Custom Reference or Carrier Tracking Reference

The Get Shipments by Custom Reference or Tracking Reference endpoint enables you to search for shipment data by either your own custom reference number or the tracking number assigned to the shipment by the carrier.

Searching by Custom Reference

In Ship, a custom_reference is a user-specified reference for a shipment or item of shipment contents. Custom references do not need to be unique. For example, you might use the custom_reference property to add your own order number to all shipments corresponding to a particular order.

To search for shipments by custom reference, send a GET request to https://api.sorted.com/pro/shipments?custom_reference={reference}, where {reference} is the custom_reference you want to search on.

Note

The custom_reference property can be applied to both shipments and shipment_contents objects. The Get Shipments by Custom Reference or Tracking Reference endpoint returns both those shipments that are directly tagged with the specified custom_reference and those shipments that contain a shipment_contents object with the specified custom_reference.

For more information on the structure of shipment contents, see the Specifying Shipment Contents section of the Creating Shipments page.

Once it has received the request, Ship returns a shipment_list object containing a list of the total number of results, the number of shipments requested and the number of shipments skipped.

Searching by Carrier Tracking Reference

To use Get Shipments by Custom Reference or Tracking Reference to search by tracking reference, send a GET request to https://api.sorted.com/pro/shipments?carrier_tracking_reference={tracking_reference}, where {tracking_reference} is the carrier tracking reference you want to search on.

Get Shipments by Custom Reference or Tracking Reference can only return allocated as carrier tracking references are assigned to shipments at the point of allocation. The carrier tracking_reference can be found in the shipment's allocation.tracking_references property. It can also be found in the tracking_details.shipment.tracking_references property of the Allocation Summary object that is returned when a shipment is allocated.

Note

As carrier tracking references can repeat, the Get Shipments by Custom Reference or Tracking Reference endpoint only returns shipments that have been allocated within the last 30 days. Any older shipments may still be present in the database, but are not returned by the endpoint.

Get Shipments by Custom Reference or Tracking Reference only works with those tracking references provided by carriers. It does not return shipments for internally-generated Ship or Track references.

Once it has received the request, Ship returns a shipment_list object containing a list of the total number of results, the number of shipments requested and the number of shipments skipped.

Example Get Shipments by Custom Reference or Tracking Reference Call

The example shows a successful request to get all shipments that either have the custom_reference or contain contents with the custom_reference CR1234. In this case, Ship has returned one shipment.

GET https://api.sorted.com/pro/shipments?custom_reference=CR1234

Note

For full reference information on the Get Shipments by Custom Reference or Tracking Reference endpoint, see the Ship API reference.

Paging Results

The Get Shipments by Custom Reference or Tracking Reference endpoint supports optional {take} and {skip} parameters, which can be used to drive paging functions. The {take} parameter indicates the number of shipments to return (up to a maximum of 10), and the {skip} parameter indicates the number of shipment records Ship should "skip over" before it returns records.

For example, suppose that you have 15 shipments with a custom_reference of CR1234, and you want to return them as three pages of five shipments:

  • To view the first page of five, you would make a call to GET https://api.sorted.com/pro/shipments?custom_reference=CR1234&take=5&skip=0 (that is, take five shipments and do not skip over any).
  • To view the second page, you would call GET https://api.sorted.com/pro/shipments?custom_reference=CR1234&take=5&skip=5 (skip the first five shipments and then take the next five).
  • To view the third page, you would call GET https://api.sorted.com/pro/shipments?custom_reference=CR1234&take=5&skip=10 (skip the first ten shipments and then take the next five).

By default, {take} has a value of 10 and {skip} has a value of 0.

Next Steps