Metapack logo

Metapack Delivery Options API (1.0.0)

Download OpenAPI specification:Download

URL: https://www.metapack.com/ License: Apache 2.0

The Delivery Options API is an easy-to-use REST-based API that enables you to display relevant delivery choices to shoppers browsing your eCommerce websites. It works by checking which services can fulfil a shopper’s order and by which date. It determines which carriers are enabled for your Metapack shipper account, carrier availability, routing times, and whether a carrier service be used for a shipment's weights and dimensions. It also checks the operating times of your warehouses.

The results can then be displayed on your product details and checkout pages. This ensures that you show shoppers only carrier services that can fulfil their orders and display accurate delivery dates that you can meet. The API integrates with the Metapack SOAP Shipping API and Metapack Delivery Manager, which means that your eCommerce websites reflect automatically all your shipping configuration, such as carriers, carrier services, and allocation rules.

For more information about the API, go to https://help.metapack.com/.

Search for delivery options

Retrieve all delivery options that meet specific search criteria.

Request
query Parameters
wh_code
required
string

This is the code of a warehouse (shipping location) configured for your Metapack shipper account. For more information, see Configuring Shipping and Allocation.

Example: wh_code=SL123
wh_pc
string
Default: "EC1R 4PF"

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

Example: wh_pc=SL1 A23
wh_cc
string
Default: "GBR"

The three-letter ISO country code of the address of the warehouse from which the consignment is to be despatched.

Example: wh_cc=GBR
wh_l1
string
Default: "DEFAULT"

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

Example: wh_l1=Building 5
wh_l2
string
Default: "DEFAULT"

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

Example: wh_l2=50 Bell Road
wh_l3
string
Default: "DEFAULT"

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

Example: wh_l3=Westminster
wh_l4
string
Default: "DEFAULT"

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

Example: wh_l4=London
key
required
string <uuid>

Your API key (in UUID format). It is provided by Metapack Support and is generated automatically after your Metapack shipper account is created. It ensures that only the details associated with your shipper account are used to return delivery options. For more information, see Configuring your Security.

Example: key=03b2a318-bdf6-49a3-97c4-868ae039de04
c_lat
number <double> [ -90 .. 90 ]

The latitude coordinate of the delivery address. This is the distance of a place north or south of the equator, measured in degrees.

If this parameter is provided, the corresponding longitude c_long must also be provided. You can specify either c_pc or c_lat/c_long. When both c_lat/c_long and c_pc are provided,c_lat/c_long will be used for PUDO/OWNSTORE lookup and c_pc will be used for HOME delivery. To guarantee a consistent PUDO/OWNSTORE lookup when both c_lat/c_long and c_pc are provided, the c_lat/c_long coordinates should represent the c_pc.

Example: c_lat=51.5072
c_long
number <double> [ -180 .. 180 ]

The longitude coordinate of the delivery address. This is the distance of a place east or west of the Greenwich meridian, measured in degrees.

If this parameter is provided, the corresponding latitude c_lat must also be provided. You can specify either c_pc or c_lat/c_long. When both c_lat/c_long and c_pc are provided,c_lat/c_long will be used for PUDO/OWNSTORE lookup and c_pc will be used for HOME delivery. To guarantee a consistent PUDO/OWNSTORE lookup when both c_lat/c_long and c_pc are provided, the c_lat/c_long coordinates should represent the c_pc.

Example: c_long=0.1276
c_pc
string

The postal code of the delivery address (if supported).

When both c_lat/c_long and c_pc are provided, c_lat/c_long will be used for PUDO/OWNSTORE lookup and c_pc will be used for HOME delivery. To guarantee a consistent PUDO/OWNSTORE lookup when both c_lat/c_long and c_pc are provided, c_lat/c_long coordinates should represent the c_pc.

Example: c_pc=L1 7AA
c_cc
required
string

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

Example: c_cc=GBR
c_address_type
string

The address type of the delivery address.

Enum: "BUSINESS" "RESIDENTIAL"
Example: c_address_type=RESIDENTIAL
c_l1
string
Default: "DEFAULT"

