{ "openapi": "3.1.0", "info": { "title": "Pura Vida TLV Storefront & Catalog API", "version": "1.0.0", "description": "Pura Vida TLV Storefront & Catalog API v1. Versioning follows URL path versioning (/v1/) and semantic versioning. API deprecations are signaled 90 days in advance via HTTP Sunset and Deprecation headers per RFC 8594.", "contact": { "name": "Pura Vida TLV Engineering & Developer Relations", "url": "https://puravidatlv.com/developers", "email": "support@puravidatlv.com" }, "license": { "name": "Proprietary Storefront API License", "url": "https://puravidatlv.com/policies/terms-of-service" } }, "servers": [ { "url": "https://puravidatlv.com/v1", "description": "Versioned v1 Storefront API Server" }, { "url": "https://puravidatlv.com", "description": "Production Storefront API Server" } ], "components": { "securitySchemes": { "StorefrontZeroAuth": { "type": "http", "scheme": "bearer", "description": "Public storefront operations require zero authentication." }, "AdminOAuth2": { "type": "oauth2", "description": "Shopify Admin Scoped OAuth 2.0 Client Credentials Grant", "flows": { "clientCredentials": { "tokenUrl": "https://25a22e-2.myshopify.com/admin/oauth/access_token", "scopes": { "public_storefront": "Public catalog queries and cart operations", "read_products": "Read jewelry catalog and inventory levels", "write_products": "Manage jewelry listings and pricing", "read_orders": "Access order status and tracking details", "write_content": "Manage store pages and blog articles" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique UUID v4 string to ensure idempotent execution on retries", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "ProblemDetails": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "URI reference identifying error type" }, "title": { "type": "string", "description": "Short human-readable summary of problem" }, "status": { "type": "integer", "description": "HTTP status code" }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence" }, "instance": { "type": "string", "format": "uri", "description": "URI reference identifying the specific occurrence" } } }, "Product": { "type": "object", "required": [ "id", "title", "handle", "variants" ], "properties": { "id": { "type": "integer", "description": "Unique product ID" }, "title": { "type": "string", "description": "Product title in Hebrew/English" }, "handle": { "type": "string", "description": "URL handle" }, "body_html": { "type": "string", "description": "Product description and specifications" }, "vendor": { "type": "string", "description": "Brand vendor (Pura Vida TLV)" }, "product_type": { "type": "string", "description": "Jewelry type (Rings, Necklaces, Bracelets, Earrings)" }, "tags": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "price", "available" ], "properties": { "id": { "type": "integer", "description": "Variant ID" }, "title": { "type": "string", "description": "Variant title, e.g. Gold / Size 6" }, "price": { "type": "string", "description": "Price in ILS" }, "available": { "type": "boolean", "description": "Inventory availability" } } } } } }, "Cart": { "type": "object", "required": [ "token", "items", "item_count", "total_price" ], "properties": { "token": { "type": "string", "description": "Cart session token" }, "item_count": { "type": "integer", "description": "Total count of items in cart" }, "total_price": { "type": "integer", "description": "Total price in cents (ILS)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "quantity": { "type": "integer" }, "title": { "type": "string" }, "price": { "type": "integer" } } } } } } } }, "paths": { "/products.json": { "get": { "summary": "List jewelry products", "description": "Returns a paginated list of jewelry products with cursor-based and page-based pagination.", "operationId": "listProducts", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 250 }, "description": "Number of products to return" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor pagination token" } ], "responses": { "200": { "description": "Products retrieved successfully", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "page_info": { "type": "object", "properties": { "has_next_page": { "type": "boolean" }, "end_cursor": { "type": "string" } } } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/products/{handle}.json": { "get": { "summary": "Get product details by handle", "description": "Retrieve comprehensive details, pricing, and variants for a single product.", "operationId": "getProductByHandle", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product URL handle" } ], "responses": { "200": { "description": "Product details retrieved", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/collections.json": { "get": { "summary": "List collections", "description": "Retrieve jewelry collections (Rings, Necklaces, Bracelets, Earrings, Sets).", "operationId": "listCollections", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collections retrieved", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/collections/{handle}/products.json": { "get": { "summary": "List products in collection", "description": "Retrieve all jewelry items categorized under a specific collection.", "operationId": "getCollectionProducts", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection products retrieved", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/search/suggest.json": { "get": { "summary": "Search jewelry catalog", "description": "Search product titles, tags, and descriptions with instant suggestions.", "operationId": "searchCatalog", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Query term" }, { "name": "resources[type]", "in": "query", "required": false, "schema": { "type": "string", "default": "product" } } ], "responses": { "200": { "description": "Search suggestions retrieved", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "object" } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cart.json": { "get": { "summary": "Get current shopping cart", "description": "Inspect active session shopping cart items and checkout URL.", "operationId": "getCart", "security": [ { "StorefrontZeroAuth": [] } ], "responses": { "200": { "description": "Cart contents retrieved", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cart/add.json": { "post": { "summary": "Add product variant to cart", "description": "Add an item to the buyer session cart. Supports Idempotency-Key for network retries.", "operationId": "addItemToCart", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "Product variant ID" }, "quantity": { "type": "integer", "default": 1, "description": "Quantity to add" } } } } } }, "responses": { "200": { "description": "Item added to cart", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cart/batch.json": { "post": { "summary": "Batch add multiple items to cart (Bulk endpoint)", "description": "Accepts an array of line items to add to the cart in a single atomic bulk operation.", "operationId": "batchAddItemsToCart", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "Array of item variants and quantities to add", "items": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "integer", "description": "Product variant ID" }, "quantity": { "type": "integer", "default": 1 } } } } } } } } }, "responses": { "200": { "description": "Items added to cart in bulk", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cart/clear.json": { "post": { "summary": "Clear shopping cart", "description": "Empties all line items from the current cart session.", "operationId": "clearCart", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart cleared", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/jobs/catalog-export": { "post": { "summary": "Initiate async bulk catalog export job", "description": "Starts an asynchronous background job to export full product catalog data.", "operationId": "createCatalogExportJob", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Job accepted and processing asynchronously", "headers": { "Location": { "description": "URL to poll for job status", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "poll_url" ], "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "poll_url": { "type": "string" } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/jobs/{job_id}": { "get": { "summary": "Check async job status", "description": "Poll status and progress of an asynchronous job.", "operationId": "getCatalogExportJobStatus", "security": [ { "StorefrontZeroAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current job status", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "result_url": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Standard Problem Details error response per RFC 9457", "headers": { "RateLimit-Limit": { "description": "The maximum number of allowed requests in the current time window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "The number of remaining requests allowed in the current time window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Number of seconds to wait before retrying after a 429 response", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } } }