{ "openapi": "3.1.0", "info": { "title": "Orchard Storefront API (/api/v1)", "version": "1.0.0", "summary": "The live, callable external API for storefronts built on Orchard.", "description": "This spec is **generated directly from the deployed route handlers**\nunder `apps/admin/app/api/v1/`. Every path here is real code an\nexternal storefront can call today — it is not an aspirational design.\n\nFor the broader (partly aspirational) admin + design surface, see\n`docs/external-tenant/openapi.yaml`. This file is the authoritative\ncontract for what `/api/v1/*` actually exposes.\n\nAuth model: PUBLIC routes identify the tenant via the `x-tenant-slug`\nheader. Bearer routes authenticate a per-tenant API key and derive the\ntenant from the key. Many read routes are dual-mode (anonymous OR\nBearer-elevated). See the `bearerAuth` scheme for the key/scope model.\n\nRegenerate with: `node docs/external-tenant/openapi-gen/generate.mjs` (45 routes as of 2026-06-08).", "contact": { "email": "amir@dallal.me" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.theorchard.dev/api/v1", "description": "Live storefront API" }, { "url": "https://api-test.theorchard.dev/api/v1", "description": "Test-mode (separate Supabase project)" } ], "security": [], "tags": [ { "name": "products", "description": "Storefront product catalog — list, detail, images, reviews." }, { "name": "cart", "description": "Stateless storefront cart — items, promos, gift cards, save/restore." }, { "name": "checkout", "description": "Stripe Checkout Session creation + order status polling." }, { "name": "orders", "description": "Order lookup for storefront confirmation + account pages." }, { "name": "content", "description": "Published content (articles, recipes, announcements)." }, { "name": "search", "description": "Product + content search (semantic with FTS fallback)." }, { "name": "inventory", "description": "Public stock-status lookup for storefront availability." }, { "name": "leads", "description": "Email capture, quiz, waitlist, wholesale lead submission." }, { "name": "returns", "description": "Customer-initiated RMA submission." }, { "name": "wholesale", "description": "B2B / wholesale inquiry submission." }, { "name": "subscriptions", "description": "Subscription lifecycle (gift checkout, reactivate, manage)." }, { "name": "customer", "description": "Customer auth — magic-link request/consume, session, sign-out." }, { "name": "customer-portal", "description": "Customer self-service portal (orders, subs, cancel, returns)." }, { "name": "billing-portal", "description": "Stripe Billing Portal session creation." }, { "name": "storefront", "description": "Per-tenant storefront configuration snapshot." }, { "name": "partners", "description": "Affiliate / referral partner tracking." }, { "name": "analytics", "description": "Storefront analytics event ingestion." }, { "name": "shipping", "description": "Live shipping-rate quotes at checkout." }, { "name": "integrations", "description": "Third-party integration callbacks (Help Scout sidebar, etc.)." } ], "paths": { "/analytics/events": { "post": { "operationId": "postAnalyticsEvents", "tags": [ "analytics" ], "summary": "public funnel-event capture endpoint", "description": "Accepts a batch of funnel events from the storefront / fork frontend. Per STOREFRONT-API-REFERENCE.md §16 the body shape is:", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "HTTP 413." }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/analytics/events/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/billing-portal": { "post": { "operationId": "postBillingportal", "tags": [ "billing-portal" ], "summary": "create a Stripe Billing Portal session", "description": "Allows a customer to manage their subscription (update payment method, cancel, view invoices) via Stripe's hosted Billing Portal. Resolves tenant from x-tenant-slug header, looks up the customer by email, and creates a portal session with the customer's stripe_customer_id.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_email": { "type": "string" }, "return_url": { "type": "string" } }, "required": [ "customer_email", "return_url" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/billing-portal/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/cart": { "post": { "operationId": "postCart", "tags": [ "cart" ], "summary": "v1-promotion of the unversioned storefront", "description": "POST /api/cart (cart create) with Bearer dual-mode (Z-601 / WP-v2-44 Phase 1 audit §3.2 / Wave 2a-1 / mirrors Z-584 pattern).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "session_id": { "type": "string" }, "customer_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } } }, "/cart/{id}": { "get": { "operationId": "getCartId", "tags": [ "cart" ], "summary": "v1 promotion of the unversioned storefront", "description": "cart-by-id read (Z-602 / WP-v2-44 Phase 1 §3.2 / Wave 2a-1).", "security": [ {}, { "bearerAuth": [ "cart:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/[id]/route.ts", "authMode": "dual", "scopes": [ "cart:read" ], "rateLimited": true, "generated": true } } }, "/cart/{id}/items": { "post": { "operationId": "postCartIdItems", "tags": [ "cart" ], "summary": "v1 mirror of the unversioned", "description": "storefront `POST /api/cart/[id]/items` (add a line to a cart) with opt-in Bearer elevation (Z-603 / WP-v2-44 Wave 2a-1 / mirrors Z-584 inventory/status + Z-569 cart save patterns).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "string" }, "unitPriceCents": { "type": "string" }, "purchaseType": { "type": "string" }, "subscriptionInterval": { "type": "string" } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/[id]/items/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } } }, "/cart/{id}/items/{itemId}": { "delete": { "operationId": "deleteCartIdItemsItemId", "tags": [ "cart" ], "summary": "PATCH & DELETE /api/v1/cart/[id]/items/[itemId] — v1-promotion of the", "description": "unversioned storefront cart-line-modify endpoints (Z-604 / WP-v2-44 Phase 1 §3.2 / Wave 2a-1 4 of 15).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "204": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/[id]/items/[itemId]/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } }, "patch": { "operationId": "patchCartIdItemsItemId", "tags": [ "cart" ], "summary": "PATCH & DELETE /api/v1/cart/[id]/items/[itemId] — v1-promotion of the", "description": "unversioned storefront cart-line-modify endpoints (Z-604 / WP-v2-44 Phase 1 §3.2 / Wave 2a-1 4 of 15).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "204": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/[id]/items/[itemId]/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } } }, "/cart/apply-gift-card": { "post": { "operationId": "postCartApplygiftcard", "tags": [ "cart" ], "summary": "stateless gift-card validate-only", "description": "preview with opt-in Bearer elevation (Z-606 / WP-v2-44 Wave 2a-1).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "orderTotal": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/apply-gift-card/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } } }, "/cart/apply-promo": { "post": { "operationId": "postCartApplypromo", "tags": [ "cart" ], "summary": "stateless promo-code preview with", "description": "opt-in Bearer elevation (Z-605 / WP-v2-44 Phase 3 — Wave 2a-1 v1 promotion of the unversioned storefront route).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "subtotalCents": { "type": "string" }, "customerEmail": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/apply-promo/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": true, "generated": true } } }, "/cart/restore": { "get": { "operationId": "getCartRestore", "tags": [ "cart" ], "summary": "cart restore endpoint", "description": "with opt-in Bearer elevation (Z-569 / mirrors Z-538 orders/lookup pattern).", "security": [ {}, { "bearerAuth": [ "cart:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "HTTP 410." } }, "x-orchard": { "sourceFile": "api/v1/cart/restore/route.ts", "authMode": "dual", "scopes": [ "cart:read" ], "rateLimited": false, "generated": true } } }, "/cart/save": { "post": { "operationId": "postCartSave", "tags": [ "cart" ], "summary": "abandoned-cart save endpoint with opt-in", "description": "Bearer elevation (Z-569 / mirrors Z-538 orders/lookup pattern).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "items": { "type": "string" }, "variant_id": { "type": "string" }, "product_slug": { "type": "string" }, "quantity": { "type": "string" }, "price_cents": { "type": "string" }, "unit_price_cents": { "type": "string" }, "name": { "type": "string" } }, "required": [ "email", "items", "quantity" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/save/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": false, "generated": true } } }, "/cart/unsubscribe": { "get": { "operationId": "getCartUnsubscribe", "tags": [ "cart" ], "summary": "GET & POST /api/v1/cart/unsubscribe — cart unsubscribe endpoint", "description": "with opt-in Bearer elevation (Z-569 / mirrors Z-538 orders/lookup pattern).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/unsubscribe/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": false, "generated": true } }, "post": { "operationId": "postCartUnsubscribe", "tags": [ "cart" ], "summary": "GET & POST /api/v1/cart/unsubscribe — cart unsubscribe endpoint", "description": "with opt-in Bearer elevation (Z-569 / mirrors Z-538 orders/lookup pattern).", "security": [ {}, { "bearerAuth": [ "cart:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/cart/unsubscribe/route.ts", "authMode": "dual", "scopes": [ "cart:write" ], "rateLimited": false, "generated": true } } }, "/checkout/{orderId}/status": { "get": { "operationId": "getCheckoutOrderIdStatus", "tags": [ "checkout" ], "summary": "v1 promotion of the", "description": "unversioned storefront poll endpoint (Z-607 / Wave 2a-1 v1-promotion 7 of 15). Bearer dual-mode mirroring the Z-584 products/[slug] path-param GET precedent + Z-538 orders/lookup dual-auth shape.", "security": [ {}, { "bearerAuth": [ "checkout:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/checkout/[orderId]/status/route.ts", "authMode": "dual", "scopes": [ "checkout:read" ], "rateLimited": true, "generated": true } } }, "/checkout/sessions": { "post": { "operationId": "postCheckoutSessions", "tags": [ "checkout" ], "summary": "Create a Stripe Checkout Session", "description": "Creates a Stripe Checkout Session for the current cart and returns the hosted-checkout URL to redirect the shopper to. Requires a Bearer key with `checkout:write`.", "security": [ { "bearerAuth": [ "checkout:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "HTTP 409." }, "502": { "description": "HTTP 502." }, "503": { "description": "HTTP 503." } }, "x-orchard": { "sourceFile": "api/v1/checkout/sessions/route.ts", "authMode": "bearer", "scopes": [ "checkout:write" ], "rateLimited": false, "generated": true } } }, "/content/{type}": { "get": { "operationId": "getContentType", "tags": [ "content" ], "summary": "List published content of a type", "description": "Lists published content entries of the given `type` (e.g. `article`, `recipe`). Cursor-paged.", "security": [ {}, { "bearerAuth": [ "content:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CursorParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of content entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entries", "cursor" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ContentEntry" } }, "cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/content/[type]/route.ts", "authMode": "dual", "scopes": [ "content:read" ], "rateLimited": true, "generated": true } } }, "/content/{type}/{slug}": { "get": { "operationId": "getContentTypeSlug", "tags": [ "content" ], "summary": "Get a content entry by type + slug", "description": "with opt-in Bearer elevation (Z-584 / WP-v2-44 Phase 3 / mirrors Z-569 cart pattern) + per-key rate limiting on the Bearer path (Z-590).", "security": [ {}, { "bearerAuth": [ "content:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The content entry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entry" ], "properties": { "entry": { "$ref": "#/components/schemas/ContentEntry" } } } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/content/[type]/[slug]/route.ts", "authMode": "dual", "scopes": [ "content:read" ], "rateLimited": true, "generated": true } } }, "/content/announcements/active": { "get": { "operationId": "getContentAnnouncementsActive", "tags": [ "content" ], "summary": "currently-active announcements", "description": "Returns published announcement entries whose start/end window (when set) includes \"now\". Either bound may be null, which is treated as \"unbounded\" on that side.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/content/announcements/active/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer-portal": { "post": { "operationId": "postCustomerportal", "tags": [ "customer-portal" ], "summary": "request a customer magic link", "description": "Body: { customer_email, return_url? } Tenant: resolved from the `x-tenant-slug` header.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_email": { "type": "string" }, "return_url": { "type": "string" } }, "required": [ "customer_email" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer-portal/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer-portal/cancel": { "post": { "operationId": "postCustomerportalCancel", "tags": [ "customer-portal" ], "summary": "customer-initiated cancel", "description": "Body: { session_id, subscription_id, churn_reason?, mode } Tenant: resolved from x-tenant-slug.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "subscription_id": { "type": "string" }, "churn_reason": { "type": "string" }, "mode": { "type": "string" } }, "required": [ "session_id", "subscription_id", "mode" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer-portal/cancel/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer-portal/returns": { "post": { "operationId": "postCustomerportalReturns", "tags": [ "customer-portal" ], "summary": "list a customer's returns", "description": "Z-262 (WP-v2-36 T3) — closes the N-8 row in the 2026-05-20 HN frontend API-gap audit (`docs/audit/wp-v2-36-api-gap-2026-05-20.md`). Powers the storefront's /account/returns page in the HN fork (and any other tenant using the standard customer portal).", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "cursor": { "type": "string" }, "limit": { "type": "string" } }, "required": [ "session_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer-portal/returns/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer-portal/subscriptions": { "post": { "operationId": "postCustomerportalSubscriptions", "tags": [ "customer-portal" ], "summary": "list a customer's subs", "description": "Body: { session_id } Tenant: resolved from x-tenant-slug.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" } }, "required": [ "session_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer-portal/subscriptions/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer-portal/verify": { "get": { "operationId": "getCustomerportalVerify", "tags": [ "customer-portal" ], "summary": "consume a portal token", "description": "Atomic single-use: consumeCustomerPortalToken flips consumed_at and returns the customer_id, or null on missing/expired/already-used. On success we: 1. Look up the customer (needs stripe_customer_id for the portal session). 2. Resolve the tenant's Stripe client via getStripeClientForTenant. 3. Create a Stripe Billing Portal session (fallback for customers who prefer Stripe-hosted management). 4. Create a short-lived customer_portal_sessions row so the client can use storefront-hosted cancel UI without burning another token.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "return_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer-portal/verify/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer/magic-link/consume": { "post": { "operationId": "postCustomerMagiclinkConsume", "tags": [ "customer" ], "summary": "consume a token and mint a session.", "description": "Body: { token } Tenant: resolved from the x-tenant-slug header.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer/magic-link/consume/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer/magic-link/request": { "post": { "operationId": "postCustomerMagiclinkRequest", "tags": [ "customer" ], "summary": "issue a magic-link token.", "description": "Body: { email, verify_url? } email — recipient address verify_url — absolute URL callers want the token appended to as ?token=. External API consumers (Kevin's wine store model) pass their own frontend origin; omit to fall back to the storefront's /api/auth/customer/verify on the admin origin.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "verify_url": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer/magic-link/request/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer/me": { "get": { "operationId": "getCustomerMe", "tags": [ "customer" ], "summary": "v1 promotion of the unversioned", "description": "/api/auth/customer/me route. Returns the current customer's profile.", "security": [ {}, { "bearerAuth": [ "customer:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer/me/route.ts", "authMode": "dual", "scopes": [ "customer:read" ], "rateLimited": true, "generated": true } } }, "/customer/refresh": { "post": { "operationId": "postCustomerRefresh", "tags": [ "customer" ], "summary": "rotate a customer refresh token chain.", "description": "Body: { refresh_token } Tenant: resolved from the x-tenant-slug header.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer/refresh/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/customer/signout": { "post": { "operationId": "postCustomerSignout", "tags": [ "customer" ], "summary": "v1-promoted customer signout with", "description": "Bearer dual-mode (Z-610 / WP-v2-44 Wave 2a-1 / mirrors Z-569 cart pattern). v1 promotion of the unversioned apps/storefront/app/api/auth/customer/signout/route.ts.", "security": [ {}, { "bearerAuth": [ "customer:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "204": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/customer/signout/route.ts", "authMode": "dual", "scopes": [ "customer:write" ], "rateLimited": true, "generated": true } } }, "/integrations/helpscout/customer-sidebar": { "post": { "operationId": "postIntegrationsHelpscoutCustomersidebar", "tags": [ "integrations" ], "summary": "Internal — Help Scout sidebar callback", "description": "Server-to-server callback invoked by the Help Scout app (HMAC-signed by Help Scout, not Bearer/x-tenant-slug). Renders the customer sidebar. Not a storefront endpoint.", "security": [], "parameters": [ { "name": "tenant_slug", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/integrations/helpscout/customer-sidebar/route.ts", "authMode": "open", "rateLimited": false, "generated": true }, "x-internal": true } }, "/inventory/status": { "post": { "operationId": "postInventoryStatus", "tags": [ "inventory" ], "summary": "Check stock status for products", "description": "Batch stock-status lookup. Send a list of product ids; returns a coarse availability status per product (never raw stock counts, to avoid leaking inventory levels).", "security": [ {}, { "bearerAuth": [ "inventory:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 } } } } } }, "responses": { "200": { "description": "Per-product stock status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryStatusItem" } } } } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/inventory/status/route.ts", "authMode": "dual", "scopes": [ "inventory:read" ], "rateLimited": false, "generated": true } } }, "/leads": { "post": { "operationId": "postLeads", "tags": [ "leads" ], "summary": "Submit a lead (email capture)", "description": "Captures an email lead (newsletter, quiz, waitlist, wholesale, etc.). Always returns `{ ok: true }` and never reveals whether the email was already captured (privacy by design).", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "source_detail": { "type": "string" }, "metadata": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/leads/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/orders/lookup": { "post": { "operationId": "postOrdersLookup", "tags": [ "orders" ], "summary": "order-lookup endpoint with opt-in", "description": "Bearer elevation (Z-538 / WP-bearer-auth §6).", "security": [ {}, { "bearerAuth": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "order_number": { "type": "string" } }, "required": [ "email", "order_number" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/orders/lookup/route.ts", "authMode": "dual", "scopes": [ "orders:read" ], "rateLimited": false, "generated": true } } }, "/partners": { "get": { "operationId": "getPartners", "tags": [ "partners" ], "summary": "public partner directory", "description": "Returns the active partner listings (public partner directory) for the tenant resolved from the x-tenant-slug header. Backs the /friends page in tenant-fork storefronts (WP-v2-36 T3, Z-263) and any future external-API-consumer that wants to render a \"Friends / Partners\" surface.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/partners/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/partners/{id}/track": { "get": { "operationId": "getPartnersIdTrack", "tags": [ "partners" ], "summary": "302 click-tracker for partner-listings", "description": "Resolves the partner-listing row, fires fire-and-forget click tracking into public.partner_listing_clicks via the SDK (audit + counter rollups handled inside recordPartnerListingClick), and 302-redirects to the listing's website_url. 302 — NOT 301 — because partner listings are revocable; an aggressive client cache of a 301 would outlive a tenant retiring a partner.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "302": { "description": "HTTP 302." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/partners/[id]/track/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/products": { "get": { "operationId": "getProducts", "tags": [ "products" ], "summary": "List storefront products", "description": "Returns active products for the tenant. Cursor-paged via the opaque `cursor` token. Pass `?ids=a,b,c` (max 100 UUIDs) for a batched fetch by id, or `?search=` for keyword filtering. Anonymous calls send `x-tenant-slug`; Bearer calls with `products:read` derive the tenant from the key.", "security": [ {}, { "bearerAuth": [ "products:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "$ref": "#/components/parameters/CursorParam" }, { "$ref": "#/components/parameters/IdsParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/SearchParam" } ], "responses": { "200": { "description": "A page of products.", "content": { "application/json": { "schema": { "type": "object", "required": [ "products", "cursor" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItem" } }, "cursor": { "type": "string", "nullable": true, "description": "Pass as `?cursor=` for the next page; null on the last page." } } } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/products/route.ts", "authMode": "dual", "scopes": [ "products:read" ], "rateLimited": true, "generated": true } } }, "/products/{slug}": { "get": { "operationId": "getProductsSlug", "tags": [ "products" ], "summary": "Get a product by slug", "description": "Returns one active product with all variants and images. A retired slug 301-redirects (see `Location`) to its current slug. Unknown or non-active slugs return 404.", "security": [ {}, { "bearerAuth": [ "products:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "301": { "description": "Permanent redirect (SEO-preserving slug change). See `Location`." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/products/[slug]/route.ts", "authMode": "dual", "scopes": [ "products:read" ], "rateLimited": true, "generated": true } } }, "/products/{slug}/images": { "get": { "operationId": "getProductsSlugImages", "tags": [ "products" ], "summary": "public storefront product gallery", "description": "Returns the ordered image gallery for a single product by slug. Backs the HN per-tenant storefront fork's `lib/product-images-db.ts:43` `getProductImages(productId)` consumer — swaps direct Supabase reads + signed-URL minting for a tenant-scoped public API round-trip that returns plain CDN URLs (D-WP36T1-6 — no signed URLs in v1 storefront API; gallery images are public CDN assets, not access-controlled).", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/products/[slug]/images/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/products/{slug}/reviews": { "get": { "operationId": "getProductsSlugReviews", "tags": [ "products" ], "summary": "public storefront list of", "description": "approved reviews for a product, with opt-in Bearer elevation (Z-614 / WP-v2-44 Wave 2a-1 / mirrors Z-584 products-detail pattern) + per-key rate limiting on the Bearer path (Z-590).", "security": [ {}, { "bearerAuth": [ "reviews:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "301": { "description": "Permanent redirect (SEO-preserving slug change). See `Location`." }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/products/[slug]/reviews/route.ts", "authMode": "dual", "scopes": [ "reviews:read" ], "rateLimited": true, "generated": true } } }, "/returns": { "post": { "operationId": "postReturns", "tags": [ "returns" ], "summary": "public customer-initiated return request", "description": "Lets a guest customer file a return against a past order using (email, order_number) as their read credential. The lookup reuses getOrderByEmailAndNumber so the anti-enumeration posture matches the order-lookup endpoint: unknown tenant / unknown order / mismatched email all return the same 404 { error: 'not_found' }.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "order_number": { "type": "string" }, "reason": { "type": "string" }, "reason_detail": { "type": "string" }, "items": { "type": "string" } }, "required": [ "email", "order_number", "reason" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/returns/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/search": { "get": { "operationId": "getSearch", "tags": [ "search" ], "summary": "apps/admin/app/api/v1/search/route.ts", "description": "GET /api/v1/search?q=… — public storefront semantic product search (pgvector cosine + ILIKE fallback) with opt-in Bearer elevation (Z-584 / WP-v2-44 Phase 3 / mirrors Z-569 cart pattern) + per-key rate limiting on the Bearer path (Z-590). Calls @orchard/sdk/server.searchActiveProducts with an OpenAI embedder injected by apps/admin/lib/openai-embedder.", "security": [ {}, { "bearerAuth": [ "search:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/search/route.ts", "authMode": "dual", "scopes": [ "search:read" ], "rateLimited": true, "generated": true } } }, "/search/embed": { "post": { "operationId": "postSearchEmbed", "tags": [ "search" ], "summary": "Internal — generate a search embedding", "description": "Internal tooling endpoint used to (re)generate semantic-search embeddings. Not part of the public storefront contract; included here only for completeness.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "HTTP 503." } }, "x-orchard": { "sourceFile": "api/v1/search/embed/route.ts", "authMode": "open", "rateLimited": false, "generated": true }, "x-internal": true } }, "/shipping/rates": { "post": { "operationId": "postShippingRates", "tags": [ "shipping" ], "summary": "live EasyPost rate-shopping (Z-288 / WP-v2-37 T1)", "description": "PUBLISHABLE endpoint: no auth, tenant resolved from the `x-tenant-slug` header (Stripe-style, mirroring v1/returns and v1/partners). Storefront calls this pre-Stripe redirect to render rate options to the customer.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "string" }, "ship_to": { "type": "string" }, "parcel": { "type": "string" }, "adult_signature_required": { "type": "string" } }, "required": [ "items", "ship_to" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "HTTP 502." } }, "x-orchard": { "sourceFile": "api/v1/shipping/rates/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/storefront/config": { "get": { "operationId": "getStorefrontConfig", "tags": [ "storefront" ], "summary": "public storefront initialization", "description": "Lightweight endpoint that returns the tenant's public storefront configuration: display name, enabled modules, default currency. Called once by the storefront app at boot to hydrate shared state.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/storefront/config/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } }, "/subscriptions/{id}": { "patch": { "operationId": "patchSubscriptionsId", "tags": [ "subscriptions" ], "summary": "customer-scoped subscription lifecycle", "description": "with opt-in Bearer elevation (Z-611 / WP-v2-44 Wave 2a-1).", "security": [ {}, { "bearerAuth": [ "subscriptions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "503": { "description": "HTTP 503." } }, "x-orchard": { "sourceFile": "api/v1/subscriptions/[id]/route.ts", "authMode": "dual", "scopes": [ "subscriptions:write" ], "rateLimited": true, "generated": true } } }, "/subscriptions/gift/checkout": { "post": { "operationId": "postSubscriptionsGiftCheckout", "tags": [ "subscriptions" ], "summary": "Bearer-first v1 promotion", "description": "of the unversioned `apps/storefront/app/api/subscriptions/gift/checkout` route (Z-613 / Wave 2a-1 v1-promotion 13 of 15 / WP-v2-44 batch 2).", "security": [ {}, { "bearerAuth": [ "checkout:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body (schema not introspectable; see route source or add an override)." } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "502": { "description": "HTTP 502." }, "503": { "description": "HTTP 503." } }, "x-orchard": { "sourceFile": "api/v1/subscriptions/gift/checkout/route.ts", "authMode": "dual", "scopes": [ "checkout:write" ], "rateLimited": true, "generated": true } } }, "/subscriptions/reactivate": { "post": { "operationId": "postSubscriptionsReactivate", "tags": [ "subscriptions" ], "summary": "Bearer-aware v1 promotion of", "description": "the unversioned customer-JWT route (Z-612 / WP-v2-44 Wave 2a-1 v1- promotion 12 of 15).", "security": [ {}, { "bearerAuth": [ "subscriptions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string" }, "apply_current_price": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing/invalid/revoked/expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — the key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Honor the `Retry-After` header (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "x-orchard": { "sourceFile": "api/v1/subscriptions/reactivate/route.ts", "authMode": "dual", "scopes": [ "subscriptions:write" ], "rateLimited": true, "generated": true } } }, "/wholesale/inquiries": { "post": { "operationId": "postWholesaleInquiries", "tags": [ "wholesale" ], "summary": "public wholesale application endpoint", "description": "Accepts a wholesale inquiry from the storefront. Resolves tenant from the x-tenant-slug header. No audit log — this is customer-facing.", "security": [], "parameters": [ { "$ref": "#/components/parameters/TenantSlugHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_name": { "type": "string" }, "contact_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "tax_id": { "type": "string" }, "business_type": { "type": "string" }, "message": { "type": "string" } }, "required": [ "company_name", "contact_name", "email" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "Response body (add an override for the full schema)." } } } }, "400": { "description": "Bad request — malformed input or missing required header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-orchard": { "sourceFile": "api/v1/wholesale/inquiries/route.ts", "authMode": "public", "rateLimited": false, "generated": true } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "orchard-key", "description": "Per-tenant Bearer keys issued by the admin \"API keys\" UI. Four\nprefixes encode (mode, exposure):\n\n- `sk_live__…` — live secret, server-only.\n- `pk_live__…` — live publishable, browser-safe.\n- `sk_test__…` — test-mode secret.\n- `pk_test__…` — test-mode publishable.\n\nAuthorization is scope-based: each key carries an allow-list of\n`{resource}:{action}` strings. `pk_*` keys are limited to\nbrowser-safe read scopes plus `checkout:write`; `sk_*` keys may\nhold any scope and MUST be treated as secrets." } }, "parameters": { "TenantSlugHeader": { "name": "x-tenant-slug", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Identifies the tenant on PUBLIC (non-Bearer) calls. Ignored on the Bearer path — tenant is derived from the key to defeat leaked-key replay." }, "RequestIdHeader": { "name": "x-request-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Echoed into structured logs for request tracing." }, "CursorParam": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous page response." }, "LimitParam": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "SearchParam": { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, "IdsParam": { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated UUID list for batched fetch (max 100)." } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "description": "Standard error response. `error` is a stable machine code.", "properties": { "error": { "type": "string", "example": "tenant_not_found" }, "message": { "type": "string", "description": "Human-readable detail (optional)." } } }, "RateLimitError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "retry_after": { "type": "integer", "description": "Seconds until the limit resets." } } }, "Ok": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "description": "Privacy-preserving acknowledgement (never leaks resource existence)." }, "Money": { "type": "object", "description": "Monetary amount in minor units (cents) plus ISO-4217 currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "description": "Minor units, e.g. 2599 = $25.99." }, "currency": { "type": "string", "example": "usd" } } }, "Timestamp": { "type": "string", "format": "date-time" }, "ProductVariant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_product_id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "stripe_price_id": { "type": "string", "nullable": true } } }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "alt_text": { "type": "string", "nullable": true }, "sort_order": { "type": "integer" }, "is_primary": { "type": "boolean" } } }, "ProductListItem": { "type": "object", "description": "Compact product shape returned by the list endpoint.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "price": { "$ref": "#/components/schemas/Money" }, "short_description": { "type": "string" }, "available": { "type": "boolean" }, "featured": { "type": "boolean" }, "rating": { "type": "number", "minimum": 0, "maximum": 5, "nullable": true }, "review_count": { "type": "integer" }, "variant_count": { "type": "integer" }, "first_image_url": { "type": "string", "format": "uri", "nullable": true }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "Product": { "type": "object", "description": "Full product detail including variants and images.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "subtitle": { "type": "string", "nullable": true }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "price": { "$ref": "#/components/schemas/Money" }, "subscribe_price": { "$ref": "#/components/schemas/Money", "nullable": true }, "subscribable": { "type": "boolean" }, "size": { "type": "string", "description": "e.g. \"750ml\" for wine; \"60 capsules\" for a supplement." }, "tagline": { "type": "string", "nullable": true }, "short_description": { "type": "string" }, "long_description": { "type": "string", "description": "Rich text (HTML or TipTap JSON blocks)." }, "benefits": { "type": "array", "items": { "type": "string" } }, "badge": { "type": "string", "nullable": true, "description": "e.g. \"Best Seller\", \"New Release\"." }, "available": { "type": "boolean" }, "featured": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "rating": { "type": "number", "minimum": 0, "maximum": 5, "nullable": true }, "review_count": { "type": "integer" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }, "meta_title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Tenant-specific extended fields. Wine example: { \"vintage\": 2023, \"varietal\": \"Pinot Noir\", \"region\": \"Willamette Valley\", \"abv\": \"13.5\" }." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ContentEntry": { "type": "object", "description": "Published content item (article, recipe, announcement).", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "example": "article" }, "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string", "nullable": true }, "body": { "type": "string", "description": "Rich text / serialized blocks." }, "published_at": { "$ref": "#/components/schemas/Timestamp" } } }, "InventoryStatusItem": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "sku": { "type": "string", "nullable": true }, "status_key": { "type": "string", "enum": [ "in_stock", "low_stock", "out_of_stock" ] }, "available": { "type": "boolean" } } } } } }