The first line of an unstructured delivery address.

Example: c_l1=Flat 5
c_l2
string
Default: "DEFAULT"

The second line of an unstructured delivery address.

Example: c_l2=50 Bell Road
c_l3
string
Default: "DEFAULT"

The third line of an unstructured delivery address.

Example: c_l3=Westminster
c_l4
string
Default: "DEFAULT"

The fourth line of an unstructured delivery address.

Example: c_l4=London
consignmentLevelDetailsFlag
boolean
Default: true

This parameter indicates whether order information is held at consignment level. By default, the value of this parameter is set to true. However, by setting the value of this parameter to false, you can limit the returned options to only those that can handle parcels of the specified parcelDepth, parcelHeight, parcelWidth (in centimetres or inches), and parcelWeight (in kilograms or pounds).

Note: The value of this parameter also affects how the e_maxweight, e_maxdim and e_n parameters work.

e_maxdim
integer
Default: 0

The estimated maximum dimensions of the largest parcel in the order, expressed as an integer in centimetres. The default value is 0, which means that the dimensions are not taken into account when delivery options are returned.

Note: By default, this parameter uses the metric system. If you want to use the imperial system for this parameter, you will need to include the query string parameter dimensions_unit=in in your request.

Example: e_maxdim=12
e_maxweight
number <float>
Default: 0

The weight of the heaviest parcel in the order, expressed as a decimal. The default value is 0, which means that the weight is not taken into account when delivery options are returned. If this weight value is provided and the consignmentLevelDetailsFlag parameter is set to true, the first parcel will be set as the heaviest and the remainder of the consignment weight will be split equally across all remaining parcels.

For example, if the e_w parameter is set to 40.0 and the e_maxweight parameter is set to 20 and the e_n parameter is to 5, the first parcel will have a weight of 20 and the remaining four parcels will each have a weight value of five.

Note: The value of the e_maxweight parameter must be less than or equal to the value of the e_w parameter and greater than or equal to the value of the e_w and e_n parameters.

Note: By default, this parameter uses the metric system. If you want to use the imperial system for this parameter, you will need to include the query string parameter weight_unit= lb in your request.

Example: e_maxweight=3
dimensions_unit
string
Default: "CM"

The units used to measure the outer edges of a parcel or a consignment. The Metapack Platform supports both imperial units and the metric system. The default is metric (cm or CM), so you must specify dimension units only if you are using imperial units (in or IN) for shipping.

Enum: "CM" "cm" "IN" "in"
weight_unit
string
Default: "KG"

The volumetric/mass measurement unit of a parcel or consignment. The Metapack Platform supports both imperial units and the metric system. The default is metric (kg or KG), so you must specify weight units only if you are using imperial units (lb or LB) for shipping.

Enum: "KG" "kg" "lb" "LB"
e_n
integer
Default: 1

If possible, estimate the number of parcels because parcel quantity can determine which carriers are selectable.

Note: Some carriers might not allow multi-parcel consignments.

Example: e_n=3
e_w
number <float>
Default: 0.01

The estimated weight (in kilograms) of the entire consignment (the sum of all of the parcel weights), expressed as a double precision floating point number. The total weight can affect your costs and the available carriers. If provided, the value of this parameter will be split equally across all parcels.

Note: By default, this parameter uses the metric system. If you want to use the imperial system for this parameter, you will need to include the query string parameter weight_unit= lb in your request.

Example: e_w=0.02
e_v
number <float>

The estimated monetary value (in estimatedParcelValueCurrency units) of the entire consignment. If provided, the value of this parameter will be split equally across all parcels.

For example, if the value of this parameter is set to 10.0 and the value of the estimatedNoOfParcel parameter is set to 4, a monetary value of 2.5 currency units will be assigned to each parcel.

Example: e_v=2.5
e_v_currency
string

The three-letter ISO currency code of the currency used by the estimatedParcelValue parameter.

Example: e_v_currency=EUR
parcelHeight
Array of numbers <double>

