{"openapi":"3.0.0","paths":{"/api/v1/storefront/products":{"get":{"operationId":"StorefrontProductsController_list","summary":"List products visible on this storefront channel","parameters":[{"name":"category","required":false,"in":"query","description":"Category id or slug (menu-item id/slug on a channel with a custom menu). Comma-separate or repeat the parameter for several. Descendants are always included, so a parent category returns exactly what `productCount` on `/storefront/navigation` reports.","schema":{"type":"string"}},{"name":"categoryId","required":false,"in":"query","description":"Alias for `category`","schema":{"type":"string"}},{"name":"brand","required":false,"in":"query","description":"Brand id or slug","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Free-text search on product name + description, and on variant identifiers (SKU, MPN, UPC, GTIN, and channel SKU) for listed variants.","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Alias for `q`","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated expansions. Supported: `variants`.","schema":{"example":"variants","type":"string"}},{"name":"inStockOnly","required":false,"in":"query","description":"Only products with at least one in-stock listed variant. Applied before pagination, so `pagination.total` is the in-stock count.","schema":{"type":"boolean"}},{"name":"featured","required":false,"in":"query","description":"true → only featured products; false → only non-featured. Omit for all. (Also available as a sort: `sort=featured`.)","schema":{"type":"boolean"}},{"name":"priceMin","required":false,"in":"query","description":"Lower price bound (inclusive) on ChannelSku.price","schema":{"minimum":0,"type":"number"}},{"name":"priceMax","required":false,"in":"query","description":"Upper price bound (inclusive) on ChannelSku.price","schema":{"minimum":0,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"name/-name, price/-price (lowest listed price on this channel; unpriced products last), newest, featured (featured first, then manual order), manual (displayOrder).","schema":{"enum":["name","-name","price","-price","newest","featured","manual"],"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedProductsDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/products/{idOrSlug}":{"get":{"operationId":"StorefrontProductsController_get","summary":"Get a single product with variants, options, and images","parameters":[{"name":"idOrSlug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductDetailDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/variants/{id}":{"get":{"operationId":"StorefrontVariantsController_get","summary":"Resolve a single variant by id (price, availability, options, product) — for cart re-validation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontVariantResolvedDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/categories":{"get":{"operationId":"StorefrontCategoriesController_list","summary":"Hierarchical category tree for this storefront channel","description":"Pass ?expand=true to additionally return, per node, the same authored content the detail endpoint serves — description1/description2, resolved metaTitle/metaDescription, and storefront-visible custom fields — so a static build can fetch every category page in one request.","parameters":[{"name":"expand","required":false,"in":"query","description":"true to include descriptions, resolved SEO fields, and visible custom fields on every node.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCategoryNodeDto"}}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/categories/{slug}/products":{"get":{"operationId":"StorefrontCategoriesController_productsForCategory","summary":"Products in a specific category (slug or id)","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","description":"Category id or slug (menu-item id/slug on a channel with a custom menu). Comma-separate or repeat the parameter for several. Descendants are always included, so a parent category returns exactly what `productCount` on `/storefront/navigation` reports.","schema":{"type":"string"}},{"name":"categoryId","required":false,"in":"query","description":"Alias for `category`","schema":{"type":"string"}},{"name":"brand","required":false,"in":"query","description":"Brand id or slug","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Free-text search on product name + description, and on variant identifiers (SKU, MPN, UPC, GTIN, and channel SKU) for listed variants.","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Alias for `q`","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated expansions. Supported: `variants`.","schema":{"example":"variants","type":"string"}},{"name":"inStockOnly","required":false,"in":"query","description":"Only products with at least one in-stock listed variant. Applied before pagination, so `pagination.total` is the in-stock count.","schema":{"type":"boolean"}},{"name":"featured","required":false,"in":"query","description":"true → only featured products; false → only non-featured. Omit for all. (Also available as a sort: `sort=featured`.)","schema":{"type":"boolean"}},{"name":"priceMin","required":false,"in":"query","description":"Lower price bound (inclusive) on ChannelSku.price","schema":{"minimum":0,"type":"number"}},{"name":"priceMax","required":false,"in":"query","description":"Upper price bound (inclusive) on ChannelSku.price","schema":{"minimum":0,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"name/-name, price/-price (lowest listed price on this channel; unpriced products last), newest, featured (featured first, then manual order), manual (displayOrder).","schema":{"enum":["name","-name","price","-price","newest","featured","manual"],"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedProductsDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/categories/{slug}":{"get":{"operationId":"StorefrontCategoriesController_detail","summary":"Category detail: descriptions + visible custom fields (by slug)","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCategoryDetailDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/navigation":{"get":{"operationId":"StorefrontNavigationController_list","summary":"Typed navigation tree for this storefront (categories + links + groups)","description":"The storefront's full header navigation. Channels with a custom nav tree\nget it as authored (categories, links, and non-clickable groups);\nchannels without one get their category tree in the same typed shape, so\nstorefront code renders one contract either way.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontNavNodeDto"}}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/brands":{"get":{"operationId":"StorefrontBrandsController_list","summary":"Flat list of brands with at least one listed product","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontBrandDto"}}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/brands/{slug}":{"get":{"operationId":"StorefrontBrandsController_detail","summary":"Brand detail: descriptions + visible custom fields (by slug)","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontBrandDetailDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/search":{"get":{"operationId":"StorefrontSearchController_search","summary":"Free-text search across product name + description","parameters":[{"name":"q","required":false,"in":"query","description":"Free-text term (required): product name/description and listed-variant identifiers.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedProductsDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/inventory/check":{"post":{"operationId":"StorefrontInventoryController_check","summary":"Real-time inventory check (cart pre-checkout)","description":"Real-time inventory check used by storefront carts before checkout.\n\n\"available\" means `onHand (net-of-reservations) >= qty`. The on-hand\nnumber is `max(0, available + buildable - reserved)` — an assembly a\nstorefront can still have built counts as sellable\n— the same effective-available number the admin UI shows and the\noutbound sync layer pushes to other channels. Untracked variants\n(`trackInventory = false`) are always available, with `onHand` set to\n`Number.MAX_SAFE_INTEGER` so storefronts can render an \"in stock\"\nbadge without special-casing the sentinel.\n\nNo caching: cart-time inventory must reflect any race-window\nreservations from concurrent orders.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInventoryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryCheckResponseDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/orders":{"post":{"operationId":"StorefrontOrdersController_create","summary":"Create a storefront order","description":"Finalize a storefront cart into a Foundry order. The storefront owns\npayment processing — Foundry just records the order, server-recomputes\ntotals from current ChannelSku.price values, and reserves inventory.\n\nReturns `{ orderId, orderNumber, status, lookupToken }`. The token\nis the customer's escape-hatch reference: storefronts give it to\nthe customer (in the confirmation email, account page, wherever) so\nthey can fetch order status via Phase 3's\n`GET /storefront/orders/:lookupToken` without a Foundry account.\n\nPass `Idempotency-Key` to make retries safe — replays with the same\nkey + body return the cached 2xx; same key + different body returns\n409 to surface the misuse.","parameters":[{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"24-128 char client-supplied key for retry-safe order creation","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderResultDto"}}}}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/orders/{id}/regenerate-lookup-token":{"post":{"operationId":"StorefrontOrdersController_regenerateLookupToken","summary":"Regenerate the customer-facing lookup token","description":"Mint a fresh lookup token for an order, invalidating the previous one.\nUseful when a customer loses the order confirmation email — the\nstorefront calls this and emails the new link.\n\nAuth: standard storefront key. The endpoint enforces channel\nownership server-side; a key bound to channel A cannot regenerate\ntokens for orders on channel B.\n\nReturns `{ lookupToken }` (24-char base64url) ONCE — the old token\nis immediately invalid.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/orders/{lookupToken}":{"get":{"operationId":"StorefrontOrderLookupController_lookup","summary":"Customer-facing order status lookup (no auth — token IS the auth)","parameters":[{"name":"lookupToken","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOrderViewDto"}}}}},"tags":["storefront"]}},"/api/v1/storefront/webhook":{"get":{"operationId":"StorefrontWebhookController_get","summary":"Current webhook config for this key's channel (no secret)","parameters":[],"responses":{"200":{"description":""}},"tags":["storefront"],"security":[{"bearer":[]}]},"put":{"operationId":"StorefrontWebhookController_setUrl","summary":"Set the outbound webhook delivery URL (https, public host)","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetWebhookUrlDto"}}}},"responses":{"200":{"description":""}},"tags":["storefront"],"security":[{"bearer":[]}]},"delete":{"operationId":"StorefrontWebhookController_clear","summary":"Stop deliveries by clearing the webhook URL","parameters":[],"responses":{"200":{"description":""}},"tags":["storefront"],"security":[{"bearer":[]}]}},"/api/v1/storefront/webhook/rotate-secret":{"post":{"operationId":"StorefrontWebhookController_rotateSecret","summary":"Generate a new signing secret (returned once)","parameters":[],"responses":{"200":{"description":""}},"tags":["storefront"],"security":[{"bearer":[]}]}}},"info":{"title":"Foundry Storefront API","description":"Public, channel-scoped REST API for headless storefronts. Authenticate with a `fims_sf_*` storefront key bound to a HEADLESS sales channel. Full guide: https://foundryims.com/docs/storefront-api","version":"1.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"IdNameDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"StorefrontCustomFieldDto":{"type":"object","properties":{"key":{"type":"string","example":"cooling_capacity","description":"Stable machine key."},"label":{"type":"string","example":"Cooling Capacity"},"value":{"type":"object","example":18000,"description":"Typed value (string | number | boolean | array | object)."},"unit":{"type":"string","example":"BTU/h","description":"Display unit (NUMBER fields), omitted when unset."},"type":{"type":"string","enum":["text","number","boolean","enum","date","url","json"],"example":"number"},"group":{"type":"string","example":"Performance","description":"Spec-table section, omitted when ungrouped."},"displayOrder":{"type":"number","example":10,"description":"Sort order within the spec table."}},"required":["key","label","value","type","displayOrder"]},"OptionValueDto":{"type":"object","properties":{"name":{"type":"string","example":"Color"},"value":{"type":"string","example":"Red"}},"required":["name","value"]},"ImageRefDto":{"type":"object","properties":{"url":{"type":"string","example":"https://cdn.example.com/img/abc.jpg"}},"required":["url"]},"StorefrontVariantDto":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number","example":19.99,"description":"What the buyer pays now — the sale price while a sale is on."},"regularPrice":{"type":"number","example":24.99,"description":"The regular price; equals price when not on sale."},"onSale":{"type":"boolean","description":"True while a sale window is open on this listing."},"saleEndsAt":{"type":"string","nullable":true,"description":"ISO timestamp the sale ends, when one is set."},"compareAtPrice":{"type":"number","nullable":true,"example":24.99,"description":"\"Was\"/MSRP price. While on sale this is the regular price."},"map":{"type":"number","nullable":true,"description":"Minimum advertised price."},"upc":{"type":"string","nullable":true},"gtin":{"type":"string","nullable":true},"mpn":{"type":"string","nullable":true},"weight":{"type":"number","nullable":true},"inStock":{"type":"boolean"},"availableQuantity":{"type":"number","example":14},"optionValues":{"type":"array","items":{"$ref":"#/components/schemas/OptionValueDto"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ImageRefDto"}},"customFields":{"description":"This variant's effective custom fields (variant value overrides product).","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}}},"required":["id","sku","name","price","regularPrice","onSale","saleEndsAt","compareAtPrice","map","upc","gtin","mpn","weight","inStock","availableQuantity","optionValues","images","customFields"]},"StorefrontProductSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"anti-gravity-boots"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"metaTitle":{"type":"string","example":"Anti-Gravity Boots | Acme","description":"Resolved SEO <title>; falls back to the product name when unset."},"metaDescription":{"type":"string","example":"Float through your day with our best-selling anti-gravity boots.","description":"Resolved SEO meta description; falls back to a description excerpt when unset."},"brand":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/IdNameDto"}]},"category":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/IdNameDto"}]},"thumbnail":{"type":"string","nullable":true},"priceFrom":{"type":"number","example":19.99},"compareAtPriceFrom":{"type":"number","nullable":true,"example":24.99,"description":"Set only when a variant is on sale (compare-at above price)."},"currency":{"type":"string","example":"USD"},"featured":{"type":"boolean"},"displayOrder":{"type":"number","example":0},"inStock":{"type":"boolean"},"availableQuantity":{"type":"number","example":14,"description":"Aggregate on-hand across tracked variants (on-hand minus reserved). Untracked/made-to-order variants report 0 here but still set inStock=true — use inStock for availability, this for \"N left\"."},"variantCount":{"type":"number","example":3},"customFields":{"description":"Product-level custom fields flagged visible on storefront.","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}},"variants":{"description":"Full variant rows — present only when the list is requested with `?include=variants`. Same shape as the product-detail response.","type":"array","items":{"$ref":"#/components/schemas/StorefrontVariantDto"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","name","description","metaTitle","metaDescription","brand","category","thumbnail","priceFrom","compareAtPriceFrom","currency","featured","displayOrder","inStock","availableQuantity","variantCount","customFields","createdAt","updatedAt"]},"PaginationDto":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":50},"total":{"type":"number","example":137},"totalPages":{"type":"number","example":3}},"required":["page","limit","total","totalPages"]},"PaginatedProductsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductSummaryDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["data","pagination"]},"ProductOptionDto":{"type":"object","properties":{"name":{"type":"string","example":"Color"},"position":{"type":"number","example":0},"values":{"example":["Red","Blue"],"type":"array","items":{"type":"string"}}},"required":["name","position","values"]},"StorefrontProductDetailDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"anti-gravity-boots"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"metaTitle":{"type":"string","example":"Anti-Gravity Boots | Acme","description":"Resolved SEO <title>; falls back to the product name when unset."},"metaDescription":{"type":"string","example":"Float through your day with our best-selling anti-gravity boots.","description":"Resolved SEO meta description; falls back to a description excerpt when unset."},"brand":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/IdNameDto"}]},"category":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/IdNameDto"}]},"thumbnail":{"type":"string","nullable":true},"priceFrom":{"type":"number","example":19.99},"compareAtPriceFrom":{"type":"number","nullable":true,"example":24.99,"description":"Set only when a variant is on sale (compare-at above price)."},"currency":{"type":"string","example":"USD"},"featured":{"type":"boolean"},"displayOrder":{"type":"number","example":0},"inStock":{"type":"boolean"},"availableQuantity":{"type":"number","example":14,"description":"Aggregate on-hand across tracked variants (on-hand minus reserved). Untracked/made-to-order variants report 0 here but still set inStock=true — use inStock for availability, this for \"N left\"."},"variantCount":{"type":"number","example":3},"customFields":{"description":"Product-level custom fields flagged visible on storefront.","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}},"variants":{"description":"Full variant rows — present only when the list is requested with `?include=variants`. Same shape as the product-detail response.","type":"array","items":{"$ref":"#/components/schemas/StorefrontVariantDto"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductOptionDto"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ImageRefDto"}}},"required":["id","slug","name","description","metaTitle","metaDescription","brand","category","thumbnail","priceFrom","compareAtPriceFrom","currency","featured","displayOrder","inStock","availableQuantity","variantCount","customFields","createdAt","updatedAt","options","images"]},"StorefrontVariantResolvedDto":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number","example":19.99,"description":"What the buyer pays now — the sale price while a sale is on."},"regularPrice":{"type":"number","example":24.99,"description":"The regular price; equals price when not on sale."},"onSale":{"type":"boolean","description":"True while a sale window is open on this listing."},"saleEndsAt":{"type":"string","nullable":true,"description":"ISO timestamp the sale ends, when one is set."},"compareAtPrice":{"type":"number","nullable":true,"example":24.99,"description":"\"Was\"/MSRP price. While on sale this is the regular price."},"map":{"type":"number","nullable":true,"description":"Minimum advertised price."},"upc":{"type":"string","nullable":true},"gtin":{"type":"string","nullable":true},"mpn":{"type":"string","nullable":true},"weight":{"type":"number","nullable":true},"inStock":{"type":"boolean"},"availableQuantity":{"type":"number","example":14},"optionValues":{"type":"array","items":{"$ref":"#/components/schemas/OptionValueDto"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ImageRefDto"}},"customFields":{"description":"This variant's effective custom fields (variant value overrides product).","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}},"currency":{"type":"string","example":"USD"},"product":{"$ref":"#/components/schemas/IdNameDto"}},"required":["id","sku","name","price","regularPrice","onSale","saleEndsAt","compareAtPrice","map","upc","gtin","mpn","weight","inStock","availableQuantity","optionValues","images","customFields","currency","product"]},"StorefrontCategoryNodeDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"beverages"},"name":{"type":"string"},"parentId":{"type":"string","nullable":true},"position":{"type":"number","example":0,"description":"Configured merchandised sort order within siblings (lower = earlier). Nodes and children arrays are already returned in this order."},"children":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCategoryNodeDto"}},"description1":{"type":"string","nullable":true,"description":"Rich-text (HTML) description. Present only with ?expand=true."},"description2":{"type":"string","nullable":true,"description":"Rich-text (HTML) description. Present only with ?expand=true."},"metaTitle":{"type":"string","description":"Resolved SEO <title>; falls back to the category name when unset. Present only with ?expand=true."},"metaDescription":{"type":"string","description":"Resolved SEO meta description; falls back to an excerpt of description1 when unset. Present only with ?expand=true."},"customFields":{"description":"Category custom fields flagged visible on storefront. Present only with ?expand=true.","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}}},"required":["id","slug","name","parentId","position","children"]},"StorefrontCategoryDetailDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"beverages"},"name":{"type":"string"},"parentId":{"type":"string","nullable":true},"description1":{"type":"string","nullable":true,"description":"Rich-text (HTML) description."},"description2":{"type":"string","nullable":true,"description":"Rich-text (HTML) description."},"metaTitle":{"type":"string","description":"Resolved SEO <title>; falls back to the category name when unset."},"metaDescription":{"type":"string","description":"Resolved SEO meta description; falls back to an excerpt of description1 when unset."},"customFields":{"description":"Category custom fields flagged visible on storefront.","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}}},"required":["id","slug","name","parentId","description1","description2","metaTitle","metaDescription","customFields"]},"StorefrontNavNodeDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["CATEGORY","LINK","GROUP"],"description":"CATEGORY nodes have a slug that resolves against /storefront/categories/:slug; LINK nodes carry an href for the storefront to render; GROUP nodes are non-clickable headings."},"name":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"towing"},"href":{"type":"string","nullable":true,"example":"/blog"},"openInNewTab":{"type":"boolean"},"position":{"type":"number","example":0,"description":"Sort order within siblings (lower = earlier). Nodes and children arrays are already returned in this order."},"productCount":{"type":"number","nullable":true,"example":42,"description":"CATEGORY nodes: number of products listed on this storefront under the node (its categories plus their descendants). Always ≥1 for returned nodes unless the node is kept only as a parent of non-empty children. null for LINK and GROUP nodes."},"children":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontNavNodeDto"}}},"required":["id","type","name","slug","href","openInNewTab","position","productCount","children"]},"StorefrontBrandDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"acme-co"}},"required":["id","name","slug"]},"StorefrontBrandDetailDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","nullable":true,"example":"acme-co"},"description1":{"type":"string","nullable":true,"description":"Rich-text (HTML) description."},"description2":{"type":"string","nullable":true,"description":"Rich-text (HTML) description."},"metaTitle":{"type":"string","description":"Resolved SEO <title>; falls back to the brand name when unset."},"metaDescription":{"type":"string","description":"Resolved SEO meta description; falls back to an excerpt of description1 when unset."},"customFields":{"description":"Brand custom fields flagged visible on storefront.","type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomFieldDto"}}},"required":["id","name","slug","description1","description2","metaTitle","metaDescription","customFields"]},"CheckInventoryItemDto":{"type":"object","properties":{"variantId":{"type":"string","description":"Foundry variant UUID"},"qty":{"type":"number","minimum":1,"description":"Requested quantity"}},"required":["variantId","qty"]},"CheckInventoryDto":{"type":"object","properties":{"items":{"minItems":1,"maxItems":200,"type":"array","items":{"$ref":"#/components/schemas/CheckInventoryItemDto"}}},"required":["items"]},"InventoryCheckItemDto":{"type":"object","properties":{"variantId":{"type":"string"},"available":{"type":"boolean"},"onHand":{"type":"number","example":14}},"required":["variantId","available","onHand"]},"InventoryCheckResponseDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryCheckItemDto"}}},"required":["items"]},"StorefrontCustomerDto":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"}},"required":["email","name"]},"StorefrontAddressDto":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"}},"required":["name","line1","city","state","postalCode","country"]},"StorefrontLineItemDto":{"type":"object","properties":{"variantId":{"type":"string","description":"Foundry variant UUID"},"quantity":{"type":"number","minimum":1},"unitPrice":{"type":"number","minimum":0,"description":"Client-side per-unit price snapshot"}},"required":["variantId","quantity","unitPrice"]},"StorefrontShippingDto":{"type":"object","properties":{"method":{"type":"string"},"cost":{"type":"number","minimum":0}},"required":["method","cost"]},"StorefrontTaxDto":{"type":"object","properties":{"amount":{"type":"number","minimum":0}},"required":["amount"]},"StorefrontDiscountDto":{"type":"object","properties":{"code":{"type":"string"},"amount":{"type":"number","minimum":0}},"required":["amount"]},"StorefrontPaymentDto":{"type":"object","properties":{"provider":{"type":"string"},"chargeId":{"type":"string","description":"Provider-side charge / transaction id"},"amount":{"type":"number","minimum":0}},"required":["provider","chargeId","amount"]},"StorefrontTotalsDto":{"type":"object","properties":{"subtotal":{"type":"number","minimum":0},"tax":{"type":"number","minimum":0},"shipping":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"total":{"type":"number","minimum":0}},"required":["subtotal","tax","shipping","total"]},"CreateOrderDto":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/StorefrontCustomerDto"},"shippingAddress":{"$ref":"#/components/schemas/StorefrontAddressDto"},"billingAddress":{"$ref":"#/components/schemas/StorefrontAddressDto"},"lineItems":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/StorefrontLineItemDto"}},"shipping":{"$ref":"#/components/schemas/StorefrontShippingDto"},"tax":{"$ref":"#/components/schemas/StorefrontTaxDto"},"discount":{"$ref":"#/components/schemas/StorefrontDiscountDto"},"payment":{"$ref":"#/components/schemas/StorefrontPaymentDto"},"totals":{"$ref":"#/components/schemas/StorefrontTotalsDto"},"externalReference":{"type":"string"},"notes":{"type":"string"}},"required":["customer","shippingAddress","lineItems","shipping","tax","payment","totals"]},"CreateOrderResultDto":{"type":"object","properties":{"orderId":{"type":"string"},"orderNumber":{"type":"string","example":"SF-A1B2C3D4"},"status":{"type":"string","example":"PROCESSING"},"lookupToken":{"type":"string","description":"Customer-facing order-status token."}},"required":["orderId","orderNumber","status","lookupToken"]},"PublicOrderCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Partially redacted, e.g. \"k***@example.com\"."},"name":{"type":"string"}},"required":["email","name"]},"PublicOrderLineItemDto":{"type":"object","properties":{"name":{"type":"string","nullable":true},"quantity":{"type":"number"},"unitPrice":{"type":"number"},"lineTotal":{"type":"number"}},"required":["name","quantity","unitPrice","lineTotal"]},"PublicOrderTotalsDto":{"type":"object","properties":{"subtotal":{"type":"number"},"shipping":{"type":"number"},"tax":{"type":"number"},"discount":{"type":"number"},"total":{"type":"number"}},"required":["subtotal","shipping","tax","discount","total"]},"PublicOrderTrackingDto":{"type":"object","properties":{"carrier":{"type":"string","nullable":true},"number":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"shippedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["carrier","number","url","shippedAt"]},"PublicOrderViewDto":{"type":"object","properties":{"orderNumber":{"type":"string","nullable":true},"status":{"type":"string","example":"SHIPPED"},"currency":{"type":"string","example":"USD"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"customer":{"$ref":"#/components/schemas/PublicOrderCustomerDto"},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Shipping address (pass-through JSON)."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/PublicOrderLineItemDto"}},"totals":{"$ref":"#/components/schemas/PublicOrderTotalsDto"},"tracking":{"type":"array","items":{"$ref":"#/components/schemas/PublicOrderTrackingDto"}}},"required":["orderNumber","status","currency","createdAt","updatedAt","customer","shippingAddress","lineItems","totals","tracking"]},"SetWebhookUrlDto":{"type":"object","properties":{}}}}}