[GCL] Logistics API - Shipping Methods Quote | GelatoConnect

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.

Next Step: 🔗[GCL] Logistics API - Tracking

📝 Not what you needed?

Help us improve this article, send us an email to [email protected] — please include the article title.

[Order Intake - GCW] Order Management API Documentation

[GCL] Logistics API - Overview

[GCL] Logistics API - Shipping Order Create

[GCL] Logistics API - Shipping Order Create Draft

[GCL] Logistics API - Tracking