The height of each parcel in the consignment, expressed as a decimal. Enter a comma-separated list of single precision floating point numbers. The measurement unit is determined by the value of the dimension_unit parameter.

Note: The consignmentLevelDetailsFlag parameter should be set to false when giving individual parcel details.

Note: The number of elements in the list must be equal to the value of the e_n parameter.

Example: parcelHeight=1,2.5,1
parcelWeight
Array of numbers <double>

The weight of each parcel in the consignment, expressed as a decimal. Enter a comma-separated list of single precision floating point numbers. The measurement unit is determined by the value of the weight_unit parameter.

Note: The consignmentLevelDetailsFlag parameter should be set to false when giving individual parcel details.

Note: The number of elements in the list must be equal to the value of the e_n parameter.

Example: parcelWeight=1,2.2,1.1
parcelDepth
Array of numbers <double>

The depth (or length) of each parcel in the consignment, expressed as a decimal. Enter a comma-separated list of single precision floating point numbers. The measurement unit is determined by the value of the dimension_unit parameter.

Note: The consignmentLevelDetailsFlag parameter should be set to false when giving individual parcel details.

Note: The number of elements in the list must be equal to the value of the e_n parameter.

Example: parcelDepth=0.3,2.1,1.6
parcelWidth
Array of numbers <double>

The width of each parcel in the consignment, expressed as a decimal. Enter a comma-separated list of single precision floating point numbers. The measurement unit is determined by the value of the dimension_unit parameter.

Note: The consignmentLevelDetailsFlag parameter should be set to false when giving individual parcel details.

Note: The number of elements in the list must be equal to the value of the e_n parameter.

Example: parcelWidth=1.3,2.2,1
cod_amount
number <double>
Default: 0

The cash on delivery monetary amount (in cashOnDeliveryCurrency units) of the consignment, if applicable. The default value is 0, which means that the specified consignment will not require payment at the time of delivery.

cod_currency
string

The three-letter ISO currency code of the currency used by the cashOnDeliveryAmount parameter.

Example: cod_currency=EUR
hazmat_codes
Array of strings

Enter a comma-separated list of hazard codes for any parcel items in the consignment, if applicable.

Note: You can use the hazardous goods classification that best meets your needs, such as UN codes.

Example: hazmat_codes=1090
skus
string

A stock-keeping unit (SKU) is an internal identifier used by the shipping location (warehouse) for each product (trade item) in a parcel. Enter a list of SKUs for the consignment. Use semicolons to separate parcel groups and commas to separate products in the same parcel.

Note: You cannot use this parameter if you want to use any of the following parameters: e_maxdim, e_maxweight, e_n, e_w, parcelHeight, parcelWidth, parcelDepth, parcelWeight.

Example: skus=x,y;z
limit
integer >= 1

Use this parameter to limit the number of delivery options returned.

Note: You cannot use this parameter if the value of the deliveryOptionType parameter is set to OWNSTORE or if values are provided for the minown or maxown parameters.

Example: limit=10
Array of PUDO (strings) or Array of HOME (strings) or Array of OWNSTORE (strings)

Use this parameter to determine the delivery type(s) for which options are returned. If specifying more than one delivery type, use a comma-separated list. If no values are specified for this parameter, delivery options for HOME,PUDO, and OWNSTORE are returned.

Example: optionType=HOME,PUDO,OWNSTORE
multiCountry
boolean
Default: false

If set to true, this parameter enables you to return PUDO or OWNSTORE delivery options from countries that border the country specified by the c_cc parameter. By default, the value of this parameter is set to false.

For example, if you want to return options for delivery to an address in The Netherlands and include PUDO and “click and collect” options in Belgium and Germany, set the value of this parameter to true.

radius
integer [ 1 .. 100000 ]
Default: 1000

For a PUDO or OWNSTORE search, this parameter defines the search radius from the point specified by the c_lat/c_long or c_pc parameters. The value of this parameter is expressed in metres.

minown
integer [ 1 .. 20 ]

The minimum number of your own “click and collect” stores to be returned as collection points.

