{"openapi":"3.1.0","info":{"title":"Birdy Grey Catalog API","description":"The Birdy Grey Catalog API gives partners structured, real-time access to our product catalog — what we sell, in which fabrics and colors, in which sizes, and what's currently in stock.\n\n## Endpoints\n\n- **`GET /products`** — browse the catalog with optional filtering by fabric, color, and category\n- **`GET /products/rush`** — find ready-to-ship products by fabric, color, and size, optionally narrowed by exact rush fee\n- **`GET /fabrics`**, **`/sizes`** — list the distinct attribute values available in a catalog, narrowed by `category` (Shopify `product_type`, defaults to `Bridesmaid Dress`) and/or `type`\n- **`GET /colors`** — list the distinct color values available in a catalog, narrowed by `category` (Shopify `product_type`, defaults to `Bridesmaid Dress`) and/or `type`\n- **`GET /types`** — list the distinct `attr.type` values within a catalog (selected by `category`, defaults to `Bridesmaid Dress`); use these as values for the `type` filter on the endpoints above\n\n## Authentication\n\nEvery endpoint requires an API key. Birdy Grey issues your key directly; pass it on every request as the `x-api-key` header.\n\n## Pagination\n\n`/products` and `/products/rush` are paginated. Each response includes a `pageInfo` object with `nextCursor` and `hasMore`. Pass the cursor as `?after=<cursor>` to fetch the next page.\n\n## Defaults\n\nThe `category` parameter defaults to `Bridesmaid Dress` (Birdy Grey's primary product line). Pass `?category=Little White Dress` to browse another catalog, and an optional `?type=Jumpsuit` to narrow to a specific product type within a category.","version":"0.1.0"},"servers":[{"url":"http://localhost:8080","description":"Local"},{"url":"https://api.birdystaging.com","description":"Staging"},{"url":"https://api.birdygrey.com","description":"Production"}],"paths":{"/catalog/products":{"get":{"operationId":"getCatalogProducts","description":"Returns the in-stock product catalog. Each product carries a `variants` array — one entry per available variant — plus a product-level `rushFee` (the Rush Production surcharge, or null). Products with no available variant are omitted.\n\n**Variants** — each has its own `variantId` (full Shopify GID), `sku`, `size`, `estimatedArrival`, `price`, and `inventory`:\n- `estimatedArrival` is the Shopify option value (e.g. `Rush Production` / `Standard Production`); a variant with no such option reports `Rush Production` as inherently ready-to-ship.\n- A variant is \"available\" when it has stock (`inventoryQuantity > 0`) **or** continues selling when out of stock (covers Standard/Made-to-Order production).\n- `inventory` is the hard cap for capped variants and `null` for continue-selling ones.\n\n**Pagination** — default `limit=50` (counts products); use `pageInfo.nextCursor` to page. `count` is the number of products in this response, not the total across all pages.\n\nUse `GET /products/rush` for size-specific Rush Production availability (real stock only).","responses":{"200":{"description":"In-stock products, each with a variants array and a pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"style":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"type":"string"},"category":{"type":"string"},"vendor":{"type":"string"},"type":{"type":"string"},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","size","estimatedArrival","price","inventory"]}},"image":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["url","alt","width","height"]},{"type":"null"}]}},"required":["handle","style","title","url","fabric","color","category","vendor","type","rushFee","variants","image"]}},{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"title":{"type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["handle","title","image","price"]}}]},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"required":["nextCursor","hasMore"]}},"required":["count","values","pageInfo"]},"examples":{"full":{"value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","style":"Theresa","title":"Theresa Chiffon Dress - Dusty Blue","url":"https://www.birdygrey.com/products/theresa-chiffon-dress-dusty-blue","fabric":"Chiffon","color":"Dusty Blue","category":"Bridesmaid Dress","vendor":"Birdy Grey","type":"Dress","rushFee":{"amount":8,"currency":"USD"},"variants":[{"variantId":"gid://shopify/ProductVariant/42629933989958","sku":"BG068BL0018002","size":"S","estimatedArrival":"Rush Production","price":{"amount":99,"currency":"USD"},"inventory":2},{"variantId":"gid://shopify/ProductVariant/42629933989965","sku":"BG068BL0018003","size":"M","estimatedArrival":"Standard Production","price":{"amount":99,"currency":"USD"},"inventory":null}],"image":{"url":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","alt":"Theresa Chiffon Dress in Dusty Blue","width":1200,"height":1800}}],"pageInfo":{"nextCursor":"eyJsYXN0X2lkIjo0MjYyOTkzMzk4OTk2NX0","hasMore":true}}},"compact":{"summary":"view=compact","value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","title":"Theresa Chiffon Dress - Dusty Blue","image":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","price":99}],"pageInfo":{"nextCursor":null,"hasMore":false}}}}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"@bad","expected":"/^[\\p{L}\\p{M}\\p{N} &'/-]+$/u","received":"\"@bad\"","message":"Invalid format: Expected /^[\\p{L}\\p{M}\\p{N} &'/-]+$/u but received \"@bad\"","path":[{"type":"object","origin":"value","key":"color","value":"@bad"},{"type":"array","origin":"value","key":0,"value":"@bad"}]}],"data":{"color":"@bad"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"fabric","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Chiffon"},"description":"Filter by fabric. Comma-delimited for multiple values, combined with OR (e.g. `Chiffon,Crepe`). Up to 20 values."},{"in":"query","name":"color","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Sage"},"description":"Filter by color. Comma-delimited for multiple values, combined with OR (e.g. `Sage,Navy`). Up to 20 values."},{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog. Groups the underlying `attr.type` values (Dress, Jumpsuit, Set) so all are returned together. Single-valued."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Jumpsuit"},"description":"Optional product-type (`attr.type`) narrow within the category, e.g. `Jumpsuit`. Omit to return the whole category. Single-valued."},{"in":"query","name":"size","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 ]+$"},"minItems":1,"maxItems":20,"example":"M"},"description":"Narrow the returned variants to these sizes (drops products with no matching available variant). Comma-delimited for multiple (e.g. `S,M,L`). Up to 20 values."},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$","minimum":1,"maximum":250,"default":"50"},"description":"Max products per page (1-250). Defaults to 50."},{"in":"query","name":"after","schema":{"type":"string","minLength":1,"maxLength":500},"description":"Pagination cursor from a prior response (its `pageInfo.nextCursor`)."},{"in":"query","name":"view","schema":{"type":"string","enum":["full","compact"],"example":"compact","default":"full"},"description":"`compact` returns only `handle`, `title`, `image` (URL) and `price` per product. Defaults to `full`."}]}},"/catalog/products/rush":{"get":{"operationId":"getCatalogProductsRush","description":"Returns ready-to-ship products for the given `fabric`/`color`/`size`. Each product carries a `variants` array — one entry per rush-eligible variant (ships Rush Production, `inventory > 0`) matching the requested size(s); a product matching several sizes still appears once, with all matching variants in its array.\n\n**Variants** — each has its own `variantId` (full Shopify GID, ready to POST to cartographer `/lines`), `sku` (shared by the Standard and Rush Production variants of a size), `size`, `estimatedArrival` (raw Shopify option value, e.g. `Rush Production`), `price`, and `inventory`. The product-level `rushFee` applies to every variant.\n\n**Pagination** — `count` is the number of products in this response. Omit `limit` to fetch all matches (subject to an internal safety cap); resume via `pageInfo.nextCursor` when `pageInfo.hasMore` is true.","responses":{"200":{"description":"Ready-to-ship products, each with a variants array and a pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"style":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"type":"string"},"category":{"type":"string"},"vendor":{"type":"string"},"type":{"type":"string"},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","size","estimatedArrival","price","inventory"]}},"image":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["url","alt","width","height"]},{"type":"null"}]}},"required":["handle","style","title","url","fabric","color","category","vendor","type","rushFee","variants","image"]}},{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"title":{"type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["handle","title","image","price"]}}]},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"required":["nextCursor","hasMore"]}},"required":["count","values","pageInfo"]},"examples":{"full":{"value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","style":"Theresa","title":"Theresa Chiffon Dress - Dusty Blue","url":"https://www.birdygrey.com/products/theresa-chiffon-dress-dusty-blue","fabric":"Chiffon","color":"Dusty Blue","category":"Bridesmaid Dress","vendor":"Birdy Grey","type":"Dress","rushFee":{"amount":8,"currency":"USD"},"variants":[{"variantId":"gid://shopify/ProductVariant/42629933989965","sku":"BG068BL0018003","size":"M","estimatedArrival":"Rush Production","price":{"amount":99,"currency":"USD"},"inventory":8},{"variantId":"gid://shopify/ProductVariant/42629933989972","sku":"BG068BL0018004","size":"L","estimatedArrival":"Rush Production","price":{"amount":99,"currency":"USD"},"inventory":3}],"image":{"url":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","alt":"Theresa Chiffon Dress in Dusty Blue","width":1200,"height":1800}}],"pageInfo":{"nextCursor":null,"hasMore":false}}},"compact":{"summary":"view=compact","value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","title":"Theresa Chiffon Dress - Dusty Blue","image":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","price":99}],"pageInfo":{"nextCursor":null,"hasMore":false}}}}}}},"400":{"description":"Missing or invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"@bad","expected":"/^[A-Za-z0-9 ]+$/","received":"\"@bad\"","message":"Invalid format: Expected /^[A-Za-z0-9 ]+$/ but received \"@bad\"","path":[{"type":"object","origin":"value","key":"size","value":"@bad"},{"type":"array","origin":"value","key":0,"value":"@bad"}]}],"data":{"fabric":"Chiffon","color":"Sage","size":"@bad"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"fabric","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Chiffon"},"description":"Filter by fabric. Comma-delimited for multiple values, combined with OR (e.g. `Chiffon,Crepe`). Up to 20 values. Omit to match across all fabrics."},{"in":"query","name":"color","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Sage"},"required":true,"description":"Filter by color (required). Comma-delimited for multiple values, combined with OR (e.g. `Sage,Navy`). Up to 20 values."},{"in":"query","name":"size","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 ]+$"},"minItems":1,"maxItems":20,"example":"M"},"required":true,"description":"Sizes to match (required). Each product returns its rush-eligible, in-stock variants in these sizes. Comma-delimited for multiple (e.g. `S,M,L`). Up to 20 values."},{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog. Groups the underlying `attr.type` values (Dress, Jumpsuit, Set) so all are returned together. Single-valued."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Jumpsuit"},"description":"Optional product-type (`attr.type`) narrow within the category, e.g. `Jumpsuit`. Omit to return the whole category. Single-valued."},{"in":"query","name":"fee","schema":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","minimum":0,"example":"0"},"description":"Filter to products whose rush fee equals this exact amount (e.g. `0` for products that ship Rush at no extra charge). Products with no rush_fee metafield are excluded when this filter is active."},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$","minimum":1,"maximum":250},"description":"Max products per page (1-250). Omit to fetch all matches (subject to an internal page cap)."},{"in":"query","name":"after","schema":{"type":"string","minLength":1,"maxLength":500},"description":"Pagination cursor from a prior response (its `pageInfo.nextCursor`)."},{"in":"query","name":"view","schema":{"type":"string","enum":["full","compact"],"example":"compact","default":"full"},"description":"`compact` returns only `handle`, `title`, `image` (URL) and `price` per product. Defaults to `full`."}]}},"/catalog/products/standard":{"get":{"operationId":"getCatalogProductsStandard","description":"Returns standard-production products for the given `fabric`/`color`/`size`. Each product carries a `variants` array — one entry per available Standard Production variant matching the requested size(s); a product matching several sizes still appears once, with all matching variants in its array.\n\n**Variants** — each has its own `variantId` (full Shopify GID, ready to POST to cartographer `/lines`), `sku` (shared by the Standard and Rush Production variants of a size), `size`, `estimatedArrival` (`Standard Production`), `price`, and `inventory`:\n- Standard Production is made-to-order (sells while out of stock), so a variant is included when it has stock **or** continues selling; `inventory` is `null` for continue-selling variants.\n- No `rushFee` — that surcharge is specific to Rush Production.\n\n**Pagination** — `count` is the number of products in this response. Omit `limit` to fetch all matches (subject to an internal safety cap); resume via `pageInfo.nextCursor` when `pageInfo.hasMore` is true.","responses":{"200":{"description":"Standard-production products, each with a variants array and a pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"style":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"type":"string"},"category":{"type":"string"},"vendor":{"type":"string"},"type":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","size","estimatedArrival","price","inventory"]}},"image":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["url","alt","width","height"]},{"type":"null"}]}},"required":["handle","style","title","url","fabric","color","category","vendor","type","variants","image"]}},{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"title":{"type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["handle","title","image","price"]}}]},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"required":["nextCursor","hasMore"]}},"required":["count","values","pageInfo"]},"examples":{"full":{"value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","style":"Theresa","title":"Theresa Chiffon Dress - Dusty Blue","url":"https://www.birdygrey.com/products/theresa-chiffon-dress-dusty-blue","fabric":"Chiffon","color":"Dusty Blue","category":"Bridesmaid Dress","vendor":"Birdy Grey","type":"Dress","variants":[{"variantId":"gid://shopify/ProductVariant/42629933990001","sku":"BG068BL0018003","size":"M","estimatedArrival":"Standard Production","price":{"amount":99,"currency":"USD"},"inventory":null},{"variantId":"gid://shopify/ProductVariant/42629933990018","sku":"BG068BL0018004","size":"L","estimatedArrival":"Standard Production","price":{"amount":99,"currency":"USD"},"inventory":null}],"image":{"url":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","alt":"Theresa Chiffon Dress in Dusty Blue","width":1200,"height":1800}}],"pageInfo":{"nextCursor":null,"hasMore":false}}},"compact":{"summary":"view=compact","value":{"count":1,"values":[{"handle":"theresa-chiffon-dress-dusty-blue","title":"Theresa Chiffon Dress - Dusty Blue","image":"https://cdn.shopify.com/s/files/1/birdygrey/theresa-dusty-blue.jpg","price":99}],"pageInfo":{"nextCursor":null,"hasMore":false}}}}}}},"400":{"description":"Missing or invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"@bad","expected":"/^[A-Za-z0-9 ]+$/","received":"\"@bad\"","message":"Invalid format: Expected /^[A-Za-z0-9 ]+$/ but received \"@bad\"","path":[{"type":"object","origin":"value","key":"size","value":"@bad"},{"type":"array","origin":"value","key":0,"value":"@bad"}]}],"data":{"fabric":"Chiffon","color":"Sage","size":"@bad"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"fabric","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Chiffon"},"description":"Filter by fabric. Comma-delimited for multiple values, combined with OR (e.g. `Chiffon,Crepe`). Up to 20 values. Omit to match across all fabrics."},{"in":"query","name":"color","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Sage"},"required":true,"description":"Filter by color (required). Comma-delimited for multiple values, combined with OR (e.g. `Sage,Navy`). Up to 20 values."},{"in":"query","name":"size","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 ]+$"},"minItems":1,"maxItems":20,"example":"M"},"required":true,"description":"Sizes to match (required). Each product returns its available Standard Production variants in these sizes. Comma-delimited for multiple (e.g. `S,M,L`). Up to 20 values."},{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog. Groups the underlying `attr.type` values (Dress, Jumpsuit, Set) so all are returned together. Single-valued."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Jumpsuit"},"description":"Optional product-type (`attr.type`) narrow within the category, e.g. `Jumpsuit`. Omit to return the whole category. Single-valued."},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$","minimum":1,"maximum":250},"description":"Max products per page (1-250). Omit to fetch all matches (subject to an internal page cap)."},{"in":"query","name":"after","schema":{"type":"string","minLength":1,"maxLength":500},"description":"Pagination cursor from a prior response (its `pageInfo.nextCursor`)."},{"in":"query","name":"view","schema":{"type":"string","enum":["full","compact"],"example":"compact","default":"full"},"description":"`compact` returns only `handle`, `title`, `image` (URL) and `price` per product. Defaults to `full`."}]}},"/catalog/products/back-in-stock":{"get":{"operationId":"getCatalogProductsBackInStock","description":"Returns each live product's expected back-in-stock date: the earliest incoming purchase order date across its sizes that can't currently be bought, or `null` when no such size has one. `shopifyBackInStockDate` is the date the site shows today, and `action` is the change that would bring it in line — `set` it to `backInStockDate`, `clear` it because every size can be bought, or `none`. With no filters, every live product in every category that has a date on either side is covered, and a product requested by `handle` is always returned; resume via `pageInfo.nextCursor` while `pageInfo.hasMore` is true.","responses":{"200":{"description":"Products with their back-in-stock date and the update the site needs","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"handle":{"type":"string"},"style":{"anyOf":[{"type":"string"},{"type":"null"}]},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"backInStockDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"shopifyBackInStockDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"action":{"enum":["set","clear","none"],"type":"string"}},"required":["productId","handle","style","fabric","color","type","backInStockDate","shopifyBackInStockDate","action"]}},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"required":["nextCursor","hasMore"]}},"required":["count","values","pageInfo"]},"example":{"count":1,"values":[{"productId":"gid://shopify/Product/7966113595583","handle":"grace-chiffon-dress-with-slit-sage","style":"Grace","fabric":"Chiffon","color":"Sage","type":"Dress","backInStockDate":"2027-01-03","shopifyBackInStockDate":"2026-12-20","action":"set"}],"pageInfo":{"nextCursor":"eyJsYXN0X2lkIjo3OTY2MTEzNTk1NTgzfQ==","hasMore":true}}}}},"400":{"description":"Missing or invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"schema","type":"picklist","input":"yes","expected":"(\"true\" | \"false\")","received":"\"yes\"","message":"Invalid type: Expected (\"true\" | \"false\") but received \"yes\"","path":[{"type":"object","origin":"value","key":"needsUpdate","value":"yes"}]}],"data":{"needsUpdate":"yes"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"handle","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9-]+$"},"minItems":1,"maxItems":20,"example":"grace-chiffon-dress-sage"},"description":"Exact product handles. Comma-delimited for multiple values (e.g. `grace-chiffon-dress-sage,ash-crepe-dress-taupe`). Up to 20 values."},{"in":"query","name":"style","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Grace"},"description":"Filter by style. Comma-delimited for multiple values, combined with OR (e.g. `Grace,Ash`). Up to 20 values."},{"in":"query","name":"fabric","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Chiffon"},"description":"Filter by fabric. Comma-delimited for multiple values, combined with OR (e.g. `Chiffon,Crepe`). Up to 20 values."},{"in":"query","name":"color","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Sage"},"description":"Filter by color. Comma-delimited for multiple values, combined with OR (e.g. `Sage,Navy`). Up to 20 values."},{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$","example":"Bridesmaid Dress"},"description":"Catalog category, e.g. `Bridesmaid Dress` or `Suit Jacket`. Single-valued. Omit to cover every category."},{"in":"query","name":"type","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L}\\p{M}\\p{N} &'/-]+$"},"minItems":1,"maxItems":20,"example":"Dress"},"description":"Filter by product type. Comma-delimited for multiple values, combined with OR (e.g. `Dress,Jumpsuit`). Up to 20 values."},{"in":"query","name":"needsUpdate","schema":{"enum":["true","false"],"type":"string","example":"true"},"description":"When `true`, return only products whose `action` is `set` or `clear`."},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$","minimum":1,"maximum":250},"description":"Max products per page (1-250). Omit to return every match from the products scanned in this request."},{"in":"query","name":"after","schema":{"type":"string","minLength":1,"maxLength":500},"description":"Pagination cursor from a prior response (its `pageInfo.nextCursor`)."}]}},"/catalog/colors/families":{"get":{"operationId":"getCatalogColorsFamilies","description":"Returns the shopper-facing color families (e.g. `Greens`, `Blues`) in curated display order, each with a family swatch image and its member `colors`. Member colors use the same shape as `GET /colors` and are ordered light-to-dark: real solid colors first (by luminance), then prints/florals trailing. `category` (Shopify `product_type`, default `Bridesmaid Dress`) scopes to a catalog, matching `GET /colors`; pass `All` (any case) for every catalog. Only colors currently in use on a live product appear. Used to back navigational UIs that group colors by family.","responses":{"200":{"description":"Color families with nested, light-to-dark-ordered colors","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"hex":{"anyOf":[{"type":"string"},{"type":"null"}]},"season":{"anyOf":[{"enum":["Fall","Spring","Seasonless"],"type":"string"},{"type":"null"}]},"pattern":{"anyOf":[{"enum":["Solid","Print"],"type":"string"},{"type":"null"}]},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","family","hex","season","pattern","swatch"]}}},"required":["name","swatch","colors"]}}},"required":["count","values"]},"example":{"count":12,"values":[{"name":"Greens","swatch":null,"colors":[{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#e2e8e4","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fsage.jpg"},{"id":"recDarkGreen000001","name":"Dark Green","family":"Greens","hex":"#283c36","season":"Seasonless","pattern":"Solid","swatch":null},{"id":"recSageLeFleur0001","name":"Sage Le Fleur","family":"Florals","hex":null,"season":"Spring","pattern":"Print","swatch":null}]}]}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog, or `All` (any case) for every catalog."}]}},"/catalog/colors/bundle/{id}":{"get":{"operationId":"getCatalogColorsBundleById","description":"Resolves a swatch bundle to the distinct standardized colors its child products represent. Pass the bundle product ID as a bare numeric ID (`8208881615039`) or a URL-encoded product GID (`gid%3A%2F%2Fshopify%2FProduct%2F8208881615039`). Returns the same color shape as `GET /colors` (with the stable Airtable `id`), in the bundle's component order, deduped by color (a bundle commonly repeats a color across fabrics). Colors not yet curated in the taxonomy are skipped. Responds `404` if no product matches the ID and `422` if the product exists but is not a bundle.","responses":{"200":{"description":"The bundle's distinct standardized colors","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"hex":{"anyOf":[{"type":"string"},{"type":"null"}]},"season":{"anyOf":[{"enum":["Fall","Spring","Seasonless"],"type":"string"},{"type":"null"}]},"pattern":{"anyOf":[{"enum":["Solid","Print"],"type":"string"},{"type":"null"}]},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","family","hex","season","pattern","swatch"]}}},"required":["count","values"]},"example":{"count":3,"values":[{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#9CAF88","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=https%3A%2F%2Fv5.airtableusercontent.com%2F...&key=colors%2Fsage.jpg"},{"id":"recSageLeFleur0001","name":"Sage Le Fleur","family":"Florals","hex":null,"season":"Spring","pattern":"Print","swatch":null},{"id":"recSageBlooms00001","name":"Sage Whimsical Blooms","family":"Florals","hex":null,"season":"Spring","pattern":"Print","swatch":null}]}}}},"400":{"description":"Invalid bundle id (not a numeric ID or product GID)","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"not-an-id","expected":"/^(?:\\d+|gid:\\/\\/shopify\\/Product\\/\\d+)$/","received":"\"not-an-id\"","message":"Must be a numeric product ID or a product GID","path":[{"type":"object","origin":"value","key":"id","value":"not-an-id"}]}],"data":{"id":"not-an-id"}}}}},"404":{"description":"No product found for the given ID","content":{"application/json":{"example":{"error":"No product found for id \"999\""}}}},"422":{"description":"The product exists but is not a bundle","content":{"application/json":{"example":{"error":"Product \"123\" is not a bundle"}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1,"pattern":"^(?:\\d+|gid:\\/\\/shopify\\/Product\\/\\d+)$","example":"8208881615039"},"required":true,"description":"Product ID: a bare numeric ID (`8208881615039`) or a URL-encoded product GID (`gid%3A%2F%2Fshopify%2FProduct%2F8208881615039`)."}]}},"/catalog/colors/product/{id}":{"get":{"operationId":"getCatalogColorsProductById","description":"Returns the colors a product's style and type is sold in, each linked to the product that sells it. A style sold in several fabrics returns only the colors in the passed product's fabric and feature.","responses":{"200":{"description":"The colors the product's style and type is sold in","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"style":{"type":"string"},"type":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"feature":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"hex":{"anyOf":[{"type":"string"},{"type":"null"}]},"season":{"anyOf":[{"enum":["Fall","Spring","Seasonless"],"type":"string"},{"type":"null"}]},"pattern":{"anyOf":[{"enum":["Solid","Print"],"type":"string"},{"type":"null"}]},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]},"productId":{"type":"string"},"handle":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","size","estimatedArrival","price","inventory"]}},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]}},"required":["id","name","family","hex","season","pattern","swatch","productId","handle"]}}},"required":["style","type","fabric","feature","count","values"]},{"type":"object","properties":{"style":{"type":"string"},"type":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"feature":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"number"},"families":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"hex":{"anyOf":[{"type":"string"},{"type":"null"}]},"season":{"anyOf":[{"enum":["Fall","Spring","Seasonless"],"type":"string"},{"type":"null"}]},"pattern":{"anyOf":[{"enum":["Solid","Print"],"type":"string"},{"type":"null"}]},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]},"productId":{"type":"string"},"handle":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","size","estimatedArrival","price","inventory"]}},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]}},"required":["id","name","family","hex","season","pattern","swatch","productId","handle"]}}},"required":["name","colors"]}}},"required":["style","type","fabric","feature","count","families"]}]},"examples":{"flat":{"summary":"Default","value":{"style":"Anne","type":"Dress","fabric":"Chiffon","feature":null,"count":2,"values":[{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#e2e8e4","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fsage.jpg","productId":"gid://shopify/Product/8208881615039","handle":"anne-chiffon-dress-sage"},{"id":"recNavy0000000001","name":"Navy","family":"Blues","hex":"#2c3a4b","season":"Fall","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fnavy.jpg","productId":"gid://shopify/Product/8208881615041","handle":"anne-chiffon-dress-navy"}]}},"grouped":{"summary":"grouped=true","value":{"style":"Anne","type":"Dress","fabric":"Chiffon","feature":null,"count":2,"families":[{"name":"Blues","colors":[{"id":"recNavy0000000001","name":"Navy","family":"Blues","hex":"#2c3a4b","season":"Fall","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fnavy.jpg","productId":"gid://shopify/Product/8208881615041","handle":"anne-chiffon-dress-navy"}]},{"name":"Greens","colors":[{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#e2e8e4","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fsage.jpg","productId":"gid://shopify/Product/8208881615039","handle":"anne-chiffon-dress-sage"}]}]}},"filtered":{"summary":"size=XS&fulfillment=rush","value":{"style":"Anne","type":"Dress","fabric":"Chiffon","feature":null,"count":1,"values":[{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#e2e8e4","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=…&key=colors%2Fsage.jpg","productId":"gid://shopify/Product/8208881615039","handle":"anne-chiffon-dress-sage","variants":[{"variantId":"gid://shopify/ProductVariant/44831180669119","sku":"BG068SG0018001","size":"XS","estimatedArrival":"Rush Production","price":{"amount":99,"currency":"USD"},"inventory":4}],"rushFee":{"amount":8,"currency":"USD"}}]}}}}}},"400":{"description":"Invalid product id or query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"not-an-id","expected":"/^(?:\\d+|gid:\\/\\/shopify\\/Product\\/\\d+)$/","received":"\"not-an-id\"","message":"Must be a numeric product ID or a product GID","path":[{"type":"object","origin":"value","key":"id","value":"not-an-id"}]}],"data":{"id":"not-an-id"}}}}},"404":{"description":"No product found for the given ID","content":{"application/json":{"example":{"error":"No product found for id \"999\""}}}},"422":{"description":"The product has no resolvable color palette","content":{"application/json":{"example":{"error":"Product \"123\" has group type \"BUNDLE\", which carries no color palette"}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1,"pattern":"^(?:\\d+|gid:\\/\\/shopify\\/Product\\/\\d+)$","example":"8208881615039"},"required":true,"description":"Product ID: a bare numeric ID (`8208881615039`) or a URL-encoded product GID (`gid%3A%2F%2Fshopify%2FProduct%2F8208881615039`)."},{"in":"query","name":"grouped","schema":{"type":"string","enum":["true","false"],"example":"true"},"description":"Return the colors bucketed by family instead of as a flat list. A color in several families appears under each."},{"in":"query","name":"preview","schema":{"type":"string","enum":["true","false"],"example":"true"},"description":"Include colors that are not yet live on the site."},{"in":"query","name":"size","schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 ]+$","example":"XS"},"description":"Return only colors that can be bought in this size. Any variant filter adds `variants` and `rushFee` to each color."},{"in":"query","name":"length","schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 .'\"]+$","example":"Long"},"description":"Return only colors that can be bought in this length, e.g. `Long` or `32\"`."},{"in":"query","name":"fit","schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9 .'\"]+$","example":"Slim"},"description":"Return only colors that can be bought in this fit."},{"in":"query","name":"fulfillment","schema":{"type":"string","enum":["rush","standard"],"example":"rush"},"description":"Return only colors that can be bought by this method. Omit to accept either. `standard` also omits `rushFee`."}]}},"/catalog/colors":{"get":{"operationId":"getCatalogColors","description":"Returns the alphabetically-sorted list of distinct colors currently in use on at least one active product, with metadata for each (`family`, `hex`, `season`, `pattern`). `category` selects the catalog via Shopify `product_type` (defaults to `Bridesmaid Dress`; e.g. `?category=Little White Dress`, or `?category=All` for every catalog), returning the colors used in that catalog. Optionally narrow further by `family` — the color group the color belongs to (e.g. `?family=Greens`; use `GET /colors/families` for valid values), `season` (`Fall` / `Spring` / `Seasonless`), `pattern` (`Solid` / `Print`), or `type` (the product type the color is used on, e.g. `?type=Dress` — exact match; `Dress` does not match `Junior Dress`). Filters compose with AND.","responses":{"200":{"description":"Distinct colors with family + hex metadata","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"hex":{"anyOf":[{"type":"string"},{"type":"null"}]},"season":{"anyOf":[{"enum":["Fall","Spring","Seasonless"],"type":"string"},{"type":"null"}]},"pattern":{"anyOf":[{"enum":["Solid","Print"],"type":"string"},{"type":"null"}]},"swatch":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","family","hex","season","pattern","swatch"]}}},"required":["count","values"]},"example":{"count":3,"values":[{"id":"recDustyBlue000001","name":"Dusty Blue","family":"Blues","hex":"#8BA3C7","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=https%3A%2F%2Fv5.airtableusercontent.com%2F...&key=colors%2Fdusty-blue.jpg"},{"id":"recSage0000000001","name":"Sage","family":"Greens","hex":"#9CAF88","season":"Seasonless","pattern":"Solid","swatch":"https://cdn.birdygrey.com/asset?url=https%3A%2F%2Fv5.airtableusercontent.com%2F...&key=colors%2Fsage.jpg"},{"id":"recCabernet000001","name":"Cabernet","family":"Reds","hex":"#6D2C3D","season":"Fall","pattern":"Solid","swatch":null}]}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"schema","type":"picklist","input":"Winter","expected":"(\"Fall\" | \"Spring\" | \"Seasonless\")","received":"\"Winter\"","message":"Invalid type: Expected (\"Fall\" | \"Spring\" | \"Seasonless\") but received \"Winter\"","path":[{"type":"object","origin":"value","key":"season","value":"Winter"}]}],"data":{"season":"Winter"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog, or `All` (any case) for every catalog. Returns the colors used on products in that catalog."},{"in":"query","name":"family","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 &'-]+$","example":"Greens"},"description":"Color group to filter by, in any casing — a value from `GET /colors/families` (e.g. `Greens`). A color in several groups matches any of them."},{"in":"query","name":"season","schema":{"type":"string","enum":["Fall","Spring","Seasonless"],"example":"Fall"},"description":"Seasonality to filter by, in any casing. One of `Fall`, `Spring`, `Seasonless`."},{"in":"query","name":"pattern","schema":{"type":"string","enum":["Solid","Print"],"example":"Solid"},"description":"Restrict to solid colors or prints/patterns, in any casing. One of `Solid`, `Print`."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Dress"},"description":"Restrict to colors used on products of this Web Product Type (exact match — `Dress` does not match `Junior Dress`)."}]}},"/catalog/fabrics":{"get":{"operationId":"getCatalogFabrics","description":"Returns the alphabetically-sorted list of distinct fabric names available across active products in a catalog. `category` selects the catalog via Shopify `product_type` (defaults to `Bridesmaid Dress`; e.g. `?category=Little White Dress`); `type` optionally narrows to a specific `attr.type` within it (e.g. `?type=Jumpsuit`).","responses":{"200":{"description":"Distinct fabric names","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"string"}}},"required":["count","values"]},"example":{"count":3,"values":["Chiffon","Crepe","Velvet"]}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"@bad","expected":"/^[A-Za-z0-9 ,&'-]+$/","received":"\"@bad\"","message":"Invalid format: Expected /^[A-Za-z0-9 ,&'-]+$/ but received \"@bad\"","path":[{"type":"object","origin":"value","key":"type","value":"@bad"}]}],"data":{"type":"@bad"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog. Returns the fabrics available in that catalog."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Dress"},"description":"Optional product-type (`attr.type`) narrow within the category, e.g. `Jumpsuit`."}]}},"/catalog/sizes":{"get":{"operationId":"getCatalogSizes","description":"Returns the variant-option axes (Size, Length, Fit) currently available across active products, each sorted in natural apparel order. Response shape varies by what matched: a dress query returns only the `size` axis; `Suit Jacket` and `Suit Pants` return `size`, `length`, and `fit` as separate axes, since their products have multi-axis variants. `type` accepts any value `GET /types` returns. Each axis value is one currently in stock. Use these values to construct `/products/rush` filter queries. Narrow with `type` (product type) and/or `category` (catalog, via Shopify `product_type` — e.g. `?category=Little White Dress`); pass both to scope one type within one catalog. Defaults apply only when you pass neither: a bare request returns `Dress` within `Bridesmaid Dress`. Naming one param never implies the other, so `?type=Suit Jacket` spans every catalog and `?category=Little White Dress` spans every type in that catalog.","responses":{"200":{"description":"Distinct variant-option axes for the given product type","content":{"application/json":{"schema":{"type":"object","properties":{"size":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}},"length":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}},"fit":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}},"required":[]},"example":{"size":[{"name":"36"},{"name":"38"},{"name":"40"},{"name":"42"}],"length":[{"name":"Long"},{"name":"Regular"},{"name":"Short"}],"fit":[{"name":"Classic"},{"name":"Slim"}]}}}},"400":{"description":"Invalid query parameter, or a `type` not found in the requested catalog","content":{"application/json":{"example":{"error":"Unknown type \"Hat\""}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Little White Dress"},"description":"Catalog category (Shopify `product_type`). Scopes the size axes to that catalog — e.g. `Little White Dress`. Spans every type in the catalog unless you also pass `type`. Defaults to `Bridesmaid Dress` only when `type` is also omitted."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Suit Jacket"},"description":"Product type whose size structure to return — any value `GET /types` returns for the catalog, e.g. `Junior Dress` or `Suit Jacket`. Spans every catalog unless you also pass `category`. Defaults to `Dress` only when `category` is also omitted."}]}},"/catalog/sizes/range":{"get":{"operationId":"getCatalogSizesRange","description":"Returns the sizes a style is **expected** to carry, so you can check whether a product is missing any. Look a style up by the `style`, `fabric` and `type` values from `/products`, e.g. `?style=Anne&fabric=Chiffon&type=Dress`. Suits, tuxedos, dress shirts and alternate-length dresses report their size values only (`36`, `28`, `XS`), without length or fit. A style with no expectation on record — including `Suit` and `Tuxedo` bundles and all jewelry — returns `null` with a 200, not a 404.","responses":{"200":{"description":"Expected size range for the identified style, or `null` if none is on record","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"style":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string"},"range":{"type":"string"},"sizes":{"type":"array","items":{"type":"string"}}},"required":["style","fabric","type","range","sizes"]},{"type":"null"}]},"example":{"style":"Anne","fabric":"Chiffon","type":"Dress","range":"XXS to 3X","sizes":["XXS","XS","S","M","L","XL","XXL","0X","1X","2X","3X"]}}}},"400":{"description":"Missing required `style`/`type`, or an invalid parameter value","content":{"application/json":{"example":{"success":false,"error":[{"kind":"schema","type":"string","expected":"string","received":"undefined","message":"Invalid type: Expected string but received undefined","path":[{"type":"object","origin":"value","key":"type"}]}],"data":{"style":"Anne"}}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"style","schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\p{L}\\p{M}\\p{N} &'()./-]+$","example":"Anne"},"required":true,"description":"The product's `style`, e.g. `Anne`. Case-insensitive."},{"in":"query","name":"fabric","schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\p{L}\\p{M}\\p{N} &'()./-]+$","example":"Chiffon"},"description":"The product's `fabric`, e.g. `Chiffon`. Omit for styles that have none — that matches the fabric-less style exactly, rather than any fabric."},{"in":"query","name":"type","schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\p{L}\\p{M}\\p{N} &'()./-]+$","example":"Dress"},"required":true,"description":"The product's `type`, e.g. `Dress`."},{"in":"query","name":"fit","schema":{"type":"string","minLength":1,"enum":["Slim","Classic"],"example":"Slim"},"description":"Suiting fit, `Slim` or `Classic`. The two carry different spans — a Slim jacket stops at 48, Classic runs to 56. Omit to merge both into one span."}]}},"/catalog/sizes/product/{id}":{"get":{"operationId":"getCatalogSizesProductById","description":"Returns every size a product carries and whether it can be bought, with the variant IDs to act on it. Sizes that can't be bought return `available: false`. Suits return one entry per size, length and fit.","responses":{"200":{"description":"The product's sizes and their availability","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"handle":{"type":"string"},"title":{"type":"string"},"style":{"type":"string"},"fabric":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string"},"color":{"type":"string"},"image":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["url","alt","width","height"]},{"type":"null"}]},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]},"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"length":{"type":"string"},"fit":{"type":"string"},"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"estimatedArrival":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"inventory":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["variantId","sku","estimatedArrival","price","inventory"]}}},"required":["size","available","variants"]}}},"required":["productId","handle","title","style","fabric","type","color","image","count","values"]},"example":{"productId":"gid://shopify/Product/8208881615039","handle":"serena-matte-satin-dress-taupe","title":"Serena Matte Satin Dress - Taupe","style":"Serena","fabric":"Matte Satin","type":"Dress","color":"Taupe","image":{"url":"https://cdn.shopify.com/s/files/1/serena-matte-satin-dress-taupe.jpg","alt":"Serena Matte Satin Dress - Taupe","width":1600,"height":2400},"rushFee":{"amount":8,"currency":"USD"},"count":3,"values":[{"size":"XS","available":true,"variants":[{"variantId":"gid://shopify/ProductVariant/44831180669119","sku":"BG068TP0018001","estimatedArrival":"Rush Production","price":{"amount":99,"currency":"USD"},"inventory":4},{"variantId":"gid://shopify/ProductVariant/44831180701887","sku":"BG068TP0018001","estimatedArrival":"Standard Production","price":{"amount":99,"currency":"USD"},"inventory":null}]},{"size":"S","available":true,"variants":[{"variantId":"gid://shopify/ProductVariant/44831180767423","sku":"BG068TP0018002","estimatedArrival":"Standard Production","price":{"amount":99,"currency":"USD"},"inventory":null}]},{"size":"M","available":false,"variants":[]}]}}}},"400":{"description":"Invalid product ID, handle or query parameter","content":{"application/json":{"example":{"success":false,"error":[{"kind":"schema","type":"picklist","input":"express","expected":"(\"rush\" | \"standard\")","received":"\"express\"","message":"Invalid type: Expected (\"rush\" | \"standard\") but received \"express\"","path":[{"type":"object","origin":"value","key":"fulfillment","value":"express"}]}],"data":{"fulfillment":"express"}}}}},"404":{"description":"No live product matches the ID or handle","content":{"application/json":{"example":{"error":"No product found for \"serena-matte-satin-dress-taupe\""}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^(?:\\d+|gid:\\/\\/shopify\\/Product\\/\\d+|[a-z0-9-]+)$","example":"8208881615039"},"required":true,"description":"A bare numeric product ID (`8208881615039`), a URL-encoded product GID (`gid%3A%2F%2Fshopify%2FProduct%2F8208881615039`), or a product handle (`serena-matte-satin-dress-taupe`)."},{"in":"query","name":"fulfillment","schema":{"type":"string","enum":["rush","standard"],"example":"rush"},"description":"Count only Rush or only Standard Production variants as available. Omit to count either. `standard` also omits `rushFee`."}]}},"/catalog/types":{"get":{"operationId":"getCatalogTypes","description":"Returns the alphabetically-sorted list of distinct `attr.type` values within a catalog (e.g. `Dress`, `Jumpsuit`, `Set`). `category` selects the catalog via Shopify `product_type` (defaults to `Bridesmaid Dress`; e.g. `?category=Little White Dress`). Useful for discovering which `type` values are valid as a filter on the other endpoints.","responses":{"200":{"description":"Distinct product type names","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"values":{"type":"array","items":{"type":"string"}}},"required":["count","values"]},"example":{"count":6,"values":["Bow Tie","Dress","Pocket Square","Robe","Suit Jacket","Suit Pants"]}}}},"500":{"description":"Unexpected server error. The cause is logged and never returned.","content":{"application/json":{"example":{"error":"Internal server error"}}}}},"parameters":[{"in":"query","name":"category","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9 ,&'-]+$","example":"Little White Dress","default":"Bridesmaid Dress"},"description":"Catalog category (Shopify `product_type`). Defaults to `Bridesmaid Dress`; pass e.g. `Little White Dress` for another catalog. Returns the `attr.type` values present in that catalog (e.g. Dress, Jumpsuit, Set)."}]}}},"components":{}}