Consumer options pickup integration
Integrate consumer pickup options into your checkout flow using Consignments APIs. Allow customers to select pickup points, generate labels and manifests.
Consumer options pickup integration
The Consumer Options flow can also be used to power Pick Up / Drop-Off (PUDO) services. By integrating Consignment APIs Pickup Options endpoint, you can build click-and-collect functionality that lets your customers select a pickup location and collection date.
There are four steps to the flow:
- Get pickup options - Use the Pickup Options endpoint to request a list of available delivery locations for the (as yet uncreated) consignment that the customer’s order will generate.
- Select delivery option - Use the Select Option endpoint to tell the Consignments platform which option the customer selected. At this point, Consignments 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: Get pickup options
POST https://api.electioapp.com/deliveryoptions/pickupoptions/
A “pickup option” in the Shipments API is a combination of a delivery promise (i.e. a delivery date and pickup location), and a carrier service that could meet that delivery promise for a consignment. The Pickup Options endpoint takes the details of an as-yet uncreated consignment and returns available pickup options.
At a minimum, the Consignments API requires you to send the following data in order to receive pickup options for a potential consignment:
- Distance - The maximum distance from the destination address that you want to receive results for.
- Max Results - The maximum number of results that you want to receive. This should be a value between one and 50.
- Package Information
- Origin Address
- Destination Address
The Pickup Options endpoint returns a {Locations} array containing details of each pickup location that can accept your consignment. Consignments provides the location’s full address, distance from destination address, latitude / longitude, and opening and closing times, enabling you to surface this information at checkout so that your customers can choose a convenient option.
Each {Location} object contains a {DeliveryOptions} array listing the delivery promises available to that location for the proposed consignment.
For full reference information on the Pickup Options endpoint, see the Pickup Options page of the API reference.
For a user guide on pickup options, see the Get pickup options page.
Pickup options example
The example shows a request to get no more than 10 pickup options for a fairly standard consignment, all within 1km of the recipient’s location.
POST https://api.electioapp.com/deliveryoptions/pickupoptions/
{
"Distance": {
"Unit": "Km",
"Value": 1.0
},
"MaxResults": 10,
"ConsignmentReferenceProvidedByCustomer": "Your reference",
"DeliveryDate": "2019-06-19T00:00:00+00:00",
"GuaranteedOnly": false,
"ShippingDate": "2019-06-16T00: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": "Shipping_Location_Reference",
"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",
"IsCached": false
}
],
"Direction": "Outbound"
}
{
"Distance": 1,
"MaxResults": 10,
"Locations": [
{
"Name": "I-Smart Communications",
"ShopReference": "GB14002",
"Address": {
"AddressLine1": "41 Whitworth Street West",
"AddressLine2": "",
"AddressLine3": "The Lock Building",
"Town": "Manchester",
"Region": "",
"Postcode": "M1 5BD",
"Country": {
"Name": "United Kingdom",
"IsoCode": {
"TwoLetterCode": "GB",
"ThreeLetterCode": "GBR",
"NumericCode": "826"
}
},
"RegionCode": "",
"IsCached": false
},
"Distance": 0.15,
"OpeningTimes": {
"Monday": [
{
"Start": "11:00:00",
"End": "18:00:00",
"UtcOffset": "0:00"
}
],
"Tuesday": [
{
"Start": "11:00:00",
"End": "18:00:00",
"UtcOffset": "0:00"
}
],
"Wednesday": [
{
"Start": "11:00:00",
"End": "18:00:00",
"UtcOffset": "0:00"
}
],
"Thursday": [
{
"Start": "11:00:00",
"End": "18:00:00",
"UtcOffset": "0:00"
}
],
"Friday": [
{
"Start": "11:00:00",
"End": "18:00:00",
"UtcOffset": "0:00"
}
],
"Saturday": [],
"Sunday": []
},
"DeliveryOptions": [
{
"Reference": "EDO-000-AHP-093",
"EstimatedDeliveryDate": {
"Date": "2019-05-21T00:00:00+00:00",
"Guaranteed": true,
"DayOfWeek": "Tuesday"
},
"DeliveryWindow": {
"Start": "09:00:00",
"End": "17:30:00",
"UtcOffset": "+01:00"
},
"Carrier": "DPD",
"CarrierService": "DPD Ship To Shop",
"CarrierServiceReference": "EDC5_DPDSS",
"Price": {
"Net": 5.99,
"Gross": 7.19,
"VatRate": {
"Reference": "GB-0.2000",
"CountryIsoCode": "GB",
"Type": "Standard",
"Rate": 0.2
},
"VatAmount": 1.2,
"Currency": {
"Name": "Pound Sterling",
"IsoCode": "GBP"
}
},
"AllocationCutOff": "2019-05-17T15:30:00+01:00",
"OperationalCutOff": "2019-05-17T15:00:00+01:00"
},
{
"Reference": "EDO-000-AHP-094",
"EstimatedDeliveryDate": {
"Date": "2019-05-20T00:00:00+00:00",
"Guaranteed": true,
"DayOfWeek": "Monday"
},
"DeliveryWindow": {
"Start": "09:00:00",
"End": "17:30:00",
"UtcOffset": "+01:00"
},
"Carrier": "DPD",
"CarrierService": "DPD Ship To Shop",
"CarrierServiceReference": "EDC5_DPDSS",
"Price": {
"Net": 5.99,
"Gross": 7.19,
"VatRate": {
"Reference": "GB-0.2000",
"CountryIsoCode": "GB",
"Type": "Standard",
"Rate": 0.2
},
"VatAmount": 1.2,
"Currency": {
"Name": "Pound Sterling",
"IsoCode": "GBP"
}
},
"AllocationCutOff": "2019-05-18T12:30:00+01:00",
"OperationalCutOff": "2019-05-18T12:00:00+01:00"
},
{
"Reference": "EDO-000-AHP-09G",
"EstimatedDeliveryDate": {
"Date": "2019-05-17T00:00:00+00:00",
"Guaranteed": true,
"DayOfWeek": "Friday"
},
"DeliveryWindow": {
"Start": "09:00:00",
"End": "17:30:00",
"UtcOffset": "+01:00"
},
"Carrier": "DPD",
"CarrierService": "DPD Ship To Shop",
"CarrierServiceReference": "EDC5_DPDSS",
"Price": {
"Net": 5.99,
"Gross": 7.19,
"VatRate": {
"Reference": "GB-0.2000",
"CountryIsoCode": "GB",
"Type": "Standard",
"Rate": 0.2
},
"VatAmount": 1.2,
"Currency": {
"Name": "Pound Sterling",
"IsoCode": "GBP"
}
},
"AllocationCutOff": "2019-05-16T15:30:00+01:00",
"OperationalCutOff": "2019-05-16T15:00:00+01:00"
}
],
"Reservation": {
"IsReservationRequired": false,
"ExpiryDate": null
},
"AdditionalInformation": [
{
"Key": "Language",
"Value": "en"
},
{
"Key": "DisabledAccess",
"Value": "True"
}
]
}
],
"NonGuaranteedLocation": null
}
The API has returned one location that meets the requested criteria, and three options for delivery to that location. All three options use the same carrier service and have a delivery time window of 09:30 - 17:30, but are scheduled for different days. In practice, the Consignments platform states that the carrier can deliver to the pickup location during business hours on the 17th, 20th or 21st of May (as required by the customer).
Note the {Reference} for each pickup option. When the customer selects their preferred pickup option you will need to pass the relevant {Reference} back to the Consignments platform 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: Select 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
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
{
"StatusCode": 200,
"ApiLinks": [
{
"Rel": "detail",
"Href": "https://apisandbox.electioapp.com/consignments/EC-000-05B-MMQ"
},
{
"Rel": "label",
"Href": "https://apisandbox.electioapp.com/labels/EC-000-05B-MMQ"
}
],
"Description": "Consignment EC-000-05B-MMQ has been successfully allocated with Carrier X Tracked 48 Signed For for shipping on 17/06/2019 00:00:00 +00:00",
"ConsignmentLegs": [
{
"Leg": 1,
"TrackingReferences": [
"TRK00009823"
],
"CarrierReference": "CARRIER_X",
"CarrierServiceReference": null,
"CarrierName": "Carrier X"
}
],
"CarrierReference": "CARRIER_X",
"CarrierName": "Carrier X",
"CarrierServiceReference": "MPD_T48CX",
"CarrierServiceName": "Tracked 48 Signed For"
}
Step 3: Get a package label
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 the 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"
}