Webhooks

Overview

The Gelato API can be configured to send webhook events to notify your application any time that an event happens on your order.
The Gelato API sends the Event object, via a HTTP 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 refer to the API Portal to configure your account with a webhook URL.

Webhook URL

Your Webhook URL endpoint must be RESTful. All calls must be implemented as a HTTP post and with TLS encrypted. The HTTP response code 2xx is expected on positive calls, all other response codes will be considered as an 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

Order status

It is triggered when order status is changed. This event provides information about the new status of the order and its items, as well as its tracking codes if they are available.

Order status object example:

{
    "id": "os_5e5680ce494f6",
    "object": "orderStatus",
    "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
    "storeId": null,
    "orderReferenceId": "{{MyOrderId}}",
    "fulfillmentStatus": "shipped",
    "items": [
        {
            "itemReferenceId": "{{MyItemId}}",
            "fulfillmentStatus": "shipped",
            "fulfillments": [
                {
                    "trackingCode": "code123",
                    "trackingUrl": "http://example.com/tracking?code=code123",
                    "shipmentMethodName":"DHL Express Domestic BR",
                    "shipmentMethodUid":"dhl_express_domestic_br",
                    "fulfillmentCountry":"BR",
                    "fulfillmentStateProvince":"SP",
                    "fulfillmentFacilityId": "940fec84-54bc-44fc-a8a3-7d6f02cf8f14"
                },
                {
                    "trackingCode": "code234",
                    "trackingUrl": "http://example.com/tracking?code=code234",
                    "shipmentMethodName":"DHL Express Domestic BR",
                    "shipmentMethodUid":"dhl_express_domestic_br",
                    "fulfillmentCountry":"BR",
                    "fulfillmentStateProvince":"SP",
                    "fulfillmentFacilityId": "940fec84-54bc-44fc-a8a3-7d6f02cf8f14"
                }
            ]
        }
    ]
}

Object parameters

Parameter	Type	Description
id	string	Unique identifier for the event.
object	string	String representing the event’s type. For order status event the value is `orderStatus`.
orderId	string	Unique ID assigned by Gelato to your order
storeId	string	E-commerce store ID identifying which store the order was placed in. It will be null if the order was placed via UI or API.
orderReferenceId	string	Reference to your internal order id.
fulfillmentStatus	string	Current status for your order, can be: `created`, `uploading`, `passed`, `failed`, `canceled`, `printed` or `shipped`
items	OrderItem[]	Array of order items, including reference id, current status and fulfillment details for each item

OrderItem parameters

Parameter	Type	Description
itemReferenceId	string	Reference to your internal item id.
fulfillmentStatus	string	Current status for your order item, can be: `created`, `passed`, `failed`, `canceled`, `printed` or `shipped`
fulfillments	OrderItemFulfillment[]	Array of fulfillment details for each order items. Each fulfillment contains information about tracking codes and shipping providers

OrderItemFulfillment parameters

Parameter	Type	Description
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.
shipmentMethodName	string	Name of the shipping provider specified including shipment method
shipmentMethodUid	string	Unique identifier of shipping provider inside Gelato system
fulfillmentCountry	string	Code of the country where the ordered product was produced
fulfillmentStateProvince	string	Code of the state, province or region where the ordered product was produced
fulfillmentFacilityId	string	Id of production facility where the order was assigned to.

Item status

It is triggered 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 if an error has occured.

Item status object example:

{
  "id": "is_5b6403bd3cf1f",
  "object": "itemStatus",
  "itemReferenceId": "{{MyItemId}}",
  "orderReferenceId": "{{MyOrderId}}",
  "orderId": "e82885f8-f92a-4326-b2c7-77d010f6996f",
  "storeId": null,
  "fulfillmentCountry": "US",
  "fulfillmentStateProvince": "NY",
  "fulfillmentFacilityId": "21315db8-e694-4ded-a72a-98f60814c6e8",
  "status": "passed",
  "comment": "",
  "created": "2018-08-03T07:26:52+00:00"
}

Object parameters

Parameter	Type	Description
id	string	Unique identifier for the event.
object	string	String representing the event’s type. For item status event the value is `itemStatus`.
orderId	string	Unique ID assigned by Gelato to your order
storeId	string	E-commerce store ID identifying which store the order was placed in. It will be null if the order was placed via UI or API.
itemReferenceId	string	Reference to your internal item id.
orderReferenceId	string	Reference to your internal order id.
status	string	Current status for your order item, can be: `passed`, `failed`, `canceled`, `printed` or `shipped`
fulfillmentCountry	string	Code of the country where the ordered product was produced
fulfillmentStateProvince	string	Code of the state, province or region where the ordered product was produced
fulfillmentFacilityId	string	Id of production facility where the order was assigned to.
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

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

Tracking code object example:

