Editing Shipment Groups

  • Ship
  • api
  • shipment groups

This page explains how to add shipments to and remove them from a shipment group. It also explains how to lock shipment groups so that they can't be edited.

Adding and Removing Shipments in Bulk

The Update Shipment Group endpoint enables you to add and/or remove multiple shipments from a shipment group in a single API call. To call Update Shipment Group, send a PUT request to https://api.sorted.com/pro/shipment_groups/. The body of the request should contain:

  • The unique reference of the shipment group you want to update (not the user-defined custom_reference). This must be an open and unlocked shipment group.
  • An add_shipments property listing the unique references of the shipments you want to add to the group. These shipments must not be a member of either the specified shipment group or any other open shipment group.
  • A remove_shipments property listing the unique references of the shipments you want to remove from the group. These shipments must be a member of the specified shipment group.

Once it has received the request, Ship makes the requested additions and removals and returns a standard resource result object with links to the updated shipment group.

Note

Note that, while Ship validates the format of the provided shipment reference and confirms whether the shipment is allocated and part of an existing shipment group, it does not validate whether the shipment itself exists. As such, Ship will still return a 200 OK response if you provide a reference to a non-existing shipment, as long as that reference is in a valid format.

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

Update Shipment Group Example

The example shows a request to add three shipments to and remove two shipments from shipment group sg_00682731282010871067439042134016.

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

{
  "reference": "sg_00682731282010871067439042134016",
  "add_shipments": [
      "sp_00682731282010871067439042134016",
      "sp_00682731282010871067439042134045",
      "sp_00682731282010871067439042134076"
    ],
  "remove_shipments": [
      "sp_00682731282010871067439042134765",
      "sp_00682731282010871067439042134100"
    ]
}

Adding Individual Shipments to a Shipment Group

The Add Shipment to Group endpoints enable you to add individual shipments to an open and unlocked shipment group. You can select the group to add the shipment to in two ways:

  • Using the group's unique {reference} - send a PUT request to https://api.sorted.com/pro/shipment_groups/{reference}/shipments/{shipment_ref}.
  • Using a combination of the group's {custom_ref} and {version}- send a PUT request to https://api.sorted.com/pro/shipment_groups/custom_reference/{custom_ref}/{version}/shipments/{shipment_ref}. The {version} parameter can be either an integer or the value latest.
Note

For an explanation of versioning in Ship's shipment groups, see the Versioning in Shipment Groups section of the Getting Shipment Groups page.

In both cases, {shipment_ref} is the unique reference of the shipment you want to add to the group. This shipment must not be a member of either the specified shipment group or any other open shipment group.

Once it has received the request, Ship adds the specified shipment to the specified group and returns a standard resource result object with links to the shipment group that was updated.

Note

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

Add Shipment to Group Examples

The examples show two requests to add shipment sp_00013473827456470532303387361290 to group sg_00013464648946915264789208891778. In the first call, the group is identified by its unique {reference}, and in the second it is identified by its {custom_ref} and {version}. The response for both calls is the same.

PUT https://api.sorted.com/pro/shipment_groups/sg_00013464648946915264789208891778/shipments/sp_00013473827456470532303387361290
PUT https://api.sorted.com/pro/shipment_groups/custom_reference/CarrierX-PM/1/shipments/sp_00013473827456470532303387361290

Removing Individual Shipments from a Group

The Remove Shipment from Group endpoints enable you to remove individual shipments from an open and unlocked shipment group. You can specify the group that the shipment is to be removed from in two ways:

  • Using the group's unique {reference} - send a DELETE request to https://api.sorted.com/pro/shipment_groups/{reference}/shipments/{shipment_ref}. This must be an open and unlocked shipment group.
  • Using a combination of the group's {custom_ref} and {version}- send a DELETE request to https://api.sorted.com/pro/shipment_groups/custom_reference/{custom_ref}/{version}/shipments/{shipment_ref}. The {version} parameter can be either an integer or the value latest.
Note

For more information on how versioning works in Ship's shipment groups, see the Versioning in Shipment Groups section of the Getting Shipment Groups page.

In both cases, {shipment_ref} is the unique reference of the shipment you want to remove from the group. This shipment must be a member of the specified shipment group.

Once it has received the request, Ship removes the specified shipment from the specified group and returns a standard resource result object with links to the updated shipment group.

Note

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

Remove Shipment from Group Examples

The examples show two requests to remove shipment sp_00013473827456470532303387361290 from group sg_00013464648946915264789208891778. In the first call, the group is identified by its unique {reference}, and in the second it is identified by its {custom_ref} and {version}. The response for both calls is the same.

DELETE https://api.sorted.com/pro/shipment_groups/sg_00013464648946915264789208891778/shipments/sp_00013473827456470532303387361290
DELETE https://api.sorted.com/pro/shipment_groups/custom_reference/CarrierX-PM/1/shipments/sp_00013473827456470532303387361290

Locking and Unlocking Shipment Groups

Locking a shipment group means that it can no longer be edited.

Locking Shipment Groups

You can lock shipment groups using the Lock Shipment Group endpoint. To call Lock Shipment Group, send a POST request to https://api.sorted.com/pro/shipment_groups/{reference}/lock, where {reference} is the unique reference of the group you want to lock.

Ship locks the group and returns a standard resource result object with links to the shipment group that was updated.

Note

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

Unlocking Shipment Groups

You can unlock shipment groups using the Unlock Shipment Group endpoint. To call Unlock Shipment Group, send a POST request to https://api.sorted.com/pro/shipment_groups/{reference}/unlock, where {reference} is the unique reference of the group you want to unlock.

Ship unlocks the group and returns a standard resource result object with links to the shipment group that was updated.

Note

For full reference information on the Unlock Shipment Group endpoint, see the Shipments data contract.

Example

The example shows a successful request to lock shipment group sg_00013464648946915264789208891778.

POST https://api.sorted.com/pro/shipment_groups/sg_00013464648946915264789208891778/lock

Next Steps