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.

Note

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.

Prerequisites

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 https://dmo.metapack.com/dmoptions/find? followed by these parameters:

Your API key (this is essential).
wh_code=<the warehouse code> (this is essential).

Note

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 is required).

Note

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.
optionType=HOME.
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').
  
  Note
  
  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.

incgrp to include only the relevant 'service group', e.g. incgrp=STANDARD, incgrp=NEXT, incgrp=NOMINATE or incgrp=NOON.
limit if required, to restrict the number of choices.

Note

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'. Otherwise, not all the appropriate options may be returned.
acceptableDeliverySlots to limit the date range if you are using gsc or ggg.

Note

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:

https://dmo.metapack.com/dmoptions/find?key=<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:

https://dmo.metapack.com/dmoptions/find?key=<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": [
                "STANDARD"
            ],
            "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).

Refer also to Using the Web Cutoffs as Order Countdowns.