Skip to content

Shipping methods quote

Get shipping methods based on address and package parameters.

Returns methods list for given partner with additional parameters like availability.

POST /v1/shipping-methods/quote

Request example

{
  "orderReferenceId": "EXMPL0001234",
  "currency": "EUR",
  "options": {
    "weightUnit": "g",
    "dimensionUnit": "mm",
    "label": {
      "format": "pdf"
    }
  },
  "partner": {
    "clientName": "ExampleCustomer"
  },
  "receiver": {
    "person": {
      "firstName": "Foo",
      "lastName": "Bar",
      "company": "",
      "email": "[email protected]",
      "phone": "01273552886"
    },
    "address": {
      "country": "GB",
      "state": "East Sussex",
      "city": "Brighton",
      "postcode": "BN1 8YQ",
      "addressLine1": "11 London Rd",
      "addressLine2": "",
      "addressLine3": "",
      "street": "London Rd",
      "houseNumber": "11",
      "suburb": null
    },
    "customs": {
      "vatNumber": null
    }
  },
  "sender": {
    "person": {
      "firstName": "",
      "lastName": "",
      "company": "Example Company",
      "email": "[email protected]",
      "phone": "01666 123456"
    },
    "address": {
      "country": "DE",
      "state": "",
      "city": "Donauwörth",
      "postcode": "86609",
      "addressLine1": "Am Wassergraben 11",
      "addressLine2": null,
      "addressLine3": null,
      "street": "Am Wassergraben",
      "houseNumber": "11",
      "suburb": null
    },
    "customs": {
      "vatNumber": "DE123456789000",
      "iossNumber": null,
      "eoriNumber": "GB987654321000",
      "pcccNumber": null,
      "australianBusinessNumber": null
    }
  },
  "packages": [
    {
      "packageReferenceId": "EXMPL0001234-0-1",
      "grossWeight": 810,
      "netWeight": 760,
      "length": 229,
      "width": 200,
      "height": 36,
      "boxType": "rectangle",
      "volumetricWeight": 700,
      "items": [
        {
          "itemReferenceId": "EXMPL0001234-0-1-ITEM1",
          "description": "Mug",
          "value": 48,
          "quantity": 4,
          "weight": 760,
          "hsCode": "44199090",
          "countryOfOrigin": "DE"
        }
      ]
    }
  ]
}

Success response example

{
  "items": [
    {
      "carrier": {
        "name": "DHL",
        "uid": "dhl"
      },
      "method": {
        "name": "DHL Global Parcel",
        "uid": "dhl_global_parcel",
        "price": 3.32,
        "maxShipmentDays": 5,
        "minShipmentDays": 2,
        "deliveryPaddingDays": 0
      }
    },
    {
      "carrier": {
        "name": "UPS",
        "uid": "ups"
      },
      "method": {
        "name": "UPS Standard Tariff",
        "uid": "ups_standard_tariff",
        "price": 5.25,
        "maxShipmentDays": 5,
        "minShipmentDays": 2,
        "deliveryPaddingDays": 0
      }
    }
  ],
  "count": 2
}

Error response example

{
  "orderReferenceId": "EXMPL0001234",
  "code": "VALIDATION_ERROR",
  "message": "There are errors in submitted data",
  "errors": [
    {
      "code": "NO_SUCH_CHOICE_ERROR",
      "reference": "options.label.format",
      "message": "The value you selected is not a valid choice."
    },
    {
      "code": "IS_BLANK_ERROR",
      "reference": "receiver.address.country",
      "message": "This value should not be blank."
    }
  ]
}

Request

Parameter Type Description
orderReferenceId (required) string Unique ID for shipping order. ID provided by you.
currency (required) string Currency of the shipping order in 3-letter format.
options (optional) Options Optional parameters.
partner (optional) Partner Partner details.
receiver (required) Receiver Receiver details.
sender (required) Sender Sender details.
packages (required) Package[] Package details.

Options

Parameter Type Description
weightUnit (optional) string Unit of weight. Available choices: g, kg, oz, lb. By default: g.
dimensionUnit (optional) string Unit of length. Available choices: mm, cm, in. By default: mm.
label (optional) Label Label format settings.

Label

Parameter Type Description
format (optional) string Label format. Available choices: pdf, zpl (*). By default: pdf.

Note: Formats other than pdf might not be enabled for particular shipping carriers.

Partner

