Get started
Order structure
Via the API you provide three mandatory internal order references: customerReferenceId (your customer), orderReferenceId (this order) and itemReferenceId (your order item identifier). Each of these parameters must be a string or 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 understand 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. The response describes where products will be produced and the different shipping options that are available to deliver to the shipping address with estimated delivery times and prices. The promise expires after 24 hours, then a new quote needs to be done.
To create an order and start the production process you need to call the 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.
Files for print
Depending on the product we support different types of files. - For products with one print areas, such as Posters, Framed Posters, Canvas, Acrylic, Metallic, Mugs, we support: JPEG, PNG and PDF. - For products with more than one print area, such as photo books, greeting cards, calendars, we support multi-page PDFs.
Note
The parameter in Quote is called pdfUrl, however it still accepts JPEG and PNG for products with one print area still.
PDF details
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.
Read more about files and how to create print-ready PDFs
Your first order
The easiest way to start is to send an order quote request, select one of the Promise UIDs returned and then create the order, that's it. The order is now placed and will be printed and shipped.
Examples
$ 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);
});
});
You can setup notifications to get updates on the order as it is printed, shipped and delivered. You can also cancel the order and check status of the orders easily.