Overview of retrieving shipment groups

The Shipments platform has three endpoints that enable you to retrieve details of existing shipment groups:

  • Get Shipment Group retrieves a single shipment group by its unique reference.
  • Get Shipment Groups by Custom Reference retrieves a summary of any shipment groups that have the specified custom_reference.
  • Get Shipment Group by Custom Reference retrieves a single shipment group using a combination of custom_reference and version.

Shipment group references

In Ship, shipment groups can be retrieved by two types of reference:

  • reference is a unique identifier generated for every shipment group you create. It begins with sg.
  • custom_reference is a user-defined optional reference that is supplied as part of a Create Shipment Group call. While two open groups cannot share the same custom_reference, the custom_reference of a previously-closed group can be re-used.

Because the custom_reference can be re-used, it is not a unique identifier for a group. To this end, Ship uses versioning as a means of uniquely identifying groups by custom_reference.

Versioning in shipment groups

When you specify a custom_reference for a shipment group, the Shipments platform assigns that group a version number. Combined, the custom_reference and version provide a unique identifier for the group. A group’s version number indicates how many times you have used that group’s custom_reference.

For example, suppose that you choose to use shipment groups to represent carrier trailers, so that you can manifest an entire trailer of shipments at once. To this end, you create a shipment group with a custom_reference of CarrierX-PM to represent Carrier X’s daily afternoon collection.

The first time you create this group, the group has a version number of 1. You add the relevant shipments to the group, manifest them using the Manifest Shipments by Shipment Group endpoint as they are picked up, and then close the shipment group.

The following day, you create a new shipment group for that day’s collection. As before, you use a custom_reference of CarrierX-PM. This time, however, Shipments API responds with a version number of 2, as this is the second time that that custom_reference has been used.

You can now use the version number to point to the shipment group you want. CarrierX-PM version 1 points to the original (now closed) shipment group, while CarrierX-PM version 2 points to the new group. Note that both groups also have unique (Ship-generated) references.

Get shipment groups by group reference

To call Get Shipment Group, send a GET request to https://api.sorted.com/pro/shipment_groups/{reference}, where {reference} is the unique reference of the shipment group you want to retrieve details for.

Shipments API returns a shipment_group object. The shipment_group object contains the following information:

  • The group’s unique reference.
  • The group’s custom_reference and version (if applicable).
  • A list of the shipments in the group.
  • The current state of the group.
  • The date that the group was created.
  • The dates that the group was locked, closed, and/or updated (if applicable).

Get shipment group example

The example shows a request for shipment sg_00013464648946915264789208891778.

Get shipment group request

  GET https://api.sorted.com/pro/shipment_groups/sg_00013464648946915264789208891778

Get shipment group response

  {
    "reference": "sg_00013464648946915264789208891778",
    "shipments": [
        "sp_00013473827456470532303387361290",
        "sp_09830498509898987009909000543435"
    ],
    "custom_reference": "CarrierX-PM",
    "version": "1",
    "state": "open",
    "created": "2019-05-03T17:00:23+01:00"
}

Get shipment groups by custom reference

To call Get Shipment Groups by Custom Reference, send a GET request to https://api.sorted.com/pro/shipment_groups/custom_reference/{custom_reference}.

Ship returns details of every shipment group that has the specified custom_reference, irrespective of version. Specifically, Ship returns a list of shipment_group_summary objects.

Each shipment_group_summary is a simplified version of the full shipment_group object, containing the following information:

  • The group’s unique reference.
  • The group’s custom_reference and version (if applicable).
  • Links to the full version of the group.

Example get shipment groups by custom reference call

The example shows a request for a summary of all shipment groups with the custom_reference CarrierX-PM. Ship has returned a summary of two shipment groups.

Get shipment groups by custom reference request

  GET https://api.sorted.com/pro/shipment_groups/custom_reference/CarrierX-PM

Get shipment groups by custom reference response

  [
    {
        "reference": "sg_00013464648946915264789208891778",
        "custom_reference": "CarrierX-PM",
        "version": 1,
        "_links": [
            {
                "rel": "self",
                "href": "/pro/shipment_groups/sg_00013464648946915264789208891778"
            },
            {
                "rel": "version",
                "href": "/pro/shipment_groups/custom_reference/CarrierX-PM/1"
            }
        ]
    },
    {
        "reference": "sg_00013464648946915264789208891788",
        "custom_reference": "CarrierX-PM",
        "version": 2,
        "_links": [
            {
                "rel": "self",
                "href": "/pro/shipment_groups/sg_00013464648946915264789208891788"
            },
            {
                "rel": "version",
                "href": "/pro/shipment_groups/custom_reference/CarrierX-PM/2"
            }
        ]
    }
]

Get a shipment group by custom reference and version

To call Get Shipment Group by Custom Reference, send a GET request to https://api.sorted.com/pro/shipment_groups/custom_reference/{custom_reference}/{version}, where {custom_reference} is the reference you want to search on and {version} represents the group version you want Ship to return. {version} can be either an integer or the value latest.

Ship returns a full shipment group object (as opposed to the summaries returned by the Get Shipment Groups by Custom Reference endpoint). The shipment group object contains the following information:

  • The group’s unique reference.
  • The group’s custom_reference and version (if applicable).
  • A list of the shipments in the group.
  • The current state of the group.
  • The date that the group was created.
  • The dates that the group was locked, closed, and/or updated (if applicable).

Example get shipment group by custom reference call

These examples show two calls, based on the data used in previous examples on this page: one to get a group with a custom_reference of CarrierX-PM and a version of 1, and one to get the latest CarrierX-PM group.

Requests

  GET https://api.sorted.com/pro/shipment_groups/custom_reference/CarrierX-PM/1
GET https://api.sorted.com/pro/shipment_groups/custom_reference/CarrierX-PM/latest

Version 1 response

  {
    "reference": "sg_00013464648946915264789208891778",
    "shipments": [
        "sp_00013473827456470532303387361290",
        "sp_09830498509898987009909000543435"
    ],
    "custom_reference": "CarrierX-PM",
    "version": "1",
    "state": "open",
    "created": "2019-05-03T17:00:23+01:00"
}

Latest version response

  {
    "reference": "sg_00013464648946915264789208891788",
    "shipments": [
        "sp_00013473827456270532303387361927",
        "sp_09830498509898987009909000543108"
    ],
    "custom_reference": "CarrierX-PM",
    "version": "2",    
    "state": "open",
    "created": "2019-05-04T17:00:23+01:00"
}

Next steps