Skip to content

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 structure

Order item statuses

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

Statuses flowchart

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

Product description

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": "[email protected]",
            "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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.

 

Next: Making an Order Quote