What is a carrier 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.

Shipment’s 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.

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.

Once the request is received, the Shipments platform 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.

All Shipment API 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.

Allocate shipment with service group request

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

Allocate shipment with service group response

  {
    "shipment_reference": "sp_00794403010635468411384028069888",
    "state": "allocated",
    "price": {
        "net": 2.00,
        "gross": 2.00,
        "taxes": [
            {
                "rate": {
                    "reference": "FF_LINET-00001",
                    "country_iso_code": "GB",
                    "type": "Zero",
                    "value": 0.0000
                },
                "amount": 0.000000
            }
        ],
        "currency": "GBP"
    },
    "message": "Shipment sp_00794403010635468411384028069888 has been allocated successfully",
    "carrier": {
        "reference": "FF_LINET",
        "name": "Lineten",
        "service_reference": "FF_LINET-00001",
        "service_name": "Lineten - Standard On Demand"
    },
    "tracking_details": {
        "shipment": {
            "reference": "sp_00794403010635468411384028069888",
            "tracking_references": [
                "43765709"
            ]
        },
        "contents": []
    },
    "_links": [
        {
            "href": "https://api-int.sorted.com/pro/shipments/sp_00794403010635468411384028069888",
            "rel": "shipment",
            "reference": "sp_00794403010635468411384028069888",
            "type": "shipment"
        },
        {
            "href": "https://api-int.sorted.com/pro/labels/sp_00794403010635468411384028069888/pdf",
            "rel": "label",
            "reference": "sp_00794403010635468411384028069888",
            "type": "label"
        },
        {
            "href": "https://api-int.sorted.com/pro/labels/sp_00794403010635468411384028069888/zpl",
            "rel": "label",
            "reference": "sp_00794403010635468411384028069888",
            "type": "label"
        }
    ],
    "correlation_id": "7a53f7c4-836f-4a46-9d67-be1cadaaf7c2.SAPI_51eda51d-3efc-4afa-a8b4-47fc826420cf",
    "details": [],
    "excluded_services": [
        {
            "carrier": {
                "reference": "FF_DPD_1200_103384",
                "name": "DPD 12:00 (Parcel)",
                "service_reference": "FF_103384_DPD",
                "service_name": "DPD"
            },
            "exclusion": {
                "reason": "Service delivery is later than selected service",
                "code": "ex_rates"
            }
        },
        {
            "carrier": {
                "reference": "FF_DPD_Next_Day_103386",
                "name": "DPD Next Day (Parcel)",
                "service_reference": "FF_103386_DPD",
                "service_name": "DPD"
            },
            "exclusion": {
                "reason": "Service delivery is later than selected service",
                "code": "ex_rates"
            }
        },
        {
            "carrier": {
                "reference": "FF_DPD_Sunday_103386",
                "name": "DPD Sunday (Parcel)",
                "service_reference": "FF_103386_DPD",
                "service_name": "DPD"
            },
            "exclusion": {
                "reason": "Service delivery is later than selected service",
                "code": "ex_rates"
            }
        },
        {
            "carrier": {
                "reference": "FF_DPD_Two_Day_103386",
                "name": "DPD Two Day (Parcel)",
                "service_reference": "FF_103386_DPD",
                "service_name": "DPD"
            },
            "exclusion": {
                "reason": "Service delivery is later than selected service",
                "code": "ex_rates"
            }
        }
    ]
}