Topics

Introduction

The Gelato API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

To make the API as explorable as possible, we have test and live environments. Requests made to the test environment do not incur costs and do not create real orders. Please use the urls below to connect to the test or live environment:

If you have any questions or need help please use our contact page.

Authentication

Before you can use the Gelato API you will need to request an API key from our services team. Please use the contact link above to request a test key. Requests for live API keys are managed through our sales team.

You authenticate your account by including your secret key in all API requests. Your API key carries privileges to create and manage your orders, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

To use your API key, you need to provide it in an X-API-KEY header with each call.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without a valid API key will also fail.

Errors

The Gelato API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an structural or data error in the request (e.g., a required parameter was omitted, shipment prices are not found, etc.). Codes in the 5xx range indicate an error with Gelato's API servers (these are rare).

Error Code	Meaning
200	OK - Everything worked as expected.
400	Bad Request -- The request was unacceptable, often due to missing a required parameter.
401	Unauthorized -- No valid API key provided.
404	Not Found -- The requested resource doesn't exist.
429	Too Many Requests -- Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
502, 503, 504	Server Errors -- Something went wrong on Gelato's API end. (These are rare.).

Order structure

Via the API you provide three mandatory internal order references: customerReferenceId (your customer), orderReferenceId (this order) and itemReferenceId (your product identifier). Each of these parameters must be a numeric value representing your internal entities. To better understand the structure of reference parameters please look at the tree view below.

Order item statuses

Please look at the flowchart below to better understanding the itemReferenceId statuses.

Promise UID

Promise UID example:

{
  "promiseUid": "d_5b2251c890f4f75877b2ae9f"
}

A Promise UID is a reference to the entity that makes a promise about production and shipping of your product to the recipient. To get a promiseUid you need to call the Quote API request. This action does not start the production process but returns information about the location where the production will take place, shipping date estimates, and shipping prices.

To create an order and start the production process you need to call an Order create API request with the promiseUid that was returned from the quote. The Production process will then be initilised for the associated order requested in the Quote API call.

Product UID

Product UID example:

{
  "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver"
  }

The Product UID is a string encapsulating the detail of a product. Please look at the example in the code block. For the Live API, our sales team will agree the range of valid Product UID's associated with your API Key.

Files for print

The most print friendly files are PDF/X. This isn't a file format on its own, but a standard for PDF files that are intended for printers. PDF/X files have rules for colors, embedding of fonts, trim and bleed and cannot contain elements that are unrelated to print.

Please use this link to download a double side A5 format pdf example. This example has a product uid: cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver.

Customer support

Your Gelato sales contact will discuss the best approach for your customers support of print orders. For any issues or technical questions regarding our API, please contact us via our contact page.

Billing

Billing and API usage is currently not available via the API. The Gelato financial team will invoice and reconcile usage as agreed with your sales contact.

Your first order

$ curl -X POST \
   https://api.gelato.com/v2/quote \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{
        "order": {
            "orderReferenceId": "{{MyOrderId}}",
            "customerReferenceId": "{{MyCustomerId}}",
            "currencyIsoCode": "USD"
        },
        "recipient": {
             "countryIsoCode": "US",
             "companyName": "Example",
             "firstName": "Paul",
             "lastName": "Smith",
             "addressLine1": "451 Clarkson Ave",
             "addressLine2": "Brooklyn",
             "stateCode": "NY",
             "city": "New York",
             "postcode": "11203",
             "email": "apisupport@gelato.com",
             "phone": "123456789"
         },
        "products": [
            {
                "itemReferenceId": "{{MyItemId}}",
                "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
                "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
                "quantity": 100
            }
        ]
    }'

$ curl -X POST \
   https://api.gelato.com/v2/order/create \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{"promiseUid": "{{promiseUid}}"}'

<?php

function request($url, $data, $headers)
{
    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => $data,
        CURLOPT_HTTPHEADER => $headers,
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
        die("cURL Error #:" . $err);
    } else {
        return $response;
    }
}

# === Define headers ===
$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

# === Set-up quote request ===
$quoteUrl = "https://api.gelato.com/v2/quote";
$quoteJson = '{
  "order": {
      "orderReferenceId": "{{MyOrderId}}",
      "customerReferenceId": "{{MyCustomerId}}",
      "currencyIsoCode": "EUR"
  },
  "recipient": {
      "countryIsoCode": "US",
      "companyName": "Example",
      "firstName": "Paul",
      "lastName": "Smith",
      "addressLine1": "451 Clarkson Ave",
      "addressLine2": "Brooklyn",
      "stateCode": "NY",
      "city": "New York",
      "postcode": "11203",
      "email": "apisupport@gelato.com",
      "phone": "123456789"
  },
  "products": [
      {
          "itemReferenceId": "{{MyItemId}}",
          "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
          "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
          "quantity": 100
      }
  ]
}';

