Servers Playground How we check Add a server Log in

Gelato MCP by usefulapi

Working · 726 ms

io.usefulapi/gelatov1.9.0 Domain verified

Browse the Gelato catalog, prices, orders and shipping; quote, create draft orders and products.

Commerce

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://gelato.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

gelato_cancel_order Destructive

Cancel an order before production. Gelato refuses (HTTP 409) once any item is printed or the order has shipped. This cannot be undone. POST /v4/orders/{orderId}:cancel.

order_idstring, required

Gelato order id.

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

Gelato MCP by usefulapi MCP server | mcptry

Tools (19)

gelato_cancel_order

Cancel an order before production. Gelato refuses (HTTP 409) once any item is printed or the order has shipped. This cannot be undone. POST /v4/orders/{orderId}:cancel.

destructive

Argument	Type	Description
order_id*	string	Gelato order id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato order id."
    }
  }
}

gelato_check_stock

Stock status of stockable products per stock region (US-CA, EU, UK, OC, AS, SA, ROW): in-stock, out-of-stock-replenishable (with a replenishment date), out-of-stock, non-stockable or not-supported. POST /v3/stock/region-availability.

read-only

Argument	Type	Description
product_uids*	array	Product UIDs to check (1-250).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "product_uids"
  ],
  "properties": {
    "product_uids": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_.+-]+$",
        "maxLength": 400,
        "minLength": 1,
        "description": "Gelato product UID."
      },
      "maxItems": 250,
      "minItems": 1,
      "description": "Product UIDs to check (1-250)."
    }
  }
}

gelato_create_order

Create an order. By default it is a DRAFT: nothing is produced or charged until it is submitted with gelato_submit_draft_order (or in the dashboard). With order_type "order" Gelato starts production and charges the account right away. Shipment: a shipmentMethodUid from gelato_quote_order, or "normal"/"standard"/"express"; omitted = the cheapest. POST /v4/orders.

destructive

Argument	Type	Description
items*	array	Line items.
currency*	string	3-letter ISO 4217 currency code, e.g. USD or EUR.
metadata	array	Up to 20 key/value pairs stored on the order.
order_type	string	"draft" (default; review first) or "order" (produced and charged immediately).
shipping_address*	object	Delivery address.
order_reference_id*	string	Your internal order id.
shipment_method_uid	string	A shipmentMethodUid from gelato_quote_order, or "normal", "standard", "express". Several values may be given separated by commas (no spaces). Omitted = cheapest.

gelato_create_product_from_template

Create a product in a connected store from a template, with your own images in the template's placeholders. Gelato creates the product, then publishes variants and mockups in the background (track it with gelato_get_store_product). Hidden in the online store unless visible_in_online_store is true. POST /v1/stores/{storeId}/products:create-from-template.

destructive

Argument	Type	Description
tags	array	Product tags, at most 13 (Etsy stores: 20 characters each).
title*	string	Product title.
vendor	string	Vendor shown in the store.
store_id*	string	Gelato e-commerce store id.
variants	array	Variants to create (omit for all template variants), each with the images for its placeholders.
description*	string	Product description (HTML allowed by most stores).
template_id*	string	Template id (see gelato_get_template).
product_type

gelato_delete_draft_order

Permanently delete a DRAFT order (regular orders cannot be deleted; cancel them instead). DELETE /v4/orders/{orderId}.

destructive

Argument	Type	Description
order_id*	string	Gelato order id of a draft order.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato order id of a draft order."
    }
  }
}

gelato_get_catalog

One catalog with the attributes that define its products (e.g. PaperFormat, PaperType, ColorType) and each attribute's possible values. Use them as attribute_filters in gelato_search_products. GET /v3/catalogs/{catalogUid}.

read-only

Argument	Type	Description
catalog_uid*	string	Catalog UID, e.g. "posters" (from gelato_list_catalogs).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "catalog_uid"
  ],
  "properties": {
    "catalog_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.+-]+$",
      "maxLength": 400,
      "minLength": 1,
      "description": "Catalog UID, e.g. \"posters\" (from gelato_list_catalogs)."
    }
  }
}

gelato_get_cover_dimensions

