{ "openapi": "3.0.1", "info": { "title": "Glood.AI API Reference", "description": "Glood.AI API Reference", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://storefront.glood.ai" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/storefront/v3/headless/recommendations/top": { "post": { "description": "Fetch products by a ranking strategy (BESTSELLERS, NEW_ARRIVALS, TRENDING) with rich criteria filters, full-text query, cursor pagination, and optional facet aggregations. Unlike `/recommendations` and `/recommendations/automatic`, this endpoint does not require seed `product_ids` — it is the right choice for catalog landing pages, search results constrained by a strategy, and merchandising widgets that need filtered top-N lists.", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL", "required": true, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopRecommendationsRequest" } } } }, "responses": { "200": { "description": "Top recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopRecommendationsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticRecommendationsError" } } } } } } }, "/api/storefront/v3/headless/recommendations/automatic": { "post": { "description": "Get automatic recommendations powered using LLMs", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL", "required": true, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticRecommendationsRequest" } } } }, "responses": { "200": { "description": "Recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticRecommendationsResponse" }, "example": { "status": "ok", "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "pagination": { "cursor": null }, "products": [ { "product_id": 9311227838783, "title": "Classic Cotton T-Shirt", "handle": "classic-cotton-t-shirt", "price": 1025, "compare_at_price": null, "tags": "cotton,casual,bestseller", "product_type": "T-Shirts", "vendor": "BrandName", "image": { "id": "gid://shopify/ProductImage/123456", "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg", "altText": "Classic Cotton T-Shirt", "width": 1600, "height": 1600 }, "options": [ { "id": 123, "name": "Title", "position": 1, "values": [ "Default Title" ] } ], "variants": [ { "variant_id": 48328566276415, "title": "Default Title", "display_name": "Classic Cotton T-Shirt - Default Title", "price": "1025.00", "compare_at_price": null, "sku": "", "position": 1, "is_in_stock": true, "available_for_sale": true, "sellable_online_quantity": 50, "selected_options": [ { "name": "Title", "value": "Default Title" } ] } ], "metafields": [] } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticRecommendationsError" } } } } } } }, "/api/storefront/v3/headless/init": { "post": { "description": "Identify a visitor and retrieve shop configuration. Call this once per session before fetching sections or sending events.", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL", "required": true, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Visitor identification payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessInitRequest" } } } }, "responses": { "200": { "description": "Visitor context and shop configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessInitResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/storefront/v3/headless/sections": { "post": { "description": "Get recommendation sections with full product details for a given page context.", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL", "required": true, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Page context and section request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessSectionsRequest" } } } }, "responses": { "200": { "description": "Sections with product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessSectionsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/storefront/v3/headless/events": { "post": { "description": "Send tracking events from headless, mobile, or hydrogen storefronts.", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL (can be omitted if shop_domain is provided in the request body)", "required": false, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Event payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessEventsRequest" }, "examples": { "sectionAddToCart": { "summary": "glood:section:add_to_cart — User added a recommended product to cart", "value": { "event": { "id": "evt-atc-001", "name": "glood:section:add_to_cart", "type": "custom", "timestamp": "2026-04-17T10:30:00Z", "data": {}, "customData": { "track": { "section": "221939", "parent": { "productId": "15441118822774", "variantId": null }, "products": [ { "productId": "15441118953846", "variantId": "56640794886518", "quantity": 1 } ], "sectionServeId": "2ec3ae42-40f4-44ec-9aa8-dd907474b51c", "recommendationType": "similar_products" } } }, "session_id": "sess-abc123", "client_id": "client-xyz", "channel": "headless", "page_type": "product", "page_url": "https://example.com/products/classic-shirt" } }, "sectionClick": { "summary": "glood:section:click — User clicked a recommended product", "value": { "event": { "id": "evt-click-001", "name": "glood:section:click", "type": "custom", "timestamp": "2026-04-16T10:30:00Z", "data": {}, "customData": { "track": { "section": "219670", "page": "46334", "products": [ { "productId": "14694200541547", "variantId": "51996137914731", "quantity": 1 } ], "parent": { "productId": "14694203162987", "variantId": "51996141781355" }, "requestId": "1776322091-05bd288e-349e-4686-98b0-acf2982aba3f", "sectionServeId": "612512cd-76b3-4ea4-9e9c-1403c0634bc9" } } }, "session_id": "sess-abc123", "client_id": "client-xyz", "channel": "headless", "page_type": "product", "page_url": "https://example.com/products/classic-shirt" } }, "sectionRender": { "summary": "glood:section:render — Recommendation section rendered on page", "value": { "event": { "id": "evt-render-001", "name": "glood:section:render", "type": "custom", "timestamp": "2026-04-16T10:29:55Z", "data": {}, "customData": { "track": { "section": "220585", "parent": { "productId": "9096784544001", "variantId": null }, "products": [ { "productId": "9088934117633", "variantId": "48242362614017", "quantity": 1 }, { "productId": "9088798130433", "variantId": "48241879417089", "quantity": 1 }, { "productId": "9093915279617", "variantId": "48257196065025", "quantity": 1 }, { "productId": "9096777892097", "variantId": "48263537787137", "quantity": 1 }, { "productId": "9093946081537", "variantId": "48257233158401", "quantity": 1 }, { "productId": "9093898797313", "variantId": "48257176535297", "quantity": 1 }, { "productId": "9090401992961", "variantId": "48248369250561", "quantity": 1 }, { "productId": "9090377646337", "variantId": "48248134533377", "quantity": 1 } ], "sectionServeId": "eb07f928-ab63-4dc0-9241-1189658c2f9d", "recommendationType": "similar_products" } } }, "session_id": "sess-abc123", "client_id": "client-xyz", "channel": "headless", "page_type": "product", "page_url": "https://example.com/products/premium-jacket" } }, "sectionView": { "summary": "glood:section:view — Recommendation section entered viewport", "value": { "event": { "id": "evt-view-001", "name": "glood:section:view", "type": "custom", "timestamp": "2026-04-16T10:29:58Z", "data": {}, "customData": { "track": { "section": "91740", "parent": { "productId": "8833600782669", "variantId": null }, "products": [ { "productId": "6695028293701", "variantId": "39789995884613", "quantity": 1 }, { "productId": "8687660728653", "variantId": "47422555717965", "quantity": 1 }, { "productId": "8770163573069", "variantId": "47823353250125", "quantity": 1 }, { "productId": "6811965161541", "variantId": "40284213739589", "quantity": 1 }, { "productId": "6640685744197", "variantId": "39535348187205", "quantity": 1 }, { "productId": "9949236920653", "variantId": "50990938882381", "quantity": 1 } ], "sectionServeId": "3dd1d06b-b45c-4eeb-a246-c4cefa356842", "recommendationType": "similar_products" } } }, "session_id": "sess-abc123", "client_id": "client-xyz", "channel": "headless", "page_type": "product", "page_url": "https://example.com/products/summer-dress" } } } } } }, "responses": { "200": { "description": "Event accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessEventsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/storefront/v3/headless/recommendations": { "post": { "description": "Get AI recommendations including Manual, Rules, LLM & AI using Query.\n\nThe `product_ids` field within each query item accepts **either** a JSON array of integers (e.g. `[123, 456]`) **or** a comma-separated string (e.g. `\"123,456\"`). The CSV form is provided for clients whose serializers cannot construct arrays from variables.", "parameters": [ { "name": "x-shop", "in": "header", "description": "Shopify store URL", "required": true, "schema": { "type": "string", "example": "shop.myshopify.com" } } ], "requestBody": { "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessQueryRecommendationsRequest" }, "examples": { "arrayProductIds": { "summary": "product_ids as JSON array", "value": { "client_id": "client-abc", "user_id": "user-xyz", "queries": [ { "id": "rec-1", "recommendation_type": "similar_products", "product_ids": [ 123, 456 ], "view": "product_ids", "max_recommendations": 10 } ] } }, "csvProductIds": { "summary": "product_ids as CSV string", "value": { "client_id": "client-abc", "user_id": "user-xyz", "queries": [ { "id": "rec-1", "recommendation_type": "similar_products", "product_ids": "123,456", "view": "product_ids", "max_recommendations": 10 } ] } } } } } }, "responses": { "200": { "description": "Recommendations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessQueryRecommendationsProductDetailsResponse" }, "example": { "status": "ok", "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": { "rec-1": { "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "recommendation_type": "similar_products", "max_recommendations": 10, "creation_type": "automatic", "product_ids": [ 123, 456 ], "view": "product_details", "recommendations": [ { "product_id": 9311227838783, "title": "Classic Cotton T-Shirt", "handle": "classic-cotton-t-shirt", "price": 1025, "compare_at_price": null, "image": { "id": "gid://shopify/ProductImage/123456", "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg", "altText": "Classic Cotton T-Shirt", "width": 1600, "height": 1600 }, "tags": "cotton,casual,bestseller", "options": [ { "id": 123, "name": "Title", "position": 1, "values": [ "Default Title" ] } ], "variants": [ { "variant_id": 48328566276415, "title": "Default Title", "display_name": "Classic Cotton T-Shirt - Default Title", "price": "1025.00", "compare_at_price": null, "sku": "", "position": 1, "is_in_stock": true, "available_for_sale": true, "sellable_online_quantity": 50, "selected_options": [ { "name": "Title", "value": "Default Title" } ] } ], "metafields": [] } ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessQueryRecommendationsError" } } } } } } } }, "components": { "schemas": { "TopRecommendationsRequest": { "type": "object", "required": [ "strategy", "view" ], "properties": { "strategy": { "type": "string", "description": "Ranking strategy to apply", "enum": [ "BESTSELLERS", "NEW_ARRIVALS", "TRENDING" ] }, "strategy_options": { "type": "object", "description": "Strategy-specific tuning. Currently only BESTSELLERS uses this.", "properties": { "sales_time_period": { "type": "integer", "description": "BESTSELLERS only. Sales window in days. Defaults to 7.", "enum": [ 7, 15, 30 ] } } }, "view": { "type": "string", "description": "Response shape for each product entry.", "enum": [ "product_details", "product_ids" ] }, "query": { "type": "string", "description": "Optional free-text query. Applied as a multi_match across title, description, tags, vendor, and product_type. The strategy sort still wins; products matching the text query rank by sales/recency/trending score, not BM25." }, "filter": { "type": "object", "description": "Same filter shape as `/recommendations/automatic`, extended with `excluded_tags`, `collections`, `product_types`, and `price`.", "properties": { "variants": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Option name (e.g. Size, Color)" }, "value": { "type": "string", "description": "Option value" } } } }, "is_in_stock": { "type": "boolean", "description": "Match products with at least one in-stock variant." }, "sku": { "type": "array", "items": { "type": "string" }, "description": "Match products with at least one of the given SKUs." }, "available_for_sale": { "type": "boolean", "description": "Match products with at least one variant available for sale." } } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Include products carrying any of these tags. **Also accepts a comma-separated string** (e.g. `\"new,sale,featured\"`) for clients whose serializers can't construct arrays." }, "excluded_tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude products carrying any of these tags. **Also accepts a comma-separated string** (e.g. `\"clearance,discontinued\"`)." }, "vendors": { "type": "array", "items": { "type": "string" }, "description": "Include products from these vendors. **Also accepts a comma-separated string** (e.g. `\"UGREEN,Anker\"`)." }, "product_types": { "type": "array", "items": { "type": "string" }, "description": "Include products of these product types. **Also accepts a comma-separated string** (e.g. `\"Cable,Hub\"`)." }, "collections": { "type": "array", "items": { "type": "string" }, "description": "Include products belonging to any of these collection IDs. **Also accepts a comma-separated string** (e.g. `\"345678901,456789012\"`)." }, "price": { "type": "object", "properties": { "min": { "type": "number", "description": "Minimum price (inclusive)." }, "max": { "type": "number", "description": "Maximum price (inclusive)." } } }, "metafields": { "type": "array", "items": { "type": "object", "required": [ "namespace", "key", "value" ], "properties": { "namespace": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } }, "description": "Match products with these metafield namespace/key/value combinations." } } }, "facets": { "type": "array", "items": { "type": "string", "enum": [ "vendor", "product_type", "tag", "price" ] }, "description": "Facet dimensions to return alongside the products. Facets are computed only when this array is non-empty." }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor from a previous response. When provided, `filter`, `query`, and `strategy` must stay identical to the request that produced it." }, "limit": { "type": "integer", "description": "Page size (1-100). Default 24.", "minimum": 1, "maximum": 100 } } } } }, "TopRecommendationsResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "serve_id": { "type": "string", "description": "Unique identifier for this serve." }, "strategy": { "type": "string", "description": "Echo of the ranking strategy that produced the results." }, "products": { "type": "array", "items": { "type": "object", "description": "Same product object as the other v3 headless endpoints (product_details view). With product_ids view, each entry is `{ product_id }` only." } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` when there are no more pages." }, "hasMore": { "type": "boolean", "description": "Whether more pages exist. Equivalent to `cursor !== null`." }, "total": { "type": "integer", "description": "Total matching products. Capped at 10,000 by ES default — see `totalRelation`." }, "totalRelation": { "type": "string", "enum": [ "eq", "gte" ], "description": "Whether `total` is exact (`eq`) or a lower bound (`gte`)." }, "limit": { "type": "integer" } } }, "facets": { "type": "object", "description": "Present only when the request specified `facets`. Each requested dimension is a top-level key.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "count": { "type": "integer" } } } } } }, "example": { "ok": true, "serve_id": "7c3f5e8a-2b14-49c1-a7d3-93f4e2bb1c8e", "strategy": "TRENDING", "products": [ { "product_id": 8123456789012, "title": "Uno USB-C to USB-C Cable 100W", "handle": "uno-usb-c-cable-100w", "vendor": "UGREEN", "product_type": "Cable", "price": 9.34, "compare_at_price": 14.99 } ], "pagination": { "cursor": "eyJzIjpbMC44Mzc3LCI4MTIzNDU2Nzg5MDEyIl0sInNlc3Npb24iOiI1NWRhNDYzOS01MjE2LTRhODItYjJjZS01MWE1NzJmYzM1YzQifQ==", "hasMore": true, "total": 327, "totalRelation": "eq", "limit": 24 }, "facets": { "vendor": [ { "value": "UGREEN", "count": 142 }, { "value": "Anker", "count": 98 } ], "price": [ { "min": 0, "max": 50, "count": 210 }, { "min": 50, "max": 100, "count": 78 }, { "min": 100, "max": 250, "count": 39 } ] } } }, "AutomaticRecommendationsRequest": { "type": "object", "required": [ "product_ids", "recommendation_type", "view" ], "properties": { "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of product IDs to get recommendations for" }, "recommendation_type": { "type": "string", "description": "Type of recommendations to retrieve", "enum": [ "similar_products" ] }, "view": { "type": "string", "description": "Context where recommendations will be displayed", "enum": [ "product_details", "product_ids" ] }, "filter": { "type": "object", "properties": { "variants": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Option name" }, "value": { "type": "string", "description": "Option value" } } } }, "is_in_stock": { "type": "boolean", "description": "Filter by in-stock status" }, "sku": { "type": "array", "items": { "type": "string" }, "description": "Filter by SKU" }, "available_for_sale": { "type": "boolean", "description": "Filter by availability for sale" } } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by product tags" }, "vendors": { "type": "array", "items": { "type": "string" }, "description": "Filter by product vendors" }, "metafields": { "type": "array", "items": { "type": "object", "required": [ "namespace", "key", "value" ], "properties": { "namespace": { "type": "string", "description": "Metafield namespace" }, "key": { "type": "string", "description": "Metafield key" }, "value": { "type": "string", "description": "Metafield value" } } }, "description": "Filter by product metafields" } } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor for pagination" }, "limit": { "type": "integer", "description": "Number of results to return per page. Minimum is 1 and maximum is 50", "minimum": 1, "maximum": 50 } } } } }, "AutomaticRecommendationsResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response", "enum": [ "ok" ] }, "serve_id": { "type": "string", "description": "Unique identifier for this recommendation serve" }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor for pagination" } } }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Unique identifier of the product" }, "title": { "type": "string", "description": "Title of the product" }, "price": { "type": "number", "description": "Price of the product" }, "tags": { "type": "string", "description": "Comma-separated list of product tags" }, "product_type": { "type": "string", "description": "Type/category of the product" }, "vendor": { "type": "string", "description": "Vendor/brand of the product" }, "image": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the image" }, "url": { "type": "string", "description": "URL of the product image" }, "height": { "type": "integer", "description": "Height of the image in pixels" }, "width": { "type": "integer", "description": "Width of the image in pixels" }, "altText": { "type": "string", "description": "Alternative text for the image" } } }, "handle": { "type": "string", "description": "URL handle/slug for the product" }, "compare_at_price": { "type": "number", "description": "Original/compare at price of the product" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the option" }, "name": { "type": "string", "description": "Name of the option (e.g. Size, Color)" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Available values for this option" }, "position": { "type": "integer", "description": "Display position of this option" } } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Unique identifier of the variant" }, "title": { "type": "string", "description": "Title of the variant" }, "display_name": { "type": "string", "description": "Display name of the variant" }, "position": { "type": "integer", "description": "Display position of the variant" }, "sku": { "type": "string", "description": "SKU of the variant" }, "selected_options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the option" }, "value": { "type": "string", "description": "Selected value for this option" } } } }, "price": { "type": "string", "description": "Price of the variant" }, "compare_at_price": { "type": "string", "nullable": true, "description": "Original/compare at price of the variant" }, "is_in_stock": { "type": "boolean", "description": "Whether the variant is in stock" }, "available_for_sale": { "type": "boolean", "description": "Whether the variant is available for sale" }, "sellable_online_quantity": { "type": "integer", "description": "Quantity available for online sale" } } } }, "metafields": { "type": "array", "description": "Product metafields", "items": { "type": "object" } } } } } }, "example": { "status": "ok", "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "pagination": { "cursor": null }, "products": [ { "product_id": 9311227838783, "title": "Classic Cotton T-Shirt", "handle": "classic-cotton-t-shirt", "price": 1025, "compare_at_price": null, "tags": "cotton,casual,bestseller", "product_type": "T-Shirts", "vendor": "BrandName", "image": { "id": "gid://shopify/ProductImage/123456", "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg", "altText": "Classic Cotton T-Shirt", "width": 1600, "height": 1600 }, "options": [ { "id": 123, "name": "Title", "position": 1, "values": [ "Default Title" ] } ], "variants": [ { "variant_id": 48328566276415, "title": "Default Title", "display_name": "Classic Cotton T-Shirt - Default Title", "price": "1025.00", "compare_at_price": null, "sku": "", "position": 1, "is_in_stock": true, "available_for_sale": true, "sellable_online_quantity": 50, "selected_options": [ { "name": "Title", "value": "Default Title" } ] } ], "metafields": [] } ] } }, "AutomaticRecommendationsError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Human readable error message" }, "path": { "type": "array", "items": { "type": "string" }, "description": "Path to the field that caused the error" }, "type": { "type": "string", "description": "Type of validation error" }, "context": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum allowed value" }, "value": { "type": "number", "description": "Actual value provided" }, "label": { "type": "string", "description": "Field label" }, "key": { "type": "string", "description": "Field key" } } } } } } } }, "HeadlessQueryRecommendationsRequest": { "type": "object", "required": [ "queries" ], "properties": { "client_id": { "type": "string", "description": "Client identifier" }, "user_id": { "type": "string", "description": "User identifier" }, "customer_id": { "type": "string", "description": "Customer identifier" }, "queries": { "type": "array", "items": { "type": "object", "required": [ "id", "recommendation_type", "product_ids", "view" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the query" }, "recommendation_type": { "type": "string", "description": "Type of recommendations to retrieve", "enum": [ "bought_together", "similar_products" ] }, "max_recommendations": { "type": "integer", "description": "Maximum number of recommendations to return. Minimum is 1 and maximum is 50", "minimum": 1, "maximum": 50 }, "product_ids": { "description": "List of product IDs to get recommendations for. Accepts either a JSON array of integers or a comma-separated string. Maximum 10 IDs.\n\nExamples:\n- Array: `[123, 456]`\n- CSV string: `\"123,456\"`", "oneOf": [ { "title": "integer[]", "type": "array", "items": { "type": "integer" }, "maxItems": 10, "example": [ 123, 456 ] }, { "title": "string (CSV)", "type": "string", "example": "123,456", "description": "Comma-separated product IDs (e.g. \"123,456\")" } ] }, "creation_type": { "type": "string", "description": "Type of recommendation creation method", "enum": [ "manual", "automatic" ] }, "view": { "type": "string", "description": "Format of the recommendations response", "enum": [ "product_details", "product_ids" ] } } } } } }, "HeadlessQueryRecommendationsProductDetailsResponse": { "type": "object", "required": [ "status", "serve_id", "data" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Response status" }, "serve_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this recommendation serve request" }, "data": { "type": "object", "description": "Recommendation results keyed by query ID", "additionalProperties": { "type": "object", "properties": { "recommendation_serve_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this specific recommendation serve" }, "recommendation_type": { "type": "string", "enum": [ "similar_products", "bought_together" ], "description": "Type of recommendations returned" }, "max_recommendations": { "type": "integer", "description": "Maximum number of recommendations requested" }, "creation_type": { "type": "string", "nullable": true, "enum": [ "automatic", "manual", null ], "description": "Recommendation creation method used" }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Product IDs from the request (parsed from array or CSV)" }, "view": { "type": "string", "enum": [ "product_ids", "product_details" ], "description": "Response format that was requested" }, "recommendations": { "type": "array", "description": "List of recommended products. Structure depends on the `view` parameter.", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Shopify product ID" }, "title": { "type": "string", "description": "Product title (only when view = product_details)" }, "handle": { "type": "string", "description": "Product URL handle (only when view = product_details)" }, "price": { "type": "number", "description": "Product price (only when view = product_details)" }, "compare_at_price": { "type": "number", "nullable": true, "description": "Original price before discount (only when view = product_details)" }, "image": { "type": "object", "description": "Product featured image (only when view = product_details)", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "altText": { "type": "string", "nullable": true }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "tags": { "type": "string", "description": "Comma-separated product tags (only when view = product_details)" }, "options": { "type": "array", "description": "Product options (only when view = product_details)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "variants": { "type": "array", "description": "Product variants (only when view = product_details)", "items": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Shopify variant ID" }, "title": { "type": "string" }, "display_name": { "type": "string" }, "price": { "type": "string", "description": "Price as string with decimals" }, "compare_at_price": { "type": "string", "nullable": true }, "sku": { "type": "string" }, "position": { "type": "integer" }, "is_in_stock": { "type": "boolean" }, "available_for_sale": { "type": "boolean" }, "sellable_online_quantity": { "type": "integer" }, "selected_options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } } }, "metafields": { "type": "array", "description": "Product metafields (only when view = product_details)", "items": { "type": "object" } } } } } } } } }, "example": { "status": "ok", "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": { "rec-1": { "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "recommendation_type": "similar_products", "max_recommendations": 10, "creation_type": "automatic", "product_ids": [ 123, 456 ], "view": "product_details", "recommendations": [ { "product_id": 9311227838783, "title": "Classic Cotton T-Shirt", "handle": "classic-cotton-t-shirt", "price": 1025, "compare_at_price": null, "image": { "id": "gid://shopify/ProductImage/123456", "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg", "altText": "Classic Cotton T-Shirt", "width": 1600, "height": 1600 }, "tags": "cotton,casual,bestseller", "options": [ { "id": 123, "name": "Title", "position": 1, "values": [ "Default Title" ] } ], "variants": [ { "variant_id": 48328566276415, "title": "Default Title", "display_name": "Classic Cotton T-Shirt - Default Title", "price": "1025.00", "compare_at_price": null, "sku": "", "position": 1, "is_in_stock": true, "available_for_sale": true, "sellable_online_quantity": 50, "selected_options": [ { "name": "Title", "value": "Default Title" } ] } ], "metafields": [] } ] } } } }, "HeadlessQueryRecommendationsError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Human readable error message" }, "path": { "type": "array", "items": { "type": "string" }, "description": "Path to the field that caused the error" }, "type": { "type": "string", "description": "Type of validation error" }, "context": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum allowed value" }, "value": { "type": "number", "description": "Actual value provided" }, "label": { "type": "string", "description": "Field label" }, "key": { "type": "string", "description": "Field key" } } } } } } } }, "HeadlessInitRequest": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Anonymous visitor identifier (persisted across sessions)" }, "client_id": { "type": "string", "description": "Client/device identifier for the current session" }, "customer_id": { "type": "string", "description": "Shopify customer ID for authenticated visitors" }, "page_type": { "type": "string", "description": "Type of the current page", "enum": [ "home", "product", "collection", "cart", "checkout", "order_status", "search", "other" ] }, "page_url": { "type": "string", "description": "Full URL of the current page" } } }, "HeadlessInitResponse": { "type": "object", "properties": { "visit_id": { "type": "string", "description": "Unique identifier for this visit session" }, "user_id": { "type": "string", "description": "Anonymous visitor identifier to persist on the client" }, "client_id": { "type": "string", "description": "Client/device identifier" }, "customer_id": { "type": "string", "description": "Shopify customer ID if authenticated" }, "visitor": { "type": "object", "description": "Visitor's historical activity context", "properties": { "browsed_products": { "type": "array", "items": { "type": "integer" }, "description": "Product IDs recently viewed by the visitor" }, "cart_products": { "type": "array", "items": { "type": "integer" }, "description": "Product IDs currently in the visitor's cart" }, "purchased_products": { "type": "array", "items": { "type": "integer" }, "description": "Product IDs previously purchased by the visitor" } } }, "config": { "type": "object", "description": "Shop configuration relevant to the storefront", "properties": { "shop": { "type": "object", "properties": { "money_format": { "type": "string", "description": "Shopify money format string" }, "currency": { "type": "string", "description": "Shop's default currency code" } } }, "integrations_enabled": { "type": "boolean", "description": "Whether Glood integrations are active for this shop" }, "product_review_app": { "type": "string", "description": "Product review app integrated with the shop, if any" }, "analytics_enabled": { "type": "boolean", "description": "Whether analytics tracking is enabled" }, "skip_parent_product": { "type": "boolean", "description": "Whether to skip the parent product in recommendation results" } } }, "token": { "type": "string", "description": "Short-lived session token to include in subsequent requests" } } }, "HeadlessSectionsRequest": { "type": "object", "required": [ "page_url", "page_type", "locale" ], "properties": { "client_id": { "type": "string", "description": "Client/device identifier" }, "user_id": { "type": "string", "description": "Anonymous visitor identifier" }, "customer_id": { "type": "string", "description": "Shopify customer ID for authenticated visitors" }, "page_url": { "type": "string", "description": "Full URL of the current page" }, "page_type": { "type": "string", "description": "Type of the current page", "enum": [ "home", "product", "collection", "cart", "checkout", "order_status", "search", "other" ] }, "product_id": { "type": "integer", "description": "ID of the current product (required for product pages)" }, "cart_product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Product IDs currently in the visitor's cart" }, "locale": { "type": "string", "description": "BCP 47 locale code for the response language", "example": "en" }, "market": { "type": "string", "description": "Shopify market handle for market-specific content" }, "sections": { "type": "array", "items": { "type": "string" }, "description": "Specific section IDs to fetch. Omit to fetch all eligible sections for the page." }, "placed_sections": { "type": "array", "items": { "type": "string" }, "description": "Section IDs already rendered on the page (used to avoid duplicates)" }, "preview": { "type": "boolean", "description": "When true, returns sections in preview/draft mode" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Product tags to scope recommendation results" }, "collection": { "type": "string", "description": "Collection handle for collection-page context" }, "currency": { "type": "string", "description": "Currency code for pricing (defaults to shop currency)" }, "zipcode": { "type": "string", "description": "Visitor's zip/postal code for location-based recommendations" }, "cart_value": { "type": "number", "description": "Total value of the visitor's current cart" } } }, "HeadlessProductVariant": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Unique identifier of the variant" }, "title": { "type": "string", "description": "Title of the variant" }, "display_name": { "type": "string", "description": "Human-readable display name of the variant" }, "position": { "type": "integer", "description": "Display order position of the variant" }, "sku": { "type": "string", "description": "Stock keeping unit identifier" }, "selected_options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Option name" }, "value": { "type": "string", "description": "Selected value" } } } }, "price": { "type": "string", "description": "Variant price" }, "compare_at_price": { "type": "string", "description": "Original/compare-at price of the variant" }, "image": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "height": { "type": "integer" }, "width": { "type": "integer" }, "altText": { "type": "string" } } }, "sellable_online_quantity": { "type": "integer", "description": "Quantity available for online sale" }, "is_in_stock": { "type": "boolean", "description": "Whether the variant is currently in stock" }, "available_for_sale": { "type": "boolean", "description": "Whether the variant is available for purchase" } } }, "HeadlessProduct": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Unique identifier of the product" }, "title": { "type": "string", "description": "Title of the product" }, "price": { "type": "number", "description": "Minimum variant price for the product" }, "tags": { "type": "string", "description": "Comma-separated list of product tags" }, "product_type": { "type": "string", "description": "Type/category of the product" }, "vendor": { "type": "string", "description": "Vendor/brand of the product" }, "image": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "height": { "type": "integer" }, "width": { "type": "integer" }, "altText": { "type": "string" } } }, "handle": { "type": "string", "description": "URL handle/slug for the product" }, "compare_at_price": { "type": "number", "description": "Original/compare-at price of the product" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Option name (e.g. Size, Color)" }, "values": { "type": "array", "items": { "type": "string" } }, "position": { "type": "integer" } } } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/HeadlessProductVariant" } }, "metafields": { "type": "object", "description": "Key-value map of product metafields included per shop configuration" } } }, "HeadlessSectionsResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for this request (use for event tracking)" }, "visit_id": { "type": "string", "description": "Current visit session identifier" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Section identifier" }, "layout": { "type": "string", "description": "Display layout type for the section" }, "location": { "type": "string", "description": "Page location where the section should be rendered" }, "type": { "type": "string", "description": "Recommendation algorithm type" }, "position": { "type": "integer", "description": "Render order position among sections" }, "title": { "type": "string", "description": "Display title of the section" }, "extra": { "type": "object", "description": "Additional section-specific configuration" }, "discount_config": { "type": "object", "description": "Discount configuration applied to this section" }, "show_discount_label": { "type": "boolean", "description": "Whether to show a discount label on products" }, "translations": { "type": "object", "description": "Localised text strings for the section UI" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/HeadlessProduct" } } } } }, "product": { "$ref": "#/components/schemas/HeadlessProduct", "description": "The current page's product (populated on product pages)" }, "token": { "type": "string", "description": "Refreshed session token" }, "config": { "type": "object", "description": "Shop configuration snapshot (same shape as HeadlessInitResponse.config)" }, "experience": { "type": "object", "description": "A/B test experience assignment for this request" } } }, "HeadlessEventsRequest": { "type": "object", "required": [ "event", "session_id" ], "properties": { "event": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this event occurrence" }, "name": { "type": "string", "description": "Event name", "enum": [ "page_viewed", "product_viewed", "product_added_to_cart", "product_removed_from_cart", "cart_viewed", "checkout_started", "checkout_completed", "checkout_shipping_info_submitted", "checkout_contact_info_submitted", "checkout_address_info_submitted", "payment_info_submitted", "collection_viewed", "search_submitted", "glood:section:view", "glood:section:click", "glood:section:add_to_cart", "glood:section:render", "glood:bundle:view", "glood:bundle:click", "glood:bundle:add_to_cart", "glood:bundle:render", "glood:checkout:render", "glood:checkout:add_to_cart", "glood:checkout:offer_accept", "glood:checkout:offer_reject", "glood:checkout:click", "glood:init", "glood:customer_preference" ] }, "type": { "type": "string", "description": "Whether this is a standard Shopify web pixel event or a custom Glood event", "enum": [ "standard", "custom" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the event occurred" }, "data": { "type": "object", "description": "Event-specific payload data" }, "customData": { "type": "object", "description": "Additional custom data for Glood-specific events" } } }, "channel": { "type": "string", "description": "Storefront channel the event originated from", "enum": [ "web", "mobile", "headless", "hydrogen" ], "default": "web" }, "user_id": { "type": "string", "description": "Anonymous visitor identifier" }, "client_id": { "type": "string", "description": "Client/device identifier" }, "customer_id": { "type": "string", "description": "Shopify customer ID for authenticated visitors" }, "session_id": { "type": "string", "description": "Current session identifier (from HeadlessInitResponse.visit_id)" }, "shop_domain": { "type": "string", "description": "Shopify store URL. Required if the x-shop header is not set.", "example": "shop.myshopify.com" }, "device": { "type": "object", "description": "Device information for the client", "properties": { "type": { "type": "string", "description": "Device type (e.g. phone, tablet, desktop)" }, "os": { "type": "string", "description": "Operating system name" }, "os_version": { "type": "string", "description": "Operating system version" }, "app_version": { "type": "string", "description": "Version of the client app (for mobile channels)" } } }, "page_type": { "type": "string", "description": "Type of the page from which the event was fired", "enum": [ "home", "product", "collection", "cart", "checkout", "order_status", "search", "other" ] }, "page_url": { "type": "string", "description": "Full URL of the page from which the event was fired" }, "cart": { "type": "object", "description": "Cart state at the time of the event" }, "customer": { "type": "object", "description": "Customer information at the time of the event" }, "customer_privacy": { "type": "object", "description": "Customer consent/privacy preferences" } } }, "HeadlessEventsResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Indicates the event was accepted successfully" } } }, "Error": { "required": [ "error", "message" ], "type": "object", "properties": { "error": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }