NAV Navbar

curl PHP Python Node
Topics
  • Introduction
  • Authentication
  • Errors
  • Order structure
  • Order item statuses
  • Promise UID
  • Product UID
  • Files for print
  • Customer support
  • Billing
  • Your first order
  • API Reference
  • Quote API
  • Order create API
  • Order status API
  • Cancel order API
  • Webhooks
  • Overview
  • Event objects
  • 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:

    Environment URL
    test https://api-test.gelato.com
    live https://api.gelato.com

    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.
    500, 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.

    Please note: in the V1 API version only one itemReferenceId can be placed per orderReferenceId.

    Order structure

    Order item statuses

    Please look at the flowchart below to better understanding 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. 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.

    Product description

    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/v1/quote \
       -H 'Content-Type: application/json' \
       -H 'X-API-KEY: <apiKey>' \
       -d '{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.pdf",
            "quantity": 100
        }
     }'
    
    $ curl -X POST \
       https://api.gelato.com/v1/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/v1/quote";
    $quoteJson = '{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.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/v1/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/v1/quote"
    quoteJson = """{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.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/v1/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/v1/quote';
    let quoteJson = {
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.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/v1/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/v1/quote \
       -H 'Content-Type: application/json' \
       -H 'X-API-KEY: <apiKey>' \
       -d '{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.pdf",
            "quantity": 100
        }
     }'
    
    <?php
    
    $url = "https://api.gelato.com/v1/quote";
    
    $headers = [
        "Content-Type: application/json",
        "X-API-KEY: <apiKey>"
    ];
    
    $requestJson = '{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.pdf",
            "quantity": 100
        }
    }';
    
    $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/v1/quote"
    
    headers = {
        'Content-Type': 'application/json',
        'X-API-KEY': '<apiKey>'
    }
    
    requestJson = """{
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.pdf",
            "quantity": 100
        }
    }"""
    
    response = requests.request("POST", url, data=requestJson, headers=headers)
    
    print(response.json())
    
    let request = require('request');
    
    let url = 'https://api.gelato.com/v1/quote';
    let headers = {
        'Content-Type' : 'application/json',
        'X-API-KEY' : '<apiKey>'
    };
    let requestJson = {
        "order": {
            "orderReferenceId": <MyOrderId>,
            "customerReferenceId": <MyCustomerId>,
            "currencyIsoCode": "EUR"
        },
        "recipient": {
            "countryIsoCode": "EE",
            "firstName": "Vitalii",
            "lastName": "Tkachov",
            "addressLine1": "Tornimae 7-50",
            "addressLine2": "",
            "city": "Tallinn",
            "postcode": "10154",
            "email": "vitaliy@gelato.com",
            "phone": "+3721234567"
        },
        "product": {
            "itemReferenceId": <MyItemId>,
            "productUid": "cards_pf_a5_pt_350-gsm-coated-silk_cl_4-4_ver",
            "pdfUrl": "http://example.com/print_job.pdf",
            "quantity": 100
        }
    };
    
    request.post({
        url:        url,
        headers:    headers,
        body:       JSON.stringify(requestJson)
    }, function(error, response, body){
        console.log(body);
    });
    

    Response example:

    {
        "orderReferenceId": <MyOrderId>,
        "production": {
            "itemReferenceId": <MyItemId>,
            "productionCountry": "SE",
            "productionTimeZone": "Europe/Stockholm",
            "shipments": [
                {
                    "promiseUid": "d_5b2251c890f4f75877b2ae9f",
                    "name": "PostenSE Priority Letter",
                    "price": 7.02,
                    "minDeliveryDays": 4,
                    "maxDeliveryDays": 6,
                    "minDeliveryDate": "2018-06-18",
                    "maxDeliveryDate": "2018-06-20",
                    "serviceType": "normal",
                    "methodType": "both",
                    "totalWeight": 1088,
                    "numberOfParcels": 1,
                    "promiseExpirationDateTime": "2018-06-15T11:30:16+00:00"
                },
                {
                    "promiseUid": "d_5b2251c890f4f75877e27e0d",
                    "name": "PostenSE Private Parcel",
                    "price": 7.36,
                    "minDeliveryDays": 4,
                    "maxDeliveryDays": 5,
                    "minDeliveryDate": "2018-06-18",
                    "maxDeliveryDate": "2018-06-19",
                    "serviceType": "normal",
                    "methodType": "private",
                    "totalWeight": 1088,
                    "numberOfParcels": 1,
                    "promiseExpirationDateTime": "2018-06-15T11:30:16+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/v1/quote

    Query Parameters

    Parameter Type Description
    order (required) OrderObject Order details.
    recipient (required) RecipientObject Recipient address information.
    product (required) ProductObject Product information. In the V1 API version you may only provide one product per order.

    OrderObject parameters

    Parameter Type Description
    customerReferenceId (required) integer Reference to your internal customer id.
    orderReferenceId (required) integer Reference to your internal order id.
    currencyIsoCode (required) string Currency iso code in ISO_4217 standard. Shipping prices will be converted to the currency specified here.
    Pattern: ^[A-Z]{3}$

    RecipientObject parameters

    Parameter Type Description
    countryIsoCode (required) string The two-character ISO 3166-1 code that identifies the country or region. Please note: the country code for Great Britain is GB and not UK as used in the top-level domain names for that country.
    Pattern: ^[A-Z]{2}$
    firstName (required) string The first name of the recipient at this address.
    Maximum length is 25 characters
    lastName (required) string The last name of the recipient at this address.
    Maximum length is 25 characters
    addressLine1 (required) string The first line of the address. For example, number, street, and so on.
    Maximum length is 35 characters
    addressLine2 (optional) string The second line of the address. For example, suite or apartment number.
    Maximum length is 35 characters
    city (required) string The city name.
    Maximum length is 30 characters
    postcode (required) string The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
    Maximum length is 15 characters
    stateCode (optional) string The code for a US state or the equivalent for other countries. Required for requests if the address is in one of these countries: Brazil, India, Chile, Australia, Great Britain or United States. In case of Great Britain country, the state code means county.
    Maximum length is 35 characters
    email (required) string The email address for the recipient.
    Pattern: ^.+@[^"-].+$
    phone (optional) string The phone number, in E.123 format.
    Maximum length is 25 characters

    ProductObject parameters

    Parameter Type Description
    itemReferenceId (required) integer Reference to your internal item id.
    productUid (required) string Type of printing product in product uid format.
    pdfUrl (required) string Url to the product pdf file. The preference is to provide the pdf file in one of the compatible PDF/X standards, for example in PDF/X-1a:2003 or PDF/X-4 standard.
    quantity (required) integer The product quantity. Define how many copies of product should be printed. The minimum value is 1

    Response Parameters

    Parameter Type Description
    orderReferenceId integer Reference to your internal order id.
    production ProductionObject Production information with shipment options.

    ProductionObject parameters

    Parameter Type Description
    itemReferenceId integer Reference to your internal item id.
    productionCountry string The two-character ISO 3166-1 code that identifies the production country that will produce the product.
    productionTimeZone string Production location time zone in ISO_8601 standard.
    shipments ShippingObject[] List of available shipping options.

    ShippingObject parameters

    Parameter Type Description
    promiseUid integer The promise uid is unique for each shipping option. This value should be used for the Order create API.
    name string Shipment method name.
    price float Shipping price in the currency as provided in order.currencyIsoCode parameter.
    minDeliveryDays integer Minimum days estimate to produce and deliver the product.
    maxDeliveryDays integer Maximum days estimate to produce and deliver the product.
    minDeliveryDate string Minimum date estimate to produce and deliver the product.
    maxDeliveryDate string Maximum date estimate to produce and deliver the product
    serviceType string Shipping service type. Can be: normal, express or pallet.
    methodType string Shipping methods type. Can be: private, business or both.
    totalWeight integer Total weight of the product in grams, including the weight of the parcel.
    numberOfParcels integer Count of shipping parcels. Depending on the product type and quantity ordered, the product might be split into parcels if a weight of the product exceeds the available weight or size for the shipping method.
    promiseExpirationDateTime string Date and time in ISO-8601 format when the Promise UID will be expired and can not be used anymore.

    Response Messages

    Error response example:

    {
      "message": "Currency 'DES' is not supported."
    }
    
    HTTP Status Code Message
    400 Invalid request body.
    400 Product UID: "cards_pf_a0_pt_350-gsm-coated-silk_cl_4-4_ver" does not exists.
    404 Currency 'DES' is not supported.
    404 Country 'FF' is not supported.
    404 Delivery to the specdified destination is not possible. Please check the recipient address.
    404 One of the product is not supported for the specified destination.

    Order create API

    $ curl -X POST \
       https://api.gelato.com/v1/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/v1/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/v1/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/v1/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/v1/order/create

    Query Parameters

    Parameter Type Description
    promiseUid (required) string One of promiseUid from the Quote API response.
    Pattern: ^d_[a-zA-Z0-9]{24}$

    Response Parameters

    Parameter Type Description
    message string Human-readable response to the order create status.

    Response Messages

    Error response example:

    {
      "message": "Invalid request body."
    }
    
    HTTP Status Code Message
    200 Order submitted for processing.
    400 Invalid request body.

    Order status API

    $ curl -X GET \
       https://api.gelato.com/v1/order/status/<MyOrderId> \
       -H 'Content-Type: application/json' \
       -H 'X-API-KEY: <apiKey>'
    
    <?php
    
    $url = "https://api.gelato.com/v1/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/v1/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/v1/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>,
      "orderItem": {
        "itemReferenceId": <MyItemId>,
        "status": "passed",
        "trackingCode": [
          {
            "parcelNumber": 1,
            "trackingCode": "1234567890",
            "trackingUrl": "https://example.com/search?piececode=1234567890"
          }
        ],
        "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"
          }
        ]
      }
    }
    

    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/v1/order/status/<orderReferenceId>

    Query Parameters

    Parameter Type Description
    orderReferenceId (required) integer Reference to your internal order id.

    Response Parameters

    Parameter Type Description
    orderReferenceId integer Reference to your internal order id.
    orderItem OrderItemObject Order item details.

    OrderItemObject parameters

    Parameter Type Description
    itemReferenceId integer Reference to your internal item id.
    status string Current status for your order item, can be: passed, failed, canceled, printed, and shipped
    trackingCode TrackingCodeObject[] The list of tracking codes for each parcel.
    productionLog ProductionLogObject[] The log of the production process, including printing and shipping information

    TrackingCodeObject parameters

    Parameter Type Description
    parcelNumber integer The serial number of the parcel. Always started at 1.
    trackingCode string The tracking code of the parcel.
    trackingUrl string The tracking url.

    ProductionLogObject parameters

    Parameter Type Description
    date string The production log creation date and time in ISO-8601 format.
    printJobId integer Gelato's internal reference id to the print job. Please note: one itemReferenceId might be split into parcels and print jobs if the weight of the product exceeds the available weight or size for the shipping method.
    message string The production log message.

    Response Messages

    Error response example:

    {
      "message": "Order not found."
    }
    
    HTTP Status Code Message
    404 Order not found.

    Cancel order API

    $ curl -X POST \
       https://api.gelato.com/v1/order/cancel \
       -H 'Content-Type: application/json' \
       -H 'X-API-KEY: <apiKey>' \
       -d '{"orderReferenceId": <MyOrderId>}'
    
    <?php
    
    $url = "https://api.gelato.com/v1/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/v1/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/v1/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/v1/order/cancel

    Query Parameters

    Parameter Type Description
    orderReferenceId (required) integer Reference to your internal order id.

    Response Parameters

    Parameter Type Description
    message string Human-readable message to the order cancel request.

    Response Messages

    Error response example:

    {
      "message": "Order not found."
    }
    
    HTTP Status Code Message
    200 The order canceled.
    400 The order cannot be canceled, because one of the items is in 'printed' status. itemReferenceId:
    404 Order not found.

    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

    Parameter Type Description
    id string Unique identifier for the object.
    object string String representing the object’s type. For order status events the value is itemStatus.
    itemReferenceId integer Reference to your internal item id.
    status string Current status for your order item, can be: passed, failed, cancelled, printed or shipped
    comment string Short text defining the reason for the status change.
    created string Time at which the object was created. The value is in ISO-8601 format.

    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",
      "created": "2018-08-03T12:11:30+00:00"
    }
    

    Object parameters

    Parameter Type Description
    id string Unique identifier for the object.
    object string String representing the object’s type. For order status event the value is trackingCode.
    itemReferenceId integer Reference to your internal item id.
    trackingCode string The tracking code of the package with your item.
    trackingUrl string The URL to shipping provider page with tracking information about your package with the item.
    created string Time at which the object was created. The value is in ISO-8601 format.