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 request. 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.

Update shipment group example

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

Update shipment group request

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

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

Update shipment group response

  {
  "reference": "sg_00682731282010871067439042134016",
  "message": "Shipment group sg_00682731282010871067439042134016 updated successfully",
  "_links": [
    {
      "href": "https://beta.sorted.com/pro/shipments/groups/sg_00682731282010871067439042134016",
      "rel": "self",
      "reference": "sg_00682731282010871067439042134016",
      "type": "shipment_group"
    }
  ]
}

Add 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.

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.

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.

Add shipment to group request

  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

Add shipment to group response

  {
  "reference": "sg_00013464648946915264789208891778",
  "message": "Shipment group sg_00013464648946915264789208891778 updated successfully",
  "_links": [
    {
      "href": "https://beta.sorted.com/pro/shipments/groups/sg_00013464648946915264789208891778",
      "rel": "self",
      "reference": "sg_00013464648946915264789208891778",
      "type": "shipment_group"
    }
  ]
}

Remove 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.

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, Shipments removes the specified shipment from the specified group and returns a standard resource result object with links to the updated shipment group.

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.

Remove shipment from group request

  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

Remove shipment from group response 

  {
  "reference": "sg_00013464648946915264789208891778",
  "message": "Shipment group sg_00013464648946915264789208891778 updated successfully",
  "_links": [
    {
      "href": "https://beta.sorted.com/pro/shipments/groups/sg_00013464648946915264789208891778",
      "rel": "self",
      "reference": "sg_00013464648946915264789208891778",
      "type": "shipment_group"
    }
  ]
}

Lock and unlock shipment groups

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

Lock 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.

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

Unlock 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.

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

Example

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

Lock shipment group request

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

Lock shipment group response

  {
  "reference": "sg_00013464648946915264789208891778",
  "message": "Shipment group sg_00013464648946915264789208891778 locked successfully",
  "_links": [
    {
      "href": "https://beta.sorted.com/pro/shipments/groups/sg_00013464648946915264789208891778",
      "rel": "self",
      "reference": "sg_00013464648946915264789208891778",
      "type": "shipment_group"
    }
  ]
}

Next steps