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": []
}

Allocate multiple shipments with a specific carrier service

The Allocate With Carrier Service endpoint enables you to queue one or more shipments for allocation to a specific carrier service. To call Allocate With Carrier Service, send a PUT request to https://api.sorted.com/pro/shipments/allocate/service. The body of the request should contain a list of the {shipments} that you want to allocate and the {carrier_service_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 Shipments only allocates 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.

Ship queues the specified shipments for allocation to the specified service. It then returns an Allocate Shipments result detailing the results of the request.

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

Allocate with carrier service example

The example shows a request to queue four shipments for allocation to a carrier service with the {carrier_service_reference} FF_LINET-00001. Three shipments have been successfully queued, but one was rejected because its {reference} could not be found.

Allocate with carrier service request

PUT https://api.sorted.com/pro/shipments/allocate/service

  {
    "shipments": [
        "sp_00794372987452683804666199932928",
        "sp_00794373204515521320006493798400",
        "sp_00794373381493583963175932002304",
        "sp_10014418709726822400876827879904"
    ],
    "carrier_service_reference": "FF_LINET-00001"
}

Allocate with carrier service response

  {
    "message": "3 shipments queued for allocation successfully. 1 shipment rejected for allocation.",
    "queued": [
        "sp_00794372987452683804666199932928",
        "sp_00794373204515521320006493798400",
        "sp_00794373381493583963175932002304"
    ],
    "rejected": [
        {
            "code": "shipment_not_found",
            "message": "The shipment cannot be found.",
            "references": [
                "sp_10014418709726822400876827879904"
            ]
        }
    ],
    "_links": []
}

Allocation next steps