[GCL] Logistics API - Shipping Order Create | GelatoConnect

Shipping order create API is a RESTful API that allows you to create an order for shipping to generate a shipping label and tracking code for a package.

POST /v1/shipping-orders

Request example

{
  "orderReferenceId": "EXMPL0001234",
  "currency": "EUR",
  "options": {
    "weightUnit": "g",
    "dimensionUnit": "mm",
    "label": {
      "format": "pdf"
    }
  },
  "partner": {
    "clientName": "ExampleCustomer"
  },
  "shippingMethod": {
    "uid": "",
    "carrier": "",
    "tier": "standard"
  },
  "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": 18.42,
          "quantity": 4,
          "weight": 760,
          "hsCode": "44199090",
          "countryOfOrigin": "DE"
        }
      ]
    }
  ]
}

Successful response example

{
  "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b",
  "orderReferenceId": "EXMPL0001234",
  "shippingMethod": {
    "carrier": "UPS",
    "uid": "ups_standard_tariff"
  },
  "packages": [
    {
      "packageReferenceId": "EXMPL0001234-0-1",
      "trackingNumber": "EXMPL0001234TRCKNUM",
      "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST",
      "label": {
        "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",
        "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",
        "contentType": "application/pdf"
      },
      "documents": [
        {
          "documentType": "invoice",
          "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",
          "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",
          "contentType": "application/pdf"
        }
      ],
      "totalCost": {
        "value": 2.56,
        "currency": "EUR"
      }
    }
  ]
}

Error response example

{
  "orderReferenceId": "EXMPL0001234",
  "code": "PUBLIC_API_ERROR",
  "message": "Processing error",
  "detail": {
    "code": "UPS_API_ERROR",
    "message": {
      "status": {
        "title": "Bad Request",
        "status": 400,
        "detail": "0 of 1 shipment successfully created.",
        "statusCode": 400
      },
      "items": [
        {
          "sstatus": {
            "title": "Bad Request",
            "status": 400,
            "statusCode": 400
          },
          "validationMessages": [
            {
              "property": "packages[0].items[0].hsCode",
              "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.",
              "validationState": "Error"
            }
          ]
        }
      ]
    }
  },
  "errors": [
    {
      "code": "IS_BLANK_ERROR",
      "reference": "receiver.address.country",
      "message": "This value should not be blank."
    },
    {
      "code": "IS_BLANK_ERROR",
      "reference": "receiver.address.city",
      "message": "This value should not be blank."
    },
    {
      "code": "MISSING_FIELD_ERROR",
      "reference": "packages[EXMPL0001234-0-1][length]",
      "message": "This field is missing."
    }
  ]
}

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.
shippingMethod (required)	ShippingMethod	Shipping method 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).

ShippingMethod

Parameter	Type	Description
uid (optional)*	string	To be used for a specific shipping method, e.g amazon_shipping_24.
carrier (optional)	string	Shipping carrier name, e.g Amazon, DHL
tier (required)*	string	Shipping option tier. Available choices: standard, express. `standard` tier should be used when we select the `cheapest` shipping method for you `express` tier should be used when we select the `fastest` shipping method for you

Note: *Use tier for Gelato's optimized carrier selection. If you use tier, leave uid empty, and vice versa.

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
orderId	string	Unique ID for shipping order in our system.
orderReferenceId	string	Unique ID for shipping order provided by you.
shippingMethod	ResponseShippingMethod	Shipping method used for the shipping order.
packages	ResponsePackage[]	Packages used for the shipping order.

ResponseShippingMethod

Parameter	Type	Description
carrier	string	Shipping carrier used to create an order.
uid	string	Shipping method uid used to create an order.

ResponsePackage

Parameter	Type	Description
packageReferenceId	string	Partner provided ID of the package.
trackingNumber	string	Tracking number provided by the shipping carrier.
trackingUrl	string	Tracking URL provided by the shipping carrier.
label	ResponseLabel	Shipping label for the shipping order.
documents (optional)	ResponseDocument[]	Documents for the shipping order.
totalCost (optional)	ResponseTotalCost	Estimated cost of shipping the package.

ResponseLabel

Parameter	Type	Description
fileName	string	File name of the label.
fileUrl	string	URL to download the label.
contentType	string	Content type of the label.

ResponseDocument

Parameter	Type	Description
documentType	string	Document type (e.g. invoice).
fileName	string	File name of the document.
fileUrl	string	URL to download the document.
contentType	string	Content type of the document.

ResponseTotalCost

Parameter	Type	Description
value (optional)	number	Estimated cost of shipping the package. (optional)
currency (optional)	string	Currency

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 - Shipping Order Create Draft

📝 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 Draft

[GCL] Logistics API - Shipping Methods Quote

[GCL] Logistics API - Tracking