Skip to content

Shipping order create

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.