Classic Flow
Creating a new consignment, allocating it to a suitable carrier service, and then adding it to that service's manifest is perhaps PRO's most basic use case. The Classic call flow offers the lightest integration design of all PRO 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 PRO's Allocation endpoints to select the carrier service that your consignment will use. You can nominate a specific service, ask PRO 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 Ship.
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.
Note
- 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, Ship returns a {consignmentReference} of EC-000-05B-MMA. Many of Ship'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"
}
Step 2: Allocating 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 Ship, allocation is the process of selecting the carrier service that will deliver the packages that make up the consignment.
Ship allocates all packages in a consignment together, as carriers expect that all packages in a consignment will ship on the same service.
Ship has multiple allocation API endpoints, giving you the flexibility to pass instructions, hints or filtering criteria when allocating. Ship's 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 Ship.
- Any allocation tags you may have supplied when the consignment was created.
This page explains the following endpoints:
- Allocate Using Default Rules - Allocates the consignment using pre-configured default rules.
- 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.
Note
For a full user guide on allocating consignments in Ship, 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.
Tip
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 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"
}
]
Allocating using Default Rules
PUT https://api.electioapp.com/allocation/allocate
To allocate one or more consignments based on your organisation's custom allocation rules, use the Allocate Using Default Rules endpoint. Ship enables you to configure custom allocation rules - such as valid package dimensions, maximum consignment value, and geographical availability - for individual carrier services. You can configure them via the Manage Carrier Service Rules page of the Ship user interface.
The Allocate Using Default Rules endpoint can be used to allocate multiple consignments simultaneously. The request body can contain an array of one or more {consignmentReference}s to be allocated.
Once the request is received, Ship takes each consignment in turn and allocates it to the cheapest eligible carrier, based on your default rules. It then returns an array of Allocation Summaries, one for each allocated consignment.
Note
- For full reference information on the Allocate Using Default Rules endpoint, see the Allocate Using Default Rules page of the API reference.
- For a guide to using allocation rules, see the Allocating Using Default Allocation Rules page.
Allocate Using Default Rules Example
The example shows a request to allocate three consignments via default rules.
PUT https://api.electioapp.com/allocation/allocate
{
"ConsignmentReferences": [
"EC-000-05B-MMA",
"EC-000-083-45D",
"EC-000-A04-0DV"
]
}
Allocating from a Service Group
https://api.electioapp.com/allocation/{consignmentReference}/allocatewithservicegroup/{mpdCarrierServiceGroupReference}
Ship's 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.
Note
- 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.
PUT https://api.electioapp.com/allocation/EC-000-05B-MMA/allocatewithservicegroup/valuableGoods
Allocating to a Specific Carrier Service
PUT https://api.electioapp.com/allocation/allocatewithcarrierservice
To allocate one or more consignments to a specific carrier service, use the Allocate With Carrier Service endpoint.
The Allocate With Carrier Service request body contains an array of one or more {consignmentReference}s to be allocated and the {MpdCarrierServiceReference} of the carrier service that they should be allocated to. Once the request is received, Ship attempts to allocate the consignments to the specified carrier service.
Note
- For full reference information on the Allocate With Carrier Service endpoint, see the Allocate With Carrier Service page of the API reference.
- For a user guide on allocating consignments to a specific carrier service, see the Allocating to a Specific Carrier Service.
Allocate With Carrier Service Example
The example shows a request to allocate three consignments to a carrier service with an {MpdCarrierServiceReference} of Example-Carrier-Service.
PUT https://api.electioapp.com/allocation/allocatewithcarrierservice
{
"MpdCarrierServiceReference": "Example-Carrier-Service",
"ConsignmentReferences": [
"EC-000-05A-Z6S",
"EC-000-083-45D",
"EC-000-A04-0DV"
]
}
Step 3: Getting Package Labels
GET https://api.electioapp.com/labels/{consignmentReference}/{labelFormat}
When a consignment is allocated, Ship 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. Ship returns all package labels associated with that consignment as a base64-encoded byte array that decodes to the format requested.
Note
- 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 Ship, 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
Step 4: Manifesting a Consignment
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 Ship, 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 Ship 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 consignments met the terms of the query, how many of those consignments were successfully queued, and how many could not be queued.
Note
- 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 Ship found 10 consignments meeting these criteria, and that all 10 were successfully queued for manifest.
PUT https://api.electioapp.com/consignments/manifestFromQuery
{
"ShippingLocationReferences": [
"Location1"
],
"States": [
"Allocated"
],
"Carriers": [
"CARRIER_X"
],
"LabelsPrinted": true
}
Next Steps
And we're done! Read on to learn how to allocate consignments based on options presented to the customer at point of purchase, and deal with orders that may require multiple consignments to fulfil.