Allocating with a Specific Carrier Service

  • Ship
  • api
  • allocation
  • carrier service

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

Getting the Carrier Service Reference

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

Allocating A Single 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.

Ship then attempts to allocate the specified shipment to the specified carrier service and returns an Allocate Result.

Note

Allocate Shipment with Carrier Service does not override existing allocation rules. If the carrier service you selected does not meet your existing allocation rules, then Ship returns an error.

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

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

Note

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

Allocating 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 Ship 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.

Note

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

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

Note

Where an Allocate with Carrier Service request is successful, Ship returns a 202 - Accepted response. Note that, as the Allocate with Carrier Service 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.

Allocate with Carrier Service does not override existing allocation rules. If the carrier service you selected does not meet your existing allocation rules, then Ship returns an error.

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

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

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

For full reference information on the Allocate With Carrier Service endpoint, see the Ship API reference.

Next Steps