Cover layout of a multi-page product (photo book, brochure) in millimetres: spine, front, back, bleed and wraparound areas, for designing the cover file. GET /v3/products/{productUid}/cover-dimensions.

read-only

Argument	Type	Description
page_count*	integer	Total page count including covers (see validPageCounts in gelato_get_product).
product_uid*	string	Gelato product UID of a multi-page product.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "product_uid",
    "page_count"
  ],
  "properties": {
    "page_count": {
      "type": "integer",
      "maximum": 10000,
      "minimum": 1,
      "description": "Total page count including covers (see validPageCounts in gelato_get_product)."
    },
    "product_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.+-]+$",
      "maxLength": 400,
      "minLength": 1,
      "description": "Gelato product UID of a multi-page product."
    }
  }
}

gelato_get_order

One order by Gelato order id: type (order/draft), fulfillment and financial status, items with their files and statuses, shipment with packages and tracking codes/URLs, shipping address, receipts and totals. GET /v4/orders/{orderId}.

read-only

Argument	Type	Description
order_id*	string	Gelato order id (from gelato_search_orders).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato order id (from gelato_search_orders)."
    }
  }
}

gelato_get_product

One catalog product by productUid: attributes, weight, supported and unsupported countries, whether it is printable or stockable, and valid page counts for multi-page products. GET /v3/products/{productUid}.

read-only

Argument	Type	Description
product_uid*	string	Gelato product UID (from gelato_search_products).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "product_uid"
  ],
  "properties": {
    "product_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.+-]+$",
      "maxLength": 400,
      "minLength": 1,
      "description": "Gelato product UID (from gelato_search_products)."
    }
  }
}

gelato_get_product_prices

Gelato's production prices of a product for every quantity tier, optionally for one destination country and currency. page_count is required for multi-page products. Shipping is not included (use gelato_quote_order). GET /v3/products/{productUid}/prices.

read-only

Argument	Type	Description
country	string	2-letter ISO 3166-1 country code (the United Kingdom is GB, not UK).
currency	string	3-letter ISO 4217 currency code, e.g. USD or EUR.
page_count	integer	Page count, required for multi-page products.
product_uid*	string	Gelato product UID.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "product_uid"
  ],
  "properties": {
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "2-letter ISO 3166-1 country code (the United Kingdom is GB, not UK)."
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "3-letter ISO 4217 currency code, e.g. USD or EUR."
    },
    "page_count": {
      "type": "integer",
      "maximum": 10000,
      "minimum": 1,
      "description": "Page count, required for multi-page products."
    },
    "product_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.+-]+$",
      "maxLength": 400,
      "minLength": 1,
      "description": "Gelato product UID."
    }
  }
}

gelato_get_store_product

One product of a connected store: title, description, status, variants (with productUid and external ids), options, preview and publishing state. GET /v1/stores/{storeId}/products/{productId}.

read-only

Argument	Type	Description
store_id*	string	Gelato e-commerce store id.
product_id*	string	Store product id (from gelato_list_store_products).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "store_id",
    "product_id"
  ],
  "properties": {
    "store_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato e-commerce store id."
    },
    "product_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Store product id (from gelato_list_store_products)."
    }
  }
}

gelato_get_template

A product template made in the Gelato dashboard: title, description, preview, and its variants (id, title, productUid; pass the variant id as template_variant_id) with their image placeholders (names to fill in gelato_create_product_from_template). GET /v1/templates/{templateId}.

read-only

Argument	Type	Description
template_id*	string	Template id (Gelato dashboard → the template's URL).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "template_id"
  ],
  "properties": {
    "template_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Template id (Gelato dashboard → the template's URL)."
    }
  }
}

gelato_list_catalogs

List Gelato's product catalogs (posters, cards, t-shirts, mugs, photo books, ...) with their catalogUid and title. Start here to find products. GET product.gelatoapis.com/v3/catalogs.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

gelato_list_shipment_methods

Gelato's shipment methods (shipmentMethodUid, name, type normal/express/pallet, tracking, business/private, supported destination countries), optionally only those for one destination country. GET shipment.gelatoapis.com/v1/shipment-methods.

read-only

