Classic integration
Follow the classic integration in Consignments API to create, allocate, label, and manifest consignments using the simplest integration route.
Classic integration overview
Creating a new consignment, allocating it to a suitable carrier service, and then adding it to that service’s manifest is perhaps the Consignments platform’s most basic use case. The Classic call flow offers the lightest integration design of all our data flows, making it easy for your organisation to manage deliveries across multiple carriers.
The Classic flow is most useful to your business if:
- You have a single warehouse / fulfilment centre.
- You use a static delivery promise (e.g. Next day delivery before 5pm).
- You want to keep your business logic and technology architecture as simple as possible.
There are four steps to the flow:
- Create the consignment - Use the Create Consignment endpoint to record the details of your new consignment.
- Allocate the consignment - Use one of Consignment API’s Allocation endpoints to select the carrier service that your consignment will use. You can nominate a specific service, ask the Consignments API to determine the best service to use from a pre-defined group, or allocate based on pre-set allocation rules.
- Get the consignment’s labels - Use the Get Labels in Format endpoint to get the delivery label for your consignment.
- Manifest the consignment - Use the Manifest Consignments from Query endpoint to send consignment data to the selected carrier.
This section gives more detail on each step of the flow and provides worked examples.
Step 1: Creating consignments
POST https://api.electioapp.com/consignments
The first step toward manifesting a consignment is to create that consignment in the Consignments API.
Consignments are created using the Create Consignment endpoint, which takes information about new consignments, adds them to the database, and returns a link to the newly-created consignment, including its {consignmentReference}. A newly created consignment has a {consignmentState} of Unallocated.
As a minimum, the Create Consignments endpoint requires you to send package weights and dimensions, origin address, and destination address data.
For full reference information on the Create Consignment endpoint, see the Create Consignment page of the API reference.
For a user guide explaining the Create Consignment endpoint, see the Creating New Consignments page.
Create consignments example
These examples show the creation of a fairly standard consignment. In this case, we have an outbound consignment comprising a single package with a single item inside it.
After receiving the request, the Consignments API returns a {consignmentReference} of EC-000-05B-MMA. Many of the Consignment platform’s functions require you to provide a {consignmentReference} as a parameter. Therefore, you should store the {consignmentReference} for later use.
POST https://api.electioapp.com/consignments
{
"ConsignmentReferenceProvidedByCustomer": "MYCONS-098998",
"Source": "Api",
"MetaData": [
{
"KeyValue": "Restock_Date",
"DateTimeValue": "2019-06-18T00:00:00+00:00"
}
],
"Packages": [
{
"Items": [
{
"Sku": "SKU093434",
"Model": "ITM-002",
"Description": "Striped Bamboo Red/White",
"CountryOfOrigin": {
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"HarmonisationCode": "Harmonisation_Code",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"ItemReferenceProvidedByCustomer": "ITEMREF-098",
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "Picker",
"StringValue": "David Thomas"
}
],
"Quantity": 1,
"Unit": "Box",
"HarmonisationKeyWords": [
"Keyword1"
],
"ContentClassification": "Unrestricted",
"ContentClassificationDetails": "NotSpecified"
}
],
"PackageReferenceProvidedByCustomer": "MYPACK-00923",
"Weight": {
"Value": 0.5,
"Unit": "Kg"
},
"Dimensions": {
"Unit": "Cm",
"Width": 10.0,
"Length": 10.0,
"Height": 10.0
},
"Description": "Socks",
"Value": {
"Amount": 5.99,
"Currency": {
"IsoCode": "GBP"
}
},
"Barcode": {
"Code": "09887-091221",
"BarcodeType": "Code39"
},
"MetaData": [
{
"KeyValue": "WMS-REF",
"IntValue": 77656555
}
]
}
],
"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": "2019-06-14T00:00:00+00:00",
"OfficeOfPosting": "Manchester",
"ReasonForExport": "Sale",
"ShippingTerms": "CFR",
"ShippersVatNumber": "874541414",
"ReceiversTaxCode": "TC5454",
"ReceiversVatNumber": "8745474",
"InvoiceDate": "2019-06-14T00:00:00+00:00"
},
"Addresses": [
{
"AddressType": "Origin",
"ShippingLocationReference": "EDC5_Electio",
"IsCached": false
},
{
"AddressType": "Destination",
"Contact": {
"Title": "Mr",
"FirstName": "Peter",
"LastName": "McPetersson",
"Telephone": "07702123456",
"Mobile": "07702123456",
"LandLine": "0161544123",
"Email": "peter.mcpetersson@test.com"
},
"CompanyName": "Test Company (UK) Ltd.",
"AddressLine1": "13 Porter Street",
"AddressLine2": "Pressington",
"AddressLine3": "Carlsby",
"Town": "Manchester",
"Region": "Greater Manchester",
"Postcode": "M1 5WG",
"Country": {
"Name": "Great Britain",
"IsoCode": {
"TwoLetterCode": "GB"
}
},
"SpecialInstructions": "Gate code: 4454",
"LatLong": {
"Latitude": 53.474220,
"Longitude": -2.246049
},
"IsCached": false
}
],
"Direction": "Outbound"
}
[
{
"Rel": "Link",
"Href": "https://api.electioapp.com/consignments/EC-000-05B-MMA"
}
]
Step 2: Allocate consignments
PUT https://api.electioapp.com/allocation/allocate
PUT https://api.electioapp.com/allocation/{consignmentReference}/allocatewithservicegroup/{mpdCarrierServiceGroupReference}
PUT https://api.electioapp.com/allocation/allocatewithcarrierservice
Once you’ve created a consignment, it must be allocated to a carrier service. In the context of the Consignments platform, allocation is the process of selecting the carrier service that will deliver the packages that make up the consignment.
The Consignments platform allocates all packages in a consignment together, as carriers expect that all packages in a consignment will ship on the same service.
Consignments has multiple allocation API endpoints, giving you the flexibility to pass instructions, hints or filtering criteria when allocating. The allocation endpoints consider the following factors when selecting a service:
- The capabilities of the carrier services.
- Any custom allocation rules you may have configured in the Consignments platform.
- Any allocation tags you may have supplied when the consignment was created.
This page explains the following endpoints:
- Allocate Consignment With Service Group - Allocates the consignment to the cheapest carrier service in the specified Carrier Service Group.
Once allocated, the consignment’s status is updated to Allocated, enabling you to retrieve its package labels and (where applicable) customs documentation.
This section of the site explains the circumstances in which you might choose to use each allocation endpoint, and gives worked examples.
For a full user guide on allocating consignments, see the Allocating Consignments section.
The allocation summary response
All allocation endpoints return an Allocation Summary, either singularly or (where multiple consignments have been allocated at once) in an array. The Allocation Summary contains links to the consignment resource that was allocated, a summary of the carrier service that the consignment was allocated to, a link to the relevant package labels, and a ConsignmentLegs array indicating how many legs the delivery will need.
In the example, a consignment with a {consignmentReference} of EC-000-05B-MMA has been allocated to a (dummy) carrier service called Carrier X Next Day Super.
Allocation tags enable you to filter the list of available carrier services on a per-consignment basis, no matter which allocation endpoint you use in your integration. For more information on using allocation tags, see the Filter tags page.
[
{
"StatusCode": 200,
"ApiLinks": [
{
"Rel": "detail",
"Href": "https://apisandbox.electioapp.com/consignments/EC-000-05B-MMA"
},
{
"Rel": "label",
"Href": "https://apisandbox.electioapp.com/labels/EC-000-05B-MMA"
}
],
"Description": "Consignment EC-000-05B-MMA has been successfully allocated with Carrier X Next Day Super for shipping on 14/06/2019 17:00:00 +00:00",
"ConsignmentLegs": [
{
"Leg": 1,
"TrackingReferences": [
"TRK00009823"
],
"CarrierReference": "CARRIER_X",
"CarrierServiceReference": null,
"CarrierName": "Carrier X"
}
],
"CarrierReference": "CARRIER_X",
"CarrierName": "Carrier X",
"CarrierServiceReference": "CX_NDS",
"CarrierServiceName": "Next Day Super"
}
]
Allocate from a service group
Allocate Consignment with Service Group Endpoint
https://api.electioapp.com/allocation/{consignmentReference}/allocatewithservicegroup/{mpdCarrierServiceGroupReference}
The Consignments platform carrier service groups are user-defined pools of carrier services that can be used in the allocation process. To allocate a consignment to the cheapest available carrier service in a particular carrier service group, use the Allocate Consignment With Service Group endpoint.
To configure carrier service groups, use the Configuration - Carrier Service Groups UI page.
The Allocate Consignment With Service Group endpoint takes the {consignmentReference} of the consignment you want to allocate and the {mpdCarrierServiceGroupReference} of the service group you want to allocate from as path parameters, and returns an Allocation Summary with details of the service that was allocated.
For full reference information on the Allocate Consignment With Service Group endpoint, see the Allocate Consignment With Service Group page of the API reference.
For a user guide on allocating consignments within a service group, see the Allocating Via Service Group.
Allocate With Service Group Example
The example shows a request to allocate a consignment with a {consignmentReference} of EC-000-05B-MMA to a carrier service within a group named valuableGoods.
Allocate consignment with service group request
PUT https://api.electioapp.com/allocation/EC-000-05B-MMA/allocatewithservicegroup/valuableGoods
Step 3: Get package labels
GET https://api.electioapp.com/labels/{consignmentReference}/{labelFormat}
When a consignment is allocated, Consignments API generates labels for each package in that consignment. You can retrieve these delivery labels via the Get Labels in Format endpoint.
The Get Labels in Format endpoint takes a {consignmentReference} and {labelFormat} as path parameters. The Consignments API returns all package labels associated with that consignment as a base64-encoded byte array that decodes to the format requested.
For full reference information on the Get Labels in Format endpoint, see the Get Labels in Format page of the API reference.
For a user guide on retrieving labels in Consignments, see the Getting Labels page.
Get Labels in Format Example
The example shows a request to get PDF labels for a consignment with a {consignmentReference} of EC-000-05B-MMA. 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.electioapp.com/labels/EC-000-05B-MMA/pdf
{
"File": "SlZCRVJpMHhMalFLSmRQcjZ ... TVRrNU9ERUtKU1ZGVDBZPQ==",
"ContentType": "application/pdf"
}
Step 4: Manifest consignment
Manifest consignment from query endpoint
PUT https://api.electioapp.com/consignments/manifestFromQuery
Once you’ve created a consignment, allocated it to a carrier service and printed labels for it, you’re ready to manifest it. To manifest a consignment, use the Manifest Consignments From Query endpoint. In the context of the Consignments platform, the term “manifesting” refers to collating, formatting and transmitting the consignment data to carriers.
The Manifest Consignments From Query endpoint enables you to use a query to select consignments to be manifested. Once Consignments API has added those consignments to a manifest and queued the data to be sent, the Manifest Consignments From Query endpoint returns a Message detailing how many packages met the terms of the query, how many of those consignments were successfully queued, and how many could not be queued.
For full reference information on the Manifest Consignments From Query endpoint, see the Manifest Consignments From Query page of the API Reference.
For a user guide on manifesting consignments, see the Manifesting Consignments page.
Manifest consignments from query example
The example shows a request to manifest all consignments that are allocated to Carrier X, shipping from a location with the ShippingLocationReference Location1, and have already had their labels printed. The response indicates that the Consignments platform found 10 consignments meeting these criteria, and that all 10 were successfully queued for manifest.
Manifest consignments from query request
PUT https://api.electioapp.com/consignments/manifestFromQuery
{
"ShippingLocationReferences": [
"Location1"
],
"States": [
"Allocated"
],
"Carriers": [
"CARRIER_X"
],
"LabelsPrinted": true
}
Manifest consignments from query response
{
"Message": "Query found 10 consignment(s). 10 successfully queued to manifest. 0 failed to be added to the queue"
}