Creating Shipment Groups

  • Ship
  • api
  • shipment groups

This page explains how to use the Create Shipment Groups endpoint to create new shipment groups.

The Create Shipment Groups Request

To call Create Shipment Group, send a POST request to https://api.sorted.com/pro/shipment_groups. The body of the request should contain a list of up to 10,000 shipments that you want to add to the group, and an optional custom_reference that can be used as an identifier for the group.

Shipment Group Validation

All Create Shipment Group requests must conform to the following validation rules:

  • You must provide between 1 and 10,000 references in the shipments list.
  • All references must be for existing shipments that you have access to.
  • All shipments must be in a state of either allocated or manifested.
  • All shipments must have the same origin address or same origin shipping location reference.
  • A shipment may only be a member of one open shipment_group at any one time.

However, Ship still creates the group if you provide a reference for an invalid shipment, as long as there is at least once valid reference in the request.

Shipment groups cannot share a custom_reference with another open shipment group. However, you can re-use previous custom_references as long as all previous groups that have used that reference are closed. custom_reference values must be URL-safe (that is, they cannot contain characters such as /, \, ?, @ unless encoded).

The Create Shipment Group Response

Once it has received and validated the request, Ship creates the shipment group and returns a Resource Result including the following information:

  • reference. This is an auto-generated unique reference for the group. It is not to be confused with the custom_reference.
  • custom_reference - The custom reference specified in the request.
  • version - An integer indicating the number of times that the custom_reference has been used.
  • errors - Indicates any shipments in the request that failed validation and could not be added to the group.

Versioning

Versioning enables you to identify any shipment group by custom_reference, even though custom_references can be re-used as long as they are not shared with any open groups.

When you specify a custom_reference for a shipment group, PRO 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, Ship 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.

Shipment group versioning is used when retrieving shipment groups and when adding or removing shipments from a group.

Note

Examples

Successful Request

The example shows a successful request to create a shipment group. The group comprises three valid shipments and has a custom_reference of Example123.

{
    "custom_reference": "Example123",
    "shipments": [
        "sp_00013464648910021776641789788160",
        "sp_00013464648910021776641789784435",
        "sp_00013464648910021776641789790773"
    ]
}

Note the version number of 79 in the response, indicating that the user has used the custom_reference Example123 78 times before.

Invalid Shipment Reference

Like the first example, this example response shows the successful creation of a shipment group. However, in this case not all of the shipments provided are valid, with one of the provided references in an invalid formant and another corresponding to a non-existent shipment. Ship has indicated the shipments that could not be added to the group in its response.

Note

In this case, the HTTP status code of the response would be 207 (Multi-status). This code enables you to to differentiate between completely successful and partially successful group creation requests.

{
        "errors": [
        {
            "property": "shipments",
            "code": "invalid_reference_format",
            "message": "shp_000134646476641789784435 is not a valid shipment reference"
        },
        {
            "property": "shipments",
            "code": "shipment_not_found",
            "message": "sp_00013464648910021776641789790773 could not be found"
        }
    ],
    "reference": "sg_00679577652026749527919113797632",
    "custom_reference": "Example456",
    "version": 59,
    "message": "Shipment group sg_00679577652026749527919113797632 created successfully",
    "_links": //omitted for brevity
}
Note

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

Next Steps