Argument	Type	Description
country	string	Only methods that deliver to this 2-letter ISO country code.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Only methods that deliver to this 2-letter ISO country code."
    }
  }
}

gelato_list_store_products

Products of a connected e-commerce store (Shopify, Etsy, WooCommerce, ...) as Gelato knows them: id, title, status (created/publishing/publishing_error/active), external id, variants with their productUid, preview images and dates. The store id is in the Gelato dashboard URL of the store and on its orders (storeId). GET ecommerce.gelatoapis.com/v1/stores/{storeId}/products.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-100 (default 50).
order	string	Sort direction (default desc).
offset	integer	Number of results to skip (default 0). Pass the previous reply's next_offset.
order_by	string	Sort field (default createdAt).
store_id*	string	Gelato e-commerce store id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "store_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "description": "Results per page, 1-100 (default 50).",
      "exclusiveMinimum": 0
    },
    "order": {
      "enum": [
        "desc",
        "asc"
      ],
      "type": "string",
      "description": "Sort direction (default desc)."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Number of results to skip (default 0). Pass the previous reply's next_offset."
    },
    "order_by": {
      "enum": [
        "createdAt",
        "updatedAt"
      ],
      "type": "string",
      "description": "Sort field (default createdAt)."
    },
    "store_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato e-commerce store id."
    }
  }
}

gelato_quote_order

Price an order before placing it: product prices and the available shipment methods (shipmentMethodUid, price, min/max delivery days and dates) per fulfillment facility, for a recipient address. Nothing is created or charged. Pass a returned shipmentMethodUid to gelato_create_order. POST /v4/orders:quote.

read-only

Argument	Type	Description
currency*	string	3-letter ISO 4217 currency code, e.g. USD or EUR.
products*	array	Products to quote.
recipient*	object	Delivery address the quote is for.
order_reference_id*	string	Your order reference id for the quote.
allow_multiple_quotes	boolean	Default true: one quote per fulfillment facility when one facility cannot make everything. False: one combined quote.
customer_reference_id*	string	Your customer reference id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_reference_id",
    "customer_reference_id",
    "currency",
    "recipient",
    "products"
  ],
  "properties": {
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "3-letter ISO 4217 currency code, e.g. USD or EUR."
    },
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "item_reference_id",
          "product_uid",
          "quantity"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 2048,
                  "description": "Public URL Gelato downloads the file from (PDF, PNG, TIFF, SVG or JPEG)."
                },
                "type": {
                  "type": "string",
                  "pattern": "^[a-z0-9_-]+$",
                  "maxLength": 50,
                  "minLength": 1,
                  "description": "Print area: \"default\" (the primary area, e.g. the front of apparel), \"front\", \"back\", or an embroidery position. Default \"default\"."
                }
              },
              "additionalProperties": false
            },
            "maxItems": 20,
            "minItems": 1,
            "description": "Print files (required for printable products only)."
          },
          "quantity": {
            "type": "integer",
            "maximum": 100000,
            "minimum": 1,
            "description": "Quantity, at least 1."
          },
          "page_count": {
            "type": "integer",
            "maximum": 10000,
            "minimum": 1,
            "description": "Page count, multi-page products only (covers included)."
          },
          "product_uid": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.+-]+$",
            "maxLength": 400,
            "minLength": 1,
            "description": "Gelato product UID (from gelato_search_products or a store product variant)."
          },
          "item_reference_id": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "Your id for this line, unique within the order."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Products to quote."
    },
    "recipient": {
      "type": "object",
      "required": [
        "first_name",
        "last_name",
        "address_line1",
        "city",
        "country",
        "email"
      ],
      "properties": {
        "city": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "City (Gelato allows 30 characters)."
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "maxLength": 254,
          "description": "Recipient email (required by Gelato; used for delivery notifications)."
        },
        "phone": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient phone number."
        },
        "state": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "State/province code, required for US, CA and AU (e.g. NY)."
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Za-z]{2}$",
          "description": "2-letter ISO 3166-1 country code (the United Kingdom is GB, not UK)."
        },
        "last_name": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient last name (Gelato allows 25 characters)."
        },
        "post_code": {
          "type": "string",
          "maxLength": 15,
          "minLength": 1,
          "description": "Postal code (required where the country uses them)."
        },
        "first_name": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient first name (Gelato allows 25 characters)."
        },
        "is_business": {
          "type": "boolean",
          "description": "Brazil only: true if the recipient is a company (then state_tax_id and registration_state_code apply)."
        },
        "company_name": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1,
          "description": "Company name (max 60 characters)."
        },
        "state_tax_id": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "Brazil only: the company's state tax id (Inscrição Estadual)."
        },
        "address_line1": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "Street and number (Gelato allows 35 characters)."
        },
        "address_line2": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "Second address line (Gelato allows 35 characters)."
        },
        "federal_tax_id": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "Brazil only, required there: CPF (person) or CNPJ (company)."
        },
        "registration_state_code": {
          "type": "string",
          "maxLength": 10,
          "minLength": 1,
          "description": "Brazil only: the state code where the company is registered."
        }
      },
      "description": "Delivery address the quote is for.",
      "additionalProperties": false
    },
    "order_reference_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Your order reference id for the quote."
    },
    "allow_multiple_quotes": {
      "type": "boolean",
      "description": "Default true: one quote per fulfillment facility when one facility cannot make everything. False: one combined quote."
    },
    "customer_reference_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Your customer reference id."
    }
  }
}

