Integration: Quote with shipment groups
Follow the Quote with Shipment Groups integration design to create, quote, allocate, and manifest shipments in a batch. Enabling efficient pre-checking and group processing.
Quote with shipment groups
The Quote with Shipment Groups integration design enables you to perform operations on an entire group of shipments at once. A common use case for shipment groups is to match operational flows, such as adding multiple shipments to a cage or trailer to be taken in a batch by a carrier.
Similar to the Shipment Groups design, Quote with Shipment Groups contains an additional step in which you can check whether a shipment can be allocated to a carrier service by making a quote request at the start of the process. Making a quote request in this way can help you to identify shipments that cannot be allocated (for example, because their required_delivery_date and required_shipping_date parameters might be too restrictive) before those shipments are created.
There are thirteen steps to the design:
- Get a quote - Use the Quote Shipment or Quote Shipment by Service Group endpoints to perform a quote request using the shipment details.
- Create the shipment - Use the Create Shipment endpoint to record the details of your new shipments.
- (Optional) Add paperless documents - Use the Add Paperless Document endpoint to add documents to shipment data.
- Allocate the shipment - Use the Allocate Shipments with Service Group endpoint to allocate within a pre-defined list of carrier services.
- Get the shipment’s labels - Use the Get Labels endpoint to get delivery label for the shipment.
- (Optional) Get customs documents for the shipment - Use the Get Customs Documents to generate printable customs documents for international shipments.
- Create the shipment group - Use the Create Shipment Group endpoint to create the shipment group and add your shipments to it.
- (Optional) Update the szhipment group - Use the Update Shipment Group endpoint to add or remove shipments from your shipment group.
- Lock the shipment group - Use the Lock Shipment Group endpoint to prevent further changes from being made to the group.
- (Optional) Unlock the shipment group - Use the Unlock Shipment Group endpoint to release the lock, allowing further changes to be made to the group.
- (Optional) Get a collection note for the shipment group - Use the Get Collection Note by Shipment Group endpoint to generate a driver’s manifest containing all shipments in the group.
- Manifest the shipment group - Use the Manifest Shipment Group endpoint to send shipment data to the selected carrier.
- Close the shipment group - Use the Close Shipment Group endpoint to close the group, finalising all changes.
This section gives more detail on each step of the design and provides worked examples.
Step 1: Get a quote
Create quote
GET https://api.sorted.com/pro/shipments/quote
To retrieve quotes for an as-yet-uncreated shipment, use the Create Quote endpoint.
Retrieving quotes prior to creating a shipment enables you to confirm that the shipment is “shippable” (i.e. that there are carriers who can deliver the shipment within the dates specified) as well as giving an indication of delivery costs.
Once it has received the Create Quote request, the Shipments platform returns a quote result. The quote result object includes a summary of the shipment details submitted, a list of quote objects, and a list of excluded_services (that is, eligible services for which it was not possible to obtain a delivery quote).
For full reference information on the Create Quote endpoint, see the Create Quote page of the API reference.
For a user guide on working with quotes in Shipments, see the Managing Shipment Quotes page of the API User Guide.
Create quote example
The example below shows a quote request for a shipment. Note that the Shipments platform has returned two quotes, with a further service excluded as the carrier cannot meet the delivery promise.
POST https://api.sorted.com/pro/shipments/quote
{
"shipment_type": "on_demand",
"contents": [
{
"custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
"package_size_reference": null,
"weight": {
"value": 2.40,
"unit": "Kg"
},
"dimensions": {
"unit": "Cm",
"width": 15.0,
"height": 15.5,
"length": 20.0
},
"description": "Jeans",
"value": {
"amount": 8.99,
"currency": "GBP"
},
"sku": "SKU09876",
"model": "MOD-009",
"country_of_origin": "PT",
"harmonisation_code": "09021000",
"shipping_terms": "fca",
"quantity": 2,
"unit": "Box",
"metadata": [
{
"key": "Category",
"value": "Menswear",
"type": "string"
}
],
"label_properties": null,
"Contents": null
}
],
"addresses": [
{
"address_type": "Origin",
"contact": {
"reference": "co_9953035290535460864",
"title": "Mr",
"first_name": "Mark",
"last_name": "Brunell",
"contact_details": {
"mobile": "+447495747987",
"email": "mark@62-7.com"
}
},
"property_number": "1",
"property_name": "Frank's Place",
"address_line1": "Zappa Avenue",
"address_line2": "Off Rock Road",
"address_line3": "Off Heavy Crescent",
"locality": "Manchester",
"region": "Greater Manchester",
"postal_code": "M2 6LW",
"country_iso_code": "GB"
},
{
"address_type": "destination",
"custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
"contact": {
"reference": "co_9953035290535460865",
"title": "Mr",
"first_name": "Gardner",
"last_name": "Minshew",
"middle_name": null,
"position": null,
"contact_details": {
"landline": null,
"mobile": "+447495747987",
"email": "gminshew@test.com"
}
},
"property_number": "8",
"property_name": null,
"address_line1": "Norbert Road",
"address_line2": "Bertwistle",
"address_line3": null,
"locality": "Preston",
"region": "Lancashire",
"postal_code": "PR4 5LE",
"country_iso_code": "GB",
"lat_long": null
}
]
}
{
"reference": "qc_00662089901143042926175691997186",
"message": "2 quotes retrieved successfully for shipment sp_00662089297971405204020773257216",
"shipment": {
"reference": "sp_00662089297971405204020773257216",
"addresses": [
{
"address_type": "origin",
"shipping_location_reference": "ab_00662089901143042926175691997187",
"contact": {
"title": "Mr",
"first_name": "Alan",
"last_name": "McBride",
"position": "General Manager",
"contact_details": {
"landline": "020 7287 5007",
"email": "orders@redwinglondon.com"
}
},
"property_number": "17a",
"property_name": "Porter House",
"address_line1": "Newburgh Street",
"address_line2": "Oxford Circus",
"locality": "London",
"region": "Greater London",
"postal_code": "W1F 7RZ",
"country_iso_code": "GB"
},
{
"address_type": "destination",
"contact": {
"title": "Mr",
"first_name": "Andrew",
"last_name": "Lock",
"contact_details": {
"landline": "202-555-0186",
"email": "andrew_lock2000@gmail.com"
}
},
"property_number": "5801",
"property_name": "Edward H. Levi Hall",
"address_line1": "South Ellis Avenue",
"locality": "Chicago",
"region": "IL",
"postal_code": "60637",
"country_iso_code": "US"
}
],
"custom_reference": "me_00662089901143042926175691997188",
"_links": [
{
"href": "https://beta.sorted.com/pro/shipments/sp_00662089297971405204020773257216",
"rel": "shipment",
"reference": "sp_00662089297971405204020773257216",
"type": "shipment"
}
]
},
"quotes": [
{
"reference": "qu_00662089901143042926175691997184",
"shipment_reference": "sp_00662089297971405204020773257216",
"carrier": {
"reference": "PCLYINTL",
"name": "Parcelly International",
"service_reference": "PCLYINTLISF",
"service_name": "International Superfast"
},
"collection_date": {
"start": "2020-07-17T00:00:00+00:00",
"end": "2020-07-17T20:00:00+00:00",
"has_value": true
},
"delivery_date": {
"start": "2020-07-18T09:00:00+00:00",
"end": "2020-07-18T12:00:00+00:00",
"has_value": true
},
"price": {
"net": 20.0,
"gross": 20.0,
"taxes": [
{
"rate": {
"reference": "zero_rated",
"country_iso_code": "PT",
"type": "zero_rated",
"value": 0.0
},
"amount": 0.0
}
],
"currency": "EUR"
},
"created": "2020-07-16T09:59:25.4607538+00:00",
"expires": "2020-07-16T23:59:00+00:00",
"_links": [
{
"href": "https://beta.sorted.com/pro/quotes/qu_00662089901143042926175691997184",
"rel": "self",
"reference": "qu_00662089901143042926175691997184",
"type": "quote"
}
]
},
{
"reference": "qu_00662089901143042926175691997185",
"shipment_reference": "sp_00662089297971405204020773257216",
"carrier": {
"reference": "QSDOM",
"name": "QuickStep Domestic",
"service_reference": "QSDOMLOC",
"service_name": "QS Domestic Local"
},
"collection_date": {
"start": "2020-07-17T00:00:00+00:00",
"end": "2020-07-17T19:30:00+00:00",
"has_value": true
},
"delivery_date": {
"start": "2020-07-18T08:00:00+00:00",
"end": "2020-07-18T15:45:00+00:00",
"has_value": true
},
"price": {
"net": 10.0,
"gross": 12.0,
"taxes": [
{
"rate": {
"reference": "standard",
"country_iso_code": "GB",
"type": "VAT Standard",
"value": 0.2
},
"amount": 2.0
}
],
"currency": "EUR"
},
"created": "2020-07-16T09:59:25.4607593+00:00",
"expires": "2020-07-16T23:59:00+00:00",
"_links": [
{
"href": "https://beta.sorted.com/pro/quotes/qu_00662089901143042926175691997185",
"rel": "self",
"reference": "qu_00662089901143042926175691997185",
"type": "quote"
}
]
}
],
"excluded_services": [
{
"carrier": {
"reference": "DNT",
"name": "DNT Express",
"service_reference": "DNTEXPOD",
"service_name": "DNT ExpressPack On Demand"
},
"exclusion": {
"reason": "Carrier does not have availability for this shipment for the given date(s)",
"code": "ex_availability"
}
}
]
}
Create quote by service group
GET https://api.sorted.com/pro/shipments/quote/service_group/{group_ref}
The Create Quote by Service Group endpoint enables you to get quotes from a carrier service group for an as-yet uncreated shipment.
In Shipments, carrier service groups are user-defined pools of carrier services. They are designed to be used 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.
Once it has received the Create Quote by Service Group request, the Shipments API returns a quote result. The quote result object includes a summary of the shipment details submitted, a list of quote objects, and a list of excluded_services (that is, eligible services for which it was not possible to obtain a delivery quote).
For full reference information on the Create Quote by Service Group endpoint, see the Create Quote by Service Group page of the API reference.
For a user guide on working with quotes in Shipments, see the Managing Shipment Quotes page of the API User Guide.
For a user guide on configuring carrier service groups, see the Managing Carrier Service Groups section of the Sorted Admin Portal User Guide.
Create quote by service group example
The example below shows a quote request for a shipment. Note that Shipments has returned two quotes, with a further service excluded as the carrier cannot meet the delivery promise.
POST https://api.sorted.com/pro/shipments/quote/service_group/{group_ref}
{
"shipment_type": "on_demand",
"contents": [
{
"custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
"package_size_reference": null,
"weight": {
"value": 2.40,
"unit": "Kg"
},
"dimensions": {
"unit": "Cm",
"width": 15.0,
"height": 15.5,
"length": 20.0
},
"description": "Jeans",
"value": {
"amount": 8.99,
"currency": "GBP"
},
"sku": "SKU09876",
"model": "MOD-009",
"country_of_origin": "PT",
"harmonisation_code": "09021000",
"shipping_terms": "fca",
"quantity": 2,
"unit": "Box",
"metadata": [
{
"key": "Category",
"value": "Menswear",
"type": "string"
}
],
"label_properties": null,
"Contents": null
}
],
"addresses": [
{
"address_type": "Origin",
"contact": {
"reference": "co_9953035290535460864",
"title": "Mr",
"first_name": "Mark",
"last_name": "Brunell",
"contact_details": {
"mobile": "+447495747987",
"email": "mark@62-7.com"
}
},
"property_number": "1",
"property_name": "Frank's Place",
"address_line1": "Zappa Avenue",
"address_line2": "Off Rock Road",
"address_line3": "Off Heavy Crescent",
"locality": "Manchester",
"region": "Greater Manchester",
"postal_code": "M2 6LW",
"country_iso_code": "GB"
},
{
"address_type": "destination",
"custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
"contact": {
"reference": "co_9953035290535460865",
"title": "Mr",
"first_name": "Gardner",
"last_name": "Minshew",
"middle_name": null,
"position": null,
"contact_details": {
"landline": null,
"mobile": "+447495747987",
"email": "gminshew@test.com"
}
},
"property_number": "8",
"property_name": null,
"address_line1": "Norbert Road",
"address_line2": "Bertwistle",
"address_line3": null,
"locality": "Preston",
"region": "Lancashire",
"postal_code": "PR4 5LE",
"country_iso_code": "GB",
"lat_long": null
}
]
}
{
"reference": "qc_00662089901143042926175691997186",
"message": "2 quotes retrieved successfully for shipment sp_00662089297971405204020773257216",
"shipment": {
"reference": "sp_00662089297971405204020773257216",
"addresses": [
{
"address_type": "origin",
"shipping_location_reference": "ab_00662089901143042926175691997187",
"contact": {
"title": "Mr",
"first_name": "Alan",
"last_name": "McBride",
"position": "General Manager",
"contact_details": {
"landline": "020 7287 5007",
"email": "orders@redwinglondon.com"
}
},
"property_number": "17a",
"property_name": "Porter House",
"address_line1": "Newburgh Street",
"address_line2": "Oxford Circus",
"locality": "London",
"region": "Greater London",
"postal_code": "W1F 7RZ",
"country_iso_code": "GB"
},
{
"address_type": "destination",
"contact": {
"title": "Mr",
"first_name": "Andrew",
"last_name": "Lock",
"contact_details": {
"landline": "202-555-0186",
"email": "andrew_lock2000@gmail.com"
}
},
"property_number": "5801",
"property_name": "Edward H. Levi Hall",
"address_line1": "South Ellis Avenue",
"locality": "Chicago",
"region": "IL",
"postal_code": "60637",
"country_iso_code": "US"
}
],
"custom_reference": "me_00662089901143042926175691997188",
"_links": [
{
"href": "https://beta.sorted.com/pro/shipments/sp_00662089297971405204020773257216",
"rel": "shipment",
"reference": "sp_00662089297971405204020773257216",
"type": "shipment"
}
]
},
"quotes": [
{
"reference": "qu_00662089901143042926175691997184",
"shipment_reference": "sp_00662089297971405204020773257216",
"carrier": {
"reference": "PCLYINTL",
"name": "Parcelly International",
"service_reference": "PCLYINTLISF",
"service_name": "International Superfast"
},
"collection_date": {
"start": "2020-07-17T00:00:00+00:00",
"end": "2020-07-17T20:00:00+00:00",
"has_value": true
},
"delivery_date": {
"start": "2020-07-18T09:00:00+00:00",
"end": "2020-07-18T12:00:00+00:00",
"has_value": true
},
"price": {
"net": 20.0,
"gross": 20.0,
"taxes": [
{
"rate": {
"reference": "zero_rated",
"country_iso_code": "PT",
"type": "zero_rated",
"value": 0.0
},
"amount": 0.0
}
],
"currency": "EUR"
},
"created": "2020-07-16T09:59:25.4607538+00:00",
"expires": "2020-07-16T23:59:00+00:00",
"_links": [
{
"href": "https://beta.sorted.com/pro/quotes/qu_00662089901143042926175691997184",
"rel": "self",
"reference": "qu_00662089901143042926175691997184",
"type": "quote"
}
]
},
{
"reference": "qu_00662089901143042926175691997185",
"shipment_reference": "sp_00662089297971405204020773257216",
"carrier": {
"reference": "QSDOM",
"name": "QuickStep Domestic",
"service_reference": "QSDOMLOC",
"service_name": "QS Domestic Local"
},
"collection_date": {
"start": "2020-07-17T00:00:00+00:00",
"end": "2020-07-17T19:30:00+00:00",
"has_value": true
},
"delivery_date": {
"start": "2020-07-18T08:00:00+00:00",
"end": "2020-07-18T15:45:00+00:00",
"has_value": true
},
"price": {
"net": 10.0,
"gross": 12.0,
"taxes": [
{
"rate": {
"reference": "standard",
"country_iso_code": "GB",
"type": "VAT Standard",
"value": 0.2
},
"amount": 2.0
}
],
"currency": "EUR"
},
"created": "2020-07-16T09:59:25.4607593+00:00",
"expires": "2020-07-16T23:59:00+00:00",
"_links": [
{
"href": "https://beta.sorted.com/pro/quotes/qu_00662089901143042926175691997185",
"rel": "self",
"reference": "qu_00662089901143042926175691997185",
"type": "quote"
}
]
}
],
"excluded_services": [
{
"carrier": {
"reference": "DNT",
"name": "DNT Express",
"service_reference": "DNTEXPOD",
"service_name": "DNT ExpressPack On Demand"
},
"exclusion": {
"reason": "Carrier does not have availability for this shipment for the given date(s)",
"code": "ex_availability"
}
}
]
}
Step 2: Create the shipment
POST https://api.sorted.com/pro/shipments
The first step toward manifesting a shipment is to create that shipment using the Shipments API package.
Shipments are created using the Create Shipment endpoint, which takes information about new shipments, adds them to the database, and returns a link to the newly-created shipment, including its {reference}. A newly created shipment has a {state} of unallocated.
As a minimum, the Create Shipments endpoint requires you to send details of the contents of the shipment and its origin and destination addresses. You must also specify whether the shipment is on_demand (i.e. will require an ad-hoc carrier collection to be booked) or scheduled (i.e. will be picked up as part of a regularly scheduled carrier collection).
For full reference information on the Create Shipment endpoint, see the Create Shipment page of the API reference.
For a user guide explaining the Create Shipment endpoint, see the Creating Shipments page.
Create shipments example
This example shows the creation of a fairly standard shipment. In this case, we have an outbound shipment comprising a single package.
After receiving the request, Shipments API returns a {reference} of sp_00595452779180472847666078547968. Many of Shipment’s functions require you to provide this shipment {reference} as a parameter.
POST https://api.sorted.com/pro/shipments
{
"shipment_type": "on_demand",
"contents": [
{
"custom_reference": "b9fa91b0-0dd0-4dd5-986f-363fa8cb2386",
"package_size_reference": null,
"weight": {
"value": 2.40,
"unit": "Kg"
},
"dimensions": {
"unit": "Cm",
"width": 15.0,
"height": 15.5,
"length": 20.0
},
"description": "Jeans",
"value": {
"amount": 8.99,
"currency": "GBP"
},
"sku": "SKU09876",
"model": "MOD-009",
"country_of_origin": "PT",
"harmonisation_code": "09021000",
"shipping_terms": "fca",
"quantity": 2,
"unit": "Box",
"metadata": [
{
"key": "Category",
"value": "Menswear",
"type": "string"
}
],
"label_properties": null,
"Contents": null
}
],
"addresses": [
{
"address_type": "Origin",
"contact": {
"reference": "co_9953035290535460864",
"title": "Mr",
"first_name": "Mark",
"last_name": "Brunell",
"contact_details": {
"mobile": "+447495747987",
"email": "mark@62-7.com"
}
},
"property_number": "1",
"property_name": "Frank's Place",
"address_line1": "Zappa Avenue",
"address_line2": "Off Rock Road",
"address_line3": "Off Heavy Crescent",
"locality": "Manchester",
"region": "Greater Manchester",
"postal_code": "M2 6LW",
"country_iso_code": "GB"
},
{
"address_type": "destination",
"custom_reference": "21bbd58a-6dec-4097-9106-17501ddca38d",
"contact": {
"reference": "co_9953035290535460865",
"title": "Mr",
"first_name": "Gardner",
"last_name": "Minshew",
"middle_name": null,
"position": null,
"contact_details": {
"landline": null,
"mobile": "+447495747987",
"email": "gminshew@test.com"
}
},
"property_number": "8",
"property_name": null,
"address_line1": "Norbert Road",
"address_line2": "Bertwistle",
"address_line3": null,
"locality": "Preston",
"region": "Lancashire",
"postal_code": "PR4 5LE",
"country_iso_code": "GB",
"lat_long": null
}
]
}
{
"reference": "sp_00595452779180472847666078547968",
"message": "Shipment created successfully",
"_links": [
{
"href": "https://api.sorted.com/pro/shipments/sp_00595452779180472847666078547968",
"rel": "shipment",
"reference": "sp_00595452779180472847666078547968",
"type": "shipment"
}
]
}
Step 3 (Optional) Add paperless documents
Add paperless document endpoint
POST https://api.sorted.com/pro/documents/paperless/{shipment_reference}
Paperless documents are customer-generated documents that are transmitted to carriers as part of a shipment’s data, as opposed to being generated separately by the carrier. They can help to make your workflows more efficient, reducing steps in the manifest process and enabling you to attach document data to a shipment directly.
Please note: Not all carriers support paperless trade.
file_format, document_type, and file_content (as a base64-encoded byte array). You can also add expiration and usage data if required.Once it has received the request, Shipments attaches the document to the specified shipment and returns a unique reference for the paperless document. You can use this reference to retrieve details of the paperless document (via the Get Paperless Document endpoint), or delete the paperless document entirely (via the Remove Paperless Document endpoint).
For full reference information on the Add Paperless Document endpoint, see the Shipments API Reference.
For a user guide on working with paperless documents, see the Adding Paperless Documents page.
Add paperless document example
The example shows a successful request to add a commercial_invoice paperless document to shipment sp_00595452779180472847666078547968. Shipments has responded with a paperless document reference of pd_00797582543150236528252876881920.
Example add paperless document request
POST https://api.sorted.com/pro/documents/paperless/sp_00595452779180472847666078547968
{
"file_format": "pdf",
"document_type": "commercial_invoice",
"expiration": "2021-09-01T06:00:00+00:00",
"file_content": (Base64 document data),
"usage": "electronic_trade"
}
Example add paperless document response
{
"reference": "pd_00797582543150236528252876881920",
"message": "Paperless Document pd_00797582543150236528252876881920 added successfully",
"_links": [
{
"href": "https://api-int.sorted.com/pro/documents/paperless/pd_00797582543150236528252876881920",
"rel": "self",
"reference": "pd_00797582543150236528252876881920",
"type": "paperless_document"
},
{
"href": "https://api-int.sorted.com/pro/shipments/sp_00797580869643167594270016798720",
"rel": "shipment",
"reference": "sp_00797580869643167594270016798720",
"type": "shipment"
}
]
}
Step 4: Allocating the shipment
Allocate shipments with service group
Allocate Shipments with Service Group
PUT https://api.sorted.com/pro/shipments/allocate/servicegroup
To allocate shipments using carrier service groups, use the Allocate Shipments with Service Group endpoint.
In Shipments, carrier service groups are user-defined pools of carrier services. They are designed to be used 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.
Like other allocation endpoints, Allocate Shipments with Service Groups allocates based on your organisation’s custom allocation rules. Shipments enables you to configure custom allocation rules for individual carrier services - such as valid package dimensions, maximum shipment value, and geographical availability - via the UI.
The Allocate Shipments with Service Groups endpoint can be used to allocate multiple shipments simultaneously. The request body should contain an array of one or more shipment {reference}s to be allocated.
Once the request is received, the Shipments platform queues all of the listed shipments for allocation to the cheapest eligible carrier within the service group, based on your default rules. The system then returns an Allocate Shipments Response.
For full reference information on the Allocate Shipments with Service Group endpoint, see the Allocate Shipments with Service Group section of the API reference.
For a user guide on allocating within carrier service groups, see the Allocating Within a Carrier Service Group section of the Shipments API User Guide.
For a user guide on configuring carrier service groups, see the Managing Carrier Service Groups section of the Sorted Admin Portal User Guide.
Allocate shipments with shipment group example
The example shows a request to allocate three shipments via default rules. Two have been successfully queued for allocation, but one was rejected due to an invalid shipment {reference}.
Allocate Shipments by Shipment Group Request
PUT https://api.sorted.com/pro/shipments/allocate/servicegroup
"shipments": [
"sp_10014418679662051328667654221112",
"sp_10014418692546953216098308745978",
"sp_10014418709726822400232323009988"
]
"service_group": "nextDayCarrierGroup",
Allocate Shipments by Shipment Group Response
{
"message": "2 shipment(s) queued for allocation successfully. 1 shipment(s) rejected for allocation.",
"queued": [
"sp_10014418679662051328667654221112",
"sp_10014418692546953216098308745978"
],
"rejected": [
{
"code": "shipment_not_found",
"message": "The shipment cannot be found",
"references": [
"sp_10014418709726822400232323009988"
]
}
],
"_links": [
{
"href": "https://beta.sorted.com/pro/shipments/sp_10014418709726822400232323009988",
"rel": "shipment",
"reference": "sp_10014418709726822400232323009988",
"type": "rejected"
}
]
}
Step 5: Get shipment labels
GET https://api.sorted.com/pro/labels/{shipmentReference}/{contentType}/{dpi}
When a shipment is allocated, the Shipments platform generates labels for each item of contents in that shipment. You can retrieve these delivery labels via the Get Labels endpoint.
The Get Labels endpoint takes shipment {reference}, {contentType}, and {dpi} as path parameters, where {reference} is the unique reference of the shipment you want to get labels for, {contentType} is an optional property indicating the file format required (either PDF or ZPL), and {dpi} an optional property indicating is the resolution required. Shipments returns all package labels associated with that shipment as a base64-encoded byte array that decodes to the format and resolution requested.
For full reference information on the Get Labels endpoint, see the Get Labels page of the API reference.
>For a user guide on retrieving labels in Shipments, see the Getting Labels page.
Get labels example
The example shows a request to get PDF labels for a shipment with a {reference} of sp_00668400124857422605561635799040. The file data in the response has been truncated for clarity.
You will need to decode the file’s Base64 data in order to view or print the label. If you are unsure how to do so, see the MDN docs for more information.
GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/pdf
{
"file": (Base64 file data),
"content_type": "text/plain",
"document_type": "label",
"dpi": 203
}
Step 6 (Optional): Get customs docs
Get customs documents endpoint
GET https://api.sorted.com/pro/documents/{shipment_reference}
When shipping internationally, the Shipments platform automatically determines whether customs documentation is necessary for a shipment, and generates documents where required. You can retrieve customs documentation via the Get Customs Documents endpoint.
The Get Customs Documents endpoint takes a shipment {reference} as a path parameter. If CN22/CN23 or commercial invoice documents exist for the specified shipment, then Shipments returns these documents as a base64-encoded byte array that decodes to a PDF document.
You will need to decode the file’s Base64 data in order to view or print the documents. If you are unsure how to do so, see the MDN docs for more information.
For full reference information on the Get Customs Documents endpoint, see the Get Customs Documents page of the API reference.
For a user guide on retrieving customs documents and commercial invoices in Shipments, see the Getting Shipment Documents page.
Get customs documents example
This example shows a Get Customs Documents response for shipment sp_00670175533382557003917067812864. Shipments has returned a CN22 document.
GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864
Get customs documents response
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "cn22",
"dpi": 203
}
Step 7: Create the shipment group
Create shipment group endpoint
POST https://api.sorted.com/pro/shipment_groups
Next, you’ll need to create a shipment group by making a Create Shipment Group request. The body of the request should contain a list of up to 10,000 shipments that you want to add to the group, and an optional custom_reference that can be used as a unique identifier for the group.
Once it has received and validated the request, Shipments creates the shipment group and returns a Resource Result containing the group reference. This reference will be used as an identifier for the group later on in the process.
For a user guide on creating shipment groups see the Creating Shipment Groups page.
For full reference information on the Create Shipment Groups endpoint, see the Shipments API reference.
Example create shipment group call
The example shows a successful request to add three shipments to a group.
POST https://api.sorted.com/pro/shipment_groups/
{
"custom_reference": "Example123",
"shipments": [
"sp_00013464648910021776641789788160",
"sp_00013464648910021776641789784435",
"sp_00013464648910021776641789790773"
]
}
Create shipment group response
{
"reference": "sg_00679577652026749527919113797632",
"custom_reference": "Example123",
"version": 79,
"message": "Shipment group sg_00679577652026749527919113797632 created successfully",
"_links": [
{
"href": "https://api.sorted.com/pro/shipments/groups/sg_00679577652026749527919113797632",
"rel": "self",
"reference": "sg_00679577652026749527919113797632",
"type": "shipment_group"
}
]
}
Step 8: Update the shipment group
Update shipment group endpoint
PUT https://api.sorted.com/pro/shipment_groups
You can amend the shipments in a shipment group using the Update Shipment Group endpoint. For example, you may have added extra shipments to a particular warehouse cage, and you want to amend the corresponding shipment group to also contain those shipments.
The Update Shipment Group request should contain the reference of the group you want to amend and optional add_shipments and/or remove_shipments properties listing the shipments that you want to either add to or remove from the group.
Once it has received the request, the Shipments platform returns a Resource Result confirming the result of the operation.
For a user guide on updating shipment groups, see the Editing Shipment Groups page. * For full reference information on the Update Shipment Groups endpoint, see the Shipments API reference.
Example update shipment group call
The example shows a successful request to update the group created in the previous example. Three new shipments have been added to the group, while one of the group’s existing shipments has been removed.
PUT https://api.sorted.com/pro/shipment_groups/
{
"reference": "sg_00679577652026749527919113797632",
"add_shipments": [
"sp_00682731282010871067439042134016",
"sp_00682731282010871067439042134045",
"sp_00682731282010871067439042134076"
],
"remove_shipments": [
"sp_00013464648910021776641789788160"
]
}
Update shipment group response
{
"reference": "sg_00679577652026749527919113797632",
"message": "Shipment group sg_00679577652026749527919113797632 updated successfully",
"_links": [
{
"href": "https://beta.sorted.com/pro/shipments/groups/sg_00679577652026749527919113797632",
"rel": "self",
"reference": "sg_00679577652026749527919113797632",
"type": "shipment_group"
}
]
}
Step 9: Lock the shipment group
POST https://api.sorted.com/pro/shipment_groups/{reference}/lock
You’ll need to lock your shipment group via the Lock Shipment Group endpoint before you can get a collection note for it. Locking a shipment group means that it can no longer be edited.
Locked shipment groups can be unlocked via the Unlock Shipment Group endpoint, making it possible to add or remove shipments from the group. * For a user guide on locking shipment groups, see the Locking Shipment Groups section of the Editing Shipment Groups page. * For full reference information on the Lock Shipment Groups endpoint, see the Shipments API reference.
Example lock shipment group call
The example shows a successful request to lock shipment group sg_00679577652026749527919113797632.
POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/lock
{
"reference": "sg_00679577652026749527919113797632",
"message": "Shipment group sg_00679577652026749527919113797632 locked successfully",
"_links": [
{
"href": "https://api.sorted.com/pro/shipments/groups/sg_00679577652026749527919113797632",
"rel": "self",
"reference": "sg_00679577652026749527919113797632",
"type": "shipment_group"
}
]
}
Step 10: Unlock the shipment group
Unlock Shipment Group Endpoint
POST https://api.sorted.com/pro/shipment_groups/{reference}/unlock
You’ll need to unlock your shipment group via the Unlock Shipment Group endpoint to add or remove any shipments to the Shipment Group. Unlocking a shipment group means that the shipment group is again open for editing.
Unlocked shipment groups can be locked via the Lock Shipment Group endpoint.
For a user guide on unlocking shipment groups, see the Unlocking Shipment Groups section of the Editing Shipment Groups page.
For full reference information on the Unlock Shipment Groups endpoint, see the Shipments API reference.
Example Unlock shipment group call
The example shows a successful request to unlock shipment group sg_00679577652026749527919113797632.
POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/unlock
Unlock Shipment Group Response
{
"reference": "sg_00679577652026749527919113797632",
"message": "Shipment group sg_00679577652026749527919113797632 unlocked successfully",
"_links": [
{
"href": "https://api.sorted.com/pro/shipments/groups/sg_00679577652026749527919113797632",
"rel": "self",
"reference": "sg_00679577652026749527919113797632",
"type": "shipment_group"
}
]
}
Step 11: Get collection notes for the shipment group
Get shipment group collection note endpoint
POST https://api.sorted.com/pro/collection_notes/shipment_group/{reference}
In Shipments, a collection note (sometimes referred to as a driver’s manifest) is a document listing items that are to be collected by a driver. It is intended to be printed and given to the driver at the point of collection.
The Get Shipment Group Collection Note endpoint returns a collection note document listing all of the shipments in the specified group. The group must be locked in order for a collection note to be generated.
For a user guide on getting shipment group collection notes, see the Getting Collection Notes for a Shipment Group section of the Getting Collection Notes page. * For full reference information on the Get Shipment Group Collection Note endpoint, see the Shipments API reference.
Example get shipment group collection note call
The example shows a successful request to get a collection note for shipment group sg_00679577652026749527919113797632.
Get shipment group collection note request
POST https://api.sorted.com/pro/collection_notes/shipment_group/sg_00679577652026749527919113797632
Get shipment group collection note response
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "collection_note",
"dpi": 203
}
Step 12: Manifest the shipment group
Manifest shipment group endpoint
POST https://api.sorted.com/pro/shipment_groups/{reference}/manifest
Once you’ve added your shipments to the shipment group, you’re ready to manifest it. To manifest a shipment group, use the Manifest Shipments by Shipment Group endpoint.
In the context of the Sorted Shipments platform, the term “manifesting” refers to collating, formatting and transmitting shipment data to carriers. The Manifest Shipments by Shipment Group endpoint queues all of the shipments in the specified shipment group for manifest.
For a user guide on manifesting shipments, see the Manifesting Shipments page.
For full reference information on the Manifest Shipments by Shipment Group endpoint, see the Shipments API reference.
Manifest shipment group example
The example shows a successful request to manifest a shipment group.
Manifest shipment group request
POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/manifest
{
"manifest_results": [
{
"reference": "ma_01277530195429043576331230117888",
"carrier": {
"reference": "CustomerX_DPD",
"name": "DPD",
"service_reference": "CX_DPDND",
"service_name": "DPD Next Day (Parcel)"
},
"message": "2 shipments queued for manifest successfully",
"state": "manifesting",
"shipment_count": 2,
"_links": []
}
]
}
Step 13: Close the shipment group
POST https://api.sorted.com/pro/shipment_groups/{reference}/close
The Close Shipment Group endpoint permanently closes a specified shipment group. It is intended to be used when all shipments within a group have been either manifested or cancelled and the group is no longer required. A shipment group must be locked before it can be closed.
Once closed, shipment groups cannot be re-opened. If you want to prevent a shipment group from being edited but may still need to make changes to it later, use the Lock Shipment Group endpoint.
For a user guide on closing shipment groups, see the Closing Shipment Groups page.
Example Close Shipment Group Call
The example shows a successful request to close shipment group sg_00679577652026749527919113797632.
POST https://api.sorted.com/pro/shipment_groups/sg_00679577652026749527919113797632/close
{
"reference": "sg_00679577652026749527919113797632",
"message": "Shipment group sg_00679577652026749527919113797632 closed successfully",
"_links": [
{
"href": "https://api.sorted.com/pro/shipments/groups/sg_00679577652026749527919113797632",
"rel": "self",
"reference": "sg_00679577652026749527919113797632",
"type": "shipment_group"
}
]
}