Allocate to default rules
Use the Allocate shipment endpoints to automatically assign packages to eligible carrier services based on your predefined rules and modes.
Allocate a single shipment with default rules
This page explains how to use the Allocate Shipment endpoint to allocate shipments based on your pre-defined allocation rules.
The Allocate Shipment endpoint allocates a single shipment to the most appropriate carrier service. To call Allocate Shipment, send a PUT request to https://api.sorted.com/pro/shipments/{reference}/allocate, where {reference} indicates the shipment that you want to allocate.
Once the request has been received, the Shipments platform uses your shipping rules to determine which carrier services would be eligible to take the shipment, and your shipping modes to determine which of those services the shipment will be allocated to. The system then allocates the shipment and returns an Allocate Result object.
For more information on the wider process Shipments uses to allocate see the Selecting a Carrier Service section of the Allocating Shipments page.
For more information on configuring and using shipping rules, see the Managing Shipping Rules page of the UI user guide.
For more information on configuring and using shipping modes, see the Managing Shipping Modes page of the UI user guide.
All Shipments API endpoints that allocate consignments individually return an Allocate Result object. The Allocate Result contains details of:
- The shipment’s current
statefollowing the allocation request. For successful requests this would generally be Allocated. - The carrier and service that the shipment was allocated to.
- The
priceof the allocation. - Any relevant tracking references.
- The services that were unable to provide a quote.
- The
shipping_dateandexpected_delivery_datefor the shipment.
Allocate shipment example
The example shows a successful request to allocate a shipment with a {reference} of sp_01017652898121961272041674506240 via the Allocate Shipment endpoint. Shipments has selected a service and returned tracking_references for the shipment.
PUT https://api.sorted.com/pro/shipments/sp_01017652898121961272041674506240/allocate
{
"shipment_reference": "sp_01017652898121961272041674506240",
"state": "allocated",
"price": {
"net": 2.00,
"gross": 2.00,
"taxes": [
{
"rate": {
"reference": "FF_DPD_Next_Day_103386",
"country_iso_code": "GB",
"type": "Zero",
"value": 0.0000
},
"amount": 0.000000
}
],
"currency": "GBP"
},
"message": "Shipment sp_01017652898121961272041674506240 has been allocated successfully",
"carrier": {
"reference": "FF_103386_DPD",
"name": "DPD",
"service_reference": "FF_DPD_Next_Day_103386",
"service_name": "DPD Next Day (Parcel)"
},
"tracking_details": {
"contents": [
{
"reference": "sc_01017652898121961272041674506241",
"tracking_references": [
"15503566052622"
],
"_links": []
},
{
"reference": "sc_01017652898121961272041674506242",
"tracking_references": [
"15503566052623"
],
"_links": []
}
]
},
"_links": [
{
"href": "https://api-int.sorted.com/pro/shipments/sp_01017652898121961272041674506240",
"rel": "shipment",
"reference": "sp_01017652898121961272041674506240",
"type": "shipment"
},
{
"href": "https://api-int.sorted.com/pro/labels/sp_01017652898121961272041674506240/pdf",
"rel": "label",
"reference": "sp_01017652898121961272041674506240",
"type": "label"
},
{
"href": "https://api-int.sorted.com/pro/labels/sp_01017652898121961272041674506240/zpl",
"rel": "label",
"reference": "sp_01017652898121961272041674506240",
"type": "label"
},
{
"href": "https://api.sorted.com/pro/documents/sp_01017652898121961272041674506240",
"rel": "customs_documents",
"reference": "sp_01017652898121961272041674506240",
"type": "all"
}
],
"correlation_id": "3ba8481a-7dfc-49ab-8502-e58f98f8fac2.SAPI_28e18db6-2be3-45af-89d7-0e9bb72ae0f2",
"details": [],
"excluded_services": [
{
"carrier": {
"reference": "FF_FedEx_2Day_977086833",
"name": "FedEx 2 Day",
"service_reference": "FF_FedEx",
"service_name": "FedEx"
},
"exclusion": {
"reason": "This service is not available for the selected collection/delivery dates.",
"code": "ex_availability"
}
},
{
"carrier": {
"reference": "FF_FedEx_2Day_ASR_977086833",
"name": "FedEx 2 Day",
"service_reference": "FF_FedEx",
"service_name": "FedEx"
},
"exclusion": {
"reason": "This service is not available for the selected collection/delivery dates.",
"code": "ex_availability"
}
}
],
"applicable_documents": []
}
Allocation next steps
- Allocating to Default Rules - How to allocate shipments based on your pre-defined allocation rules.
- Allocating with a Specific Carrier Service - How to allocate shipments with a specific carrier service.
- Allocating Within a Carrier Service Group - How to allocate shipments with a carrier service from a specific carrier service group.