Getting Pickup Options

  • v1
  • options
  • pro
  • api
  • consignments
  • pickup options

Want to let your customers collect their deliveries from a pickup location? This page explains how to use the Pickup Options endpoint to offer available pickup locations and timeslots.

Using the Pickup Options Endpoint

The Pickup Options endpoint takes the details of an as-yet uncreated consignment and returns available pickup options. This information can be used to offer pickup timeslots and locations for the product that the customer is about to purchase.

Note

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

To call the Pickup Options endpoint, send a POST request to https://docs.sorted.com/pro/consignments-api-reference/#tag/Pickup-Options/paths/~1deliveryoptions~1pickupoptions~1/post. At a minimum, the body of the request should contain the following information:

  • Distance - The maximum distance from the destination address (in km) 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

However, there are lots of other properties you can send when getting pickup 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. Either the consignment's origin address, its destination address, or both, must include a valid ShippingLocationReference.

The Pickup Options endpoint returns a {Locations} array listing all the pickup locations that can meet your request criteria. Each {Location} object contains a {DeliveryOptions} array listing the delivery options that are available to that location for the proposed consignment.

Each {DeliveryOptions} object contains details of a particular option that could be used to deliver the consignment to the relevant {location}, including:

  • Reference - A unique identifier for the option, used when selecting options in the next step.
  • Delivery Date
  • Start and End Time
  • Carrier Service
  • Cost of Delivery
  • The latest Shipping Date and Time possible to meet the promise.

The pickup options available for a given consignment can change over time. This is primarily due to different carriers collecting at different times at each shipping location, or the pickup locations provider updating the list of active locations.

Caution

Pickup locations are classified as having either finite or infinite capacity. For locations with finite capacity, PRO may disable or enable a location at any time in line with demand for the location. Sorted strongly advise that location details are never cached for re-use in the web store or checkout due to the dynamic nature of this information.

Note

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

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. PRO returns 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, PRO is saying that the carrier can deliver to the pickup location during business hours on the 17th, 18th or 19th or March (as required by the customer).

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

{
  "Distance": {
    "Unit": "Km",
    "Value": 1.0
  },
  "MaxResults": 10,
  "ConsignmentReferenceProvidedByCustomer": "Your reference",
  "DeliveryDate": "2020-03-19T00:00:00+00:00",
  "GuaranteedOnly": false,
  "ShippingDate": "2020-03-16T00:00:00+00:00",
  "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
    }
  ]
}

Note the {Reference} for each pickup 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