Get the carrier service reference

Want to specify the carrier service that should take your shipment? This guide explains how to allocate shipments to specific services.

In order to allocate a shipment to a specific carrier service, you’ll need to know that service’s {carrier_service_reference}. The {carrier_service_reference} is a unique identifier for each service available in the Shipments platform.

Allocate a shipment with a specific carrier service

The Allocate Shipment with Carrier Service endpoint enables you to allocate a shipment to a specific carrier service. To call Allocate Shipment with Carrier Service, send a PUT request to https://api.sorted.com/pro/shipments/{reference}/allocate/service/{service_ref}, where {reference}refers to the shipment you want to allocate and {service_ref} is the reference of the carrier service that you want to allocate to.

The Shipments platform then attempts to allocate the specified shipment to the specified carrier service and returns an Allocate Result.

All Shipments 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 carrier service example

The example shows a successful request to allocate shipment sp_00794355402411366010308868571136 to a carrier service with the {carrier_service_reference} FF_LINET-00001.

Allocate shipment with carrier service request

PUT https://api.sorted.com/pro/shipments/sp_00794355402411366010308868571136/allocate/service/FF_LINET-00001

Allocate shipment with carrier service response

  {
    "shipment_reference": "sp_00794355402411366010308868571136",
    "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_00794355402411366010308868571136 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_00794355402411366010308868571136",
            "tracking_references": [
                "8376568"
            ]
        },
        "contents": []
    },
    "_links": [
        {
            "href": "https://api-int.sorted.com/pro/shipments/sp_00794355402411366010308868571136",
            "rel": "shipment",
            "reference": "sp_00794355402411366010308868571136",
            "type": "shipment"
        },
        {
            "href": "https://api-int.sorted.com/pro/labels/sp_00794355402411366010308868571136/pdf",
            "rel": "label",
            "reference": "sp_00794355402411366010308868571136",
            "type": "label"
        },
        {
            "href": "https://api-int.sorted.com/pro/labels/sp_00794355402411366010308868571136/zpl",
            "rel": "label",
            "reference": "sp_00794355402411366010308868571136",
            "type": "label"
        }
    ],
    "correlation_id": "e35a94cd-f3e5-401a-85b8-dcda0aa2d553.SAPI_496bfd60-08b5-4cd3-86a7-502601288357",
    "details": [],
    "excluded_services": []
}