Note: If the minimum number is not available within the area specified by the locationRadius parameter, the search for delivery options will extend beyond it.

Example: minown=1
maxown
integer [ 1 .. 50 ]
Default: 50

The maximum number of your own “click and collect” stores to be returned as collection points.

lgg (string) or lsc (string) or lsd (string) or lss (string) or gas (string) or ggg (string) or gsc (string) or gss (string)

The three letter code of a return type. If a code starts with l, it signifies list. If a code starts with g, it signifies grid. The second letter of a code distinguishes between carrier service groups (g) and carrier services (s).

The cheapest service is based on cost (paid by the shipper to the carrier). If a carrier service is in more than one carrier service group, each time that that service is selected will cause the associated group to appear. For example, in lgg and ggg queries, you might see service groups appear more than once in the response.

Note: If you omit this parameter from a request, delivery options will be returned based on the default Metapack Platform allocation hierarchy as follows:

  • Prioritised service. This will be used if one has been selected automatically by using carrier allocation rules.
  • Shipping cost. The Metapack Platform will always try and select the cheapest service if there is no prioritised carrier service.
  • Earliest despatch. If two services cost the same, the one that leaves the warehouse first will be chosen.
  • Earliest delivery. If two carrier services cost the same and leave the warehouse at the same time, the one that can deliver first is selected.
    • Enum: "lgg" "lsc" "lss" "lsd" "gas" "ggg" "gsc" "gss"
    Example: r_t=lgg
    incgrp
    Array of strings

    Enter a comma-separated list of carrier service groups to include in the search for delivery options. Only carrier services in these groups will be considered provided if they satisfy other parameters in the request. By default, all carrier services associated with your Metapack shipper account are considered. For more information, see Creating your Carrier 'Service Groups’.

    Example: incgrp=STANDARD,RETURNS
    excgrp
    Array of strings

    Enter a comma-separated list of carrier service groups to exclude from the search for delivery options. Carrier services in these groups will not be considered even if they satisfy other parameters in the request. By default, all carrier services associated with your Metapack shipper account are considered. For more information, see Creating your Carrier 'Service Groups’.

    Example: excgrp=26000156,RETURNS,TRANSFER
    acceptableCollectionSlots
    Array of strings <date-time> <= 2 items

    The date range within which collection is acceptable or possible. To specify the collection window, enter two timestamps separated by a comma.

    Example: acceptableCollectionSlots=2022-04-05 00:00:00,2022-04-11 23:59:59
    acceptableDeliverySlots
    Array of strings <date-time> <= 2 items

    The date range within which delivery is possible. To specify the delivery window, enter two timestamps separated by a comma.

    Example: acceptableDeliverySlots=2022-04-05 00:00:00,2022-04-11 23:59:59
    custom1
    string

    You can use this parameter to specify a value that can be subsequently retrieved and used in one or more custom allocation rules in Metapack Delivery Manager.

    For more information, see Creating your own Allocation Rules.

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom1=example1
    custom2
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom2=example2
    custom3
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom3=example3
    custom4
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom4=example4
    custom5
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom5=example5
    custom6
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom6=example6
    custom7
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom7=example7
    custom8
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom8=example8
    custom9
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom9=example9
    custom10
    string

    You can use this parameter to specify a value for use in a custom allocation rule (defined in Delivery Manager).

    Note: The maximum number of custom parameters that can be included in a request is 10.

    Example: custom10=example10
    header Parameters
    traceId
    string <uuid>

    Identifier (in UUID format) to trace an individual request in the Metapack Platform. If provided, it will be returned as requestId in a 200 response.

    Example: 2bd19526-7abb-42b5-ad53-77c4d94af0df
    Responses
    200

    List of possible delivery options that satisfies find search criteria

    400

    Bad Request

    401

    Unauthorized

    500

    Internal Server Error

    502

    Bad Gateway

    503

    Service Unavailable

    504

    Gateway Timeout

    get/find
    Request samples 
    Response samples 
    application/json
    {
    • "header": {
      },
    • "results": [
      ]
    }