Basic Parameters

The Delivery Options API requires a minimum set of parameters to be passed, in order to return valid and meaningful delivery options. These are listed in the table below,

Note

For the other possible parameters that can be passed, refer to Extended Parameters.

Table 1. Minimum required parameters

Query parameter

Description

Format

Default (where applicable)

Notes

key

The API key provided by Metapack.

string

Refer to Configuring your Security.

wh_code

The required warehouse code as set up in Delivery Manager (refer to Configuring Shipping and Allocation), to identify the required carrier configurations.

code

Your Order Management System or equivalent service must determine the required warehouse. Failure to specify a warehouse will result in an empty response.

c_pc

The postal code of the delivery location.

If you are presenting delivery options prior to final checkout, i.e. before the consumer has entered the required delivery address, you can use a default postcode. For the purposes of estimation, this should, if possible, be a small town postcode, rather than one in a large city or the middle of the countryside.

string

If you are delivering to a single location, you would typically specify either c_lat/c_long or c_pc. However, you might use both when delivering to a HOME address but with PUDO and/or OWNSTORE 'Click and Collect' options.

In this case, c_lat/c_long is used for PUDO/OWNSTORE lookup and c_pc is used for HOME delivery. Refer to the example below.

In order to guarantee a consistent PUDO/OWNSTORE lookup when both c_lat/c_long and c_pc are provided, c_lat/c_long should represent the coordinates of c_pc.

c_lat and c_long

c_lat is the latitude coordinate of the search point for the delivery location, whilst c_long is the longitude coordinate.

double precision floating point number

c_cc

The ISO 3166 alpha-3 three-letter country code of the delivery address.

This filters out couriers who cannot deliver to the specified country, although it is not strictly necessary if you are delivering to a specific latitude/longitude and/or postcode that does not cross borders.

string

GBR

If you are going to be delivering across borders, then you should set c_cc as the country for the main delivery address, and set multiCountry to true.

For example, if you wish to return options for delivery to the south of The Netherlands, but include PUDO and 'Click and Collect' options across the borders in Belgium and Germany, then set c_cc to NLD and multiCountry to true.

You should use c_lat/c_long for the cross-border Belgian/German PUDO/OWNSTORE lookup, and c_pc for the postal code of the Dutch HOME delivery address.

optionType

This determines the delivery type(s) for which options are returned: HOME (for home deliveries), PUDO (for deliveries to pickup/drop off points), and/or OWNSTORE (for 'Click and Collect').

string

All types

if specifying more than one optionType, use a comma-separated list, e.g. PUDO,OWNSTORE.

r_t

This stands for 'return type'.

Specify the appropriate three-letter code, from the following:

  • lgg - Returns the cheapest next available delivery option for each carrier 'service group'. 

  • lsc - Returns the next available delivery option for each carrier service.

  • ggg - Returns the cheapest delivery option for each carrier 'service group', for the next 20 days.

  • gsc - Returns the delivery options for each carrier service, for the next 20 days.

code

Where a code starts with 'l', it signifies List, and where it starts with 'g', it signifies Grid.

The second letter distinguishes between carrier 'service groups' ('g'), and carrier services ('s'). A 'service group' is a collection of services (e.g. 'Next Day'), and a service is an individual carrier service belonging to a group (e.g. 'Royal Mail 1st Class' within 'Next Day').

The 'cheapest' service is based on cost (as paid by you, the retailer, to the carrier). The shipping charges are also returned by the API, so that they can be displayed to the end consumer.

Note

If a carrier service is in more than carrier 'service group', then, each time that service is selected, it will cause the associated group to appear. So, in queries returned by lgg and ggg, you may see 'service groups' appear more than once.