Ship Explained: API packages
A look at Sorted’s Consignments and Shipments API packages, helping you understand the difference between warehouse dispatch and flexible, on-demand shipping.
Ship API packages
The Consignments and Shipments API packages are two core components of our Ship platform, each package is tailored for the two main retail delivery models. While they both handle the logistics of getting parcels from sender to recipient using Shipping Data Units, they serve distinct operational needs and are built with different use cases in mind.
| Type | Consignments API | Shipments API |
|---|---|---|
| Distribution Model | Centralised, scheduled | Distributed, on-demand |
| Pickup Type | Fixed schedule | Scheduled or on-demand |
| Shipping Origin | Warehouses | Stores, warehouses, homes |
| Volume | High-volume, batched | Individual or grouped |
| Use Case | Daily warehouse dispatch | Real-time, flexible deliveries |
Consignments API package
The Consignments API is purpose-built for structured, high-volume shipping workflows. It’s designed to work best with centralised, warehouse-based operations where packages are batched and shipped on a regular, scheduled basis.
Shipments API package
In contrast, the Shipments API is designed for flexibility. It supports both scheduled and on-demand shipping models, allowing businesses to ship from multiple origins, like stores, warehouses, temporary sites, and even home locations.
Comparing Consignments and Shipments API
Although the end-goal is the same, there are some key differences between the two API packages, should you find you’re in a situation where the functionality of both API packages can apply to your operations model.
Referenced below are some example JSON API payloads for registering a shipment in both API packages and the key property differences and definitions.
consignment and a shipment is used in both platforms, particularly in their respective API packages, they both generally mean the same thing in the sense that they refer to the movement of goods being sent to a customer/consumer. As the names suggest, the term ‘consignments’ is primarily used within the Consignments API, while ‘shipments’ is the preferred terminology on the Shipments API.Package contents payload
Both APIs support detailed item-level data, but they structure and name this information differently.
Consignments: package payload
In the Consignments API, a Packages array defines the contents of the shipment. Each package can include extensive item-level detail such as SKU, harmonisation code, weight, and metadata, with properties like ContentClassification to describe the nature of goods.
"Packages": [
{
"Items": [
{
...
"ContentClassification": "Unrestricted",
"ContentClassificationDetails": "NotSpecified"
}
],
...
}
]
Shipments: package payload
In comparison, the Shipments API uses a contents array to describe what’s being shipped. This structure also captures detailed package data but introduces specific properties such as dangerous_goods and hazard_classes to allow more granular handling of regulated items. This functionality allows carriers to determine eligibility for shipments with hazardous content.
Additionally, properties like label_properties which were previously included in metadata within the Consignments API are defined explicitly in Shipments, providing a clearer model for specifying label-related information.
"contents": [
{
...
"dangerous_goods": {
"id_number": "string",
"proper_shipping_name": "string",
"technical_name": "string",
"custom_label_text": "string",
"hazard_classes": [
{
"code": "string"
}
]
},
"label_properties": [
{
"key": "string",
"value": "string"
}
]
}
]
Delivery dates payload
Both APIs offer ways to set shipping and delivery expectations, though the Shipments API provides a more flexible structure.
Consignments: delivery date payload
The Consignments API uses properties like RequiredDeliveryDate and ShippingDate, which are suited for scenarios with fixed dates. These fields indicate either a specific required delivery day or a single shipping date.
"RequiredDeliveryDate": {
"Date": "2022-04-17T00:00:00+01:00",
"IsToBeExactlyOnTheDateSpecified": false
},
"ShippingDate": "2022-04-16T00:00:00+01:00"
Shipments: delivery date payload
The Shipments API adds flexibility by allowing date ranges through start and end fields for both shipping and delivery. This enables businesses to define a time window for collection or delivery, which can help align better with carrier availability or customer expectations.
"required_delivery_date": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
},
"required_shipping_date": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
}
Customs documentation payload
When it comes to customs documentation, both APIs enable the provision of essential data, but their models differ in how the fields are presented and extended.
Consignments: custom docs payload
In the Consignments API, the CustomsDocumentation object allows entry of critical customs-related details like VAT numbers, tax codes, and references to required documents. This is appropriate for standard customs compliance.
"CustomsDocumentation": {
"DesignatedPersonResponsible": "Peter McPetersson",
"ImportersVatNumber": "02345555",
"CategoryType": "Other",
"ShipperCustomsReference": "CREF0001",
"ImportersTaxCode": "TC001",
"ImportersTelephone": "0161123456",
"ImportersFax": "01611124547",
"ImportersEmail": "peter.mcpetersson@test.com",
"CN23Comments": "Comments",
"ReferencesOfAttachedInvoices": [
"INV001"
],
"ReferencesOfAttachedCertificates": [
"CERT001"
],
"ReferencesOfAttachedLicences": [
"LIC001"
],
"CategoryTypeExplanation": "Explanation",
"DeclarationDate": "2022-04-15T00:00:00+01:00",
"OfficeOfPosting": "Manchester",
"ReasonForExport": "Sale",
"ShippingTerms": "CFR",
"ShippersVatNumber": "874541414",
"ReceiversTaxCode": "TC5454",
"ReceiversVatNumber": "8745474",
"InvoiceDate": "2022-04-15T00:00:00+01:00"
}
Shipments: custom docs payload
The Shipments API builds on this with a similarly structured customs_documentation object but includes extended fields like eori_number, carriage_charge, and tax_paid. These fields, while not mandatory, allow users to provide a more comprehensive customs declaration when needed.
This difference is particularly useful for international shipments with stricter compliance requirements, offering flexibility depending on the shipment’s destination and content.
"customs_documentation": {
"designated_person_responsible": "string",
"importers_vat_number": "string",
"category_type": "string",
"category_type_explanation": "string",
"shippers_customs_reference": "string",
"importers_tax_code": "string",
"importers_telephone": "string",
"importers_fax": "string",
"importers_email": "string",
"cn23_comments": "string",
"attached_invoice_references": [
"string"
],
"attached_certificate_references": [
"string"
],
"attached_licence_references": [
"string"
],
"declaration_date": "2019-08-24T14:15:22Z",
"reason_for_export": "string",
"shippers_vat_number": "string",
"receivers_tax_code": "string",
"receivers_vat_number": "string",
"receivers_eori": "string",
"invoice_date": "2019-08-24T14:15:22Z",
"eori_number": "string",
"invoice_number": "string",
"office_of_origin": "string",
"declaration_statement": "string",
"invoice_comments": "string",
"ioss_vat_identification_number": "string",
"total_customs_value": {
"amount": 0,
"currency": "string"
},
"carriage_charge": {
"amount": 0,
"currency": "string",
"discount": 0
},
"duty_paid": {
"amount": 0,
"currency": "string",
"discount": 0
},
"tax_paid": {
"amount": 0,
"currency": "string",
"discount": 0
},
"shipping_terms": "string"
}
Corresponding API requests
Now that you know the payload structural differences between each API package, we’ve linked the main Consignments API endpoints with it’s corresponding endpoint in the Shipment API package. This can help if your are unsure which API package is best suited to your oraganisation’s shipping operations.
| Consignments | Ship |
|---|---|
| Create Consignment POST/consignments | Create Shipment POST/pro/shipments |
| Allocate Consignment With Service Group PUT/allocation/{consignmentReference}/allocatewithservicegroup/{mpdCarrierServiceGroupReference} | Allocate Shipment with Service Group GET/pro/shipments/{shipmentReference}/allocate/service_group/{groupReference} |
| Get Consignment GET/consignments/{consignmentReference} | Get Shipment GET/pro/shipments/{shipmentReference} |
| Get Labels in Format GET/labels/{consignmentReference}/{labelFormat} | Get Labels GET/pro/labels/{shipmentReference}/{contentType}/{dpi} |
| Manifest Consignments From Query POST/consignments/manifestFromQuery | N/A |
| N/A | Manifest Shipments by Shipment Group POST/pro/shipment_groups/{shipmentGroupReference}/manifest |
| Set Ready to Ship PUT/consignments/setreadytoship | Change Shipment State PUT/pro/shipments/state |
| Cancel Consignment PUT/consignments/{consignmentReference}/cancel | Cancel Shipment PUT/pro/shipments/{shipmentReference}/cancel |