{ "openapi": "3.1.0", "info": { "title": "Shopify Store API", "version": "1.0.0", "description": "Any Shopify storefront read as structured JSON: store detection, store profile, the full product catalog with variants, prices and stock, collections, and product images — through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/shopify-stores" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/detect-store": { "post": { "operationId": "detect-store", "tags": [ "Stores" ], "summary": "Check whether a domain is Shopify", "description": "Report whether a domain is a Shopify store, with the evidence behind the answer: which signals fired, how confident the verdict is, the store name and currency, the permanent myshopify domain behind a custom one, the theme in use, and which of products, collections and store metadata that store actually publishes. A domain that is not Shopify comes back as a normal 200 with isShopify false, so this is safe to run across a list of domains before spending requests on any of them. It works on stores that do not look like Shopify: every classic storefront answers the same endpoints regardless of theme, and a headless store is read at the myshopify domain its own markup reveals.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "type": "string", "description": "Store domain, or any URL on the store — for example example.com, https://example.com/products/foo, or a myshopify.com domain." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "store" ] }, "examples": { "default": { "value": { "store": "allbirds.com" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedUrl": { "type": "string", "description": "The store URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "When the store was read, as an ISO timestamp." }, "transport": { "type": "string", "description": "Always shopify-storefront — the upstream source this data came from." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result: a truncated walk, an upstream limit, or a field this store does not publish. Read it before treating a result as complete." }, "resultType": { "type": "string", "description": "Always store-detection." }, "domain": { "type": "string", "description": "The domain that was checked." }, "storeUrl": { "type": "string", "description": "The canonical store URL the other endpoints should be pointed at." }, "isShopify": { "type": "boolean", "description": "Whether this domain is a Shopify store." }, "confidence": { "type": "string", "description": "confirmed when a decisive signal matched, likely when only indirect evidence did, no when nothing did." }, "signals": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Each check that ran and what it found: platform-header, storefront-cookie, cdn-assets, storefront-runtime, product-catalog, store-metadata." }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Whether the store publishes products, collections and store-metadata, with the status code each returned. A store can switch any of them off." }, "storeName": { "type": "string", "description": "The store's name, when its storefront publishes one." }, "currency": { "type": "string", "description": "The currency the storefront prices in." }, "permanentDomain": { "type": "string", "description": "The store's myshopify.com address, when the storefront reveals it. This is how a headless store is read." }, "theme": { "type": "object", "additionalProperties": true, "description": "The storefront theme: name, id, role, and the theme store id for an off-the-shelf theme (null for a custom one)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "store-detection", "domain": "allbirds.com", "storeUrl": "https://allbirds.com", "isShopify": true, "confidence": "confirmed", "storeName": "Allbirds", "currency": "USD", "permanentDomain": "allbirds.myshopify.com", "signals": [ { "name": "platform-header", "detected": true, "detail": "Storefront served the Shopify platform header." } ], "endpoints": [ { "endpoint": "products", "available": true, "status": 200 } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/store-profile": { "post": { "operationId": "store-profile", "tags": [ "Stores" ], "summary": "Get a store's profile", "description": "Read what a store publishes about itself: name, description, permanent myshopify domain, store id, currency and money format, locale, country, city and province, the countries it ships to, the payment card brands it accepts and whether it offers installments, its product and collection totals, its theme, its logo and every social profile it links to.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "type": "string", "description": "Store domain, or any URL on the store — for example example.com, https://example.com/products/foo, or a myshopify.com domain." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "store" ] }, "examples": { "default": { "value": { "store": "allbirds.com" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedUrl": { "type": "string", "description": "The store URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "When the store was read, as an ISO timestamp." }, "transport": { "type": "string", "description": "Always shopify-storefront — the upstream source this data came from." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result: a truncated walk, an upstream limit, or a field this store does not publish. Read it before treating a result as complete." }, "resultType": { "type": "string", "description": "Always store-profile." }, "profile": { "type": "object", "properties": { "name": { "type": "string", "description": "The store's name, with description alongside it." }, "permanentDomain": { "type": "string", "description": "The store's myshopify.com address, when its storefront reveals it." }, "storeId": { "type": "string", "description": "The store's own id." }, "currency": { "type": "string", "description": "Selling currency, with moneyFormat, locale, country, city and province alongside it." }, "shipsToCountries": { "type": "array", "items": { "type": "string" }, "description": "Countries the storefront offers shipping to." }, "paymentCardBrands": { "type": "array", "items": { "type": "string" }, "description": "Card brands accepted at checkout, with offersInstallments alongside it." }, "productCount": { "type": "number", "description": "The store's own product total, with collectionCount alongside it." }, "theme": { "type": "object", "additionalProperties": true, "description": "The storefront theme: name, id, role and theme store id." }, "socialLinks": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Linked profiles on Instagram, Facebook, TikTok, X, YouTube, Pinterest, LinkedIn, Snapchat and Threads." }, "logoUrl": { "type": "string", "description": "The store's logo, when its storefront publishes one." } }, "additionalProperties": false }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Whether the store publishes products, collections and store-metadata." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "store-profile", "profile": { "domain": "allbirds.com", "name": "Allbirds", "currency": "USD", "locale": "en", "country": "US", "productCount": 412, "collectionCount": 38, "socialLinks": [ { "platform": "instagram", "url": "https://instagram.com/allbirds" } ] }, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/products": { "post": { "operationId": "products", "tags": [ "Catalog" ], "summary": "List a store's products", "description": "Walk a store's catalog. Each product comes back with its title, handle, vendor, product type, tags, description as plain text and as HTML, publish and update timestamps, every image with its dimensions, the full option matrix, and every variant with price, compare-at price, SKU, barcode, option values, weight and availability — plus the product's price range, currency and whether anything on it is discounted. Collect several pages in one request with pages, or resume with a previous response's nextCursor. Per-unit stock is not published here; use /product-detail for that.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "type": "string", "description": "Store domain, or any URL on the store — for example example.com, https://example.com/products/foo, or a myshopify.com domain." }, "limit": { "type": "number", "description": "Maximum items returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 40), or -1 for the maximum allowed. Each page counts as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "store" ] }, "examples": { "default": { "value": { "store": "allbirds.com", "limit": 50, "pages": 2 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedUrl": { "type": "string", "description": "The store URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "When the store was read, as an ISO timestamp." }, "transport": { "type": "string", "description": "Always shopify-storefront — the upstream source this data came from." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result: a truncated walk, an upstream limit, or a field this store does not publish. Read it before treating a result as complete." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "resultType": { "type": "string", "description": "Always product-list." }, "domain": { "type": "string", "description": "The store the products came from." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product's id on the store." }, "handle": { "type": "string", "description": "The product's identifier in its store URL — what product-detail takes." }, "title": { "type": "string", "description": "Product title." }, "productUrl": { "type": "string", "description": "Canonical product page URL on the store." }, "vendor": { "type": "string", "description": "Vendor or brand the store attributes the product to." }, "productType": { "type": "string", "description": "The store's own product type for this item." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Merchandising tags, often the store's internal taxonomy." }, "description": { "type": "string", "description": "Description as plain text; descriptionHtml carries the original markup." }, "publishedAt": { "type": "string", "description": "When the product was published, and createdAt / updatedAt alongside it." }, "images": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every image, each with url, downloadUrl, width, height, position, altText and the variants it belongs to." }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The choices a buyer makes — for example Size and the sizes available." }, "variants": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "inventoryQuantity": { "type": "number", "description": "Units on hand. Published only by product-detail, and only by stores that track inventory." } } }, "description": "Every buyable version, with price, compareAtPrice, sku, barcode, optionValues, grams, requiresShipping, taxable and available." }, "variantsTruncated": { "type": "boolean", "description": "True when the product has more variants than the store publishes; the first 250 are returned." }, "priceMin": { "type": "string", "description": "Lowest variant price, with priceMax and currency alongside it." }, "available": { "type": "boolean", "description": "True when at least one variant can be bought." }, "onSale": { "type": "boolean", "description": "True when at least one variant carries a compareAtPrice above its price." } } }, "description": "The products, in the order the store publishes them." }, "productCount": { "type": "number", "description": "Number of products in this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-list", "domain": "allbirds.com", "productCount": 50, "pagesScraped": 2, "hasNextPage": true, "nextCursor": "cGFnZT0z", "products": [ { "handle": "mens-tree-runners", "title": "Men's Tree Runners", "vendor": "Allbirds", "priceMin": "98.00", "priceMax": "98.00", "currency": "USD", "onSale": false, "variants": [ { "sku": "TR-M-10-NAT", "title": "10 / Natural White", "price": "98.00", "compareAtPrice": null, "available": true } ] } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-detail": { "post": { "operationId": "product-detail", "tags": [ "Catalog" ], "summary": "Get one product in full", "description": "Read everything a store publishes about a single product, from its URL or from its handle plus the store: the complete description in both plain text and HTML, every image with dimensions and alt text, the option matrix, and every variant with price, compare-at price, SKU, barcode, weight, taxability and stock. This is the only endpoint that returns inventoryQuantity, and only for stores that track inventory.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "Product URL, or the product's handle as it appears in the URL." }, "store": { "type": "string", "description": "Required only when product is a handle rather than a full URL." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "product" ] }, "examples": { "default": { "value": { "product": "https://allbirds.com/products/mens-tree-runners" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedUrl": { "type": "string", "description": "The store URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "When the store was read, as an ISO timestamp." }, "transport": { "type": "string", "description": "Always shopify-storefront — the upstream source this data came from." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result: a truncated walk, an upstream limit, or a field this store does not publish. Read it before treating a result as complete." }, "resultType": { "type": "string", "description": "Always product-detail." }, "domain": { "type": "string", "description": "The store the product came from." }, "handle": { "type": "string", "description": "The resolved product handle." }, "product": { "type": "object", "additionalProperties": true, "description": "The full product record, or null when the store has no such product.", "properties": { "variants": { "type": "array", "items": { "type": "object", "properties": { "inventoryQuantity": { "type": "number", "description": "Units on hand, for stores that track and publish inventory. Null where they do not." } }, "additionalProperties": false } }, "variantsTruncated": { "type": "boolean", "description": "True when the product carries more than the 250 variants the store publishes." }, "images": { "type": "array", "items": { "type": "object", "properties": { "downloadUrl": { "type": "string", "description": "Pass to GET /media to stream the image bytes through FetchLayer." } }, "additionalProperties": false } } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-detail", "domain": "allbirds.com", "handle": "mens-tree-runners", "product": { "title": "Men's Tree Runners", "priceMin": "98.00", "currency": "USD", "variantCount": 24, "variants": [ { "sku": "TR-M-10-NAT", "price": "98.00", "available": true, "inventoryQuantity": 112 } ] }, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/collections": { "post": { "operationId": "collections", "tags": [ "Catalog" ], "summary": "List collections, or one collection's products", "description": "See how a store organizes its catalog, or read one of those groups. Without collection, this returns the store's collections with their titles, handles, descriptions, images and product counts. With a collection URL or handle, it returns that collection's products in the same full shape /products returns. Both forms page with pages and cursor. A collection's reported productCount is the store's own number and can exceed what the collection actually returns.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "type": "string", "description": "Store domain, or any URL on the store — for example example.com, https://example.com/products/foo, or a myshopify.com domain." }, "collection": { "type": "string", "description": "Collection URL or handle. Omit to list the store's collections; supply it to get that collection's products." }, "limit": { "type": "number", "description": "Maximum items returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 40), or -1 for the maximum allowed. Each page counts as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "store" ] }, "examples": { "default": { "value": { "store": "allbirds.com", "collection": "mens-shoes", "limit": 100 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedUrl": { "type": "string", "description": "The store URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "When the store was read, as an ISO timestamp." }, "transport": { "type": "string", "description": "Always shopify-storefront — the upstream source this data came from." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result: a truncated walk, an upstream limit, or a field this store does not publish. Read it before treating a result as complete." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "resultType": { "type": "string", "description": "Always collection-list." }, "domain": { "type": "string", "description": "The store the result came from." }, "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The store's collections, each with id, handle, title, collectionUrl, description, descriptionHtml, imageUrl, productCount and timestamps. Empty when one collection was requested." }, "collectionCount": { "type": "number", "description": "Number of collections in this response." }, "collection": { "type": "object", "additionalProperties": true, "description": "The collection the products below belong to, when one was requested. Null when listing collections." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product's id on the store." }, "handle": { "type": "string", "description": "The product's identifier in its store URL — what product-detail takes." }, "title": { "type": "string", "description": "Product title." }, "productUrl": { "type": "string", "description": "Canonical product page URL on the store." }, "vendor": { "type": "string", "description": "Vendor or brand the store attributes the product to." }, "productType": { "type": "string", "description": "The store's own product type for this item." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Merchandising tags, often the store's internal taxonomy." }, "description": { "type": "string", "description": "Description as plain text; descriptionHtml carries the original markup." }, "publishedAt": { "type": "string", "description": "When the product was published, and createdAt / updatedAt alongside it." }, "images": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every image, each with url, downloadUrl, width, height, position, altText and the variants it belongs to." }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The choices a buyer makes — for example Size and the sizes available." }, "variants": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "inventoryQuantity": { "type": "number", "description": "Units on hand. Published only by product-detail, and only by stores that track inventory." } } }, "description": "Every buyable version, with price, compareAtPrice, sku, barcode, optionValues, grams, requiresShipping, taxable and available." }, "variantsTruncated": { "type": "boolean", "description": "True when the product has more variants than the store publishes; the first 250 are returned." }, "priceMin": { "type": "string", "description": "Lowest variant price, with priceMax and currency alongside it." }, "available": { "type": "boolean", "description": "True when at least one variant can be bought." }, "onSale": { "type": "boolean", "description": "True when at least one variant carries a compareAtPrice above its price." } } }, "description": "The products, in the order the store publishes them." }, "productCount": { "type": "number", "description": "Number of products in this response. Zero when listing the store's collections." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "collection-list", "domain": "allbirds.com", "collections": [], "collectionCount": 0, "collection": { "handle": "mens-shoes", "title": "Men's Shoes", "productCount": 64 }, "productCount": 64, "hasNextPage": false, "nextCursor": null, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Media" ], "summary": "Download a product image", "description": "Stream a product image file, using a url taken from an image returned by /products or /product-detail. Only store image hosts are accepted. HTTP Range requests are supported, so a partial fetch works. This is a GET with query parameters, not a JSON POST, and it bills as one request.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Product image URL, as returned on a product image. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a store URL", "description": "Turn any store URL into the fields the other endpoints take: whether it points at a product, a collection or the store itself, plus the domain, the canonical store URL, the handle, the selected variant id and the permanent myshopify domain. It makes no request to the store, so it is the cheap way to find out what a pasted URL is before spending a request on it. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any store URL, to be parsed into structured fields." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://allbirds.com/products/mens-tree-runners?variant=39812345678901" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: product, collection, store, or unknown." }, "url": { "type": "string", "description": "The URL that was parsed." }, "domain": { "type": "string", "description": "The store domain carried in the URL." }, "storeUrl": { "type": "string", "description": "The canonical store URL to pass as store elsewhere." }, "targetUrl": { "type": "string", "description": "The canonical URL of the product or collection the URL points at." }, "handle": { "type": "string", "description": "The product or collection handle, when the URL carries one." }, "variantId": { "type": "string", "description": "The variant selected in the URL query string, when there is one." }, "permanentDomain": { "type": "string", "description": "The myshopify.com domain, when the URL is one." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "product", "domain": "allbirds.com", "storeUrl": "https://allbirds.com", "handle": "mens-tree-runners", "variantId": "39812345678901", "permanentDomain": null } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }