Allocating Within a Carrier Service Group

  • Ship
  • api
  • allocation
  • service group

Service groups enable you to specify a custom pool of carrier services to allocate a shipment from. This page explains how to use the Allocate Shipment with Service Group and Allocate with Service Group endpoints to allocate from within a specified shipping group.

What Is a Carrier Service Group?

Ship carrier service groups are user-defined pools of carrier services. They are designed to be used in conjunction with the Allocate Shipment with Service Group and Allocate with Service Group endpoints as a means of limiting the carrier services that a particular shipment could be allocated to.

For example, you might set up a group containing all services that will ship dangerous goods. You would then allocate within that group for all shipments involving dangerous items.

You can use any combination of carrier services in a carrier service group.

Note

Carrier service groups are configured through the UI. For information on managing your carrier service groups, see the Managing Carrier Service Groups section of the Ship Admin User Guide.

Allocating a Single Shipment with a Carrier Service Group

The Allocate Shipment with Service Group endpoint allocates a shipment with a carrier service from a specific carrier service group.

To call Allocate Shipment With Service Group, send a PUT request to https://api.sorted.com/pro/shipments/{reference}/allocate/service_group/{group_ref}, where {reference} is the unique reference for the shipment you want to allocate and {group_ref} is the Service Group Code of the group you want to allocate within.

Note

You can look up the Service Group Code of a particular group by logging in to Ship Admin and selecting Settings > Carrier Service Groups. This UI page displays details of your available groups, including their Code.

Once the request is received, Ship uses shipping rules to eliminate any carrier services in the group that would not be suitable to take the shipment, allocates the shipment to the cheapest remaining service, and returns an Allocate Result.

Note

For information on using shipping rules, see the What Is a Shipping Rule? section of the Allocating Shipments page.

All Ship endpoints that allocate consignments individually return an Allocate Result object. The Allocate Result contains details of:

  • The shipment's current state following the allocation request. For successful requests this would generally be Allocated.
  • The carrier and service that the shipment was allocated to.
  • The price of the allocation.
  • Any relevant tracking references.
  • The services that were unable to provide a quote.
  • The shipping_date and expected_delivery_date for the shipment.

Allocate Shipment with Service Group Example

The example shows a successful request to allocate a shipment with a {reference} of sp_00794403010635468411384028069888 within a group that has a {group_ref} of valuableGoods.

PUT https://api.sorted.com/pro/shipments/sp_00794403010635468411384028069888/allocate/service_group/valuableGoods
Note

For full reference information on the Allocate Shipment with Service Group endpoint, see the Ship API reference.

Allocating Multiple Shipments with a Carrier Service Group

The Allocate with Service Group endpoint queues one or more shipments for allocation to a carrier service that is a member of a specific carrier service group.

To call Allocate with Service Group, send a PUT request to https://api.sorted.com/pro/shipments/allocate/service_group. The body of the request should contain a list of the {shipments} that you want to allocate and the {service_group} reference of the carrier service you want to allocate to.

Optionally, you can also include a list of service capabilities. Where capabilities are provided, then Ship only allocated the shipment to a carrier service that meets those capabilities. Each capability should list the type of service capability specified and the value that that capability should have.

Note

For information on available service capabilities and values, see the Ship API reference.

Ship uses allocation rules to eliminate any carrier services in the group that would not be suitable to take the and the queues the shipments for allocation to the cheapest remaining service. It then returns an Allocate Shipments result detailing the results of the request.

Note

Where an Allocate with Service Group request is successful, Ship returns a 202 - Accepted response. Note that, as the Allocate with Service Group operation is asynchronous, this response only indicates that the specified shipments have been queued for allocation and does not guarantee that the shipments have been or will be successfully allocated.

All Ship endpoints that queue multiple shipments for allocation return an Allocate Shipments result. The Allocate Shipments result includes a list of all shipments that were successfully queued and details of all shipments that were rejected for allocation, including the references of those shipments and the reason for rejection.

When you make a request to allocate multiple shipments simultaneously, Ship queues those shipments to be allocated at a later time rather than allocating them straight away. This helps to optimise performance. Ship then allocates queued shipments via an automated background process.

Note

If you only need to allocate a single shipment, you should use one of PRO's allocation endpoints for individual shipments (Allocate Shipment with Carrier Service, Allocate Shipment with Service Group and Allocate Shipment with Virtual Service) rather than a bulk allocation endpoint. Using an individual endpoint means that the shipment is allocated straight away.

Allocate with Service Group Example

The example shows a request to queue four shipments for allocation within carrier service group exampleSG123. Three shipments have been successfully queued, but one was rejected because its {reference} could not be found.

{
    "shipments": [
        "sp_00794407328944469090495223169024",
        "sp_00794407551522883083874672967680",
        "sp_00794407763918694348566450274304",
        "sp_00794407763918694348566459974304"
    ],
    "service_group ": "exampleSG123"
}
Note

For full reference information on the Allocate with Service Group endpoint, see the Ship API reference.

Next Steps