Extended Parameters

Please find below the parameters that can be passed by a Delivery Options API call, in addition to the Basic Parameters.

The more parameters you define, the more relevant the options returned are likely to be to the consumer.

Note

The parameters do not have to be supplied in the order given below. They can be in any order, provided that they are separated using the & character.

Recipient address details

The postcode c_pc or latitude/longitude c_lat/c_long normally constitute sufficient address details to return valid delivery options, but you can add the following consumer address details to return even more accurate results:

  • c_li

    The first line of the consumer's address.

  • c_l2

    The second line of the consumer's address.

  • c_l3

    The third line of the consumer's address.

  • c_l4

    The fourth line of the consumer's address.

For example:

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_cc=NLD&c_pc=1083 HN&optionType=HOME&r_t=lsc&c_l1=Barbara Strozzilaan 999&c_l2= Postbus 75047

Alternative sender (warehouse) details

If the package is being delivered from a warehouse other than the one associated with wh_code, you can enter the parameters detailed below.

Note

You still need to specify wh_code as this determines the carrier network to be used by the API call.

  • wh_cc

    The ISO 3166 alpha-3 three-letter country code of the warehouse from which the consignment is to be despatched,

  • wh_pc

    The postal code of the warehouse from which the consignment is to be despatched,

  • wh_l1

    The first line of the address of the warehouse from which the consignment is to be despatched.

  • wh_l2

    The second line of the address of the warehouse from which the consignment is to be despatched.

  • wh_l3

    The third line of the address of the warehouse from which the consignment is to be despatched.

  • wh_l4

    The fourth line of the address of the warehouse from which the consignment is to be despatched.

For example:

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_cc=NLD&c_pc=1083 HN&optionType=HOME&r_t=lsc&c_l1=Barbara Strozzilaan 999&c_l2= Postbus 75047&wh_cc=GBR&wh_pc=SL1 1LE&wh_l1=The Observatory&wh_l2=Slough

Known consignment and parcel values

These values all have valid defaults that will allow the API to return valid delivery options. However, you should pay particular attention to the consignmentLevelDetailsFlag.

  • cod_amount

    You can use this parameter to specify the amount of cash on delivery that the returned options need to be able to handle. It is expressed as a double precision floating point number, and the default is 0.0, which indicates that the consignment is not cash on delivery.

  • cod_currency

    The currency of any cash on delivery amounts, e.g. EUR.

  • consignmentLevelDetailsFlag

    This is a flag that indicates whether or not information is held at the consignment level. In order to enter parcel values, it needs to be set to false (as opposed to the default true).

    This then allows you to specify the following parcel values to limit the returned options to those that can handle parcels of the specified depth, height and width (in centimetres), and specified weight (in kilograms):

    • parcelDepth

    • parcelHeight

    • parcelWeight

    • parcelWidth

    Note

    You can also specify the values for multiple parcels, in conjunction with e_n.

  • hazmat_codes

    If the consignment contains any hazardous goods, supply a list of comma-separated hazardous goods codes.

For example:

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_cc=NLD&c_pc=1083 HN&optionType=HOME&r_t=lsc&c_l1=Barbara Strozzilaan 999&c_l2= Postbus 75047&wh_cc=GBR&wh_pc=SL1 1LE&wh_l1=The Observatory&wh_l2=Slough&cod_amount=2&cod_currency=EUR&consignmentLevelDetailsFlag=false&e_n=2&parcelHeight=10,11&parcelWeight=21,22&hazmat_codes=9

Estimated values

Wherever possible, it is advisable to estimate the number of parcels, the consignment weight and value, and the maximum parcel weight and longest parcel dimension.