# === Send quote request ===
$response = request($quoteUrl, $quoteJson, $headers);
$quoteData = json_decode($response);


# === Set-up order create request ===
$promiseUid = $quoteData->production->shipments[0]->promiseUid;
$orderCreateUrl = "https://api.gelato.com/v2/order/create";
$orderCreateJson = '{
    "promiseUid": "'.$promiseUid.'"
}';

# === Send order create request ===
$response = request($orderCreateUrl, $orderCreateJson, $headers);
$orderCreateData = json_decode($response);

echo $orderCreateData->message;

import requests

# === Define headers ===
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

# === Set-up quote request ===
quoteUrl = "https://api.gelato.com/v2/quote"
quoteJson = """{
   "order": {
       "orderReferenceId": "{{MyOrderId}}",
       "customerReferenceId": "{{MyCustomerId}}",
       "currencyIsoCode": "USD"
   },
   "recipient": {
       "countryIsoCode": "US",
       "companyName": "Example",
       "firstName": "Paul",
       "lastName": "Smith",
       "addressLine1": "451 Clarkson Ave",
       "addressLine2": "Brooklyn",
       "stateCode": "NY",
       "city": "New York",
       "postcode": "11203",
       "email": "apisupport@gelato.com",
       "phone": "123456789"
   },
   "products": [
       {
           "itemReferenceId": "{{MyItemId}}",
           "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
           "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
           "quantity": 100
       }
   ]
}"""

# === Send quote request ===
response = requests.request("POST", quoteUrl, data=quoteJson, headers=headers)
quoteData = response.json()

# === Set-up order create request ===
promiseUid = quoteData['production']['shipments'][0]['promiseUid']
orderCreateUrl = "https://api.gelato.com/v2/order/create"
orderCreateJson = """{
    "promiseUid": "%s"
}""" % promiseUid

# === Send order create request ===
response = requests.request("POST", orderCreateUrl, data=orderCreateJson, headers=headers)
print(response.json())

let request = require('request');

// === Define headers ===
let headers = {
    'Content-Type' : 'application/json',
    'X-API-KEY' : '{{apiKey}}'
};

// === Set-up quote request ===
let quoteUrl = 'https://api.gelato.com/v2/quote';
let quoteJson = {
   "order": {
       "orderReferenceId": "{{MyOrderId}}",
       "customerReferenceId": "{{MyCustomerId}}",
       "currencyIsoCode": "USD"
   },
   "recipient": {
       "countryIsoCode": "US",
       "companyName": "Example",
       "firstName": "Paul",
       "lastName": "Smith",
       "addressLine1": "451 Clarkson Ave",
       "addressLine2": "Brooklyn",
       "stateCode": "NY",
       "city": "New York",
       "postcode": "11203",
       "email": "apisupport@gelato.com",
       "phone": "123456789"
   },
   "products": [
       {
           "itemReferenceId": "{{MyItemId}}",
           "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
           "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
           "quantity": 100
       }
   ]
};

// === Send quote request ===
request.post({
    url:        quoteUrl,
    headers:    headers,
    body:       JSON.stringify(quoteJson)
}, function(error, response, body){
    // === Set-up order create request ===
    let data = JSON.parse(body);
    let promiseUid = data.production.shipments[0].promiseUid;
    let orderCreateUrl = 'https://api.gelato.com/v2/order/create';
    let orderCreateJson = {
        "promiseUid": "" + promiseUid + ""
    };

    // === Send order create request ===
    request.post({
        url:        orderCreateUrl,
        headers:    headers,
        body:       JSON.stringify(orderCreateJson)
    }, function(error, response, body){
        console.log(body);
    });
});

The easiest way to start integrating with the Gelato API is to send a Quote API request, select one of the Promise UID returned and then send us an Order create API request, that's all. Please look at the example on the code tab.

Then you can use Cancel order API or Status order API to manage your order.

API Reference

Quote API

$ curl -X POST \
   https://api.gelato.com/v2/quote \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{
        "order": {
            "orderReferenceId": "{{MyOrderId}}",
            "customerReferenceId": "{{MyCustomerId}}",
            "currencyIsoCode": "USD"
        },
        "recipient": {
             "countryIsoCode": "US",
             "companyName": "Example",
             "firstName": "Paul",
             "lastName": "Smith",
             "addressLine1": "451 Clarkson Ave",
             "addressLine2": "Brooklyn",
             "stateCode": "NY",
             "city": "New York",
             "postcode": "11203",
             "email": "apisupport@gelato.com",
             "phone": "123456789"
         },
        "products": [
            {
                "itemReferenceId": "{{MyItemId1}}",
                "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
                "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
                "quantity": 100
            },
            {
                "itemReferenceId": "{{MyItemId2}}",
                "productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
                "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_5R_4-4_hor_none.pdf",
                "quantity": 30,
                "options": [
                    {
                        "type": "envelope",
                        "productUid": "blank-envelopes_pf_a7-env_pt_120-g-env",
                        "quantity": 40 
                    }
                ]
            }
        ]
    }'

