Delivery options overview

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

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.

At a minimum, the Consignments platform requires you to send the 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 - Enables you to record additional data about a package in custom fields. For more information on using metadata in Consignments, see the metadata page.
  • Tags. Allocation tags enable you to filter the list of carrier services that a particular package could be allocated to. For more information on allocation tags, see the allocation filter tags guide.

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

Once it has received the request, Consignments 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 Consignments UI.
  • Operational Cutoff - The operational cut off date as specified by the fulfilling shipping location.
  • Service Direction

Consignments 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.

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.

Get delivery options request

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
    }
  ]
}

Get delivery options response

  {
    "DeliveryOptions": [
        {
            "Reference": "EDO-000-79G-RXC",
            "EstimatedDeliveryDate": {
                "Date": "2020-03-18T00:00:00+00:00",
                "Guaranteed": true,
                "DayOfWeek": "Wednesday"
            },
            "DeliveryWindow": {
                "Start": "00:00:00",
                "End": "23:59:00",
                "UtcOffset": "+00:00"
            },
            "Carrier": "Carrier X",
            "CarrierService": "Tracked 48 ",
            "CarrierServiceReference": "MPD_RMDTPS48HNAUT",
            "CarrierServiceTypes": [
                "Standard"
            ],
            "Price": {
                "Net": 27.69,
                "Gross": 33.23,
                "TaxRate": {
                    "Reference": "GB-0.2000",
                    "CountryIsoCode": "GB",
                    "Type": "Standard",
                    "Rate": 0.2000
                },
                "VatAmount": 5.54,
                "Currency": {
                    "Name": "Pound Sterling",
                    "IsoCode": "GBP"
                }
            },
            "AllocationCutOff": "2020-03-14T00:00:00+00:00",
            "OperationalCutOff": "2020-03-14T00:00:00+00:00",
            "ServiceDirection": "Inbound, Outbound"
        },
        {
            "Reference": "EDO-000-79G-RXD",
            "EstimatedDeliveryDate": {
                "Date": "2020-03-19T00:00:00+00:00",
                "Guaranteed": true,
                "DayOfWeek": "Thursday"
            },
            "DeliveryWindow": {
                "Start": "00:00:00",
                "End": "23:59:00",
                "UtcOffset": "+00:00"
            },
            "Carrier": "Carrier X",
            "CarrierService": "Tracked 48 ",
            "CarrierServiceReference": "MPD_RMDTPS48HNAUT",
            "CarrierServiceTypes": [
                "Standard"
            ],
            "Price": {
                "Net": 27.69,
                "Gross": 33.23,
                "TaxRate": {
                    "Reference": "GB-0.2000",
                    "CountryIsoCode": "GB",
                    "Type": "Standard",
                    "Rate": 0.2000
                },
                "VatAmount": 5.54,
                "Currency": {
                    "Name": "Pound Sterling",
                    "IsoCode": "GBP"
                }
            },
            "AllocationCutOff": "2020-03-16T00:00:00+00:00",
            "OperationalCutOff": "2020-03-16T00:00:00+00:00",
            "ServiceDirection": "Inbound, 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 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 Consignments 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 delivery options page.

Next steps

  • Learn how to get pickup options for a consignment with our Get pickup options guide.
  • Learn how to create consignments and orders from delivery options with our Selecting options guide.