Consumer Options Flow
The Consumer Options flow enables you to provide real-time delivery choices - including delivery date, time, and carrier brand - to your customer at point of purchase. After the customer has chosen their preferred option, PRO can create a consignment based on their details, and allocate that consignment to a carrier service based on the customers choice.
Note
Access to PRO's delivery and pickup option endpoints requires a SortedHERO license. This component is sold separately to the main SortedPRO product.
The Consumer Options flow is most useful to your business if:
- You want to present your customer with a dynamic checkout that offers delivery timeslot options.
- You operate a single warehouse / fulfilment centre.
- You develop and configure your own e-commerce platform.
There are four steps to the flow:
- Get delivery options - Use the Delivery Options endpoint to request a list of available delivery options for the (as yet uncreated) consignment that the customer's order will generate.
- Select delivery option - Use the Select Option endpoint to tell PRO which option the customer selected. At this point, PRO has all the information it needs to create and allocate a consignment.
- 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: Getting Delivery Options
POST https://api.electioapp.com/deliveryoptions
In the context of Ship, a "delivery option" is a combination of a delivery date, a start time and an end time. These details form a delivery promise for a consignment. Ship then recommends a carrier service that can meet the delivery promise, the delivery cost, and the required shipping date, completing the data for each delivery option.
The Delivery Options endpoint takes the details of the (as yet uncreated) consignment. As a minimum, Ship requires you to send package, origin address and destination address data in order to return delivery options.
The endpoint returns an array of {DeliveryOptions} objects. Each {DeliveryOptions} object contains details of a delivery option that can be used to take a consignment with the details you passed in the request. Ship always returns the cheapest carrier service for each delivery promise, unless using the cheapest service would conflict with existing business rules.
If you do not provide a DeliveryDate in the request, then Ship returns delivery options for a maximum of fourteen days from the current date. If you provide a DeliveryDate, then Ship provides options up to and including the supplied date.
The delivery options available for a given consignment can change over time. This is primarily due to differing carrier collection times at each shipping location.
Note
- For full reference information on the Delivery Options endpoint, see the Delivery Options page of the API reference.
- For a user guide on Ship delivery options, see the Using Delivery and Pickup Options section.
Get Delivery Options Example
The example shows a request to get delivery options for a fairly standard consignment. The API has returned two delivery options, both for Carrier X: one with an {estimatedDeliveryDate} of 2019-06-19 and one with an {estimatedDeliveryDate} of 2019-06-20.
POST https://api.electioapp.com/deliveryoptions
{
"ConsignmentReferenceProvidedByCustomer": "Your Reference",
"DeliveryDate": "2019-06-19T00:00:00+00:00",
"GuaranteedOnly": false,
"ShippingDate": "2019-06-17T00: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"
}
Both of these options have a time window starting at 00:00 and ending at 23:59. In practice, the carrier is offering to make the delivery at some point on either the 19th or 20th of June (as selected by the customer), but isn't offering a more specific timeslot on that service.
Note the {Reference} for each delivery option. When the customer selects their preferred delivery option you will need to pass the relevant {Reference} back to Ship via the Select Option endpoint.
At this point, you would present some or all of the options returned to your customer via your site or app. In the next step, we'll see how to handle the choice the customer makes.
Step 2: Selecting a Delivery Option
POST https://api.electioapp.com/deliveryoptions/select/{deliveryOptionReference}
Once the customer has selected an available option, you'll need to record their choice in Ship via the Select Option endpoint.
Ship creates and allocates a consignment using the details supplied previously in the delivery options call, and returns:
- A link to the consignment resource that was allocated
- A summary of the carrier service the consignment was allocated to
- A link to the relevant package labels
Note
- For full reference information on the Select Option endpoint, see the Select Option page of the API reference.
- For a user guide on selecting options, see the Selecting Options page.
Select Option Example
The example shows a request to select a delivery option that has a {deliveryOptionReference} of EDO-000-6DX-6XP. Ship creates a consignment with a {consignmentReference} of EC-000-05B-MMQ, which it then allocates to the carrier service associated with delivery option EDO-000-6DX-6XP. Ship then returns the relevant {consignmentReference} and label link, enabling you to retrieve labels for the consignment.
POST https://api.electioapp.com/deliveryoptions/select/EDO-000-6DX-6XP
Step 3: Getting a Package Label
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 the 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
The next section explains a similar call flow that enables you to offer pickup options (aka click-and-collect) rather than home delivery timeslots.