{ "openapi": "3.1.0", "info": { "title": "Storefront BulqC API Doc", "version": "2.0.0-seller-ui-integration", "description": "Storefront-only extraction. Missing success schemas supplemented from buyer-safe backend DTOs and storefront types." }, "servers": [ { "url": "https://api.bulqc.com", "description": "BulqC API" } ], "paths": { "/api/v2/storefront/{slug}/me/support/tickets": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "buyerSupportTickets", "summary": "List the signed-in buyer's tickets", "description": "Private, no-store. Store is resolved from slug and must match the active buyer session. Returns items (buyer-safe tickets), nextOffset and total; excludes staff fields, counts and internal activity.", "security": [ { "session": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Buyer-only ticket page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSupportPage" } } } }, "401": { "description": "Sign in required" }, "404": { "description": "Wrong store or buyer scope" } } }, "post": { "operationId": "createBuyerSupportTicket", "summary": "Create a buyer support ticket", "description": "Customer and store are derived on the server. Rejects seller-only fields. Optional orderId must belong to this buyer in this store. Same support tickets as Seller Hub; channel storefront. Requires Idempotency-Key; retries with the same body return the same ticket, conflicting reuse returns 409.", "security": [ { "session": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject", "body", "category" ], "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 240 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "category": { "type": "string", "enum": [ "order_issue", "payment", "return_replacement", "product_query", "other" ] }, "orderId": { "type": "string", "nullable": true, "pattern": "^[a-f0-9]{24}$" } } } } } }, "responses": { "201": { "description": "Buyer-safe created ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSupportTicket" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Sign in required" }, "404": { "description": "Wrong scope or order" }, "409": { "description": "Idempotency conflict" } } } }, "/api/v2/storefront/{slug}/me/support/tickets/{ticketId}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "get": { "operationId": "buyerSupportTicket", "summary": "Read own ticket conversation", "description": "Private, no-store. Returns buyer-safe ticket and public messages only, never internal notes, staff identifiers, assignment, resolution notes or activity. ticketId accepts an existing Mongo ID or the authoritative store-scoped T-\u2026 ticket number; current buyer ownership is required for both.", "security": [ { "session": [] } ], "responses": { "200": { "description": "Ticket and messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSupportConversation" } } } }, "401": { "description": "Sign in required" }, "404": { "description": "Ticket outside buyer/store scope" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:[a-f0-9]{24}|T-[1-9][0-9]{0,14})$" } } ] } }, "/api/v2/storefront/{slug}/me/support/tickets/{ticketId}/messages": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "post": { "operationId": "replyToBuyerSupportTicket", "summary": "Reply to own support ticket", "description": "Private, no-store. Optimistic version and durable idempotency required. Public buyer message only. A reply reopens resolved/waiting tickets; closed tickets reject replies.", "security": [ { "session": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "body" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 } } } } } }, "responses": { "200": { "description": "Updated buyer-safe ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSupportTicket" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Sign in required" }, "404": { "description": "Wrong buyer scope" }, "409": { "description": "Version/idempotency conflict or closed ticket" } } } }, "/api/v2/storefront/{slug}/me/support/attachments/{attachmentId}/download": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "get": { "operationId": "buyerSupportAttachment", "summary": "Download an attachment from a public message in own ticket", "security": [ { "session": [] } ], "responses": { "200": { "description": "Short-lived signed download URL; private, no-store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportDownload" } } } }, "401": { "description": "Sign in required" }, "404": { "description": "Attachment inaccessible to buyer" } } } }, "/api/v2/storefront/{slug}/me": { "get": { "summary": "Read own store-bound buyer profile", "description": "", "operationId": "get__api_v2_storefront_slug_me", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] }, "patch": { "summary": "Update own buyer contact or business name", "description": "", "operationId": "patch__api_v2_storefront_slug_me", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerProfileUpdate" } } } }, "security": [ { "session": [] } ] }, "delete": { "operationId": "deleteBuyerAccount", "summary": "Soft-delete the current store-bound buyer account", "description": "Requires the current buyer session for this slug and the normal cookie/Origin protections. No target ID is accepted. Atomically retires the identity, releases its phone for a fresh OTP signup, revokes every session and existing login/email challenges, and suppresses notifications to the retired buyer. Retains historical records and private original phone; this is not irreversible erasure. Re-registration creates a new buyer ID with no old profile, addresses, orders, approval, tier assignment, verified email, consent or sessions. Email must be enrolled and verified again. Does not delete merchant accounts, organizations or stores. Repeat calls using the retired cookie return 401 and cannot change the fresh identity. A lost response should be followed by a profile check; 401 means the cookie is no longer active, not proof by itself of deletion. Existing commercial commitments continue through their normal lifecycle. An existing active session can self-delete when its store is no longer public; signup still requires an available public store.", "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "204": { "description": "Account retired; session cookie cleared" }, "400": { "description": "Unexpected request fields or invalid slug" }, "401": { "description": "Missing, expired or revoked session; includes repeated deletion with the old cookie" }, "403": { "description": "Origin protection rejected the request" }, "404": { "description": "Missing store, merchant session, or buyer session bound to another store" } }, "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } } ] } }, "/api/v2/storefront/{slug}/checkout/quotes": { "post": { "summary": "Create an expiring server-priced buyer quote", "operationId": "createCheckoutQuote", "description": "Creates a five-minute server-priced quote for a live public store with published delivery and tax settings. GST uses the explicit delivery state code as place of supply, active product HSN rates, line-level mixed-rate shipping allocation and the published rounding mode. A quote does not reserve stock.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutQuoteInput" } } } }, "responses": { "201": { "description": "Immutable five-minute quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutQuote" } } } }, "409": { "description": "Stale cart, missing policy or HSN, unavailable price/stock, serviceability or delivery state code" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/catalog/products": { "get": { "summary": "List published Phase 3 catalog products with store offers and shared stock", "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "query", "schema": { "type": "string", "maxLength": 100 } }, { "in": "query", "name": "categoryId", "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } }, { "in": "query", "name": "attributes", "schema": { "type": "string", "description": "Comma-separated attributeCode:optionCode filters; all must match one selected variation." } }, { "in": "query", "name": "sort", "schema": { "enum": [ "rank", "name" ], "default": "rank" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogPage" } } } }, "403": { "description": "Store-specific buyer sign-in or explicit approval required to view this catalogue." }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Search matches displayed product names or organization-scoped brand names using escaped literal matching. Name sort uses the lowercased displayed name and listing ID. Name cursors are version 2; obsolete cursors return INVALID_CURSOR. Rank cursors are unchanged." } }, "/api/v2/storefront/{slug}/me/addresses": { "get": { "summary": "List own buyer addresses in this store", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active addresses", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerAddress" } } } } } } }, "401": { "description": "Buyer login required" }, "404": { "description": "Store unavailable" } }, "security": [ { "session": [] } ] }, "post": { "summary": "Create an own-store buyer address with an idempotency key", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerAddressInput" } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCreatedAddress" } } } }, "201": { "description": "Address created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCreatedAddress" } } } }, "400": { "description": "Invalid input" }, "409": { "description": "Address limit or conflict" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/cart": { "get": { "summary": "Read or create store-bound guest or buyer cart; merge guest cart after buyer login", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current cart; checkout remains unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } } } } }, "/api/v2/storefront/{slug}/me/whatsapp/preferences": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read own buyer WhatsApp preferences for this store", "description": "Missing preferences default to utilityEnabled true and marketingEnabled false, with null consent timestamps and version. Existing opt-outs remain effective. The policy default does not create a consent record.", "operationId": "getBuyerWhatsAppPreference", "responses": { "200": { "description": "Current preference and version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontWhatsAppPreference" } } } }, "404": { "description": "Wrong buyer or store" } }, "security": [ { "session": [] } ] }, "put": { "summary": "Set own buyer WhatsApp preferences for this store", "description": "Marketing is disabled until the buyer explicitly enables it for this store.", "operationId": "setBuyerWhatsAppPreference", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppPreferenceInput" } } } }, "responses": { "200": { "description": "Updated preference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontWhatsAppPreference" } } } }, "409": { "description": "Version conflict" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/media/{assetId}": { "get": { "summary": "Redirect to a short-lived ready-media download", "security": [ { "session": [] } ], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "assetId", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Signed media redirect" }, "403": { "description": "Store-specific buyer sign-in or explicit approval required to view this catalogue." }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Published eligible product media redirects to the CloudFront detail URL when the feature is enabled; unpublished product originals are denied. Legacy single-key public derivatives remain supported. Published catalogue/price visibility is enforced for an optional same-store buyer session. Cache-Control: private, no-store; Vary: Cookie. Restricted catalogue denies data/media/facets; bootstrap keeps public business branding but returns no products/About product IDs. Hidden prices use null and empty quantityBreaks. Restricted authorized product media uses private signed URLs, never public CDN URLs." } }, "/api/v2/storefront/{slug}/cart/items/{sellableId}": { "patch": { "summary": "Set pack count for an existing cart line", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sellableId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "packs", "expectedVersion" ], "properties": { "packs": { "type": "integer", "minimum": 1, "maximum": 100000 }, "expectedVersion": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "400": { "description": "Invalid pack quantity" }, "409": { "description": "Cart version conflict" } } }, "delete": { "summary": "Remove a cart line", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sellableId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "409": { "description": "Cart version conflict" } } } }, "/api/v2/storefront/{slug}/orders/{orderId}/invoices/{documentId}": { "get": { "summary": "Read own invoice", "operationId": "Readowninvoice", "description": "", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string", "pattern": "^(?:[a-f0-9]{24}|ORD-[A-F0-9]{24}|[A-Z0-9]{6})$" } }, { "in": "path", "name": "documentId", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedDownload" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/orders": { "get": { "summary": "List buyer orders", "operationId": "Listbuyerorders", "description": "", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/cart/items": { "post": { "summary": "Add whole packs of a listed sellable", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sellableId", "packs", "expectedVersion" ], "properties": { "sellableId": { "type": "string" }, "packs": { "type": "integer", "minimum": 1, "maximum": 100000 }, "expectedVersion": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "400": { "description": "Invalid pack quantity" }, "404": { "description": "Sellable unavailable" }, "409": { "description": "Cart version conflict" } } } }, "/api/v2/storefront/{slug}/auth/otp/request": { "post": { "summary": "Request store-bound buyer OTP", "description": "Store must be live or paused in an active organization. Does not accept tenant IDs. Phone limits span all stores. Optional emailCopy selects an additional verified-email copy; it never replaces SMS/WhatsApp or enrolls/links an address.", "operationId": "post__api_v2_storefront_slug_auth_otp_request", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOtpRequest" } } } } } }, "/api/v2/storefront/{slug}/orders/{orderId}": { "get": { "summary": "Read a buyer-owned historical order", "operationId": "getBuyerOrder", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string", "pattern": "^(?:[a-f0-9]{24}|ORD-[A-F0-9]{24}|[A-Z0-9]{6})$" } } ], "responses": { "200": { "description": "Order snapshot, including after store closure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOrder" } } } }, "404": { "description": "Not found or not owned" } }, "security": [ { "session": [] } ] } }, "/api/v2/auth/logout": { "post": { "summary": "Revoke current session", "description": "Revoke a valid session and clear the host-only cookie. Missing or invalid sessions also receive 204 with cookie clearing. Production requires an allowed canonical buyer or seller origin; wrong-origin valid sessions remain forbidden.", "operationId": "post__api_v2_auth_logout", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "responses": { "204": { "description": "Session revoked; cookie cleared" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/me/addresses/{addressId}": { "patch": { "summary": "Update an own-store address with its expected version", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerAddressUpdateInput" } } } }, "responses": { "200": { "description": "Updated address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerAddress" } } } }, "404": { "description": "Address inaccessible" }, "409": { "description": "Version or default conflict" } }, "security": [ { "session": [] } ] }, "delete": { "summary": "Delete an own-store address", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "204": { "description": "Address deleted" }, "404": { "description": "Address inaccessible" }, "409": { "description": "Version or default conflict" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/checkout/attempts": { "post": { "summary": "Hold stock and create a pending buyer order", "operationId": "createCheckoutAttempt", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAttemptInput" } } } }, "responses": { "201": { "description": "Pending order and fifteen-minute stock hold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAttempt" } } } }, "409": { "description": "Requote, payment connection, stock, or acknowledgement required" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/checkout/attempts/{attemptId}/payment": { "post": { "summary": "Initiate Razorpay test-mode payment", "operationId": "initiateCheckoutPayment", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "attemptId", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "Provider order for browser checkout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInitiation" } } } }, "409": { "description": "Expired or unknown initiation; reconcile before retry" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/order-links/{orderId}": { "get": { "operationId": "getStorefrontLinkedOrder", "summary": "Read linked order as its owning buyer or authorized store merchant", "description": "Requires a revocable session. Store scope is resolved from the persisted slug; merchants require current orders.read. Returns only order presentation fields. A URL is not authorization.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:[a-f0-9]{24}|ORD-[A-F0-9]{24}|[A-Z0-9]{6})$" } } ], "responses": { "200": { "description": "Authorized order snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedOrder" } } } }, "400": { "description": "Invalid route identifier" }, "401": { "description": "Authentication required" }, "404": { "description": "Order not found or access denied" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/checkout/attempts/{attemptId}": { "get": { "summary": "Read own checkout attempt", "operationId": "getCheckoutAttempt", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "attemptId", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "Buyer-owned attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAttempt" } } } }, "404": { "description": "Not found or not owned" } }, "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/checkout/quotes/{quoteId}": { "get": { "summary": "Read the buyer's own quote", "operationId": "getCheckoutQuote", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "quoteId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Buyer-owned quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutQuote" } } } }, "404": { "description": "Quote unavailable or owned by another buyer" } }, "security": [ { "session": [] } ] } }, "/api/v2/auth/otp/request": { "post": { "summary": "Request merchant OTP", "description": "Does not return or log OTP. Maximum five phone requests and twenty source requests per fixed UTC-hour window, and rolling sixty-second resend cooldown. No real sender is enabled by default.", "operationId": "post__api_v2_auth_otp_request", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } } } }, "/api/v2/storefront/{slug}/products": { "get": { "summary": "Browse published store products", "description": " Published catalogue/price visibility is enforced for an optional same-store buyer session. Cache-Control: private, no-store; Vary: Cookie. Restricted catalogue denies data/media/facets; bootstrap keeps public business branding but returns no products/About product IDs. Hidden prices use null and empty quantityBreaks. Restricted authorized product media uses private signed URLs, never public CDN URLs.", "operationId": "get_api_v2_storefront_slug_products", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Store-specific buyer sign-in or explicit approval required to view this catalogue." }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, stale version or readiness blocker", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or import exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Import contains validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] } }, "/api/v2/auth/otp/verify": { "post": { "summary": "Verify single-use OTP and establish cookie session", "description": "Five attempts per challenge, five-minute expiry, fifty verification requests/source per five-minute window. Challenge determines merchant versus buyer/store scope.", "operationId": "post__api_v2_auth_otp_verify", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "Set-Cookie": { "description": "Opaque eight-hour session cookie; HttpOnly; SameSite=Strict; Path=/api/v2; Secure in production. Rotation preserves absolute expiry.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } } } }, "/api/v2/storefront/{slug}/me/catalog/products": { "get": { "summary": "List buyer-specific catalogue products with tier prices", "security": [ { "session": [] } ], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "query", "schema": { "type": "string", "maxLength": 100 } }, { "in": "query", "name": "categoryId", "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } }, { "in": "query", "name": "attributes", "schema": { "type": "string", "description": "Comma-separated attributeCode:optionCode filters; all must match one selected variation." } }, { "in": "query", "name": "sort", "schema": { "enum": [ "rank", "name" ], "default": "rank" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogPage" } } } }, "403": { "description": "Store-specific buyer sign-in or explicit approval required to view this catalogue." }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "ListBuyerCatalogProducts", "description": "Search matches displayed product names or organization-scoped brand names using escaped literal matching. Name sort uses the lowercased displayed name and listing ID. Name cursors are version 2; obsolete cursors return INVALID_CURSOR. Rank cursors are unchanged." } }, "/api/v2/storefront/{slug}/catalog/filters": { "get": { "summary": "Get published category and attribute facet counts", "description": "Category facets include categoryId, count and name. Names are resolved from active categories belonging to this store's organization; unavailable names are null. Published catalogue/price visibility is enforced for an optional same-store buyer session. Cache-Control: private, no-store; Vary: Cookie. Restricted catalogue denies data/media/facets; bootstrap keeps public business branding but returns no products/About product IDs. Hidden prices use null and empty quantityBreaks. Restricted authorized product media uses private signed URLs, never public CDN URLs.", "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "categories": { "type": "array" }, "attributes": { "type": "array" } } } } } }, "403": { "description": "Store-specific buyer sign-in or explicit approval required to view this catalogue." }, "404": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/storefront/{slug}/bootstrap": { "get": { "summary": "Get published storefront configuration and capabilities", "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published storefront bootstrap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBootstrap" } } } }, "404": { "description": "Store unavailable or not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Published configuration and real products only. Responses use Cache-Control: no-store and no ETag. Host/slug mismatches return 404 in subdomain mode. Published catalogue/price visibility is enforced for an optional same-store buyer session. Cache-Control: private, no-store; Vary: Cookie. Restricted catalogue denies data/media/facets; bootstrap keeps public business branding but returns no products/About product IDs. Hidden prices use null and empty quantityBreaks. Restricted authorized product media uses private signed URLs, never public CDN URLs." } }, "/api/v2/storefront/bootstrap": { "get": { "summary": "Resolve storefront bootstrap from its configured subdomain", "description": "Subdomain mode only. Uses Host; X-Forwarded-Host is ignored. Unknown hosts return 404. Published catalogue/price visibility is enforced for an optional same-store buyer session. Cache-Control: private, no-store; Vary: Cookie. Restricted catalogue denies data/media/facets; bootstrap keeps public business branding but returns no products/About product IDs. Hidden prices use null and empty quantityBreaks. Restricted authorized product media uses private signed URLs, never public CDN URLs.", "operationId": "get_api_v2_storefront_bootstrap", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBootstrap" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, stale version or readiness blocker", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload or import exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Import contains validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/v2/storefront/{slug}/checkout/orders": { "post": { "summary": "Place a production manual-terms order without online payment", "description": "Default public order flow after onboarding publication. pay_later mode needs no online-payment approval, live-provider flags or payment connection, including production. Requires ready/enabled checkout, buyer session, current quote and Idempotency-Key. Checks warehouse, delivery, pricing and tax. Pay-later defaults to untracked inventory (unlimited stock capacity) unless published settings select inventoryMode=tracked. Only tracked orders check stock/backorders and commit inventory demand. paymentMethod=manual_terms, paymentStatus=unpaid and paidMinor=0. Settlement is recorded separately. Successful manual/pay-later placement clears the quoted buyer cart and increments its version atomically with order creation. Concurrent cart edits conflict instead of losing unquoted items; failed checkout leaves the cart unchanged. Same-key retries return the original order without duplicate demand or clearing subsequently added cart items. Legacy test/live modes retain their existing production gates.", "operationId": "placeManualOrder", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAttemptInput" } } } }, "responses": { "201": { "description": "Unpaid pay-later order placed and demand committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerOrder" } } } }, "404": { "description": "Store or buyer context unavailable" }, "409": { "description": "Quote expired, stock conflict, or backorder acknowledgement required" } }, "security": [ { "session": [] } ] } }, "/api/v2/auth/me": { "get": { "summary": "Read authenticated identity", "description": "", "operationId": "get__api_v2_auth_me", "parameters": [], "responses": { "200": { "description": "Own profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccountProfile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication or challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing or inaccessible resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] }, "patch": { "summary": "Merchant-only personal name update", "parameters": [], "responses": { "200": { "description": "Own updated profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccountProfile" } } } }, "400": { "description": "Invalid or inactive selection" }, "401": { "description": "Authentication required" }, "409": { "description": "Slug, version or idempotency conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "email": { "type": "string", "maxLength": 254 }, "photo": { "type": "string", "nullable": true, "maxLength": 220000 }, "expectedVersion": { "type": "integer", "minimum": 0 } } } } } }, "description": "Update own merchant name, optional contact email and/or a bounded profile photo. expectedVersion protects against stale updates. Photo input is null to remove, or JPG/PNG/WebP data URI, at most 220000 characters; server validates actual bytes, rejects animation and more than 16 million pixels, crops to at most 400px square, strips metadata and stores a small private WebP. Existing photo is retained when omitted. No mobile changes are accepted here.", "security": [ { "session": [] } ] } }, "/api/v2/storefront/{slug}/me/email/request": { "post": { "summary": "Request buyer email verification", "operationId": "requestBuyerEmailOwnership", "description": "Authenticated store-bound buyer and live session. Uses actual OTP lifetime, 60-second cooldown, ownership-only purpose. Does not verify or link accounts. Unknown submission can return 202; definitive rejection returns 503.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "security": [ { "session": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } }, "400": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Email enrollment unavailable or definite provider rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerEmailEnrollmentRequest" } } } } } }, "/api/v2/storefront/{slug}/me/email/verify": { "post": { "summary": "Verify buyer email ownership", "operationId": "verifyBuyerEmailOwnership", "description": "Session/store/identity-bound ownership proof, five attempts, single-use, cannot authenticate. Successful proof updates address, verification, consent and profile version together.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Email enrollment unavailable or definite provider rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } } } }, "/api/v2/storefront/{slug}/me/email/preferences": { "patch": { "summary": "Update buyer email preferences", "operationId": "updateBuyerEmailNotificationConsent", "description": "Requires a live store-bound buyer session and matching profile version; identity email verification is not required to opt out or opt in. Records an explicit transactional email preference for the seller customer-record email and invalidates pending delivery contexts through version change. Login OTP email copies still require verified identity email.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Email enrollment unavailable or definite provider rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerEmailPreferenceRequest" } } } } } }, "/api/v2/storefront/{slug}/me/email": { "delete": { "summary": "Remove buyer email", "operationId": "removeBuyerEmail", "description": "Clears address, verification and consent; invalidates pending proofs and delivery contexts.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must exactly match a configured allowed origin, including port. Required for all mutations, including OTP requests." } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Invalid input, challenge, context, version or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Email enrollment unavailable or definite provider rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/storefront/{slug}/render-data": { "get": { "summary": "Get storefront render-data", "operationId": "getStorefrontRenderData", "security": [], "description": "Always anonymous, including when Cookie is supplied. Catalog returns the first 50 rank-sorted products and facets; About includes selected products or a published fallback. Policies omit catalog work. No cart creation or Set-Cookie. Current publication and visibility checks precede internal caching.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$" } }, { "in": "query", "name": "view", "schema": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy" ], "default": "catalog" } } ], "responses": { "200": { "description": "Current storefront data; Cache-Control: private, no-store; Vary: Cookie", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Server-Timing": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontRenderData" } } } }, "400": { "description": "Invalid view/slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Store unavailable or host mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Dependency failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/storefront/{slug}/session-context": { "get": { "summary": "Get storefront session-context", "operationId": "getStorefrontSessionContext", "security": [], "description": "Optional live authentication is resolved once. Matching buyer receives profile and permitted catalog/pricing. Guest or incompatible account never receives buyer catalog/profile. Rechecks approval and visibility on every request. No cart creation or merge.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$" } }, { "in": "query", "name": "view", "schema": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy", "shell" ], "default": "catalog" } } ], "responses": { "200": { "description": "Current storefront data; Cache-Control: private, no-store; Vary: Cookie", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Server-Timing": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSessionContext" } } } }, "400": { "description": "Invalid view/slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Store unavailable or host mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Dependency failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/storefront/{slug}/cart/context": { "get": { "summary": "Restore storefront identity and cart in one request", "operationId": "getStorefrontCartContext", "security": [], "description": "Resolves current publication, visibility and live identity once. With cart=1 (default), creates/restores a guest cart or restores a matching buyer cart and merges an eligible guest cart. With cart=0, defers cart work and returns cartDeferred. Incompatible sessions never receive buyer cart/profile. A valid anonymous publicVersion can reuse SSR catalog data; buyer pricing is always restored from current access. Independent cart/catalog/filter failures are reported separately.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$" } }, { "in": "query", "name": "view", "schema": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy", "shell" ], "default": "catalog" } }, { "name": "publicVersion", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Fresh anonymous SSR configuration version; never used to grant access." }, { "name": "cart", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "1" }, "description": "Defer cart work on views that do not need it." } ], "responses": { "200": { "description": "Current storefront data; Cache-Control: private, no-store; Vary: Cookie", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Server-Timing": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCartContext" } } } }, "400": { "description": "Invalid view/slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Store unavailable or host mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Dependency failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "StorefrontSupportPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontSupportTicket" } }, "nextOffset": { "type": "integer", "nullable": true }, "total": { "type": "integer" } }, "required": [ "items", "nextOffset", "total" ] }, "StorefrontSupportTicket": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "subject": { "type": "string" }, "category": { "type": "string", "enum": [ "order_issue", "payment", "return_replacement", "product_query", "other" ] }, "status": { "type": "string", "enum": [ "open", "waiting_on_buyer", "resolved", "closed" ] }, "createdAt": { "type": "string" }, "lastActivityAt": { "type": "string" }, "orderId": { "type": "string", "nullable": true }, "version": { "type": "integer" } }, "required": [ "id", "number", "subject", "category", "status", "createdAt", "lastActivityAt", "orderId", "version" ] }, "StorefrontSupportConversation": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/StorefrontSupportTicket" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string", "enum": [ "buyer", "seller" ] }, "body": { "type": "string" }, "at": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "from", "body", "at", "attachments" ] } } }, "required": [ "ticket", "messages" ] }, "SupportDownload": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri" }, "expiresIn": { "type": "integer", "const": 300 } }, "required": [ "url", "expiresIn" ] }, "Profile": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "name": { "type": "string" }, "phone": { "type": "string" }, "kind": { "enum": [ "merchant", "buyer" ] }, "storeId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "businessName": { "type": "string" }, "businessProfileVersion": { "type": [ "integer", "null" ] }, "email": { "type": "string", "description": "Empty when absent. Only ownership-proof flow verifies buyer email." }, "emailVerified": { "type": "boolean" }, "transactionalEmailPreference": { "type": "string", "enum": [ "default", "enabled", "disabled", "unknown" ], "description": "Customer-record transactional email policy. Default applies only to newly created identities; unknown legacy false preferences are suppressed. Buyer preferences may be changed without verifying the authentication email." }, "emailNotificationsEnabled": { "type": "boolean", "description": "Buyer notification consent; false by default." }, "profileVersion": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "phone", "kind" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "error", "requestId" ] }, "BuyerProfileUpdate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "businessName": { "type": "string", "maxLength": 120 }, "expectedBusinessProfileVersion": { "type": [ "integer", "null" ], "minimum": 0 } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "businessName", "expectedBusinessProfileVersion" ] } ] }, "CreateCheckoutQuoteInput": { "type": "object", "additionalProperties": false, "required": [ "expectedCartVersion", "addressId" ], "properties": { "expectedCartVersion": { "type": "integer", "minimum": 0 }, "addressId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "billingAddressId": { "type": "string", "pattern": "^[a-f0-9]{24}$", "description": "Optional buyer-owned billing address. When absent, the delivery address is used for billing." } } }, "CheckoutQuote": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "expiresAt", "currency", "address", "lines", "merchandiseSubtotalMinor", "shippingMinor", "taxMinor", "grandTotalMinor", "requiresBackorderAcknowledgement", "taxableValueMinor", "taxAddedMinor", "roundOffMinor", "taxMode", "roundingMode", "supplierGstin", "supplierStateCode", "placeOfSupplyStateCode", "billingAddress" ], "properties": { "id": { "type": "string" }, "status": { "enum": [ "valid", "consumed" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "currency": { "const": "INR" }, "address": { "type": "object" }, "lines": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "productId", "sellableId", "packs", "baseUnits", "pricePerPackMinor", "merchandiseMinor", "taxMinor", "lineTotalMinor", "backorder" ], "properties": { "productId": { "type": "string" }, "sellableId": { "type": "string" }, "packs": { "type": "integer", "minimum": 1 }, "baseUnits": { "type": "integer", "minimum": 1 }, "pricePerPackMinor": { "type": "integer", "minimum": 0 }, "merchandiseMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "lineTotalMinor": { "type": "integer", "minimum": 0 }, "backorder": { "type": "boolean" }, "dispatchLeadDays": { "type": [ "integer", "null" ] }, "availableToPromiseBaseUnits": { "type": [ "integer", "null" ], "description": "Null when stock is not tracked, never fabricated stock." }, "backorderedBaseUnits": { "type": "integer", "minimum": 0 }, "productTaxableMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "shippingAllocationMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "shippingTaxableMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "taxableValueMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "cgstMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "sgstMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "igstMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "cessMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "taxAddedMinor": { "type": "integer", "minimum": 0, "description": "INR paise" }, "hsnId": { "type": [ "string", "null" ] }, "hsnCode": { "type": [ "string", "null" ] }, "taxRateId": { "type": [ "string", "null" ], "description": "Referenced platform tax rate, snapshotted at quote time; null for tenant HSN/no-tax." }, "taxRateVersion": { "type": [ "integer", "null" ], "description": "Immutable accepted tax-rate version." }, "gstRateBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000 }, "cessRateBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000 }, "taxInclusive": { "type": "boolean", "description": "Listed product price includes both GST and cess." }, "name": { "type": "string" }, "sku": { "type": "string" }, "unit": { "enum": [ "pc", "set" ] }, "attributeValues": { "type": "array", "items": { "$ref": "#/components/schemas/VariationAttributeValue" } }, "packSize": { "type": "integer", "minimum": 1 } }, "description": "lineTotalMinor includes allocated shipping and tax added at checkout. Product and shipping taxable values and tax components are snapshotted separately." } }, "merchandiseSubtotalMinor": { "type": "integer", "minimum": 0 }, "shippingMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "grandTotalMinor": { "type": "integer", "minimum": 0 }, "inventoryMode": { "enum": [ "tracked", "untracked" ], "description": "Server-derived snapshot. Untracked quotes have no stock capacity/backorder requirement; changing mode requires a fresh quote." }, "deliveryMode": { "enum": [ "configured", "deferred" ], "description": "Deferred V0 pay-later allows all Indian delivery PINs with no seller address/policy requirement, no order-value minimum and zero shipping fee. Existing quotes must be refreshed when this mode changes." }, "requiresBackorderAcknowledgement": { "type": "boolean" }, "taxableValueMinor": { "type": "integer", "description": "INR paise; roundOffMinor may be negative." }, "taxAddedMinor": { "type": "integer", "description": "INR paise; roundOffMinor may be negative." }, "roundOffMinor": { "type": "integer", "description": "INR paise; roundOffMinor may be negative." }, "taxMode": { "type": "string", "enum": [ "none", "gst" ] }, "roundingMode": { "type": "string", "enum": [ "paise", "nearest_rupee" ] }, "supplierGstin": { "type": [ "string", "null" ] }, "supplierStateCode": { "type": [ "string", "null" ] }, "placeOfSupplyStateCode": { "type": [ "string", "null" ] }, "billingAddress": { "type": "object", "description": "Immutable billing address snapshot. Place of supply still uses the delivery state code." }, "warehouseName": { "type": [ "string", "null" ], "readOnly": true }, "taxDisplay": { "$ref": "#/components/schemas/CheckoutTaxDisplay" } } }, "VariationAttributeValue": { "type": "object", "additionalProperties": false, "required": [ "attributeCode", "optionCode" ], "properties": { "attributeCode": { "type": "string" }, "optionCode": { "type": "string" } } }, "CheckoutTaxDisplay": { "type": "object", "additionalProperties": false, "description": "Informational integer paise split, from the authoritative calculator. Does not change payable totals or allocated line totals; inclusive taxes are already included.", "required": [ "product", "delivery" ], "properties": { "product": { "$ref": "#/components/schemas/CheckoutTaxComponents" }, "delivery": { "$ref": "#/components/schemas/CheckoutTaxComponents" } } }, "CheckoutTaxComponents": { "type": "object", "additionalProperties": false, "required": [ "cgstMinor", "sgstMinor", "igstMinor", "cessMinor", "taxMinor" ], "properties": { "cgstMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sgstMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "igstMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cessMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "taxMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "PublicCatalogPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCatalogRoot" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] }, "PublicCatalogRoot": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "type": { "enum": [ "simple", "variable" ] }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{24}$" } }, "featured": { "type": "boolean" }, "sellables": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCatalogSellable" } }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCatalogMedia" } }, "specifications": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "id", "type", "name", "slug", "description", "imageUrl", "categories", "featured", "sellables", "media" ] }, "PublicCatalogSellable": { "type": "object", "additionalProperties": false, "properties": { "sellableId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "sku": { "type": "string" }, "name": { "type": "string" }, "attributeValues": { "type": "array", "items": { "$ref": "#/components/schemas/VariationAttributeValue" } }, "packSize": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "enum": [ "pc", "set" ] }, "pricePerPackMinor": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "priceOnRequest": { "type": "boolean" }, "quantityBreaks": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/QuantityBreak" } }, "minimumPacks": { "type": "integer", "minimum": 1, "maximum": 100000 }, "incrementPacks": { "type": "integer", "minimum": 1, "maximum": 100000 }, "inventoryMode": { "enum": [ "tracked", "untracked" ] }, "availablePacks": { "type": [ "integer", "null" ], "minimum": 0, "description": "Null for untracked inventory: no stock-based order limit." }, "availableToPromiseBaseUnits": { "type": [ "integer", "null" ] }, "backorderedBaseUnits": { "type": "integer", "minimum": 0 }, "available": { "type": "boolean" }, "orderable": { "const": false }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCatalogMedia" } }, "imageUrl": { "type": [ "string", "null" ] }, "pricesVisible": { "type": "boolean", "description": "false when the current viewer must sign in or obtain store-specific approval to view prices." } }, "required": [ "sellableId", "sku", "name", "attributeValues", "packSize", "unit", "pricePerPackMinor", "priceOnRequest", "quantityBreaks", "minimumPacks", "incrementPacks", "availablePacks", "availableToPromiseBaseUnits", "backorderedBaseUnits", "available", "orderable", "media", "imageUrl" ] }, "QuantityBreak": { "type": "object", "additionalProperties": false, "properties": { "minimumPacks": { "type": "integer", "minimum": 1, "maximum": 100000 }, "pricePerPackMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "minimumPacks", "pricePerPackMinor" ] }, "PublicCatalogMedia": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "url": { "type": "string" }, "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 }, "altText": { "type": "string" }, "sortOrder": { "type": "integer" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "thumb", "card", "detail" ] }, "url": { "type": "string" }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 } } } }, "primary": { "type": "boolean" }, "status": { "type": "string" }, "publicationStatus": { "type": "string", "enum": [ "private", "publishing", "published", "revoking" ] } }, "required": [ "id", "url", "width", "height", "altText", "sortOrder" ] }, "BuyerAddress": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "recipientName", "businessName", "line1", "line2", "city", "state", "postalCode", "country", "isDefault", "version" ], "properties": { "id": { "type": "string" }, "kind": { "enum": [ "delivery", "billing" ] }, "recipientName": { "type": "string" }, "businessName": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "const": "IN" }, "isDefault": { "type": "boolean" }, "version": { "type": "integer" }, "stateCode": { "type": [ "string", "null" ], "pattern": "^(?:0[1-9]|[12][0-9]|3[0-8]|97)$", "description": "Explicit two-digit Indian GST state code; required on the delivery address for GST checkout." }, "gstin": { "type": [ "string", "null" ], "pattern": "^[0-9]{2}[A-Z0-9]{13}$", "description": "If provided, its first two digits must match stateCode." } } }, "BuyerAddressInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "recipientName", "line1", "city", "state", "postalCode" ], "properties": { "kind": { "enum": [ "delivery", "billing" ] }, "recipientName": { "type": "string", "minLength": 1, "maxLength": 120 }, "businessName": { "type": "string", "maxLength": 120 }, "line1": { "type": "string", "minLength": 1, "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "pattern": "^[0-9]{6}$" }, "country": { "const": "IN" }, "isDefault": { "type": "boolean" }, "stateCode": { "type": [ "string", "null" ], "pattern": "^(?:0[1-9]|[12][0-9]|3[0-8]|97)$", "description": "Explicit two-digit Indian GST state code; required on the delivery address for GST checkout." }, "gstin": { "type": [ "string", "null" ], "pattern": "^[0-9]{2}[A-Z0-9]{13}$", "description": "If provided, its first two digits must match stateCode." } } }, "StorefrontCreatedAddress": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "recipientName", "businessName", "line1", "line2", "city", "state", "postalCode", "country", "isDefault", "version", "replay" ], "properties": { "id": { "type": "string" }, "kind": { "enum": [ "delivery", "billing" ] }, "recipientName": { "type": "string" }, "businessName": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "const": "IN" }, "isDefault": { "type": "boolean" }, "version": { "type": "integer" }, "stateCode": { "type": [ "string", "null" ], "pattern": "^(?:0[1-9]|[12][0-9]|3[0-8]|97)$", "description": "Explicit two-digit Indian GST state code; required on the delivery address for GST checkout." }, "gstin": { "type": [ "string", "null" ], "pattern": "^[0-9]{2}[A-Z0-9]{13}$", "description": "If provided, its first two digits must match stateCode." }, "replay": { "type": "boolean" } } }, "Cart": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "items", "checkoutAvailable" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "checkoutAvailable": { "const": false }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "sellableId", "packs", "issues" ], "properties": { "sellableId": { "type": "string" }, "packs": { "type": "integer" }, "pricePerPackMinor": { "type": [ "integer", "null" ] }, "issues": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "sku": { "type": "string" }, "unit": { "enum": [ "pc", "set" ] }, "attributeValues": { "type": "array", "items": { "$ref": "#/components/schemas/VariationAttributeValue" } }, "packSize": { "type": "integer", "minimum": 1 } } } }, "merchandiseEstimate": { "type": [ "object", "null" ], "description": "Current permitted merchandise prices and product GST/cess only. Excludes delivery and final rounding; not a placeable quote. Null for missing tax classification or hidden/unavailable prices.", "additionalProperties": false, "required": [ "merchandiseSubtotalMinor", "taxMinor", "taxAddedMinor", "cessMinor", "grandTotalMinor", "taxMode" ], "properties": { "merchandiseSubtotalMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "taxAddedMinor": { "type": "integer", "minimum": 0 }, "cessMinor": { "type": "integer", "minimum": 0 }, "grandTotalMinor": { "type": "integer", "minimum": 0 }, "taxMode": { "enum": [ "none", "gst" ] } } } } }, "StorefrontWhatsAppPreference": { "type": "object", "properties": { "utilityEnabled": { "type": "boolean" }, "marketingEnabled": { "type": "boolean" }, "version": { "type": "integer", "nullable": true } }, "required": [ "utilityEnabled", "marketingEnabled", "version" ] }, "WhatsAppPreferenceInput": { "type": "object", "required": [ "expectedVersion", "utilityEnabled", "marketingEnabled" ], "additionalProperties": false, "properties": { "expectedVersion": { "type": [ "integer", "null" ], "minimum": 0 }, "utilityEnabled": { "type": "boolean" }, "marketingEnabled": { "type": "boolean" } } }, "SignedDownload": { "type": "object", "required": [ "url", "expiresIn" ], "properties": { "url": { "type": "string", "format": "uri" }, "expiresIn": { "type": "integer" } } }, "OrderPage": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "total": { "type": "integer", "minimum": 0, "description": "Seller list only: matching total, independent of cursor/limit." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerOrder" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "BuyerOrder": { "type": "object", "allOf": [ { "properties": { "inventoryMode": { "enum": [ "tracked", "untracked" ], "description": "Immutable placement snapshot. Old orders remain tracked; untracked orders create no reservations or stock movements." }, "deliveryMode": { "enum": [ "configured", "deferred" ], "description": "Immutable delivery behavior snapshot; legacy orders use configured. Deferred pay-later orders retain zero shipping charges without fabricating a delivery-policy version." } } } ], "required": [ "id", "status", "currency", "address", "lines", "merchandiseSubtotalMinor", "shippingMinor", "taxMinor", "grandTotalMinor", "taxableValueMinor", "taxAddedMinor", "roundOffMinor", "taxMode", "roundingMode", "billingAddress" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "payment_pending", "expired", "placed", "payment_exception" ] }, "currency": { "type": "string", "enum": [ "INR" ] }, "address": { "type": "object" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sellableId": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "unit": { "enum": [ "pc", "set" ] }, "attributeValues": { "type": "array", "items": { "$ref": "#/components/schemas/VariationAttributeValue" } }, "packs": { "type": "integer", "minimum": 1 }, "packSize": { "type": "integer", "minimum": 1 }, "lineTotalMinor": { "type": "integer", "minimum": 0 } }, "required": [ "sellableId", "name", "packs", "packSize" ] } }, "merchandiseSubtotalMinor": { "type": "integer" }, "shippingMinor": { "type": "integer" }, "taxMinor": { "type": "integer" }, "grandTotalMinor": { "type": "integer" }, "taxableValueMinor": { "type": "integer", "description": "INR paise" }, "taxAddedMinor": { "type": "integer", "description": "INR paise" }, "roundOffMinor": { "type": "integer", "description": "INR paise" }, "taxMode": { "type": "string" }, "roundingMode": { "type": "string" }, "supplierGstin": { "type": [ "string", "null" ] }, "supplierStateCode": { "type": [ "string", "null" ] }, "placeOfSupplyStateCode": { "type": [ "string", "null" ] }, "billingAddress": { "type": "object", "description": "Immutable billing address snapshot." }, "commercialState": { "type": "string", "enum": [ "awaiting_acceptance", "accepted", "cancelled" ] }, "fulfillmentState": { "type": "string", "enum": [ "unfulfilled", "dispatched", "delivered" ] }, "version": { "type": "integer" }, "invoice": { "type": [ "object", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "accountingMode": { "type": "string", "enum": [ "zoho_books", "external_invoice" ] } } }, "Challenge": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "expiresIn": { "type": "integer", "const": 300 }, "resendAfter": { "type": "integer", "const": 60 } }, "required": [ "challengeId", "expiresIn", "resendAfter" ] }, "BuyerOtpRequest": { "type": "object", "additionalProperties": false, "required": [ "phone" ], "properties": { "phone": { "type": "string", "pattern": "^\\+91[6-9]\\d{9}$" }, "emailCopy": { "type": "boolean", "default": false, "description": "Additional copy to matching store-bound verified buyer address. Phone remains primary; response does not expose eligibility/outcome." } } }, "BuyerAddressUpdateInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "recipientName", "line1", "city", "state", "postalCode", "expectedVersion" ], "properties": { "kind": { "enum": [ "delivery", "billing" ] }, "recipientName": { "type": "string", "minLength": 1, "maxLength": 120 }, "businessName": { "type": "string", "maxLength": 120 }, "line1": { "type": "string", "minLength": 1, "maxLength": 200 }, "line2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "pattern": "^[0-9]{6}$" }, "country": { "const": "IN" }, "isDefault": { "type": "boolean" }, "expectedVersion": { "type": "integer", "minimum": 0 }, "stateCode": { "type": [ "string", "null" ], "pattern": "^(?:0[1-9]|[12][0-9]|3[0-8]|97)$", "description": "Explicit two-digit Indian GST state code; required on the delivery address for GST checkout." }, "gstin": { "type": [ "string", "null" ], "pattern": "^[0-9]{2}[A-Z0-9]{13}$", "description": "If provided, its first two digits must match stateCode." } } }, "CheckoutAttemptInput": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "backorderAcknowledged" ], "properties": { "quoteId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "backorderAcknowledged": { "type": "boolean" } } }, "CheckoutAttempt": { "type": "object", "required": [ "id", "status", "expiresAt", "quoteId", "order", "payment" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "payment_pending", "expired", "placed", "payment_exception" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "quoteId": { "type": "string" }, "order": { "$ref": "#/components/schemas/BuyerOrder" }, "payment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "initiating", "ready", "unknown" ] }, "providerOrderId": { "type": [ "string", "null" ] } } } } }, "PaymentInitiation": { "type": "object", "required": [ "mode", "provider", "keyId", "providerOrderId", "amountMinor", "currency" ], "properties": { "mode": { "type": "string", "enum": [ "test" ] }, "provider": { "type": "string", "enum": [ "razorpay" ] }, "keyId": { "type": "string" }, "providerOrderId": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "enum": [ "INR" ] } } }, "LinkedOrder": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "object" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sellableId": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "unit": { "enum": [ "pc", "set" ] }, "attributeValues": { "type": "array", "items": { "$ref": "#/components/schemas/VariationAttributeValue" } }, "packs": { "type": "integer", "minimum": 1 }, "packSize": { "type": "integer", "minimum": 1 }, "lineTotalMinor": { "type": "integer", "minimum": 0 } }, "required": [ "sellableId", "name", "packs", "packSize" ] } }, "commercialState": { "type": "string", "enum": [ "awaiting_acceptance", "accepted", "cancelled" ] }, "fulfillmentState": { "type": "string", "enum": [ "unfulfilled", "dispatched", "delivered" ] }, "grandTotalMinor": { "type": "integer" }, "invoice": { "type": [ "object", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "orderNumber": { "type": "string", "description": "Immutable six uppercase alphanumeric characters for newly created orders; historical ORD references are unchanged." }, "createdAt": { "type": "string", "format": "date-time" }, "paymentStatus": { "type": "string" }, "viewer": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "enum": [ "buyer", "merchant" ] } }, "required": [ "id", "kind" ] } }, "required": [ "id", "lines", "grandTotalMinor", "commercialState", "fulfillmentState", "viewer" ] }, "Phone": { "type": "object", "additionalProperties": false, "properties": { "phone": { "type": "string", "pattern": "^\\+91[6-9]\\d{9}$" } }, "required": [ "phone" ] }, "ProductPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProduct" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] }, "PublicProduct": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "sellableId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "sku": { "type": "string" }, "packSize": { "type": "integer", "minimum": 1 }, "unit": { "enum": [ "pc", "set" ] }, "minimumPacks": { "type": "integer", "minimum": 1 }, "incrementPacks": { "type": "integer", "minimum": 1 }, "pricePerPackMinor": { "type": [ "integer", "null" ], "minimum": 0 }, "currency": { "const": "INR" }, "priceOnRequest": { "type": "boolean" }, "orderable": { "const": false }, "type": { "enum": [ "simple", "variable" ] }, "productId": { "type": "string" }, "pricesVisible": { "type": "boolean", "description": "false when the current viewer must sign in or obtain store-specific approval to view prices." }, "quantityBreaks": { "type": "array", "items": { "type": "object", "properties": { "minimumPacks": { "type": "integer" }, "pricePerPackMinor": { "type": "integer" } } }, "description": "Empty whenever prices are hidden." }, "displayCode": { "type": [ "string", "null" ], "description": "Root product display code for new records; independent of selected sellable SKU." } }, "required": [ "id", "sellableId", "name", "slug", "description", "imageUrl", "sku", "packSize", "unit", "minimumPacks", "incrementPacks", "pricePerPackMinor", "currency", "priceOnRequest", "orderable", "type", "productId" ] }, "Session": { "type": "object", "additionalProperties": false, "properties": { "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "expiresAt" ] }, "Proof": { "type": "object", "additionalProperties": false, "properties": { "challengeId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "challengeId", "code" ] }, "StorefrontBootstrap": { "type": "object", "additionalProperties": false, "required": [ "store", "configuration", "capabilities", "readiness", "products" ], "properties": { "store": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string" }, "state": { "enum": [ "live", "paused" ] }, "pauseMessage": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "buyerAccessMode": { "type": "string", "enum": [ "public", "approval_gated" ] } }, "required": [ "slug", "state", "pauseMessage", "url" ] }, "configuration": { "type": "object" }, "capabilities": { "type": "object", "properties": { "checkout": { "type": "boolean", "description": "Effective order placement availability, not merely the enabled intent." }, "payLater": { "type": "boolean" }, "onlinePayments": { "type": "boolean" }, "paymentMethods": { "type": "array", "items": { "enum": [ "pay_later", "razorpay" ] } }, "catalogVisible": { "type": "boolean", "description": "Effective visibility for the current same-store buyer session; guest/seller/other-store sessions cannot unlock buyer restrictions." }, "pricesVisible": { "type": "boolean", "description": "Effective visibility for the current same-store buyer session; guest/seller/other-store sessions cannot unlock buyer restrictions." }, "catalogVisibility": { "type": "string", "enum": [ "public", "logged_in", "approved" ] }, "pricesVisibility": { "type": "string", "enum": [ "public", "logged_in", "approved" ] } } }, "readiness": { "type": "object", "properties": { "checkoutReady": { "type": "boolean" }, "checkoutMode": { "enum": [ "pay_later", "test", "live" ] } } }, "products": { "$ref": "#/components/schemas/ProductPage" }, "aboutProducts": { "type": "array", "maxItems": 6, "description": "Selected active products publicly listed in this store, in seller-selected order. Hidden/archived products omitted; independent of catalog pagination.", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] } } } } } }, "MerchantAccountProfile": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "merchant" ] }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "description": "Optional unverified contact email; never a sign-in credential." }, "emailVerified": { "type": "boolean", "enum": [ false ] }, "photo": { "type": "string", "nullable": true }, "profileVersion": { "type": "integer", "minimum": 0 } } }, "BuyerEmailEnrollmentRequest": { "type": "object", "additionalProperties": false, "required": [ "email", "expectedVersion" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "expectedVersion": { "type": "integer", "minimum": 0 }, "notificationsEnabled": { "type": "boolean", "default": false } } }, "BuyerEmailPreferenceRequest": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "notificationsEnabled" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0 }, "notificationsEnabled": { "type": "boolean" } } }, "StorefrontRenderData": { "type": "object", "required": [ "bootstrap", "catalog", "filters", "generatedAt", "view" ], "properties": { "bootstrap": { "$ref": "#/components/schemas/StorefrontBootstrap" }, "catalog": { "oneOf": [ { "$ref": "#/components/schemas/PublicCatalogPage" }, { "type": "null" } ] }, "filters": { "oneOf": [ { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "required": [ "categoryId", "count" ], "properties": { "categoryId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } }, "attributes": { "type": "array", "items": { "type": "object" } } } }, { "type": "null" } ] }, "generatedAt": { "type": "integer", "description": "Creation time in milliseconds since Unix epoch; browser reuse must not exceed 30 seconds." }, "view": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy" ] } } }, "StorefrontSessionContext": { "type": "object", "required": [ "bootstrap", "catalog", "filters", "generatedAt", "view", "session" ], "properties": { "bootstrap": { "$ref": "#/components/schemas/StorefrontBootstrap" }, "catalog": { "oneOf": [ { "$ref": "#/components/schemas/PublicCatalogPage" }, { "type": "null" } ] }, "filters": { "oneOf": [ { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "required": [ "categoryId", "count" ], "properties": { "categoryId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } }, "attributes": { "type": "array", "items": { "type": "object" } } } }, { "type": "null" } ] }, "generatedAt": { "type": "integer", "description": "Creation time in milliseconds since Unix epoch; browser reuse must not exceed 30 seconds." }, "view": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy", "shell" ] }, "session": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "guest" } } }, { "type": "object", "required": [ "kind", "profile" ], "properties": { "kind": { "const": "buyer" }, "profile": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "businessName": { "type": "string" }, "businessProfileVersion": { "type": [ "integer", "null" ] } } } } }, { "type": "object", "required": [ "kind", "name", "accountKind" ], "properties": { "kind": { "const": "incompatible" }, "name": { "type": "string" }, "accountKind": { "type": "string", "enum": [ "buyer", "merchant" ] } } } ] } } }, "StorefrontCartContext": { "type": "object", "required": [ "bootstrap", "catalog", "filters", "generatedAt", "view", "session", "cart", "cartError" ], "properties": { "bootstrap": { "$ref": "#/components/schemas/StorefrontBootstrap" }, "catalog": { "oneOf": [ { "$ref": "#/components/schemas/PublicCatalogPage" }, { "type": "null" } ] }, "filters": { "oneOf": [ { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "required": [ "categoryId", "count" ], "properties": { "categoryId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } }, "attributes": { "type": "array", "items": { "type": "object" } } } }, { "type": "null" } ] }, "generatedAt": { "type": "integer", "description": "Creation time in milliseconds since Unix epoch; browser reuse must not exceed 30 seconds." }, "view": { "type": "string", "enum": [ "catalog", "about", "terms", "privacy", "shell" ] }, "session": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "guest" } } }, { "type": "object", "required": [ "kind", "profile" ], "properties": { "kind": { "const": "buyer" }, "profile": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "businessName": { "type": "string" }, "businessProfileVersion": { "type": [ "integer", "null" ] } } } } }, { "type": "object", "required": [ "kind", "name", "accountKind" ], "properties": { "kind": { "const": "incompatible" }, "name": { "type": "string" }, "accountKind": { "type": "string", "enum": [ "buyer", "merchant" ] } } } ] }, "cart": { "oneOf": [ { "$ref": "#/components/schemas/Cart" }, { "type": "null" } ] }, "cartDeferred": { "type": "boolean" }, "cartError": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "catalogError": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "filtersError": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "securitySchemes": { "session": { "type": "apiKey", "in": "cookie", "name": "bulqc_session" } } } }