1. Metapack
  2. Checkout
  3. Delivery Options
  4. Best Practice

Returning a range of Collection Options

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

  • Nearest pickup points (PUDOs).

  • 'Click and Collect' from own store.

Note

These options can be returned either in combination with, or totally separately from, the Home Delivery 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.

Options_Collection_Smallest.png

Note

For an example of returning options for lockers, refer to Using PUDOs to return Lockers.

For an example of returning options for the closest service points, refer to Nearest PUDOs.

For an example of returning the next available service point deliveries, refer to Next Day 'Click and Collect'.

Prerequisites

Ensure that:

  • You can capture the latitude and longitude coordinates of the delivery collection postcode. Refer to the Caution for c_pc, c_lat and c_long.

  • The required carrier 'service groups' have been set up in Delivery Manager (refer to Setup).

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

  • Each of your own stores has up to date opening times in Location Services If you are returning 'Click and Collect' options (stores without opening times will not be returned - 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).

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

  • optionType=PUDO, optionType=OWNSTORE, or optionType=PUDO,OWNSTORE (for both).

  • 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 or excgrp, depending on whether you wish to include or exclude specific carrier 'service groups'.

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

  • radius if you require the search radius from the specified latitude/longitude to differ from the default 1000 metres.

  • minown (if you wish to return a specific number of own stores regardless of radius), maxown (if you wish to limit the number of own stores returned), or limit (if you wish to restrict the number of PUDOs returned).

For example, this is a call used to return a limited range of acceptableDeliverySlots for pickup points within 750 metres of a particular latitude/longitude, but excluding next day deliveries:

https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&optionType=PUDO&r_t=ggg&radius=750&c_lat=51.474316&c_long=-0.278015&excgrp=NEXT&acceptableDeliverySlots=2020-03-17T15:53:38.171Z,2020-03-19T15:53:38.171Z

The following is a call used to return individual carrier service options for next day 'Click and Collect' delivery within 7000 metres of a particular latitude/longitude:

https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_lat=51.5234&c_long=-0.1141&optionType=OWNSTORE&incgrp=NEXT&r_t=lgg&radius=7000

And the following call uses the lsc return type to return the specified minimum number (minown) of 'Click and Collect' options from the search point defined via the c_lat and c_long values. If minown stores cannot be found within the default radius, then the search extends beyond it until minown is returned.

https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_lat=51.474316&c_long=-0.278015&optionType=OWNSTORE&r_t=lsc&minown=2&c_cc=GBR
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": 128
            },
            "description": null,
            "carrierServiceCode": "HERMPSSTD_7753_6613",
            "long": -0.113678,
            "optionType": "PUDO",
            "storeName": "Retail 24",
            "shippingCharge": 2.66,
            "lat": 51.522278,
            "delivery": {
                "from": "2020-02-26T08:00:00.000Z",
                "to": "2020-02-29T20:00:59.999Z"
            },
            "address": "Retail 24,  164 GRAYS INN ROAD, KINGS CROSS",
            "carrierServiceName": "ParcelShop Standard\nS07753\nRetail 24\n 164 GRAYS INN ROAD\n\n\nKINGS CROSS\n\nGBR\nWC1X 8ED",
            "postcode": "WC1X 8ED",
            "fullName": "Hermes ParcelShop Standard\nS07753\nRetail 24\n 164 GRAYS INN ROAD\n\n\nKINGS CROSS\n\nGBR\nWC1X 8ED",
            "collection": {
                "from": "2020-02-24T18:30:00.000Z",
                "to": "2020-02-24T19:30:59.999Z"
            },
            "storeId": null,
            "logoUrl": null,
            "storeTimes": {
                "monday": [
                    "07:00-20:00"
                ],
                "tuesday": [
                    "07:00-20:00"
                ],
                "wednesday": [
                    "07:00-20:00"
                ],
                "thursday": [
                    "07:00-20:00"
                ],
                "friday": [
                    "07:00-20:00"
                ],
                "saturday": [
                    "07:00-20:00"
                ],
                "sunday": null
            },
            "carrierCode": "HERMESPOS",
            "hasDisabledAccess": false,
            "bookingCode": "HERMPSSTD_7753_6613/2020-02-24/*-*/*/*-*",
            "cutOffDateTime": "2020-02-24T18: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).