If you do not know the number of parcels and/or consignment weight, then using the average calculations mentioned below is the recommended course of action.

  • e_n

    The estimated number of parcels. The number of parcels can affect which carriers are selectable. For example, some carriers will not allow more than 30 parcels to be placed on a single order. The number of parcels can also have a direct retail cost, and so an estimate of the number of parcels required to ship a consignment is important. As a rough guide, if you know the approximate sizes of the items to be shipped, and the sizes of the parcels that are used, you can estimate the number of parcels using an 'average number of items per parcel'.

  • e_w

    The estimated weight (in kg) of the entire consignment (i.e. the sum of all the parcel weights), expressed as a double precision floating point number. The default is 0.01.

    The total weight can also affect your costs and the available carriers. If you know the actual weights of the items, you can work out the total weight. However, this is also just an estimate as packing materials (such as padding), and the boxes themselves, also affect the total shipping weight. Where the weights are completely unknown, you can apply the 'average total consignment weight' to all orders.

  • e_maxdim

    The estimated length of the longest dimension of the largest parcel, expressed as an integer in cm. The default is '0' (i.e. the dimension is not taken into account when options are returned).

  • e_maxweight

    The estimated weight (in kg) of the heaviest parcel, expressed as a double precision floating point number. The default is 0.00 (i.e. the weight is not taken into account when options are returned).

  • e_v

    The estimated consignment value, expressed as a double precision floating point number. Where provided, this value is split equally across all parcels. For example, if e_v is 10.0 and e_n is 4, then a value of 2.5 is assigned to each parcel.

  • e_v_currency

    The currency of the estimated consignment value, e.g. EUR.

For example:

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&c_cc=NLD&c_pc=1083 HN&optionType=HOME&r_t=lsc&c_l1=Barbara Strozzilaan 999&c_l2= Postbus 75047&wh_cc=GBR&wh_pc=SL1 1LE&wh_l1=The Observatory&wh_l2=Slough&consignmentLevelDetailsFlag=false&e_n=2&parcelHeight=10,11&parcelWeight=21,22&e_w=25&e_maxdim=25&e_maxweight=22&e_v=5000&e_v_currency=EUR

Filtering

These parameters serve to restrict the number of delivery options returned, If insufficient options are being returned, then consider increasing the radius (if returning options for delivery to PUDOs or your own stores), or specifying minown (if returning options just for delivery to your own stores).

  • acceptableCollectionSlots

    Two timestamps to mark the acceptable collection window, separated by a comma.

    Note

    For the construction of dates, times and overall timestamps, refer to Introduction to Booking Codes.

  • acceptableDeliverySlots

    Two timestamps to mark the acceptable delivery window, separated by a comma.

  • excgrp

    Comma-separated list of carrier 'service groups' to exclude - i.e. services in these groups are not considered, even if they can fulfil the needs demanded by the other parameters.

  • incgrp

    Comma-separated list of carrier 'service groups' to include - i.e. only the services in these groups are considered (provided that they can fulfil the needs demanded by the other parameters).

    Note

    If a carrier service is in more than one carrier 'service group', then, each time that service is selected, it will cause the associated group to appear. So, it is possible that you will see 'service groups' that you have opted to include, appear more than once in the response.

  • limit

    The maximum number of options to be returned.

    Caution

    This does not apply to own stores if the minown and/or maxown parameter is set.

  • minown

    The minimum number of your own stores to be returned as collection points. If the required minimum are not available within the radius, then the search will extend beyond it.

  • maxown

    The maximum number of 'Click and Collect' stores that can be returned within the radius. The default is 100.

  • radius

    For a PUDO or Ownstore search, this defines the search radius from the point specified by the c_lat/c_long or c_pc. It is specified in metres, and the default is 1000.

For example:

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&wh_code=SL123&optionType=PUDO&r_t=lsc&c_lat=51.474316&c_long=-0.278015&acceptableCollectionSlots=2020-09-28,2020-09-29&acceptableDeliverySlots=2020-09-30,2020-10-01&incgrp=NEXT&minown=1&radius=750

Cross-border deliveries

This option allow you to return PUDO or Ownstore options from a country across the border from the country where the package is being delivered.

  • multiCountry

    When set to true, this flag causes options to be returned from countries that border the one specified using the c_cc parameter. The default is false.

For example, if you wish to return options for delivery to an address in Maastricht, but include PUDO and 'Click and Collect' options across the borders in Belgium and Germany, then you would set multiCountry to true. You would also set c_cc to NLD, set c_lat/c_long to be that for Maastricht, set an appropriate search radius, and set c_pc to be the postal code of the Dutch HOME delivery address in Maastricht, e.g.

GET https://dmo.metapack.com/dmoptions/find?key=<API-Key>&c_cc=NLD&wh_code=SL123&c_pc=4202 MS&&c_lat=50.851368&c_long= 5.690973&r_t=lsc&radius=38000&multiCountry=true