Getting Delivery Options

  • v1
  • options
  • pro
  • api
  • consignments
  • delivery options

This page explains how to get a list of delivery options for a consignment, both as a summary and with full details.

Getting Detailed Options

The Delivery Options endpoint takes the details of an as-yet-nonexistent consignment and returns a list of delivery options. To call Delivery Options, send a POST request to https://api.electioapp.com/deliveryoptions.

Note

For further information on what constitutes a delivery option, see the Using Delivery and Pickup Options page.

At a minimum, PRO requires you to send the consignment's package, origin address and destination address data in your Delivery Options request. However, there are lots of other properties you can send when getting delivery options, including:

  • Your own consignment reference.
  • The consignment's source.
  • Shipping and delivery dates.
  • Customs documentation.
  • The consignment's direction of travel.
  • Metadata. PRO metadata enables you to record additional data about a consignment in custom fields. For more information on using metadata in PRO, see the Metadata page.
  • Tags. Allocation tags enable you to filter the list of carrier services that a particular consignment could be allocated to. For more information on allocation tags, see the Tags page.

Providing extra information can help you to improve the relevance of the options returned, and means that any consignments or orders you generate from an option will be populated with richer data.

Once it has received the request, PRO returns an array of {DeliveryOptions} objects. Each {DeliveryOptions} object contains details of a particular delivery option that is available to take a consignment with the details you passed in the request, including:

  • Reference - A unique identifier for the delivery option, used when selecting delivery options in the next step.
  • Dates and Delivery Windows
  • Carrier Service
  • Price (cost)
  • Allocation Cutoff - The option's expiry time. If the option is not used by this time, it is rendered invalid. This value is usually set by the carrier, but can be configured manually via the Settings > Shipping Locations > [Select Location] > Collection Calendar page of the PRO UI.
  • Operational Cutoff - The operational cut off date as specified by the fulfilling shipping location.
  • Service Direction

PRO only returns a single carrier service for each delivery window on each date. This is generally the cheapest service, unless using the cheapest service would conflict with existing business rules.

Note

For full reference information on the Delivery Options endpoint, see the Delivery Options page of the API reference.

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 2020-03-18 and one with an {estimatedDeliveryDate} of 2020-03-19.

POST https://api.electioapp.com/deliveryoptions

{
  "Packages": [
    {
      "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"
        }
      }
    }  
  ],
  "Addresses": [
    {
      "AddressType": "Origin",
      "ShippingLocationReference": "Sorted1",
      "IsCached": false
    },
    {
      "AddressType": "Destination",
      "Contact": {
        "Title": "Mr",
        "FirstName": "Peter",
        "LastName": "McPetersson",
        "Telephone": "07702123456",
        "Mobile": "07702123456",
        "LandLine": "0161544123",
        "Email": "peter.mcpetersson@test.com"
      },
      "AddressLine1": "13 Porter Street",
      "Region": "Greater Manchester",
      "Postcode": "M1 5WG",
      "Country": {
        "Name": "Great Britain",
        "IsoCode": {
          "TwoLetterCode": "GB"
        }
      },
      "IsCached": false
    }
  ]
}

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 18th or 19th of March (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 PRO 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. For information on how to handle the choice the customer makes, see the Selecting Options page.

Next Steps