<?php

$url = "https://api.gelato.com/v2/quote";

$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

$requestJson = '{
        "order": {
            "orderReferenceId": "{{MyOrderId}}",
            "customerReferenceId": "{{MyCustomerId}}",
            "currencyIsoCode": "USD"
        },
        "recipient": {
             "countryIsoCode": "US",
             "companyName": "Example",
             "firstName": "Paul",
             "lastName": "Smith",
             "addressLine1": "451 Clarkson Ave",
             "addressLine2": "Brooklyn",
             "stateCode": "NY",
             "city": "New York",
             "postcode": "11203",
             "email": "apisupport@gelato.com",
             "phone": "123456789"
         },
        "products": [
            {
                "itemReferenceId": "{{MyItemId1}}",
                "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
                "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
                "quantity": 100
            },
            {
                "itemReferenceId": "{{MyItemId2}}",
                "productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
                "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_5R_4-4_hor_none.pdf",
                "quantity": 30,
                "options": [
                    {
                        "type": "envelope",
                        "productUid": "blank-envelopes_pf_a7-env_pt_120-g-env",
                        "quantity": 40 
                    }
                ]
            }
        ]
    }';

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $requestJson,
    CURLOPT_HTTPHEADER => $headers,
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/quote"

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

requestJson = """{
     "order": {
         "orderReferenceId": "{{MyOrderId}}",
         "customerReferenceId": "{{MyCustomerId}}",
         "currencyIsoCode": "USD"
     },
     "recipient": {
          "countryIsoCode": "US",
          "companyName": "Example",
          "firstName": "Paul",
          "lastName": "Smith",
          "addressLine1": "451 Clarkson Ave",
          "addressLine2": "Brooklyn",
          "stateCode": "NY",
          "city": "New York",
          "postcode": "11203",
          "email": "apisupport@gelato.com",
          "phone": "123456789"
      },
     "products": [
         {
             "itemReferenceId": "{{MyItemId1}}",
             "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
             "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
             "quantity": 100
         },
         {
             "itemReferenceId": "{{MyItemId2}}",
             "productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
             "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_5R_4-4_hor_none.pdf",
             "quantity": 30,
             "options": [
                 {
                     "type": "envelope",
                     "productUid": "blank-envelopes_pf_a7-env_pt_120-g-env",
                     "quantity": 40 
                 }
             ]
         }
     ]
}"""