Parameter Type Description
clientName (optional) string Shipping customer profile.
Used for including a brand name on the label (based on the carrier specifications).

Receiver

Parameter Type Description
person (required) ReceiverPerson Personal details of the receiver.
address (required) Address Address details of the receiver.
customs (optional) ReceiverCustoms Customs details of the receiver.

Sender

Parameter Type Description
person (required) SenderPerson Personal details of the sender.
address (required) Address Address details of the sender.
customs (required for international shipping) SenderCustoms Customs details of the sender.

ReceiverPerson

Parameter Type Description
firstName (required) string First name of the receiver person.
lastName (required) string Last name of the receiver person.
company (optional) string The title of the company.
email (optional*) string Email address of the person. This can be used for shipping notifications.
phone (optional*) string Phone number of the person. This can be used for shipping notifications.

Note: *Email and phone can be a required field dependent on shipping carrier

SenderPerson

Parameter Type Description
firstName (optional) string First name of the sender person.
lastName (optional) string Last name of the sender person.
company (required) string The title of the sender company.
email (optional*) string Email address of the sender person / company.
phone (optional*) string Phone number of the sender person / company.

Note: *Email and phone can be a required field dependent on shipping carrier

Address

Parameter Type Description
country (required) string Country code in 2-letter format.
state (optional*) string State / county / region.
city (required) string City.
postcode (required) string Postcode.
addressLine1 (required) string First line of the postal address. Should include street and house number.
addressLine2 (optional) string Second line of the postal address. Apartment / office / floor number.
addressLine3 (optional) string Third line of the postal address.
street (optional*) string Street (required for DE addresses).
houseNumber (optional*) string House number (required for DE addresses).
suburb (optional*) string Suburb (required for AU / NZ addresses).

Note: *These optional fields are required for specific countries and carriers.

ReceiverCustoms

Parameter Type Description
vatNumber (optional) string VAT number of the receiver.

SenderCustoms

Parameter Type Description
vatNumber (optional*) string VAT number of the sender.
iossNumber (optional*) string IOSS number of the sender.
eoriNumber (optional*) string EORI number of the sender.
pcccNumber (optional*) string PCCC number of the sender.
australianBusinessNumber (optional*) string Australian business number of the sender.

Note: *Depending on sender and receiver country, these fields can be required.

Package

Parameter Type Description
packageReferenceId (required) string Partner provided ID of the package.
grossWeight (required) number Packaging weight + items weight (in grams by default).
netWeight (optional) number Weight of the items (in grams by default).
length (required) number Length of package (in mm by default).
width (required) number Width of package (in mm by default).
height (required) number Height of package (in mm by default).
volumetricWeight (optional) number Weight calculated based on the size of the package (in grams by default).
boxType (optional) string Shape of the box (e.g., rectangle, tube).
value (required for international shipping) number Total value of all items in the package (in selected currency).
items (required for international shipping) Item[] Array of items in the package.

Item*

Parameter Type Description
itemReferenceId (required) string Partner provided ID of the package item.
description (required) string Description of the item.
quantity (required) number Quantity of the item.
value (required) number Value of the item (in selected currency).
weight (required) number Weight of the item (in grams by default).
hsCode (required) string Harmonized System Code (Wiki).
countryOfOrigin (required) string Country code in 2-letter format where item was produced.

Note: *All Item parameters required for international shipping only.

Successful response

Parameter Type Description
count number Number of founded results.
items ResponseItems An array of the quotes

ResponseItems

Parameter Type Description
carrier ResponseItemsCarrier Shipping carrier details.
method ResponseItemsMethod Shipping method details.

ResponseItemsCarrier

Parameter Type Description
carrier string Shipping carrier used for order.
uid string Shipping method used for order.

ResponseItemsMethod

Parameter Type Description
name string Shipping method name.
uid string Shipping method UID.
price number Shipping method estimated price for partner.
maxShipmentDays number Shipping method max shipment days.
minShipmentDays number Shipping method min shipment days.
deliveryPaddingDays (optional) number Shipping method delivery padding days.

Error response

Parameter Type Description
orderReferenceId string Unique ID for shipping order provided by you.
code string Error code.
message string Error message.
detail (optional) object Detailed error message (JSON object of an arbitrary structure).
errors (optional) ResponseErrorDetails[] Array of errors.

ResponseErrorDetails

Parameter Type Description
code string Error code.
message string Error message
reference (optional) string Reference ID.