gelato_search_orders

Search orders and drafts, newest first: id, your reference ids, order type, fulfillment and financial status, channel, store, country, currency, totals and dates. Filter by status, type, country, channel, store, reference, date range or free text (recipient name or order reference). POST /v4/orders:search.

read-only

Argument	Type	Description
ids	array	Only these Gelato order ids.
limit	integer	Results per page, 1-100 (default 50).
offset	integer	Number of results to skip (default 0). Pass the previous reply's next_offset.
search	string	Free text matched against the recipient's first or last name and orderReferenceId.
channels	array	Only orders from these channels (ui, api, shopify, etsy).
end_date	string	Only orders ordered or created on or before this ISO 8601 date-time.
countries	array	Only orders shipping to these countries (2-letter ISO codes).
store_ids	array	Only orders from these e-commerce store ids.

gelato_search_products

List the products of a catalog, optionally filtered by attribute values, with each product's productUid, attributes, weight and dimensions, plus hit counts per attribute value. POST /v3/catalogs/{catalogUid}/products:search.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-100 (default 50).
offset	integer	Number of results to skip (default 0). Pass the previous reply's next_offset.
catalog_uid*	string	Catalog UID, e.g. "posters".
attribute_filters	object	Attribute name → accepted values, e.g. {"Orientation":["hor"],"PaperFormat":["A4","A3"]} (names and values from gelato_get_catalog).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "catalog_uid"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "description": "Results per page, 1-100 (default 50).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Number of results to skip (default 0). Pass the previous reply's next_offset."
    },
    "catalog_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.+-]+$",
      "maxLength": 400,
      "minLength": 1,
      "description": "Catalog UID, e.g. \"posters\"."
    },
    "attribute_filters": {
      "type": "object",
      "description": "Attribute name → accepted values, e.g. {\"Orientation\":[\"hor\"],\"PaperFormat\":[\"A4\",\"A3\"]} (names and values from gelato_get_catalog).",
      "propertyNames": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1
        },
        "maxItems": 50,
        "minItems": 1
      }
    }
  }
}

gelato_submit_draft_order

Convert a DRAFT order into a regular order: Gelato starts production and charges the account. Items stay as they are. Only drafts can be submitted. PATCH /v4/orders/{orderId} {"orderType":"order"}.

destructive