response = requests.request("POST", url, data=requestJson, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/quote';
let headers = {
    'Content-Type' : 'application/json',
    'X-API-KEY' : '{{apiKey}}'
};
let requestJson = {
    "order": {
       "orderReferenceId": "{{MyOrderId}}",
       "customerReferenceId": "{{MyCustomerId}}",
       "currencyIsoCode": "USD"
    },
    "recipient": {
        "countryIsoCode": "US",
        "companyName": "Example",
        "firstName": "Paul",
        "lastName": "Smith",
        "addressLine1": "451 Clarkson Ave",
        "addressLine2": "Brooklyn",
        "stateCode": "NY",
        "city": "New York",
        "postcode": "11203",
        "email": "apisupport@gelato.com",
        "phone": "123456789"
    },
    "products": [
        {
           "itemReferenceId": "{{MyItemId1}}",
           "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
           "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_BX_4-4_hor_none.pdf",
           "quantity": 100
        },
        {
            "itemReferenceId": "{{MyItemId2}}",
            "productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
            "pdfUrl": "https://s3-eu-west-1.amazonaws.com/developers.gelato.com/product-examples/test_print_job_5R_4-4_hor_none.pdf",
            "quantity": 30,
            "options": [
                {
                   "type": "envelope",
                   "productUid": "blank-envelopes_pf_a7-env_pt_120-g-env",
                   "quantity": 40 
                }
            ]
        }
    ]
};

request.post({
    url:        url,
    headers:    headers,
    body:       JSON.stringify(requestJson)
}, function(error, response, body){
    console.log(body);
});

Response example:

{
    "orderReferenceId": "{{MyOrderId}}",
    "production": {
        "itemReferenceId": [
            "{{MyItemId1}}",
            "{{MyItemId2}}"
        ],
        "productionCountry": "US",
        "productionTimeZone": "America/Chicago",
        "shipments": [
            {
                "promiseUid": "d_5d5f9f7b5faf183b4504cfbc",
                "name": "UPS Surepost",
                "uid": "ups_surepost",
                "price": 7.29,
                "minDeliveryDays": 6,
                "maxDeliveryDays": 7,
                "minDeliveryDate": "2019-08-29",
                "maxDeliveryDate": "2019-08-30",
                "serviceType": "normal",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            },
            {
                "promiseUid": "d_5d5f9f7b5faf183b456df752",
                "name": "UPS Ground Commercial",
                "uid": "ups_ground_commercial",
                "price": 6.61,
                "minDeliveryDays": 5,
                "maxDeliveryDays": 6,
                "minDeliveryDate": "2019-08-28",
                "maxDeliveryDate": "2019-08-29",
                "serviceType": "normal",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            },
            {
                "promiseUid": "d_5d5f9f7b5faf183b45c6b7b0",
                "name": "UPS Next Day Commercial",
                "uid": "ups_next_day_commercial",
                "price": 28.25,
                "minDeliveryDays": 4,
                "maxDeliveryDays": 4,
                "minDeliveryDate": "2019-08-27",
                "maxDeliveryDate": "2019-08-27",
                "serviceType": "express",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            }
        ]
    }
}

Use the Quote API to get the list of shipping options and Promise UIDs for your product.

HTTP Request

POST https://api.gelato.com/v2/quote

Query Parameters

OrderObject parameters

RecipientObject parameters

ProductObject parameters

Product options

Product options is used to specify additional product attributes or for adding non-printed product additions (such as envelopes). The parameter type must be specified to define the product option category. Currently only envelope is supported as a valid type option.

Use the envelope option to add blank envelopes to product

{
    "type": "envelope",
    "productUid": "blank-envelopes_pf_c6_pt_145-g-env-white",
    "quantity": 40
}

Response Parameters

ProductionObject parameters

ShippingObject parameters

Response Messages

Error response example:

{
  "message": "Currency 'DES' is not supported."
}

Order create API

$ curl -X POST \
   https://api.gelato.com/v2/order/create \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{"promiseUid": "{{promise_uid}}"}'

<?php

$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

$url = "https://api.gelato.com/v2/order/create";
$requestJson = '{
    "promiseUid": "{{promiseUid}}"
}';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $requestJson,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

orderCreateUrl = "https://api.gelato.com/v2/order/create"
orderCreateJson = """{
    "promiseUid": "{{promiseUid}}"
}"""

response = requests.request("POST", orderCreateUrl, data=orderCreateJson, headers=headers)
print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/order/create';
let headers = {
    'Content-Type' : 'application/json',
    'X-API-KEY' : '{{apiKey}}'
};
let requestJson = {
    "promiseUid": "{{promiseUid}}"
};

request.post({
    url:        url,
    headers:    headers,
    body:       JSON.stringify(requestJson)
}, function(error, response, body){
    console.log(body);
});

Response example:

{
  "message": "Promise Uid is accepted for processing"
}

Use the Order create API to start the production and shipping process against your Promise UID returned from the Quote API.

HTTP Request

POST https://api.gelato.com/v2/order/create

Query Parameters

Response Parameters

Response Messages

Error response example:

{
  "message": "Invalid request body."
}

Order status API

$ curl -X GET \
   https://api.gelato.com/v2/order/status/{{MyOrderId}} \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}'

<?php

$url = "https://api.gelato.com/v2/order/status/{{MyOrderId}}";

