Returning a range of Home Delivery Options

In this section we will take you through the API calls required to build a checkout experience with the following Home Delivery services:  

  • Economy for a range of fulfilment dates.

  • Next day.

  • Nominated day.

  • Timed.


These options can be returned either in combination with, or totally separately from, the Pickup and 'Click and Collect' options.

How you design and lay out your front end is up to you. However, this section provides guidance on how to use Delivery Options to return all the data that you need to build a front end offering a variety of delivery choices, e.g.



Ensure that:

  • You can capture the delivery postcode for each Home delivery call.

  • The required carrier 'service groups' have been set up in Delivery Manager, i.e. one each for Economy, Next day, Nominated day and Timed (refer to Setup).

  • The carrier costs and charges are up to date in Delivery Manager (refer to Setup

Making the API Call

You make a call to GET followed by a selection of parameters.

You can make a basic call using just these parameters:

  • Your API key (this is essential).

  • wh_code=<the warehouse code> (this is essential).


    If you wish to fulfil the order from a different warehouse, but with the same carrier network that was set up when Creating your Retailer Account, then you should also specify the wh_pc and wh_cc parameters.

  • c_cc=<ISO 3166 alpha-3 three-letter country code of the delivery address> (this is optional for UK deliveries, as the parameter defaults to the GBR United Kingdom setting).

  • c_pc=<the delivery postcode> (either this or the latitude/longitude are required).


    If you wish to deliver to a different address from the one in the Order Management System, then, in addition to capturing the new postcode added by the consumer for use in the c_pc field, you can use the additional consumer address fields.

The following parameters can be thought of as non-mandatory filters but it is best practice to set them as follows:

  • optionType=HOME. However, you can leave this field blank if you wish to include the whole range of Collection Options as well. Alternatively, just specify PUDO and/or OWNSTORE in addition to HOME if you wish to return just PUDO and/or 'Click and Collect' options in addition to the Home Delivery options.

  • return type

    Use one beginning with 'g' if you wish to return options for a range of days in the future, e.g.

    • gsc or ggg (depending on whether you want the options returned by carrier service or carrier 'service group'). In either case, the cheapest options will be returned for the next 20 days.

    or one beginning with 'l' if you wish to return the next available options, e.g.

    • lsc or lgg (depending on whether you want the options returned by carrier service or carrier 'service group').


      If you only want lsc or lgg to return carrier services that actually deliver next day (as opposed to simply returning the next available services), then you can set allocation rules in Delivery Manager. Refer to Next Day Allocation Rules.

  • Include only the relevant 'service group' that is set up in Delivery Manager, by using the incgrp parameter, e.g. incgrp=STANDARD, incgrp=NEXT, incgrp=NOMINATE or incgrp=NOON.

  • If required, limit the number of selections to be offered, by setting the limit parameter as required.


    This is particularly useful for Nominated Day delivery, but is only recommended if you are using the incgrp parameter to limit the number of carrier 'delivery groups' for every call. Otherwise, as groups are added to the call, all the appropriate options may not be returned.

  • If you are using gsc or ggg and do not require options for the full 20 days, use acceptableDeliverySlots to limit the date range.


    You will have to keep adjusting these so that they remain up to date.

For example, this is a call used to return carrier 'service group' Economy options for a range of fulfilment dates:<API-Key>&c_cc=GBR&wh_code=SL123&c_pc=SL10AG&optionType=HOME&r_t=ggg&incgrp=STANDARD&acceptableDeliverySlots=2020-03-11T15:53:38.171Z,2020-03-17T15:53:38.171Z

And this is a call used to return individual carrier service options for next day delivery:<API-Key>&c_cc=GBR&wh_code=SL123&c_pc=SL10AG&optionType=HOME&r_t=lsc&incgrp=NEXT

Processing the JSON Results of the Call

In the JSON that is returned, each delivery option will appear under "results" within a set of matching braces '{ }', for example:

            "groupCodes": [
            "photoUrls": [],
            "telephoneNumber": null,
            "distance": {
                "unit": "m",
                "value": 0
            "description": null,
            "carrierServiceCode": "RMSECONDSTL",
            "long": null,
            "optionType": "HOME",
            "storeName": "",
            "shippingCharge": 3.00,
            "lat": null,
            "delivery": {
                "from": "2020-03-14T08:00:00.000Z",
                "to": "2020-03-16T17:00:59.999Z"
            "address": "",
            "carrierServiceName": "2nd Class Packet",
            "postcode": "",
            "fullName": "Royal Mail 2nd Class Packet",
            "collection": {
                "from": "2020-03-13T18:30:00.000Z",
                "to": "2020-03-13T19:30:59.999Z"
            "storeId": null,
            "logoUrl": null,
            "storeTimes": {},
            "carrierCode": "ROYALMAIL",
            "hasDisabledAccess": false,
            "bookingCode": "RMSECONDSTL/2020-03-13/*-*/*/*-*",
            "cutOffDateTime": "2020-03-13T18:00:00.000Z"

For each result as shown above, the JSON can be interpreted to display a single option on your checkout page (refer to Designing your Front End). The JSON fields are populated from both Delivery Manager (refer to Configuring Shipping and Allocation) and, for own stores, Location Services (refer to Introduction to Location Services).

Refer also to Using the Web Cutoffs as Order Countdowns.