{
  "id": "tc_5b6403bd3cf2e",
  "object": "trackingCode",
  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
  "storeId": "84086be9-8499-4420-a4c5-02235e126e56",
  "itemReferenceId": "{{MyItemId}}",
  "orderReferenceId": "{{MyOrderId}}",
  "trackingCode": "code123",
  "trackingUrl": "http://example.com/tracking?code=code123",
  "shipmentMethodName":"DHL Express Domestic BR",
  "shipmentMethodUid":"dhl_express_domestic_br",
  "productionCountry":"BR",
  "productionStateProvince":"SP",
  "productionFacilityId": "940fec84-54bc-44fc-a8a3-7d6f02cf8f14",
  "created": "2018-08-03T12:11:30+00:00"
}

Object parameters

Parameter	Type	Description
id	string	Unique identifier for the event.
object	string	String representing the event’s type. For tracking code event the value is `trackingCode`.
orderId	string	Unique ID assigned by Gelato to your order
storeId	string	E-commerce store ID identifying which store the order was placed in. It will be null if the order was placed via UI or API.
itemReferenceId	string	Reference to your internal item id.
orderReferenceId	string	Reference to your internal order 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.
shipmentMethodName	string	Name of the shipping provider specified including shipment method
shipmentMethodUid	string	Unique identifier of shipping provider inside Gelato system
fulfillmentCountry	string	Code of the country where the ordered product was produced
fulfillmentStateProvince	string	Code of the state, province or region where the ordered product was produced
fulfillmentFacilityId	string	Id of production facility where the order was assigned to.
created	string	Time at which the object was created. The value is in ISO-8601 format.

Stock region availability

It is triggered when the status of Stock availability in a region has changed. This event provides information about depleted or replenished stock of a product at Gelato Partners.

Stock region availability object example:

{
  "object": "stockRegionAvailability",
  "productAvailability": [
    {
      "productUid": "frame_product_frs_500x500-mm_frc_black_frm_wood_frp_w12xt22-mm_gt_plexiglass",
      "availability": [
        {
          "stockRegionUid": "EU",
          "status": "out-of-stock"
        },
        {
          "stockRegionUid": "ROW",
          "status": "out-of-stock-replenishable"
        }
      ]
    },
    {
      "productUid": "frame_product_frs_279x432-mm_frc_black_frm_wood_frp_w12xt22-mm_gt_plexiglass",
      "availability": [
        {
          "stockRegionUid": "US-CA",
          "status": "in-stock"
        }
      ]
    }
  ]
}

Object parameters

Parameter	Type	Description
object	string	String representing the event’s type. For "Stock region availability update" event the value is `stockRegionAvailability`.
productsAvailability (required)	ProductAvailability[]	Array of product's availability in region.

ProductAvailability parameters

Parameter	Type	Description
productUid (required)	string	Product UID from the request.
availability (required)	Availability	Availability in region.

Availability parameters

Parameter	Type	Description
stockRegionUid (required)	string	One of defined stock region UIDs.
status (required)	string	One of the possible availability statuses.

Parameter status can be one of 3 possible values:

in-stock - Product is in stock at one of Gelato Partners and can be be delivered to given region by at least one of the partners.
out-of-stock-replenishable - Product is temporarily out of stock at Gelato Partners but is in stock at the Gelato Hub which acts as a fallback solution, thus still can be delivered to the given region. Meantime the product is about to be replenished soon at the partners.
out-of-stock - Product is currently out of stock at both Gelato Partners and the Gelato Hub, thus cannot be delivered to the given region.

Order Delivery Estimate Changed

Beta Feature

To get access to this beta feature contact us on apisupport@gelato.com.

Triggered when an order's delivery estimate has increased. If either the estimated min or max delivery date is increased then the event will be fired. If an order contains multiple packages that would have different delivery dates then the most conservative delivery estimate will be used.

Order Delivery Estimated Changed Object example:

{
    "id": "os_5e5680ce494f6",
    "object": "orderDeliveryEstimateChanged",
    "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",
    "storeId": null,
    "orderReferenceId": "9AKJFFH372",
    "minDeliveryDate": "2022-11-03",
    "maxDeliveryDate": "2022-11-05",
    "created": "2022-11-01T07:26:52+00:00"
}

Object parameters

Parameter	Type	Description
id	string	Unique identifier for the event.
object	string	String representing the event’s type. For order delivery estimated changed status event the value is `orderDeliveryEstimateChanged`.
orderId	string	Unique ID assigned by Gelato to your order
storeId	string	E-commerce store ID identifying which store the order was placed in. It will be null if the order was placed via UI or API.
orderReferenceId	string	Reference to your internal order id.
minDeliveryDate	string	The most recent estimated minimum delivery date of the order.
maxDeliveryDate	string	The most recent estimated maximum delivery date of the order.
created	string	Time at which the object was created. The value is in ISO-8601 format.