$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/order/status/{{MyOrderId}}"

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/order/status/{{MyOrderId}}';
let headers = {
    'Content-Type' : `application/json`,
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

{
  "orderReferenceId": "{{MyOrderId}}",
  "orderItems": [
      {
        "itemReferenceId": "{{MyItemId1}}",
        "status": "passed",
        "trackingCode": [
          {
            "parcelNumber": 1,
            "trackingCode": "",
            "trackingUrl": ""
          }
        ],
        "productionLog": [
          {
            "date": "2018-06-14T11:30:33+00:00",
            "printJobId": 1000077008,
            "message": "PdfToolbox - Uploaded original pdf to s3"
          },
          {
            "date": "2018-06-14T11:30:32+00:00",
            "printJobId": 1000077008,
            "message": "PrintJob created"
          }
        ]
      },
      {
        "itemReferenceId": "{{MyItemId2}}",
        "status": "shipped",
        "trackingCode": [
          {
            "parcelNumber": 1,
            "trackingCode": "1234567890",
            "trackingUrl": "https://example.com/search?piececode=1234567890"
          }
        ],
        "productionLog": [
          {
            "date": "2018-06-14T11:30:33+00:00",
            "printJobId": 1000078008,
            "message": "PdfToolbox - Uploaded original pdf to s3"
          },
          {
            "date": "2018-06-14T11:30:32+00:00",
            "printJobId": 1000078008,
            "message": "PrintJob created"
          },
         {
           "date": "2018-06-15T11:30:32+00:00",
           "printJobId": 1000078008,
           "message": "The package is shipped"
         }
        ]
      }
  ]
}

Use the Order status API to get the order details about status, production log or tracking information. Please note: Order creation is internally queued and therefore there can be a small delay (typically 1-3 seconds) between the order placement call and the Order status API being able to return a meaningful status.

HTTP Request

GET https://api.gelato.com/v2/order/status/{{orderReferenceId}}

Query Parameters

Response Parameters

OrderItemObject parameters

TrackingCodeObject parameters

ProductionLogObject parameters

Response Messages

Error response example:

{
  "message": "Order not found."
}

Address get API

$ curl -X GET \
   https://api.gelato.com/v2/order/{{MyOrderId}}/address \
   -H 'X-API-KEY: {{apiKey}}'

<?php

$url = "https://api.gelato.com/v2/order/{{MyOrderId}}/address";

$headers = [
    "X-API-KEY: {{apiKey}}"
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/order/{{MyOrderId}}/address"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/order/{{MyOrderId}}/address';
let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

{
    "id": "d6bcf17f-3a48-4ec8-888e-70766ae8b56a",
    "countryIsoCode": "US",
    "firstName": "Paul",
    "lastName": "Smith",
    "companyName": "Example",
    "addressLine1": "451 Clarkson Ave",
    "addressLine2": "Brooklyn",
    "city": "New York",
    "postcode": "11203",
    "stateCode": "NY",
    "email": "apisupport@gelato.com",
    "phone": "123456789"
}

HTTP Request

GET https://api.gelato.com/v2/order/{{orderReferenceId}}/address

Query Parameters

Response Parameters

Response data represented by RecipientObject. This is the same object as in Quote API request.

Response Messages

Error response example:

{
  "message": "Order not found."
}

Address update API

$ curl -X PUT \
    https://api.gelato.com/v2/order/{{MyOrderId}}/address \
    -H 'Accept: */*' \
    -H 'Content-Type: application/json' \
    -H 'X-API-KEY: {{apiKey}}' \
    -d '{
      "countryIsoCode": "US",
      "companyName": "Example",
      "firstName": "Paul",
      "lastName": "Smith",
      "addressLine1": "451 Clarkson Ave",
      "addressLine2": "Brooklyn",
      "stateCode": "NY",
      "city": "New York",
      "postcode": "11203",
      "email": "apisupport@gelato.com",
      "phone": "123456789"
  }'

<?php

$url = "https://api.gelato.com/v2/order/{{MyOrderId}}/address";

$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

$requestJson = '{
      "countryIsoCode": "US",
      "companyName": "Example",
      "firstName": "Paul",
      "lastName": "Smith",
      "addressLine1": "451 Clarkson Ave",
      "addressLine2": "Brooklyn",
      "stateCode": "NY",
      "city": "New York",
      "postcode": "11203",
      "email": "apisupport@gelato.com",
      "phone": "123456789"
  }';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS => $requestJson,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/order/{{MyOrderId}}/address"

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

requestJson = """{
   "countryIsoCode": "US",
   "companyName": "Example",
   "firstName": "Paul",
   "lastName": "Smith",
   "addressLine1": "451 Clarkson Ave",
   "addressLine2": "Brooklyn",
   "stateCode": "NY",
   "city": "New York",
   "postcode": "11203",
   "email": "apisupport@gelato.com",
   "phone": "123456789"
}"""

