Gelato

Gelato

This connector talks to the Gelato API. Gelato prints and ships products on demand (posters, wall art, apparel, mugs, cards, photo books...) from production partners in over 30 countries, so most orders are produced close to the customer. It is used directly through the API and as the fulfilment behind Etsy and Shopify stores.

Setup

1. In the Gelato dashboard open Developer → API Keys and click Add API key. Only admins, or users given the permission, see this page.
2. Name the key, click Create key and copy it right away: it is not shown again.
3. Paste it into GELATO_API_KEY.

The key is sent as the X-API-KEY header on every request.

One key, four hosts

Gelato splits its API across several hosts, and this connector calls each of them with the same key:

• product.gelatoapis.com: catalogs, products, prices, cover dimensions and stock (the connector's base URL and health check).
• order.gelatoapis.com: order quote, create, get, search, confirm and cancel (Order API v4).
• shipment.gelatoapis.com: shipment methods.
• ecommerce.gelatoapis.com: products and templates of connected stores.

Start here

1. gelato_list_catalogs, then gelato_get_catalog for the attributes (size, paper, colour...) of the product family you need.
2. gelato_search_products with attribute_filters to find the exact productUid. Every price, quote and order uses this UID.
3. gelato_get_product_prices for production prices per quantity, gelato_check_stock for stockable items such as frames, and gelato_quote_order for the full price with shipping options for a real address.

Gelato and Etsy or Shopify

A store connected to Gelato sends its orders to Gelato on its own; they show up in gelato_search_orders with channel etsy or shopify and a storeId. Do not create them again with gelato_create_order. The store id is that storeId, or the id in the store page URL of the Gelato dashboard. Use gelato_list_store_products to see which listings are connected to Gelato products, and gelato_get_template with gelato_create_product_from_template to create new listings from a template built in the dashboard (the template id is on the Templates page).

Orders

• Three ids you choose are required: order_reference_id (your order), customer_reference_id (your customer) and an itemReferenceId per line. Gelato returns its own order id (a UUID) for the get, confirm and cancel tools.
• gelato_create_draft_order creates a draft that is neither produced nor charged. Review it in the dashboard; gelato_confirm_draft_order turns it into a real order.
• An order with items that need different production sites is split into connected orders: each has its own Gelato id, all share your order_reference_id, and connectedOrderIds lists them.
• Fulfillment statuses run from created and passed through in_production, printed, shipped, in_transit and delivered; other states include draft, pending_approval, on_hold, not_connected, failed and canceled. Tracking codes and URLs are in shipment.packages of gelato_get_order.
• Print files are given by public URL (PDF, PNG, TIFF, SVG or JPEG; PDF/X-1a or PDF/X-4 preferred for PDFs). File type default is the primary print area.
• Addresses: country is ISO 3166-1 alpha-2 (GB, not UK); state is required for the US, Canada and Australia; addresses in China, Japan, South Korea and Russia must be written in the local language.

Paging

gelato_search_products, gelato_search_orders and gelato_list_store_products page with limit (at most 100) and offset.

Write tools

gelato_create_order, gelato_confirm_draft_order and gelato_create_product_from_template are installed switched off: the first two charge the Gelato account, the third publishes a listing to the connected store (Etsy charges a listing fee). Enable them on the connector page if you want them. gelato_cancel_order only works before an order is printed (409 otherwise).

Errors

• 401: the key is wrong or was deleted. Create a new one under Developer → API Keys.
• 404: unknown id or UID. Look ids up with the list and search tools rather than guessing them.
• 409 on cancel: an item is already printed.
• 429: too many requests. Wait a minute and retry.