{"openapi":"3.1.0","info":{"title":"Et Al Australia Storefront API","description":"Storefront API for Et Al Australia. Browse collections and search or retrieve product information.\n\nVersioning and deprecation: The public endpoints are currently unversioned. No removal is scheduled. If an endpoint is deprecated, this guide and the OpenAPI document will identify its replacement and removal date before it is removed. A deprecation would be signalled ahead of removal with Deprecation and Sunset response headers on the affected operations.","version":"1.0.0","contact":{}},"servers":[{"url":"https://ai.etal-australia.com","description":"Et Al Australia storefront"}],"paths":{"/products.json":{"get":{"operationId":"listProducts","summary":"List products","description":"Retrieve a paginated list of products with optional filtering by category, brand, availability, and text search.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Text search across product titles, descriptions, and handles"},{"name":"handle","in":"query","schema":{"type":"string"},"description":"Exact product handle filter"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category"},{"name":"brand","in":"query","schema":{"type":"string"},"description":"Filter by brand name"},{"name":"availability","in":"query","schema":{"type":"string","enum":["in_stock","out_of_stock","preorder","backorder"]},"description":"Filter by availability status"},{"name":"sort","in":"query","schema":{"type":"string","enum":["title_asc","price_asc","price_desc","rating","newest","relevance"]},"description":"Sort order for results"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Maximum number of products to return"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of products to skip for pagination"}],"responses":{"200":{"description":"A paginated list of products","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."}},"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["products","pagination"]}}}},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{itemId}.json":{"get":{"operationId":"getProduct","summary":"Get product details","description":"Retrieve full details for a single product including variants, shipping, reviews, and return policy.","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"The product catalog ID"}],"responses":{"200":{"description":"Product details","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."}},"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/ProductDetail"}},"required":["product"]}}}},"404":{"description":"Product or store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections.json":{"get":{"operationId":"listCollections","summary":"List public collections","description":"List public, serviceable collections. Each item supplies exact canonical HTML and JSON URLs; mirrored merchant paths must not be constructed from the handle.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"One-based collection-list page"},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":100},"description":"Maximum collections per page"}],"responses":{"200":{"description":"A paginated list of public collections","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window for this caller"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window for this caller"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets"}},"content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CollectionSummary"}},"pagination":{"$ref":"#/components/schemas/CollectionListPagination"}},"required":["collections","pagination"]}}}},"404":{"description":"Store or collection page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/collections/{handle}":{"get":{"operationId":"getCollection","summary":"Get an ordered collection","description":"Retrieve one active collection by stable handle. Follow canonical_url for HTML and json_url for its exact machine-readable sibling.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"Stable merchant collection handle"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"One-based product page within the collection"}],"responses":{"200":{"description":"Active collection metadata and ordered products","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window for this caller"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window for this caller"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets"}},"content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/CollectionDetail"}},"required":["collection"]}}}},"404":{"description":"Collection or store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/redirect":{"get":{"operationId":"redirectToProduct","summary":"Redirect to merchant product page","description":"Redirect the user to the original merchant product page. Provide either a product_id or a search query to match a product.","parameters":[{"name":"product_id","in":"query","schema":{"type":"string"},"description":"The product catalog ID to redirect to"},{"name":"query","in":"query","schema":{"type":"string"},"description":"Search query to find and redirect to the best matching product"}],"responses":{"302":{"description":"Redirect to the merchant product page","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"The merchant product URL"}}},"400":{"description":"Missing product_id or query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brand-facts.json":{"get":{"operationId":"getBrandFacts","summary":"Get brand facts","description":"Retrieve structured brand information including store policies, support details, and product metadata. Supports conditional requests via If-Modified-Since.","parameters":[{"name":"If-Modified-Since","in":"header","schema":{"type":"string","format":"date-time"},"description":"Return 304 Not Modified if the brand facts have not changed since this date"}],"responses":{"200":{"description":"Brand facts object","content":{"application/json":{"schema":{"type":"object","description":"Structured brand information. Shape varies per store configuration."}}},"headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"The anonymous rate-limit allowance for this route, as <requests>;w=<window seconds>. A shared cache may serve this response, so it never describes one caller."},"Last-Modified":{"schema":{"type":"string"},"description":"When the brand facts were last updated"}}},"304":{"description":"Brand facts have not been modified since the requested date"},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the rate limit window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Product":{"type":"object","properties":{"catalog_id":{"type":"string"},"item_id":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"image_url":{"type":["string","null"],"format":"uri"},"additional_image_urls":{"type":["array","null"],"items":{"type":"string","format":"uri"}},"brand":{"type":["string","null"]},"price":{"type":["string","null"],"description":"Formatted price string, e.g. \"29.99 USD\""},"sale_price":{"type":["string","null"]},"availability":{"type":["string","null"],"enum":["in_stock","out_of_stock","preorder","backorder",null]},"product_category":{"type":["string","null"]},"star_rating":{"type":["number","null"],"minimum":0,"maximum":5},"review_count":{"type":["integer","null"],"minimum":0},"condition":{"type":["string","null"],"enum":["new","refurbished","used",null]},"product_insights":{"type":"array","description":"LLM-facing sections only; merchant-review claims and the source artifact summary are not included.","items":{"$ref":"#/components/schemas/ProductInsightSection"}},"product_guide":{"$ref":"#/components/schemas/ProductGuide","description":"Optional buying guide with independently enabled use cases and cross-brand product comparisons. Disabled sections, same-brand comparisons, and variant guidance are omitted. Omitted entirely when the product has no valid schemaVersion-3 guide with enabled content."}},"required":["catalog_id"]},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"group_id":{"type":["string","null"]},"has_variants":{"type":"boolean"},"variants":{"type":"object","properties":{"color":{"type":["string","null"]},"size":{"type":["string","null"]},"custom":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"option":{"type":"string"}},"required":["category","option"]}}}},"gender":{"type":["string","null"],"enum":["male","female","unisex",null]},"gtin":{"type":["string","null"]},"mpn":{"type":["string","null"]},"inventory_quantity":{"type":["integer","null"]},"shipping":{"description":"Shipping configuration object"},"delivery_estimate":{"type":["string","null"]},"return_policy":{"type":["string","null"]},"return_window_days":{"type":["integer","null"]},"accepts_returns":{"type":"boolean"},"reviews":{"description":"Product reviews data"},"target_countries":{"type":["string","null"]},"popularity_score":{"type":["number","null"]},"updated_at":{"type":"string","format":"date-time"}}}]},"ProductInsightProvenance":{"type":"object","description":"Source families and resolved URLs that ground one product-insight item.","properties":{"productData":{"type":"boolean"},"reviews":{"type":"boolean"},"qna":{"type":"boolean"},"urls":{"type":"array","items":{"type":"string","format":"uri"}}},"required":["productData","reviews","qna","urls"]},"ProductInsightItem":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"group":{"type":"string"},"detail":{"type":"string"},"claimType":{"type":"string"},"sourceTier":{"type":"string","enum":["primary","secondary"]},"provenance":{"$ref":"#/components/schemas/ProductInsightProvenance"}},"required":["value","provenance"]},"ProductInsightSection":{"type":"object","description":"An LLM-facing Product Insights section whose items carry compact provenance.","properties":{"title":{"type":"string"},"type":{"type":"string","enum":["key_value","card","bullets","paragraph","faq","comparison"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductInsightItem"}}},"required":["title","type","items"]},"ProductGuideSource":{"type":"object","description":"A cited source of the decision guide. Every sourceIds value in the guide resolves to one of these entries.","properties":{"id":{"type":"string"},"label":{"type":"string"},"url":{"type":"string","format":"uri"},"domain":{"type":"string"},"productRef":{"type":"string"},"sourceType":{"type":"string","enum":["focal_brand_pdp","alternative_brand_pdp","retailer_pdp","marketplace_pdp","unknown_pdp"],"description":"Where this product-page evidence came from."}},"required":["id","label","url","domain"]},"ProductGuideUseCase":{"type":"object","description":"One buyer situation the product is a good fit for, or not.","properties":{"id":{"type":"string"},"label":{"type":"string"},"audience":{"type":"string"},"buyerJob":{"type":"string"},"constraint":{"type":"string"},"outcome":{"type":"string"},"recommendation":{"type":"string"},"alternative":{"type":"object","description":"The product to choose instead (notBestFor entries).","properties":{"type":{"type":"string"},"refId":{"type":"string","description":"A comparison subject refId"},"label":{"type":"string"}},"required":["type","label"]},"claimAddress":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","recommendation","sourceIds"]},"ProductGuideDecisionRule":{"type":"object","description":"When to choose the option identified by chooseRefId.","properties":{"id":{"type":"string"},"chooseRefId":{"type":"string"},"when":{"type":"string"},"because":{"type":"string"},"claimAddress":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["id","chooseRefId","when","sourceIds"]},"ProductGuideDecisionValue":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["key","label","value"]},"ProductGuideVariantChoice":{"type":"object","properties":{"refId":{"type":"string"},"targetType":{"type":"string"},"variantId":{"type":"string"},"label":{"type":"string"},"price":{"type":"string"},"availability":{"type":"string"},"isCurrentSelection":{"type":"boolean","description":"True for the merchant listing's default variant. The storefront page shows every variant side by side and does not mark one as selected."},"decisionValues":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideDecisionValue"}},"sourceIds":{"type":"array","items":{"type":"string"}}},"required":["refId","targetType","label","isCurrentSelection","decisionValues","sourceIds"]},"ProductGuideVariantComparison":{"type":"object","description":"Choosing between variants of this product along one axis.","properties":{"id":{"type":"string"},"comparisonType":{"type":"string","enum":["variant_selection"]},"title":{"type":"string"},"focalProductRef":{"type":"string"},"axis":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"merchantOptionName":{"type":"string"}},"required":["key","label"]},"choices":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideVariantChoice"}},"decisionRules":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideDecisionRule"}}},"required":["id","comparisonType","title","choices","decisionRules"]},"ProductGuideSubject":{"type":"object","description":"One product in the compact product comparison.","properties":{"refId":{"type":"string"},"targetType":{"type":"string","const":"product"},"title":{"type":"string"},"brand":{"type":"string"},"url":{"type":"string","format":"uri"},"price":{"type":"string"},"availability":{"type":"string"},"isFocal":{"type":"boolean","description":"True for the product this JSON describes."},"relationship":{"type":"string","enum":["focal","same_brand","cross_brand"]}},"required":["refId","targetType","title","isFocal"]},"ProductGuideProductSummary":{"type":"object","description":"One cited summary explaining why and when to choose a product.","properties":{"productRef":{"type":"string"},"summary":{"type":"string"},"sourceIds":{"type":"array","minItems":1,"items":{"type":"string"}}},"required":["productRef","summary","sourceIds"]},"ProductGuideProductComparison":{"type":"object","description":"One compact comparison with one cited summary for every displayed product.","properties":{"id":{"type":"string"},"comparisonType":{"type":"string","const":"product_comparison"},"title":{"type":"string"},"focalProductRef":{"type":"string"},"subjects":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideSubject"}},"summaries":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ProductGuideProductSummary"}}},"required":["id","comparisonType","title","focalProductRef","subjects","summaries"]},"ProductGuide":{"type":"object","description":"Evidence-backed buying guide (contract schemaVersion 3). Read useCases for fit, variantSelection for documented option differences and productComparison for one cited summary per product. Every sourceIds value resolves in sources.","properties":{"id":{"type":"string"},"schemaVersion":{"type":"integer","const":3},"title":{"type":"string"},"answer":{"type":"string","deprecated":true,"description":"Deprecated compatibility field; the storefront does not display it."},"useCases":{"type":"object","properties":{"bestFor":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideUseCase"}},"notBestFor":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideUseCase"}}},"required":["bestFor","notBestFor"]},"comparisons":{"type":"object","properties":{"variantSelection":{"type":"array","items":{"$ref":"#/components/schemas/ProductGuideVariantComparison"}},"productComparison":{"$ref":"#/components/schemas/ProductGuideProductComparison"}},"required":["variantSelection"]},"sources":{"type":"array","description":"Only the sources the guide cites.","items":{"$ref":"#/components/schemas/ProductGuideSource"}}},"required":["id","schemaVersion","title","useCases","comparisons","sources"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"CollectionSummary":{"type":"object","properties":{"handle":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"canonical_url":{"type":"string","format":"uri"},"json_url":{"type":"string","format":"uri","description":"Exact JSON sibling of canonical_url."},"api_url":{"type":"string","format":"uri"},"source_product_count":{"type":"integer","minimum":0},"served_product_count":{"type":"integer","minimum":1},"source_updated_at":{"type":["string","null"],"format":"date-time"}},"required":["handle","title","description","canonical_url","json_url","api_url","source_product_count","served_product_count","source_updated_at"]},"CollectionListPagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["total","page","page_size","total_pages","has_more"]},"CollectionDetailPagination":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":1,"maximum":50},"total_pages":{"type":"integer","minimum":1}},"required":["page","page_size","total_pages"]},"CollectionDetail":{"type":"object","properties":{"handle":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"canonical_url":{"type":"string","format":"uri","description":"Exact AI Storefront HTML URL. Shopify collections use /collections/{handle}; mirrored merchants may use an arbitrary nested merchant path."},"json_url":{"type":"string","format":"uri","description":"Exact machine-readable sibling of canonical_url, preserving collection pagination."},"source_url":{"type":"string","format":"uri"},"generation_id":{"type":"string","format":"uuid"},"source_product_count":{"type":"integer","minimum":0},"served_product_count":{"type":"integer","minimum":1},"pagination":{"$ref":"#/components/schemas/CollectionDetailPagination"},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductDetail"}}},"required":["handle","title","description","canonical_url","json_url","source_url","generation_id","source_product_count","served_product_count","pagination","products"]}}}}