response = requests.request("PUT", url, data=requestJson, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/order/{{MyOrderId}}/address';
let headers = {
    'Content-Type' : 'application/json',
    'X-API-KEY' : '{{apiKey}}'
};
let requestJson = {
    "countryIsoCode": "US",
    "companyName": "Example",
    "firstName": "Paul",
    "lastName": "Smith",
    "addressLine1": "451 Clarkson Ave",
    "addressLine2": "Brooklyn",
    "stateCode": "NY",
    "city": "New York",
    "postcode": "11203",
    "email": "apisupport@gelato.com",
    "phone": "123456789"
};

request.put({
    url:        url,
    headers:    headers,
    body:       JSON.stringify(requestJson)
}, function(error, response, body){
    console.log(body);
});

Response example:

{
    "id": "d6bcf17f-3a48-4ec8-888e-70766ae8b56a",
    "countryIsoCode": "US",
    "firstName": "Paul",
    "lastName": "Smith",
    "companyName": "Example",
    "addressLine1": "451 Clarkson Ave",
    "addressLine2": "Brooklyn",
    "city": "New York",
    "postcode": "11203",
    "stateCode": "NY",
    "email": "apisupport@gelato.com",
    "phone": "123456789"
}

Use the Change order address API to update delivery address details. Please note: if the order has moved to status shipped the order address can't be changed.

HTTP Request

PUT https://api.gelato.com/v2/order/{{MyOrderId}}/address

Request and Response data

Request and response data represented by RecipientObject. This is the same object as in Quote request

Response Messages

Error response: Country change attempt rejected

{
    "message": "Address can't be updated",
    "details": [
        {
            "message": "Country change isn't allowed",
            "reference": "countryIsoCode"
        }
    ]
}

Error response: Deep address validation failed

{
    "message": "Address is incorrect",
    "details": [
        {
            "message": "The value is not a valid postcode. Please use 5 digits without whitespaces",
            "reference": null
        }
    ]
}

Error response: Simple address validation failed

{
    "message": "Request object contain errors!",
    "details": [
        {
            "message": "This value should not be blank.",
            "reference": "firstName"
        },
        {
            "message": "This value should not be blank.",
            "reference": "lastName"
        }
    ]
}

Error response: Order not found

{
    "message": "Order not found",
    "details": []
}

Cancel order API

$ curl -X POST \
   https://api.gelato.com/v2/order/cancel \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{"orderReferenceId": "{{MyOrderId}}"}'

<?php

$url = "https://api.gelato.com/v2/order/cancel";

$headers = [
    "Content-Type: application/json",
    "X-API-KEY: {{apiKey}}"
];

$requestJson = '{
  "orderReferenceId" : "{{MyOrderId}}"
}';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $requestJson,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/order/cancel"

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{{apiKey}}'
}

requestJson = """{
    "orderReferenceId" : "{{MyOrderId}}"
}"""

