Order Flex Flow
The Order Flex flow enables you to process customer orders comprising items that will ship from different physical locations, ship on different dates or require multiple carrier services to fulfil.
The Order Flex flow is useful to your business if:
- You operate multiple warehouses / fulfilment centres, or run a customer marketplace.
- You use drop ship vendors.
- You supply a range of products with large variations in weights and dimensions.
There are five steps to the flow:
- Create order - Use the Create Order endpoint to record the customer's order in PRO.
- Pack order - Use the Pack Order endpoint to create one or more consignments from the order.
- Allocate the consignments - Use one of PRO's Allocation endpoints to select the carrier service that your consignments will use. You can select 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 delivery labels - Use the Get Labels in Format endpoint to get the delivery label for your consignments.
- Manifest the consignments - 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 the Order
POST https://api.electioapp.com/orders
The Create Order endpoint enables you to record details of a customer's order in Ship.
As a minimum, the Create Order endpoint requires you to send package and item details, origin address, and destination address data.
Note
- For full reference information on the Create Order endpoint, see the Create Order page of the API reference.
- For a user guide on creating orders, see the Creating New Orders page.
Create Order Example
The example shows the creation of a fairly standard order. In this case, we have an outbound order comprising a single package with a single item inside it.
POST https://api.electioapp.com/orders
{
"OrderReferenceProvidedByCustomer": "MY_ORDER_REF_001",
"RequiredDeliveryDate": {
"Date": "2019-06-19T00:00:00+00:00",
"IsToBeExactlyOnTheDateSpecified": false
},
"Source": "Api",
"ShippingDate": "2019-06-17T13:23:44.3774435Z",
"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
}
],
"MetaData": [
{
"KeyValue": "Key1",
"StringValue": "Value1"
},
{
"KeyValue": "Key2",
"DecimalValue": 12.45
}
],
"Direction": "Outbound"
}
After receiving the request, Ship returns an {orderReference} of EO-000-002-0TS. You should store the {orderReference}, as it will be required later when we pack the order into shippable consignments.
Step 2: Packing the Order
POST https://api.electioapp.com/orders/{orderReference}/pack
Once your order is created, you'll need to use the Pack Order endpoint to create consignments from it. The Pack Order endpoint enables you to group those items on an order that share an origin and are to be shipped together, generating a shippable consignment for them. You will need to send a Pack Order request for each consignment that you want to create from the order.
To make a Pack Order request, send a GET request to https://api.electioapp.com/orders/{orderReference}/pack. The body of the request can contain various properties that are used when creating the consignment, but at a minimum should contain the {orderReference} of the associated order and details of at least one {package} containing at least one {item} from the order. The items and packages listed make up the consignment.
Once Ship has received a Pack Order request, it creates the consignment and returns the relevant {consignmentReference}.
Note
- For full reference information on the Pack Order endpoint, see the Pack Order page of the API reference.
- For a user guide on orders in PRO, see the Managing Orders section.
Pack Order Example
The example shows a Pack Order request to create a consignment with one package containing a single item from order EO-000-002-0TT. Ship creates the consignment and responds with a {consignmentReference} of EC-000-05B-MQ4.
POST https://api.electioapp.com/orders/EO-000-002-0TT/pack
{
"OrderReference": "EO-000-002-0TT",
"OrderReferenceProvidedByCustomer": "MyOrderRef001",
"GenerateReturn": false,
"Packages": [
{
"Dimensions": {
"Unit": "Cm",
"Width": 15.4,
"Length": 21.7,
"Height": 10.0
},
"Weight": {
"Value": 1.3,
"Unit": "Kg"
},
"PackageSizeReference": "",
"Items": [
{
"Sku": "SKU093434",
"Quantity": 1
}
]
}
],
"MetaData": [
{
"KeyValue": "SampleKey",
"StringValue": "SampleValue"
}
]
}
Step 3: Allocating the Consignment
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"
}
]
You'll need to allocate all of the consignments packed from your order. Bear in mind that Allocate Using Default Rules and Allocate with Carrier Service enable you to allocate multiple consignments at once, but you can only allocate one consignment at a time via Allocate Consignment with Service Group. If you allocate via Allocate Consignment with Service Group you'll need to make one API call per consignment on the order.
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 4: 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
Note
You'll need to make one Get Labels call per consignment on the order.
Step 5: 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
}
Note
You'll need to manifest all the consignments on the order.
Next Steps
Finished! The next section explains a similar process, whereby the order is generated from delivery options that the customer selects rather than created up front.