Argument	Type	Description
order_id*	string	Gelato order id of a draft order.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato order id of a draft order."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "order_reference_id",
    "customer_reference_id",
    "currency",
    "items",
    "shipping_address"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "item_reference_id",
          "product_uid",
          "quantity"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 2048,
                  "description": "Public URL Gelato downloads the file from (PDF, PNG, TIFF, SVG or JPEG)."
                },
                "type": {
                  "type": "string",
                  "pattern": "^[a-z0-9_-]+$",
                  "maxLength": 50,
                  "minLength": 1,
                  "description": "Print area: \"default\" (the primary area, e.g. the front of apparel), \"front\", \"back\", or an embroidery position. Default \"default\"."
                }
              },
              "additionalProperties": false
            },
            "maxItems": 20,
            "minItems": 1,
            "description": "Print files (required for printable products only)."
          },
          "quantity": {
            "type": "integer",
            "maximum": 100000,
            "minimum": 1,
            "description": "Quantity, at least 1."
          },
          "page_count": {
            "type": "integer",
            "maximum": 10000,
            "minimum": 1,
            "description": "Page count, multi-page products only (covers included)."
          },
          "product_uid": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.+-]+$",
            "maxLength": 400,
            "minLength": 1,
            "description": "Gelato product UID (from gelato_search_products or a store product variant)."
          },
          "item_reference_id": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "Your id for this line, unique within the order."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Line items."
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "3-letter ISO 4217 currency code, e.g. USD or EUR."
    },
    "metadata": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "key",
          "value"
        ],
        "properties": {
          "key": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1
          },
          "value": {
            "type": "string",
            "maxLength": 100
          }
        },
        "additionalProperties": false
      },
      "maxItems": 20,
      "minItems": 1,
      "description": "Up to 20 key/value pairs stored on the order."
    },
    "order_type": {
      "enum": [
        "draft",
        "order"
      ],
      "type": "string",
      "description": "\"draft\" (default; review first) or \"order\" (produced and charged immediately)."
    },
    "shipping_address": {
      "type": "object",
      "required": [
        "first_name",
        "last_name",
        "address_line1",
        "city",
        "country",
        "email"
      ],
      "properties": {
        "city": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "City (Gelato allows 30 characters)."
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "maxLength": 254,
          "description": "Recipient email (required by Gelato; used for delivery notifications)."
        },
        "phone": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient phone number."
        },
        "state": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "State/province code, required for US, CA and AU (e.g. NY)."
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Za-z]{2}$",
          "description": "2-letter ISO 3166-1 country code (the United Kingdom is GB, not UK)."
        },
        "last_name": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient last name (Gelato allows 25 characters)."
        },
        "post_code": {
          "type": "string",
          "maxLength": 15,
          "minLength": 1,
          "description": "Postal code (required where the country uses them)."
        },
        "first_name": {
          "type": "string",
          "maxLength": 25,
          "minLength": 1,
          "description": "Recipient first name (Gelato allows 25 characters)."
        },
        "is_business": {
          "type": "boolean",
          "description": "Brazil only: true if the recipient is a company (then state_tax_id and registration_state_code apply)."
        },
        "company_name": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1,
          "description": "Company name (max 60 characters)."
        },
        "state_tax_id": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "Brazil only: the company's state tax id (Inscrição Estadual)."
        },
        "address_line1": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "Street and number (Gelato allows 35 characters)."
        },
        "address_line2": {
          "type": "string",
          "maxLength": 35,
          "minLength": 1,
          "description": "Second address line (Gelato allows 35 characters)."
        },
        "federal_tax_id": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "Brazil only, required there: CPF (person) or CNPJ (company)."
        },
        "registration_state_code": {
          "type": "string",
          "maxLength": 10,
          "minLength": 1,
          "description": "Brazil only: the state code where the company is registered."
        }
      },
      "description": "Delivery address.",
      "additionalProperties": false
    },
    "order_reference_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Your internal order id."
    },
    "shipment_method_uid": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.:-]+(,[A-Za-z0-9_.:-]+)*$",
      "maxLength": 200,
      "minLength": 1,
      "description": "A shipmentMethodUid from gelato_quote_order, or \"normal\", \"standard\", \"express\". Several values may be given separated by commas (no spaces). Omitted = cheapest."
    },
    "customer_reference_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Your internal customer id."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "store_id",
    "template_id",
    "title",
    "description"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 255,
        "minLength": 1
      },
      "maxItems": 13,
      "minItems": 1,
      "description": "Product tags, at most 13 (Etsy stores: 20 characters each)."
    },
    "title": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Product title."
    },
    "vendor": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Vendor shown in the store."
    },
    "store_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Gelato e-commerce store id."
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "template_variant_id"
        ],
        "properties": {
          "image_placeholders": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "file_url"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Placeholder (layer) name from the template."
                },
                "file_url": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 2048,
                  "description": "Public image URL (jpg, jpeg, png or pdf)."
                },
                "fit_method": {
                  "enum": [
                    "slice",
                    "meet"
                  ],
                  "type": "string",
                  "description": "\"slice\" (default: fill and crop) or \"meet\" (fit the whole image)."
                }
              },
              "additionalProperties": false
            },
            "maxItems": 50,
            "minItems": 1
          },
          "template_variant_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]+$",
            "maxLength": 100,
            "minLength": 1,
            "description": "The variant id (variants[].id) from gelato_get_template."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Variants to create (omit for all template variants), each with the images for its placeholders."
    },
    "description": {
      "type": "string",
      "maxLength": 20000,
      "minLength": 1,
      "description": "Product description (HTML allowed by most stores)."
    },
    "template_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "Template id (see gelato_get_template)."
    },
    "product_type": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Product type shown in the store."
    },
    "sales_channels": {
      "type": "array",
      "items": {
        "enum": [
          "web",
          "global"
        ],
        "type": "string"
      },
      "maxItems": 2,
      "minItems": 1,
      "description": "Sales channels: \"web\" (default) or \"global\" (Shopify Point of Sale)."
    },
    "visible_in_online_store": {
      "type": "boolean",
      "description": "Show the product in the online store (default false)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]+$",
        "maxLength": 100,
        "minLength": 1,
        "description": "Gelato order id."
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Only these Gelato order ids."
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "description": "Results per page, 1-100 (default 50).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Number of results to skip (default 0). Pass the previous reply's next_offset."
    },
    "search": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Free text matched against the recipient's first or last name and orderReferenceId."
    },
    "channels": {
      "type": "array",
      "items": {
        "enum": [
          "ui",
          "api",
          "shopify",
          "etsy"
        ],
        "type": "string"
      },
      "maxItems": 4,
      "minItems": 1,
      "description": "Only orders from these channels (ui, api, shopify, etsy)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,9})?)?(Z|[+-](\\d{2}):(\\d{2})))?$",
      "description": "Only orders ordered or created on or before this ISO 8601 date-time."
    },
    "countries": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z]{2}$",
        "description": "2-letter ISO 3166-1 country code (the United Kingdom is GB, not UK)."
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Only orders shipping to these countries (2-letter ISO codes)."
    },
    "store_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]+$",
        "maxLength": 100,
        "minLength": 1,
        "description": "Gelato e-commerce store id."
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Only orders from these e-commerce store ids."
    },
    "currencies": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z]{3}$",
        "description": "3-letter ISO 4217 currency code, e.g. USD or EUR."
      },
      "maxItems": 20,
      "minItems": 1,
      "description": "Only orders in these currencies."
    },
    "start_date": {
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,9})?)?(Z|[+-](\\d{2}):(\\d{2})))?$",
      "description": "Only orders ordered or created on or after this ISO 8601 date-time (e.g. 2026-10-01T00:00:00Z)."
    },
    "order_types": {
      "type": "array",
      "items": {
        "enum": [
          "order",
          "draft"
        ],
        "type": "string"
      },
      "maxItems": 2,
      "minItems": 1,
      "description": "Only these order types."
    },
    "financial_statuses": {
      "type": "array",
      "items": {
        "enum": [
          "draft",
          "pending",
          "invoiced",
          "to_be_invoiced",
          "paid",
          "canceled",
          "partially_refunded",
          "refunded",
          "refused"
        ],
        "type": "string"
      },
      "maxItems": 9,
      "minItems": 1,
      "description": "Only these financial statuses."
    },
    "order_reference_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1,
        "description": "Your order reference id."
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Only orders with these orderReferenceIds."
    },
    "fulfillment_statuses": {
      "type": "array",
      "items": {
        "enum": [
          "created",
          "passed",
          "failed",
          "canceled",
          "printed",
          "shipped",
          "draft",
          "pending_approval",
          "not_connected",
          "on_hold"
        ],
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "description": "Only these fulfillment statuses."
    }
  }
}