response = requests.request("POST", url, data=requestJson, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/order/cancel';
let headers = {
    'Content-Type' : 'application/json',
    'X-API-KEY' : '{{apiKey}}'
};
let requestJson = {
    "orderReferenceId": "{{MyOrderId}}"
};

request.post({
    url:        url,
    headers:    headers,
    body:       JSON.stringify(requestJson)
}, function(error, response, body){
    console.log(body);
});

Response example:

{
  "message" : "The order {{orderReferenceId}} canceled"
}

Use the Cancel order API to stop the production and shipment process. Please note: if the order has moved to status printed or shipped the order can't be canceled, please review the Order item statuses flowchart.

HTTP Request

POST https://api.gelato.com/v2/order/cancel

Query Parameters

Response Parameters

Response Messages

Error response example:

{
  "message": "Order not found."
}

Catalogue get API

$ curl -X GET \
    https://api.gelato.com/v2/catalogues/default \
    -H 'X-API-KEY: {{apiKey}}'

<?php

$url = 'https://api.gelato.com/v2/catalogues/default';

$headers = [
    'X-API-KEY: {{apiKey}}'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/catalogues/default"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/catalogues/default';
let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

{
    "id": "e848ac36-1350-4527-a80e-0ee0c3913bc2",
    "title": "Default catalogue",
    "alias": "default",
    "clientId": null,
    "rootNodeId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138",
    "isPublic": true,
    "status": "enabled",
    "createdAt": "2019-08-27T19:58:56+00:00",
    "updatedAt": "2019-08-27T19:58:56+00:00"
}

Use the Catalogue get API to getting info about the catalogue.

Note: We have the public catalogue with alias default which available for all clients.

HTTP Request

GET https://api.gelato.com/v2/catalogues/{{catalogueId|catalogueAlias}}

Query Parameters

Response Parameters

Response Messages

Error response example:

{
  "message": "Catalogue not found."
}

Catalogue nodes get API

$ curl -X GET \
    https://api.gelato.com/v2/catalogues/default/nodes \
    -H 'X-API-KEY: {{apiKey}}'

<?php

$url = 'https://api.gelato.com/v2/catalogues/default/nodes';

$headers = [
    'X-API-KEY: {{apiKey}}'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/catalogues/default/nodes"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/catalogues/default/nodes';
let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

[
    {
        "id": "929c12ca-1004-4118-adb3-60d726f69718",
        "title": "Business Cards",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "d36dd041-dee6-4d5b-8f2b-3a18976245d1",
        "title": "Roll ups",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "9cb92a98-1401-4aa7-a179-a6305ebdc45a",
        "title": "Calendars",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "bdaf1b21-56fe-4c69-9948-48415ed39d45",
        "title": "Folders",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "6d8c6cd6-5a43-4865-8176-1ed6459bd579",
        "title": "Flyers",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "74205fd5-988e-415c-a735-b099b5a60803",
        "title": "Letterheads",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "abe0b2f9-a258-4553-84e6-81154aaa6a42",
        "title": "Brochures",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "aa7bb863-ae0f-4f81-880a-bd940db425a3",
        "title": "Posters",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "3f9765fc-b03d-44fd-8ad5-76971eb85d3d",
        "title": "Test Category",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "aaded6f4-9e6a-4d9a-b534-bca648a0f5b0",
        "title": "Cards",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    },
    {
        "id": "39b19e7a-77f2-474a-b9cd-5e8cab4c48da",
        "title": "Notebooks",
        "parentId": "25a47b2c-bf8b-4d14-bb03-50e95dff7138"
    }
]

Use the Catalogue node get API to getting nodes in the catalogue.

Note: We have the public catalogue with alias default which available for all clients.

HTTP Request

GET https://api.gelato.com/v2/catalogues/{{catalogueId|catalogueAlias}}/nodes

Query Parameters

Response Parameters

Response data represented by an array of CatalogueNode object with these params

Response Messages

Error response example:

{
  "message": "Catalogue not found."
}

Catalogue sub-nodes get API

$ export NODE_ID='929c12ca-1004-4118-adb3-60d726f69718' && \ 
   curl -X GET "https://api.gelato.com/v2/catalogues/default/nodes/${NODE_ID}/subnodes" \
    -H 'X-API-KEY: {{apiKey}}'

<?php

$nodeId = '929c12ca-1004-4118-adb3-60d726f69718';
$url = "https://api.gelato.com/v2/catalogues/default/nodes/{$nodeId}/products";

$headers = [
    'X-API-KEY: {{apiKey}}'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

nodeId = '929c12ca-1004-4118-adb3-60d726f69718'
url = "https://api.gelato.com/v2/catalogues/default/nodes/" + nodeId + "/subnodes"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let nodeId = '929c12ca-1004-4118-adb3-60d726f69718';
let url = 'https://api.gelato.com/v2/catalogues/default/nodes/' + nodeId + '/subnodes';
let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

[
    {
        "id": "0e7576ba-a842-4f90-872e-8ecc276c0db9",
        "title": "Single-sided",
        "parentId": "929c12ca-1004-4118-adb3-60d726f69718"
    },
    {
        "id": "1e2e8f0d-1dfb-4419-a607-6f6353e8ec45",
        "title": "Double-sided",
        "parentId": "929c12ca-1004-4118-adb3-60d726f69718"
    }
]

Use the Catalogue sub-nodes get API to getting children nodes in the catalogue.

Note: We have the public catalogue with alias default which available for all clients.

HTTP Request

GET https://api.gelato.com/v2/catalogues/{{catalogueId|catalogueAlias}}/nodes/{{nodeId}}/subnodes

Query Parameters

Response Parameters

Response data represented by an array of CatalogueNode object similar to Catalogue nodes get API

Response Messages

Error response example: Catalogue not found

{
  "message": "Catalogue not found"
}

Error response example: Node doesn't exist in the catalogue

{
  "message": "This node not exists in the catalogue"
}

Catalogue products get API

$ export NODE_ID='929c12ca-1004-4118-adb3-60d726f69718' && \ 
   curl -X GET "https://api.gelato.com/v2/catalogues/default/nodes/${NODE_ID}/products" \
    -H 'X-API-KEY: {{apiKey}}'

<?php

$nodeId = '929c12ca-1004-4118-adb3-60d726f69718';
$url = "https://api.gelato.com/v2/catalogues/default/nodes/{$nodeId}/products";

$headers = [
    'X-API-KEY: {{apiKey}}'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

nodeId = '929c12ca-1004-4118-adb3-60d726f69718';
url = "https://api.gelato.com/v2/catalogues/default/nodes/" + nodeId + "/products"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let nodeId = '929c12ca-1004-4118-adb3-60d726f69718';
let url = 'https://api.gelato.com/v2/catalogues/default/nodes/' + nodeId + '/products';
let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

[
    {
        "id": "cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor",
        "modelId": "flat_product"
    },
    {
        "id": "cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-4_hor",
        "modelId": "flat_product"
    },
    {
        "id": "cards_pf_bb_pt_130-lb-cover-uncoated_cl_4-0_hor",
        "modelId": "flat_product"
    },
    {
        "id": "cards_pf_bb_pt_130-lb-cover-uncoated_cl_4-4_hor",
        "modelId": "flat_product"
    },
    {
        "id": "cards_pf_bb_pt_300-gsm-uncoated_cl_4-0_hor",
        "modelId": "flat_product"
    }
]

Use the Catalogue products get API to getting products list in catalogue nodes.

Note: We have the public catalogue with alias default which available for all clients.

HTTP Request

GET https://api.gelato.com/v2/catalogues/{{catalogueId|catalogueAlias}}/nodes/{{nodeId}}/products?limit={{limit}}&offset={{offset}}

Query Parameters

Response Parameters

Response data represented by an array of Product object

Response Messages

Error response example: Catalogue not found

{
  "message": "Catalogue not found"
}

Error response example: Node doesn't exist in the catalogue

{
  "message": "This node not exists in the catalogue"
}

Product info get API

$ curl -X GET "https://api.gelato.com/v2/products/cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor" \
    -H 'X-API-KEY: {{apiKey}}'

<?php

$url = 'https://api.gelato.com/v2/products/cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor';

$headers = [
    'X-API-KEY: {{apiKey}}'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

import requests

url = "https://api.gelato.com/v2/products/cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor"

headers = {
    'X-API-KEY': '{{apiKey}}'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

let request = require('request');

let url = 'https://api.gelato.com/v2/products/cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor';

let headers = {
    'X-API-KEY' : '{{apiKey}}'
};

request.get({
    url:        url,
    headers:    headers
}, function(error, response, body){
    console.log(body);
});

Response example:

{
    "id": "cards_pf_bb_pt_110-lb-cover-uncoated_cl_4-0_hor",
    "modelId": "flat_product",
    "attributes": [
        {
            "key": "PaperFormat",
            "value": "BB"
        },
        {
            "key": "ColorType",
            "value": "4-0"
        },
        {
            "key": "SpotFinishingType",
            "value": "none"
        },
        {
            "key": "Variable",
            "value": "no"
        },
        {
            "key": "ProductStatus",
            "value": "activated"
        },
        {
            "key": "PaperType",
            "value": "110-lb-cover-uncoated"
        },
        {
            "key": "Orientation",
            "value": "hor"
        },
        {
            "key": "ProtectionType",
            "value": "none"
        },
        {
            "key": "CoatingType",
            "value": "none"
        },
        {
            "key": "ShapeEdgeType",
            "value": "none"
        }
    ],
    "weight": {
        "value": 1.341,
        "measureUnit": "grams"
    },
    "supportedCountries": [
        "US",
        "CA"
    ],
    "notSupportedCountries": [
        "BD",
        "BM",
        "BR",
        "AI",
        "DO",
        "IS"
    ]
}

Use the Product info get API to getting product details.

HTTP Request

GET https://api.gelato.com/v2/products/{{productId}}

Query Parameters

Response Parameters

AttributeObject parameters

WeightObject parameters

Response Messages

Error response example: Product not found

{
  "message": "This product does not exist"
}

Webhooks

Overview

The Gelato API can be configured to send webhook events to notify your application any time an event happens on your order.
The Gelato API sends the Event object, via an HTTP POST request, to any endpoint URLs that you have provided us.
The Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Please contact us to configure your account with a webhook URL.

Webhook URL

Your Webhook URL endpoint must be RESTful. All calls must be implemented as HTTP post and with TLS encrypted. The HTTP response code 2xx is expected on positive calls, all other response codes will be considered as error.

Request data

All events will be posted as JSON objects to your Webhook URL endpoint. The documentation for each webhook request is described below.

Response data

No response content is expected, any content will be ignored.

Retries

Webhooks will try to send the request data 3 times, with 5 seconds delay between each try, if an HTTP status 2xx is not returned.

Event objects

Item status

The webhook triggers when the status of an item has changed. This is a useful event to track information about your item, including notification if the item has been printed or some error has occured.

Item status object example:

{
  "id": "is_5b6403bd3cf1f",
  "object": "itemStatus",
  "itemReferenceId": "{{MyItemId}}",
  "status": "passed",
  "comment": "",
  "created": "2018-08-03T07:26:52+00:00"
}

Object parameters

Tracking code

When the item is shipped, this event provides information about the tracking code and the shipping provider.

Tracking code object example:

{
  "id": "tc_5b6403bd3cf2e",
  "object": "trackingCode",
  "itemReferenceId": "{{MyItemId}}",
  "trackingCode": "code123",
  "trackingUrl": "http://example.com/tracking?code=code123",
  "carrierName":"DHL Express Domestic BR",
  "carrierUid":"dhl_express_domestic_br",
  "productionCountry":"BR",
  "productionStateProvinceCode":"SP",
  "created": "2018-08-03T12:11:30+00:00"
}

Object parameters