{ "openapi": "3.0.0", "paths": { "/api/v1/merchant/auth/session": { "get": { "operationId": "AuthController_getSession", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSessionResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Return the current user + all their memberships.", "tags": [ "auth" ] } }, "/api/v1/merchant/auth/profile": { "patch": { "operationId": "AuthController_updateProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantProfileDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProfileResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [], "OrganizationSlug": [] } ], "summary": "Update the current user's own profile (name).", "tags": [ "auth" ] } }, "/api/v1/merchant/auth/memberships": { "get": { "operationId": "AuthController_listMemberships", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMembershipListItemDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [], "OrganizationSlug": [] } ], "summary": "List memberships for the active organization.", "tags": [ "auth" ] }, "post": { "operationId": "AuthController_createMembership", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMembershipDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantMembershipCreateResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [], "OrganizationSlug": [] } ], "summary": "Grant a membership to a user (permission required).", "tags": [ "auth" ] } }, "/api/v1/merchant/auth/permission-presets": { "get": { "operationId": "AuthController_listPermissionPresets", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPermissionPresetDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [], "OrganizationSlug": [] } ], "summary": "List permission presets for the active organization.", "tags": [ "auth" ] } }, "/api/v1/merchant/auth/memberships/{id}": { "patch": { "operationId": "AuthController_updateMembership", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMembershipDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantMembershipUpdateResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [], "OrganizationSlug": [] } ], "summary": "Update a membership role or Staff permission assignments.", "tags": [ "auth" ] } }, "/api/v1/merchant/onboarding": { "get": { "description": "Returns the full canonical step set for the org bound to the request (resolved by `x-organization-slug`). On first call, the service lazy-seeds any missing rows from the canonical step list so the client never has to handle a 404 or a partial list.\n\nResponse shape: `{ steps: OnboardingStep[], summary: { totalSteps, completedSteps, percent } }`. `steps` is ordered to match the canonical key list; `summary.percent` is an integer 0-100.\n\nOpen to any authenticated member of the org (Staff included).", "operationId": "MerchantOnboardingController_listOnboarding", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOnboardingStateDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch the active org's onboarding checklist.", "tags": [ "merchant-onboarding" ] } }, "/api/v1/merchant/onboarding/steps/{stepKey}": { "patch": { "description": "Body `{ \"completed\": true }` stamps `completedAt = now()` and `completedBy = `. Body `{ \"completed\": false }` clears both fields back to `null` (reopen).\n\nThe `:stepKey` path param must be one of the canonical step keys enumerated on the `stepKey` parameter below — unrecognized keys return 404.\n\nIf no prior GET has materialized the row, the service lazy-creates it in the requested state — the merchant never needs to read the list first to make a write succeed.\n\nEmits `onboarding.step_completed` or `onboarding.step_reopened` to the audit log; metadata records only `{ stepKey }`.", "operationId": "MerchantOnboardingController_setStepCompleted", "parameters": [ { "name": "stepKey", "required": true, "in": "path", "description": "Canonical step key (e.g. `business_profile`, `first_product`). The full set is returned by `GET /api/v1/merchant/onboarding`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnboardingStepDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOnboardingStepDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Toggle a single onboarding step's completion state (Owner/Admin only).", "tags": [ "merchant-onboarding" ] } }, "/api/v1/merchant/email-templates": { "get": { "description": "Returns the fixed set of tenant-editable transactional email types, their defaults, current overrides, available merge variables, resolved sample copy, and sender/compliance defaults for the active org. Any authenticated member can read this surface.", "operationId": "MerchantEmailTemplateController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmailTemplatesResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List editable transactional email template slots.", "tags": [ "merchant-email-templates" ] } }, "/api/v1/merchant/email-templates/{type}": { "patch": { "description": "Upserts the active org override for one fixed email type. Only approved copy slots are writable: subject, heading, body text, CTA label, from display name, and reply-to. Unknown merge variables are rejected. System links, unsubscribe links, and compliance footer copy are not client-writable. Emits `email_template.updated` to the audit log with field names only, never copy values.", "operationId": "MerchantEmailTemplateController_update", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "enum": [ "CUSTOMER_AUTH", "ORDER_CONFIRMATION", "ABANDONED_CART_RECOVERY", "BACK_IN_STOCK", "STOCK_NOTIFICATION_CONFIRMATION", "NEWSLETTER_CONFIRMATION", "RETURN_REQUESTED", "RETURN_APPROVED", "RETURN_RECEIVED", "RETURN_COMPLETED", "RETURN_REJECTED", "COMMERCE_QUOTE_SEND", "COMMERCE_INVOICE_SEND", "COMMERCE_CONTRACT_SEND", "COMMERCE_CONTRACT_COUNTERSIGNED", "COMMERCE_CONTRACT_VOIDED", "COMMERCE_QUOTE_EXPIRED", "BOOKING_NOTIFICATION", "COMMERCE_PAYMENT_RECEIVED", "ORDER_SHIPPED", "SUBSCRIPTION_PAYMENT_RECOVERY" ], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailTemplateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update one transactional email template override.", "tags": [ "merchant-email-templates" ] } }, "/api/v1/merchant/email-templates/{type}/preview": { "post": { "description": "Resolves the saved override plus an optional unsaved draft against sample merge variables. This powers live admin preview without persisting partial form state.", "operationId": "MerchantEmailTemplateController_preview", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "enum": [ "CUSTOMER_AUTH", "ORDER_CONFIRMATION", "ABANDONED_CART_RECOVERY", "BACK_IN_STOCK", "STOCK_NOTIFICATION_CONFIRMATION", "NEWSLETTER_CONFIRMATION", "RETURN_REQUESTED", "RETURN_APPROVED", "RETURN_RECEIVED", "RETURN_COMPLETED", "RETURN_REJECTED", "COMMERCE_QUOTE_SEND", "COMMERCE_INVOICE_SEND", "COMMERCE_CONTRACT_SEND", "COMMERCE_CONTRACT_COUNTERSIGNED", "COMMERCE_CONTRACT_VOIDED", "COMMERCE_QUOTE_EXPIRED", "BOOKING_NOTIFICATION", "COMMERCE_PAYMENT_RECEIVED", "ORDER_SHIPPED", "SUBSCRIPTION_PAYMENT_RECOVERY" ], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewEmailTemplateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplatePreviewDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Render a sample preview for one email template.", "tags": [ "merchant-email-templates" ] } }, "/api/v1/merchant/email-templates/{type}/send-test": { "post": { "description": "Sends the resolved sample template to the server-resolved authenticated merchant user by default. The temporary CUSTOM_ADDRESS mode accepts a raw candidate only for the #3358 persistent-staging bridge; centralized server email policy still evaluates it before provider I/O. #1744 replaces that mode with an opaque verified destination identifier. The optional draft body lets the admin test unsaved changes.", "operationId": "MerchantEmailTemplateController_sendTest", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "enum": [ "CUSTOMER_AUTH", "ORDER_CONFIRMATION", "ABANDONED_CART_RECOVERY", "BACK_IN_STOCK", "STOCK_NOTIFICATION_CONFIRMATION", "NEWSLETTER_CONFIRMATION", "RETURN_REQUESTED", "RETURN_APPROVED", "RETURN_RECEIVED", "RETURN_COMPLETED", "RETURN_REJECTED", "COMMERCE_QUOTE_SEND", "COMMERCE_INVOICE_SEND", "COMMERCE_CONTRACT_SEND", "COMMERCE_CONTRACT_COUNTERSIGNED", "COMMERCE_CONTRACT_VOIDED", "COMMERCE_QUOTE_EXPIRED", "BOOKING_NOTIFICATION", "COMMERCE_PAYMENT_RECEIVED", "ORDER_SHIPPED", "SUBSCRIPTION_PAYMENT_RECOVERY" ], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestEmailTemplateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestEmailTemplateResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Send a sample email to an explicitly selected test recipient.", "tags": [ "merchant-email-templates" ] } }, "/api/v1/public/signup": { "post": { "description": "Always returns the same neutral acknowledgement for accepted payloads. The body does not expose the pending-signup row id, lifecycle status, creation timestamp, or whether the email already has a pending/approved signup.", "operationId": "PublicSignupController_createPendingSignup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePendingSignupDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPendingSignupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-IP signup rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "summary": "Capture a public self-serve signup request for review.", "tags": [ "public-signup" ] } }, "/api/v1/public/items/{itemId}/stock-notifications": { "post": { "description": "Public-facing capture for the \"email me when available\" PDP form. Idempotent: re-submitting the same (item, variant, email) returns the existing signup row instead of erroring. Fresh signups and still-subscribed re-arms send a confirmation email; an existing opt-out remains inactive.", "operationId": "PublicStockNotificationController_subscribe", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStockNotificationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockNotificationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Subscribe to a back-in-stock notification for an item.", "tags": [ "public-stock-notifications" ] } }, "/api/v1/merchant/stock-notifications": { "get": { "description": "Newest first. Filter by lifecycle status: `pending` (default — still un-notified and still subscribed, the actionable list), `sent` (already notified, historical), `unsubscribed` (opted out, historical), `all` (every row). Cursor-paginated via `limit` (default 50, max 200) + the returned `nextCursor`.", "operationId": "MerchantStockNotificationController_list", "parameters": [ { "name": "filter", "required": false, "in": "query", "description": "Lifecycle filter: `pending` (default — un-sent + still subscribed, the actionable list), `sent` (already notified, historical), `unsubscribed` (opted out, historical), `all` (every row).", "schema": { "type": "string", "enum": [ "pending", "sent", "unsubscribed", "all" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of signups to return.", "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (the `nextCursor` field). Currently a stringified signup id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantStockNotificationPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List back-in-stock signup signups for the active org.", "tags": [ "merchant-stock-notifications" ] } }, "/api/v1/public/newsletter/subscribe": { "post": { "description": "Public-facing capture for a storefront newsletter signup widget. Creates a PENDING subscriber and sends a confirmation email; the subscriber is only added to the mailing list after they click the confirm link. Idempotent and enumeration-safe: the response is the same regardless of whether the address was new, pending, already confirmed, or resubscribing.", "operationId": "PublicNewsletterController_subscribe", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeNewsletterDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscribeResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Subscribe to a tenant newsletter / mailing list (double opt-in).", "tags": [ "public-newsletter" ] } }, "/api/v1/merchant/newsletter/subscribers": { "get": { "description": "Newest first. Filter by lifecycle status: `confirmed` (default — completed double opt-in, the real mailing list), `pending` (awaiting confirmation), `unsubscribed` (opted out, historical), `all` (every row). Cursor-paginated via `limit` (default 50, max 200) + the returned `nextCursor`; the full set is available via the `/export` CSV route.", "operationId": "MerchantNewsletterController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over email and source.", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "Lifecycle filter: `confirmed` (default — completed double opt-in, the real mailing list), `pending` (awaiting confirmation), `unsubscribed` (opted out, historical), `all` (every row).", "schema": { "type": "string", "enum": [ "pending", "confirmed", "unsubscribed", "all" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of subscribers to return.", "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (the `nextCursor` field). Currently a stringified subscriber id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantNewsletterSubscriberPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List newsletter subscribers for the active org.", "tags": [ "merchant-newsletter" ] } }, "/api/v1/merchant/newsletter/subscribers/export": { "get": { "description": "Streams the FULL set of subscribers matching the given `filter` (same values as the list endpoint; default `confirmed`) as `text/csv`, in the same `createdAt DESC` order, with NO pagination or row cap. Columns: email, status, source, createdAt, confirmedAt, unsubscribedAt. Served as an attachment download; an empty result still returns a header-only CSV. Exporting the mailing list is a bulk PII read, so it requires the `customers:support` permission group (Owner/Admin always; Staff need the group) — unlike the list read, which stays open to all org members. The export is recorded in the audit log.", "operationId": "MerchantNewsletterController_export", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over email and source.", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "enum": [ "pending", "confirmed", "unsubscribed", "all" ], "type": "string" } } ], "responses": { "200": { "description": "CSV stream of the matching subscribers (attachment).", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Export newsletter subscribers as CSV.", "tags": [ "merchant-newsletter" ] } }, "/api/v1/public/abandoned-carts": { "post": { "description": "Public-facing capture for the storefront's abandoned-cart hooks. Idempotent on (organizationId, sessionId): re-submitting with the same sessionId updates the existing row in-place rather than creating a duplicate — EXCEPT when that row has passed the retention window, in which case the expired record is deleted and the capture starts a fresh one, so the response reports `wasCreated: true`. The storefront generates a high-entropy `captureToken` and sends it on EVERY capture: the first binds it, and later updates to that session MUST present the same token — the sessionId alone is not proof of ownership. An update without the matching token is rejected with 403.", "operationId": "PublicAbandonedCartController_upsert", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAbandonedCartDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbandonedCartCaptureResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "The sessionId already exists and no valid captureToken was supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Capture or update an abandoned-cart snapshot.", "tags": [ "public-abandoned-carts" ] } }, "/api/v1/merchant/abandoned-carts": { "get": { "description": "Newest captures first. Filter by lifecycle status: `pending` (default — recoveredAt IS NULL, the actionable list), `recovered` (matched to an order, historical), `all` (both). Cursor-paginated via `limit` (default 50, max 200) + the returned `nextCursor`. List rows omit the full cart `snapshot` blob to keep the response light.", "operationId": "MerchantAbandonedCartController_list", "parameters": [ { "name": "filter", "required": false, "in": "query", "description": "Lifecycle filter: `pending` (default — recoveredAt IS NULL, the actionable list), `recovered` (matched to an order, historical), `all` (both).", "schema": { "type": "string", "enum": [ "pending", "recovered", "all" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of carts to return.", "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (the `nextCursor` field). Currently a stringified cart id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAbandonedCartPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List captured abandoned carts for the active org.", "tags": [ "merchant-abandoned-carts" ] } }, "/api/v1/public/items": { "get": { "description": "Always filters to `status = ACTIVE` and excludes archived rows regardless of query params. A caller passing `?status=DRAFT` is silently ignored — DRAFT and ARCHIVED items are not visible to public storefront callers. Defense-in-depth: previously this route honored the caller-supplied status and could leak drafts. #1206 — when `limit` is omitted the response is bounded to a conservative default page size (24); oversized values are clamped to a hard maximum (200). Pass an explicit `limit` (up to 200) for a larger page. The response is a flat array; to page past the bound, pass the `id` of the last item you received as the `cursor` query param on the next request (keyset pagination). A page shorter than `limit` (or empty) means there are no more items.", "operationId": "PublicCatalogController_listItems", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over name, description, tags.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating large lists — the `id` of the last item from the previous page. The merchant paginated list returns this value as `nextCursor`; the public list endpoint returns a flat array, so use the `id` of the last item you received. Treat it as opaque.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by item type.", "schema": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] } }, { "name": "status", "required": false, "in": "query", "description": "Filter by item status. On the public route this is forced to ACTIVE. On the merchant route the default is \"any status\".", "schema": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ] } }, { "name": "archived", "required": false, "in": "query", "description": "Merchant-only. When true, soft-deleted (archivedAt != null) items are included in the result. Public reads ignore this and never expose archived data. Accepts: `true`/`1`/`yes` (case-insensitive) for true, `false`/`0`/`no` for false. Any other value is rejected as 400.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List ACTIVE items (public).", "tags": [ "public-catalog" ] } }, "/api/v1/public/items/featured": { "get": { "operationId": "PublicCatalogController_getFeaturedItems", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of featured items to return.", "schema": { "minimum": 1, "maximum": 50, "format": "int32", "default": 6, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Featured items for storefront hero.", "tags": [ "public-catalog" ] } }, "/api/v1/public/items/search": { "get": { "description": "#1206 — results are bounded server-side: a conservative default page size (24) when `limit` is omitted, clamped to a hard maximum (200) for oversized values.", "operationId": "PublicCatalogController_searchItems", "parameters": [ { "name": "q", "required": true, "in": "query", "description": "Search term for active public catalog items.", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of search results to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Full-text search across active items.", "tags": [ "public-catalog" ] } }, "/api/v1/public/items/resolve": { "post": { "description": "Accepts at most 200 distinct slugs and returns one minimal, tenant-safe catalog projection per currently ACTIVE item. Missing, DRAFT, and archived slugs are omitted. This lets a storefront validate a saved cart through one tenant-wide public API rate-limit admission instead of one request per line.", "operationId": "PublicCatalogController_resolveCartItems", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePublicCartItemsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCartCatalogItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Resolve bounded ACTIVE item projections for saved-cart restore.", "tags": [ "public-catalog" ] } }, "/api/v1/public/items/{slug}": { "get": { "description": "Missing, DRAFT, or archived slugs are masked as 404 so storefronts cannot probe for unpublished slugs.", "operationId": "PublicCatalogController_getItemBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ACTIVE item matching the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicItemDto" } } } }, "404": { "description": "No ACTIVE item matches the slug (unknown, DRAFT, or archived) — neutral `RESOURCE_NOT_FOUND`, matching the merchant read (#1221).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch a single ACTIVE item by slug.", "tags": [ "public-catalog" ] } }, "/api/v1/public/collections": { "get": { "description": "Always filters to `status = ACTIVE` and excludes archived rows. Storefronts use this.", "operationId": "PublicCatalogController_getCollections", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCollectionDto" } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List ACTIVE collections (public).", "tags": [ "public-catalog" ] } }, "/api/v1/public/collections/{slug}": { "get": { "description": "DRAFT or archived collections are masked as 404 so storefronts cannot probe for unpublished slugs.", "operationId": "PublicCatalogController_getCollectionBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ACTIVE collection matching the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCollectionDto" } } } }, "404": { "description": "No ACTIVE collection matches the slug (unknown, DRAFT, or archived) — neutral `RESOURCE_NOT_FOUND` (#1221).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch an ACTIVE collection by slug.", "tags": [ "public-catalog" ] } }, "/api/v1/public/collections/{slug}/items": { "get": { "description": "Hides archived items. If the parent collection is DRAFT or archived the response is an empty array (same as \"no items\"), preserving the storefront-cannot-probe property.", "operationId": "PublicCatalogController_getCollectionItems", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Items belonging to an ACTIVE collection.", "tags": [ "public-catalog" ] } }, "/api/v1/merchant/items": { "get": { "description": "Returns items ordered by merchant-controlled `sortOrder` ascending, then `createdAt` descending + `id` descending as stable tiebreakers, with cursor pagination. By default soft-deleted (`archivedAt`) items are hidden. Pass `?archived=true` to include them, optionally with `?status=ARCHIVED` to see only soft-deleted rows. Each page item is decorated like the public read (`salePriceInCents`, `ratingAverage`, `collectionIds`), unlike the raw single-item GET.", "operationId": "MerchantCatalogController_listItems", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over name, description, tags.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating large lists — the `id` of the last item from the previous page. The merchant paginated list returns this value as `nextCursor`; the public list endpoint returns a flat array, so use the `id` of the last item you received. Treat it as opaque.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by item type.", "schema": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] } }, { "name": "status", "required": false, "in": "query", "description": "Filter by item status. On the public route this is forced to ACTIVE. On the merchant route the default is \"any status\".", "schema": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ] } }, { "name": "archived", "required": false, "in": "query", "description": "Merchant-only. When true, soft-deleted (archivedAt != null) items are included in the result. Public reads ignore this and never expose archived data. Accepts: `true`/`1`/`yes` (case-insensitive) for true, `false`/`0`/`no` for false. Any other value is rejected as 400.", "schema": { "type": "boolean" } }, { "name": "compositionCandidate", "required": false, "in": "query", "description": "When true, return only Items that do not already own a package/kit composition, for server-backed component discovery. Accepts the same explicit boolean forms as `archived`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List items for the active org.", "tags": [ "merchant-items", "merchant-collections" ] }, "post": { "operationId": "MerchantCatalogController_createItem", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create an item (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/by-slug/{slug}": { "get": { "operationId": "MerchantCatalogController_getItemBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a single item by slug (includes archived).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}": { "get": { "operationId": "MerchantCatalogController_getItemById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a single item by id (includes archived).", "tags": [ "merchant-items", "merchant-collections" ] }, "patch": { "operationId": "MerchantCatalogController_updateItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update an item (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/reorder": { "patch": { "description": "M2 / #306 — bulk \"set the whole order\" reorder. Assigns each item `sortOrder = its index` in `orderedIds` inside a transaction, so the result is always unique + contiguous (tie-free by construction). The supplied array MUST be the complete set of the tenant's non-archived items; any missing, extra, or foreign id returns 400 so a stale client cannot partially reorder. Archived items are excluded from the ordering — archive/restore is the membership lever.", "operationId": "MerchantCatalogController_reorderItems", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderItemsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder the tenant's items (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}/archive": { "post": { "description": "Sets `archivedAt = now()` and `status = ARCHIVED`. The prior status is preserved in `metafields.__archivedFromStatus` so `restore` can return the item to its previous lifecycle state. Idempotent — archiving an already-archived item returns the same row.", "operationId": "MerchantCatalogController_archiveItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive (soft-delete) an item.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}/restore": { "post": { "description": "Clears `archivedAt` and restores `status` from `metafields.__archivedFromStatus` (falls back to `DRAFT`). Idempotent.", "operationId": "MerchantCatalogController_restoreItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted item.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/variants": { "get": { "operationId": "MerchantCatalogController_listVariants", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "archived", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantVariantDto" } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List variants for an item.", "tags": [ "merchant-items", "merchant-collections" ] }, "post": { "operationId": "MerchantCatalogController_createVariant", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVariantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantVariantDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a variant.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/variants/{variantId}": { "get": { "operationId": "MerchantCatalogController_getVariant", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "variantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantVariantDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a single variant.", "tags": [ "merchant-items", "merchant-collections" ] }, "patch": { "operationId": "MerchantCatalogController_updateVariant", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "variantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVariantDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantVariantDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a variant.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/variants/reorder": { "patch": { "description": "M2 / #290 — bulk \"set the whole order\" reorder scoped to one item's variants. Assigns each variant `sortOrder = its index` in `orderedVariantIds` inside a transaction (tie-free by construction). The supplied array MUST be the complete set of the item's non-archived variants; any missing, extra, or foreign id returns 400. Archived variants are excluded from the ordering.", "operationId": "MerchantCatalogController_reorderVariants", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderVariantsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder an item's variants (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/variants/{variantId}/archive": { "post": { "operationId": "MerchantCatalogController_archiveVariant", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "variantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantVariantDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive (soft-delete) a variant. Idempotent.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/variants/{variantId}/restore": { "post": { "operationId": "MerchantCatalogController_restoreVariant", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "variantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantVariantDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted variant. Idempotent.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections": { "get": { "description": "Returns ACTIVE + DRAFT collections by default; pass `?archived=true` to include soft-deleted rows, optionally with `?status=ARCHIVED` to see only archived ones.", "operationId": "MerchantCatalogController_listCollections", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over name and description.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by collection status. On the public route this is forced to ACTIVE. On the merchant route the default is \"any non-archived\".", "schema": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ] } }, { "name": "archived", "required": false, "in": "query", "description": "Merchant-only. When true, soft-deleted (`archivedAt != null`) collections are included. Public reads ignore this and never expose archived data. Accepts: `true`/`1`/`yes` for true, `false`/`0`/`no` for false. Any other value is rejected as 400.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCollectionWithImagesDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List collections for the active org.", "tags": [ "merchant-items", "merchant-collections" ] }, "post": { "operationId": "MerchantCatalogController_createCollection", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a collection (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/by-slug/{slug}": { "get": { "operationId": "MerchantCatalogController_getCollectionBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a collection by slug (merchant — includes DRAFT + archived).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}": { "get": { "operationId": "MerchantCatalogController_getCollectionById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a collection by id (merchant — includes DRAFT + archived).", "tags": [ "merchant-items", "merchant-collections" ] }, "patch": { "operationId": "MerchantCatalogController_updateCollection", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a collection (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/by-slug/{slug}/items": { "get": { "description": "Merchant view: includes archived items and shows items even when the parent collection is DRAFT or archived. Public storefront callers should use the equivalent `/public/collections/.../items` route which hides those.", "operationId": "MerchantCatalogController_getCollectionItemsBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List items in a collection by slug (merchant).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/order": { "patch": { "description": "Replaces the sortOrder sequence for every non-archived collection in the tenant. The supplied array MUST be the full current set; partial lists return 400.", "operationId": "MerchantCatalogController_reorderCollections", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderCollectionsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder the tenant's collections (permission required).", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/archive": { "post": { "description": "Sets `archivedAt = now()` and `status = ARCHIVED`. Idempotent. Item assignments are preserved so restore returns the same lineup.", "operationId": "MerchantCatalogController_archiveCollection", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive (soft-delete) a collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/restore": { "post": { "description": "Clears `archivedAt` and sets `status = DRAFT` (conservative — merchant must republish to make it visible). Idempotent.", "operationId": "MerchantCatalogController_restoreCollection", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCollectionDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/items": { "post": { "description": "Items already in the collection are silently skipped. Items not belonging to the tenant fail the call with a 404. New items are appended after the existing highest `sortOrder`.", "operationId": "MerchantCatalogController_assignItemsToCollection", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignCollectionItemsDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignCollectionItemsResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Bulk-add items to a collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/items/{itemId}": { "delete": { "description": "Idempotent — re-removing an absent item returns `{removed: 0}`. The item itself is not deleted.", "operationId": "MerchantCatalogController_removeItemFromCollection", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionItemRemovalResultDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove an item from a collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/items/order": { "patch": { "description": "Replaces the sortOrder sequence for every item. The supplied array MUST be the complete set currently in the collection; submitting a partial list returns 400 to prevent accidental half-removes.", "operationId": "MerchantCatalogController_reorderCollectionItems", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderCollectionItemsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder all items in a collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}/images": { "get": { "description": "Returns the image metadata rows ordered by sortOrder ascending. Includes the full structured-media columns (storagePath, focal points, dimensions, mime type).", "operationId": "MerchantCatalogController_listItemImages", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantItemImageDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List images attached to an item.", "tags": [ "merchant-items", "merchant-collections" ] }, "post": { "description": "Writes the metadata row for an image uploaded via the signed-URL endpoint. `imageId`, `url`, and `storagePath` should be propagated verbatim from the signed-URL response. `isPrimary=true` clears the flag on every other image for the item, atomically.", "operationId": "MerchantCatalogController_confirmItemImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmItemImageDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemImageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Confirm an item image after upload.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}/images/order": { "patch": { "description": "Replaces the sortOrder sequence for every image. The supplied array MUST be the complete set currently on the item; submitting a partial list returns 400 to prevent accidental half-removes.", "operationId": "MerchantCatalogController_reorderItemImages", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderImagesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder all images attached to an item.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{id}/images/{imageId}": { "patch": { "description": "Only metadata fields (alt, focalX/Y, isPrimary) are mutable. To swap bytes, upload a new image and delete the old one. `isPrimary=true` clears the flag on every other image for the item, atomically.", "operationId": "MerchantCatalogController_updateItemImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "imageId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemImageDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantItemImageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update item image metadata.", "tags": [ "merchant-items", "merchant-collections" ] }, "delete": { "description": "Hard-deletes the metadata row. The storage object is NOT deleted synchronously — a future bucket-sweep job reconciles orphaned objects against the row table. The audit log captures the storagePath so the sweeper can confirm the delete intent.", "operationId": "MerchantCatalogController_removeItemImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "imageId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteImageResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete an item image.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/images": { "get": { "description": "Returns the image metadata rows ordered by sortOrder ascending. Mirrors the item-image endpoint; rows live in `collection_images`.", "operationId": "MerchantCatalogController_listCollectionImages", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCollectionImageDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List images attached to a collection.", "tags": [ "merchant-items", "merchant-collections" ] }, "post": { "description": "Writes the metadata row for an image uploaded via the signed-URL endpoint. Same shape as the item-image confirm endpoint.", "operationId": "MerchantCatalogController_confirmCollectionImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmCollectionImageDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCollectionImageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Confirm a collection image after upload.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/images/order": { "patch": { "description": "Replaces the sortOrder sequence for every image. The supplied array MUST be the complete set currently on the collection.", "operationId": "MerchantCatalogController_reorderCollectionImages", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderImagesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reorder all images attached to a collection.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/collections/{id}/images/{imageId}": { "patch": { "description": "Only metadata fields (alt, focalX/Y, isPrimary) are mutable. `isPrimary=true` clears the flag on every other image for the collection, atomically.", "operationId": "MerchantCatalogController_updateCollectionImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "imageId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionImageDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCollectionImageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update collection image metadata.", "tags": [ "merchant-items", "merchant-collections" ] }, "delete": { "description": "Hard-deletes the metadata row. The storage object is NOT deleted synchronously — a future bucket-sweep job reconciles orphans.", "operationId": "MerchantCatalogController_removeCollectionImage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "imageId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteImageResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete a collection image.", "tags": [ "merchant-items", "merchant-collections" ] } }, "/api/v1/merchant/items/{itemId}/composition": { "get": { "description": "Member-readable merchant projection of one ordered PACKAGE/KIT definition. Missing, foreign-tenant, and not-yet-composed parents share one neutral 404 response.", "operationId": "MerchantItemCompositionController_getComposition", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCompositionDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active tenant’s Item composition.", "tags": [ "merchant-items" ] }, "put": { "description": "Revision-guarded whole-definition write. expectedRevision 0 creates revision 1; replacing revision N requires N and returns N+1. Array order becomes contiguous server-owned position. The parent must remain a non-archived DRAFT and no pricing, capacity, checkout, or public behavior is activated by this route.", "operationId": "MerchantItemCompositionController_putComposition", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutItemCompositionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCompositionDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create or replace an Item composition (permission required).", "tags": [ "merchant-items" ] } }, "/api/v1/merchant/item-compositions": { "get": { "description": "Member-readable catalog-backed package picker. Returns current Inventory / BookingService mapping readiness and derived component pricing without creating capacity, fulfillment, or package-owned state.", "operationId": "MerchantItemCompositionPreviewController_listPreviews", "parameters": [ { "name": "selectedQuantity", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 2147483647, "format": "int32", "default": 1, "type": "integer" } }, { "name": "servicePeriodStartsAt", "required": false, "in": "query", "description": "Optional operational window start. Required with servicePeriodEndsAt when a tracked booking-service component is selected.", "schema": { "format": "date-time", "type": "string" } }, { "name": "servicePeriodEndsAt", "required": false, "in": "query", "description": "Optional operational window end. Required with servicePeriodStartsAt when a tracked booking-service component is selected.", "schema": { "format": "date-time", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Case-insensitive parent Item name or slug search.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCompositionPreviewListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List current package/kit previews for the active tenant.", "tags": [ "merchant-items" ] } }, "/api/v1/merchant/items/{itemId}/composition/preview": { "get": { "description": "Member-readable derived projection. Mapping readiness follows Inventory for SALE components and active BookingService authority for RENTAL/SERVICE components. FIXED_PRICE commercial quantity remains one while effectiveQuantity preserves operational units.", "operationId": "MerchantItemCompositionPreviewController_getPreview", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "selectedQuantity", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 2147483647, "format": "int32", "default": 1, "type": "integer" } }, { "name": "servicePeriodStartsAt", "required": false, "in": "query", "description": "Optional operational window start. Required with servicePeriodEndsAt when a tracked booking-service component is selected.", "schema": { "format": "date-time", "type": "string" } }, { "name": "servicePeriodEndsAt", "required": false, "in": "query", "description": "Optional operational window end. Required with servicePeriodStartsAt when a tracked booking-service component is selected.", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCompositionPreviewDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Preview one package/kit from current domain authorities.", "tags": [ "merchant-items" ] } }, "/api/v1/merchant/sale-windows": { "get": { "description": "Optional `status` filter narrows by derived lifecycle bucket (upcoming / active / expired / all). Newest first by `createdAt`. Reads are open to any org member.", "operationId": "MerchantSaleWindowController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "all", "upcoming", "active", "expired" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SaleWindowResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List sale windows for the active org.", "tags": [ "merchant-sale-windows" ] }, "post": { "description": "Choose FIXED_PRICE, AMOUNT_OFF, or PERCENT_OFF and provide exactly its matching value field. A legacy body that omits valueType remains FIXED_PRICE. Amount Off clamps at $0.00; Percent Off uses basis points and floor-rounds each resolved discount. endsAt must be strictly after startsAt. variantId (when set) must belong to itemId. The service enforces no-overlap against existing windows for the same (itemId, variantId) tuple — half-open intervals, so back-to-back schedules are allowed.", "operationId": "MerchantSaleWindowController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSaleWindowDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleWindowResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a sale window (permission required).", "tags": [ "merchant-sale-windows" ] } }, "/api/v1/merchant/sale-windows/{id}": { "get": { "operationId": "MerchantSaleWindowController_getById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleWindowResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a sale window by id.", "tags": [ "merchant-sale-windows" ] }, "patch": { "description": "Patch-style: provided fields overwrite, omitted fields are left alone. `variantId` accepts explicit `null` to clear the per-variant scope back to item-level. itemId is NOT updatable — delete + recreate if the target item should change. Supplying `valueType` requires exactly its matching value field and atomically switches arms; omitting all value fields keeps the current arm. The resulting (startsAt, endsAt) and (itemId, variantId) tuple are re-validated against sibling rows for overlap.", "operationId": "MerchantSaleWindowController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSaleWindowDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleWindowResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a sale window (permission required).", "tags": [ "merchant-sale-windows" ] }, "delete": { "description": "Removes the row outright. Sale windows are usage-agnostic — no `usageCount`, no customer-visible code — so there is no value in preserving disabled rows. Audit trail lives in `audit_logs` (action `sale_window.deleted`) and requires a reason.", "operationId": "MerchantSaleWindowController_delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleWindowDeleteResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Hard-delete a sale window (permission required).", "tags": [ "merchant-sale-windows" ] } }, "/api/v1/public/inventory": { "get": { "description": "Covers publicly visible items only — ACTIVE and not archived. Stock rows for DRAFT or archived items are not returned, and neither are rows for composed (bundle-parent) items, which the public catalog does still list. New rows are auto-initialized for SALE items only, so SERVICE and RENTAL items normally have none, and a SALE item predating auto-initialization (or whose row was removed) may also have none. Treat the array as publicly eligible rows, not every row that exists. For SALE items, an item-level row (`variantId: null`) is publicly eligible only when the item has never had a variant. Any live or archived variant history retires only that SALE item-level target. A legacy item-level row on a SERVICE or RENTAL item remains publicly eligible even when the item has variant history, because those types do not use SALE stock targeting. An empty array means no publicly eligible rows matched; it does not prove that no inventory rows are stored. Read the public catalog for current variants; this inventory surface does not disclose archived variant details. TRUNCATION: this response is capped at 5000 rows and is a bare array — no envelope, cursor or total — so a truncated response is INDISTINGUISHABLE from a complete one. The per-item read carries the identical cap and is not a workaround.", "operationId": "PublicInventoryController_getInventory", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInventoryDto" } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List inventory snapshots for the tenant.", "tags": [ "public-inventory" ] } }, "/api/v1/public/inventory/{itemId}": { "get": { "description": "Returns an ARRAY of the publicly eligible stock rows for the item, not a single object and not one row per variant. Non-archived variant rows are returned when present. For SALE items, an item-level row (`variantId: null`) is publicly eligible only when the item has never had a variant. Any live or archived variant history retires only that SALE item-level target. A legacy item-level row on a SERVICE or RENTAL item remains publicly eligible even when the item has variant history, because those types do not use SALE stock targeting. An empty array means no publicly eligible rows matched; it does not prove that no inventory rows are stored. Read the public catalog for current variants; this inventory surface does not disclose archived variant details. A current variant may be absent because no row was ever created for it. Row creation is auto-initialized for SALE items only, so a SERVICE or RENTAL item normally yields an empty array, while a SALE item predating auto-initialization (or whose row was removed) may yield nothing. A DRAFT, archived, or composed (bundle-parent) item always yields an empty array. TRUNCATION: this response carries the same 5000-row cap as the list read, with no envelope, cursor or total, so a truncated response is INDISTINGUISHABLE from a complete one.", "operationId": "PublicInventoryController_getInventoryByItemId", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicInventoryDto" } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Inventory rows for a specific item.", "tags": [ "public-inventory" ] } }, "/api/v1/public/availability/check": { "post": { "operationId": "PublicInventoryController_checkAvailability", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAvailabilityDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityCheckResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Check availability of an item across a date range.", "tags": [ "public-inventory" ] } }, "/api/v1/merchant/inventory": { "get": { "description": "Returns inventory rows with the joined `item.name`/`item.slug` and, for variant-scoped rows, a `variant` summary (`id`, `name`, `sku`, `options`) so the admin viewer can render a readable row without a second roundtrip. Optional `?stockStatus=` and `?itemId=` filters compose. (The anonymous `/public/inventory` endpoints omit the `variant` summary.)", "operationId": "MerchantInventoryController_listInventory", "parameters": [ { "name": "stockStatus", "required": false, "in": "query", "description": "Filter by derived stock status. Maps directly to the row's `stockStatus` column which the service keeps in sync with `availableQuantity` and `lowStockThreshold` on every mutation.", "schema": { "$ref": "#/components/schemas/StockStatus" } }, { "name": "itemId", "required": false, "in": "query", "description": "Restrict to inventory rows for a single item (any variant). Useful for the item-detail view in the admin. Canonical item ids are UUIDs; the Prisma column remains `String` for compatibility with imported or historical rows, so this filter intentionally does not perform UUID validation. The service does the tenant + existence check.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List inventory rows for the active org (enriched).", "tags": [ "merchant-inventory" ] }, "post": { "description": "Creates the inventory row for a tenant-owned item, optionally scoped to one of its variants (`variantId`). A matching pre-existing item-level row may be returned unchanged with `created: false`, even when the item now has variant history. Only creation of a new item-level row is rejected when variant history exists; varianted items otherwise require an exact variant. This is the supported path to (re)establish a MISSING row — catalog create now auto-initializes rows, so this covers items/variants that predate that or whose row was removed (#1850). Idempotent: if a row already exists for the `(itemId, variantId)` pair it is returned unchanged rather than duplicated — so the handler is a create-OR-return and always responds `200` (not `201`), since it may not have created anything. The response `created` flag says which happened; when `false` the request's `totalQuantity`/`lowStockThreshold` were NOT applied (use `:id/adjust`). Only stock-managed (SALE) items are accepted — RENTAL/SERVICE get a `400`. Staff needs `inventory:adjust`.", "operationId": "MerchantInventoryController_createInventoryRow", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInventoryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureInventoryResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create the stock row for an existing item/variant (idempotent).", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/summary": { "get": { "description": "Returns one count per `stockStatus` value plus a `total`. Powers the admin dashboard's low-stock widget. Available to any authenticated org member (reads are not policy-gated on this controller). Missing statuses are normalized to `0` so the response shape is stable.", "operationId": "MerchantInventoryController_getSummary", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventorySummaryDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Aggregate inventory counts by stock status.", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/targets": { "get": { "description": "The lookup behind the admin inventory picker (#1857). Returns a bounded, merged page of stock-managed targets: variants of SALE items (`kind: 'variant'`) and no-variant SALE items' item-level default rows (`kind: 'item-default'`, `variantId: null`). `search` is a case-insensitive fuzzy match over variant name/SKU and item name; `sku` is a separate exact match; `missingInventory=true` restricts to targets whose row does not exist (the #1850 create-missing repair surface). Identity fields (`itemName`, `variantName`, `sku`) are for rendering — operators never see ids.", "operationId": "MerchantInventoryController_listInventoryTargets", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Case-insensitive substring match against variant name, variant SKU, and item name. A blank/absent term returns the first page of targets (a useful default list for the picker).", "schema": { "type": "string" } }, { "name": "sku", "required": false, "in": "query", "description": "Exact SKU match (variant targets only — items have no SKU). Separate from `search` so an exact lookup can never be diluted by fuzzy matches; when both are sent, `sku` takes precedence and `search` is ignored.", "schema": { "type": "string" } }, { "name": "variantId", "required": false, "in": "query", "description": "Resolve ONE variant target directly by its id (exact match; variant targets only — the item-default side drops out, and `search` is ignored, mirroring `sku` precedence). Used by the admin filter to re-resolve a URL-selected variant to its label without scanning pages — an item may have up to 1,000 variants, so a first-page scan cannot guarantee a hit.", "schema": { "type": "string" } }, { "name": "itemId", "required": false, "in": "query", "description": "Restrict to targets of a single item. Used by the picker to enumerate one item's variants and by the admin filter bar to re-resolve a URL-selected target to its label. Canonical item ids are UUIDs; imported or historical rows remain string-compatible, so this filter intentionally does not perform UUID validation (see `ListInventoryQueryDto.itemId`).", "schema": { "type": "string" } }, { "name": "missingInventory", "required": false, "in": "query", "description": "Only targets whose inventory row does not exist yet — the create-missing repair surface (#1850 modal). The audited mint paths are closed by #2008, so this population is normally the legacy tail plus anything a future writer slips past the invariant.", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size (default 20, max 50). The lookup is a bounded typeahead-style read — narrow the search rather than paging deep.", "schema": { "minimum": 1, "maximum": 50, "format": "int32", "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Merged-list offset for the next page (`nextOffset` from the previous response). Bounded (max 500): the union spans two models, so deep paging is deliberately unsupported — refine the search instead.", "schema": { "minimum": 0, "maximum": 500, "format": "int32", "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTargetListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Search selectable inventory targets (variant | item-default).", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/{itemId}": { "get": { "description": "Returns the item's inventory rows with the joined `item` summary and, for variant-scoped rows, a `variant` summary (`id`, `name`, `sku`, `options`).", "operationId": "MerchantInventoryController_getInventoryByItemId", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Inventory rows for a specific item.", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/{id}/adjust": { "post": { "description": "Adjusts both `totalQuantity` and `availableQuantity` by the same signed delta (`reservedQuantity` is unchanged). Recomputes `stockStatus` in the same transaction. Rejects deltas that would push availableQuantity (or totalQuantity) negative.", "operationId": "MerchantInventoryController_adjust", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustInventoryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Apply a signed delta to total + available quantities.", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/{id}/threshold": { "post": { "description": "Updates `lowStockThreshold` (>= 0; 0 disables the alarm). Recomputes `stockStatus` in the same transaction so a threshold change can flip a row IN_STOCK ↔ LOW_STOCK without a separate mutation. Staff needs `inventory:adjust` to set thresholds.", "operationId": "MerchantInventoryController_updateThreshold", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateThresholdDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set the low-stock threshold for an inventory row.", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/{id}/reserve": { "post": { "description": "Decrements `availableQuantity` and increments `reservedQuantity` by the same amount. `totalQuantity` is unchanged. Rejects requests where quantity > availableQuantity (negative-available guard runs against the locked row to prevent double-spend on concurrent reserves).", "operationId": "MerchantInventoryController_reserve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveInventoryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reserve units (move available → reserved).", "tags": [ "merchant-inventory" ] } }, "/api/v1/merchant/inventory/{id}/release": { "post": { "description": "Inverse of reserve. Decrements `reservedQuantity` and increments `availableQuantity` by the same amount. `totalQuantity` is unchanged. Rejects requests where quantity > reservedQuantity, where `reservedQuantity` is already below the capacity protected by live booking inventory claims, or where the requested release would cross that protected floor.", "operationId": "MerchantInventoryController_release", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseInventoryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventoryRowDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Reserved inventory already violates the live booking-claim floor, or the requested release would cross that floor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Release units (move reserved → available).", "tags": [ "merchant-inventory" ] } }, "/api/v1/public/bookings/{id}": { "get": { "operationId": "PublicBookingController_getBookingById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch a booking by id.", "tags": [ "public-bookings" ] } }, "/api/v1/public/bookings": { "post": { "operationId": "PublicBookingController_createBooking", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "RESOURCE_CONFLICT when the item has moved to the booking-service hold and checkout flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Create a booking (storefront checkout flow).", "tags": [ "public-bookings" ] } }, "/api/v1/public/booking-holds/{id}/checkout": { "post": { "description": "Auto-confirm payment services return a bearer c-token that remains reusable until checkout expiry and must be retained for reads/payment. Manual-approval and pay-later services create a capacity-free REQUESTED booking.", "operationId": "PublicBookingCheckoutController_create", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "x-idempotency-key", "in": "header", "description": "The same possession/idempotency key used to create the hold.", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingCheckoutDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCheckoutResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_PRICE_CONFIRMATION_REQUIRED returns the typed two-phase confirmation challenge. Other operation-specific conflicts use the canonical API error envelope. TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BookingPriceConfirmationRequiredErrorDto" }, { "$ref": "#/components/schemas/ApiErrorDto" } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Convert a live booking hold into checkout or an approval request.", "tags": [ "public-booking-checkout" ] } }, "/api/v1/public/booking-groups/quote": { "post": { "description": "Returns a short-lived, request-bound tax-inclusive cart quote and customer-safe frozen pricing presentation. It creates no BookingGroup, BookingHold, Booking, Commerce record, CheckoutSession, PaymentAttempt, or provider payment object. The create operation always performs a fresh server evaluation before a PAY_NOW hold.", "operationId": "PublicBookingGroupController_quoteCart", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicBookingGroupDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupCartQuoteResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "BOOKING_PRICE_CONFIRMATION_UNAVAILABLE or BOOKING_DELIVERY_UNAVAILABLE. PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Evaluate one complete booking cart without creating capacity.", "tags": [ "public-booking-groups" ] } }, "/api/v1/public/booking-groups": { "post": { "description": "Normalizes the complete booking.group/v1 intent, enforces 20 submitted selections, 20 normalized members, 100 server-expanded capacity anchors, and—when any selection is composed—100 total materialized Commerce lines before provider or durable domain work, then rejects incompatible groups or either creates all request-first bookings without capacity or claims every member hold under one globally ordered transaction. HELD responses contain only capacity/expiry and sanitized frozen delivery evidence; checkout totals and processor state are out of scope.", "operationId": "PublicBookingGroupController_create", "parameters": [ { "name": "booking-group-create-recovery-key", "in": "header", "description": "A separate caller-generated CSPRNG capability matching r[a-z0-9]{25}. Required before the initial POST and exact lost-response replay; stored only as SHA-256.", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^r[a-z0-9]{25}$" } }, { "name": "x-idempotency-key", "in": "header", "description": "8-255 character caller-generated key. Same key plus the same canonical complete intent replays only with the exact create-recovery proof; a changed intent returns 409.", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicBookingGroupDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "400": { "description": "Can include VALIDATION_FAILED for malformed input, including PICKUP with destinationAddress; COMPOSITION_INVALID; BOOKING_DELIVERY_INVALID; BOOKING_DELIVERY_DESTINATION_INVALID; or BOOKING_DELIVERY_OUT_OF_RANGE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "RESOURCE_NOT_FOUND for an unavailable booking service or an invalid, expired, or revoked create-recovery proof.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_PRICE_CONFIRMATION_REQUIRED with CART_QUOTE_STALE returns the prior rendered and fresh tax-inclusive totals. Other create conflicts use the canonical API error envelope: BOOKING_GROUP_IDEMPOTENCY_CONFLICT, BOOKING_CAPACITY_UNAVAILABLE, BOOKING_DELIVERY_CONFIGURATION_CHANGED, COMPOSITION_REVISION_STALE, COMPOSITION_COMPONENT_MAPPING_MISSING, COMPOSITION_COMPONENT_MAPPING_AMBIGUOUS, COMPOSITION_INVALID, or RESOURCE_CONFLICT. TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BookingCartQuoteStaleErrorDto" }, { "$ref": "#/components/schemas/ApiErrorDto" } ] } } } }, "422": { "description": "BOOKING_GROUP_LIMIT_EXCEEDED for more than 20 selections, 20 normalized members, 100 expanded capacity anchors, or (for a composed group) 100 materialized Commerce lines; BOOKING_GROUP_INCOMPATIBLE; or BOOKING_GROUP_SECURITY_AUTH_UNSUPPORTED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "BOOKING_DELIVERY_UNAVAILABLE when server-owned delivery evaluation cannot complete safely. PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Atomically create a bounded booking group.", "tags": [ "public-booking-groups" ] } }, "/api/v1/public/booking-groups/{publicRef}/request": { "post": { "description": "Reuses the exact normalized OPEN intent and its server-held original create idempotency identity after the booking-request agreement is satisfied. It revalidates the current native or verified-external satisfaction transactionally, then advances the same group without accepting new member input or creating a duplicate group. Pending agreement, wrong proof, or cross-tenant authority fail without capacity, Commerce, CheckoutSession, or PaymentAttempt writes.", "operationId": "PublicBookingGroupController_resumeRequest", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^b[a-z0-9]{25}$" } }, { "name": "booking-group-resume-key", "in": "header", "description": "The response-only group resume proof. It is distinct from the public reference, idempotency key, and create-recovery capability and is stored only as SHA-256.", "required": true, "schema": { "type": "string", "pattern": "^g[a-z0-9]{25}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPriceConfirmationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_PRICE_CONFIRMATION_REQUIRED returns the typed two-phase confirmation challenge. Other operation-specific conflicts use the canonical API error envelope. TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BookingPriceConfirmationRequiredErrorDto" }, { "$ref": "#/components/schemas/ApiErrorDto" } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Resume an agreement-gated booking request.", "tags": [ "public-booking-groups" ] } }, "/api/v1/public/booking-groups/{publicRef}": { "get": { "description": "Unknown, cross-tenant, malformed, expired-proof, and wrong-proof requests are the same neutral 404. After commercial binding, pricing comes only from the persisted CheckoutSession or exact member Sales records and never exposes a checkout capability. A successful resume-authenticated read acknowledges the separate create-recovery proof.", "operationId": "PublicBookingGroupController_get", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^b[a-z0-9]{25}$" } }, { "name": "booking-group-resume-key", "in": "header", "description": "The response-only group resume proof. It is distinct from the public reference, idempotency key, and create-recovery capability and is stored only as SHA-256.", "required": true, "schema": { "type": "string", "pattern": "^g[a-z0-9]{25}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_GROUP_ACTION_INVALID with details.reason PAYMENT_RECONCILIATION_PENDING when an expired payment-bound group cannot yet prove authoritative payment absence. Retry the same proof-bound read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read one proof-bound booking group status.", "tags": [ "public-booking-groups" ] }, "delete": { "description": "Cancels every live child hold or request-first booking in one transaction. Unknown/cross-tenant/wrong-proof requests are neutral 404s; confirmed groups cannot be rewound.", "operationId": "PublicBookingGroupController_cancel", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^b[a-z0-9]{25}$" } }, { "name": "x-idempotency-key", "in": "header", "description": "Caller-generated key that serializes this proof-bound cancellation. Replays are terminal no-ops.", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, { "name": "booking-group-resume-key", "in": "header", "description": "The response-only group resume proof. It is distinct from the public reference, idempotency key, and create-recovery capability and is stored only as SHA-256.", "required": true, "schema": { "type": "string", "pattern": "^g[a-z0-9]{25}$" } } ], "responses": { "204": { "description": "Cancelled or already cancelled." }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Cancel one proof-bound pre-confirmation booking group.", "tags": [ "public-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}": { "get": { "operationId": "MerchantBookingGroupController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read one tenant-scoped booking aggregate.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}/approve": { "post": { "operationId": "MerchantBookingGroupController_approve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Atomically approve every member in a booking aggregate.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}/decline": { "post": { "operationId": "MerchantBookingGroupController_decline", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Decline every request member atomically.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}/cancel": { "post": { "operationId": "MerchantBookingGroupController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel one pre-confirmation booking aggregate atomically.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}/refunds/stripe": { "post": { "operationId": "MerchantBookingGroupController_issueSharedRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "x-idempotency-key", "in": "header", "description": "Required idempotency key. One key maps to one frozen allocation plan and one provider refund.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueBookingGroupRefundDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupSharedRefundResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Issue one shared Stripe refund across an exact set of booking-group member amounts.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/booking-groups/{id}/refunds/{refundPaymentAttemptId}/reconcile": { "post": { "operationId": "MerchantBookingGroupController_reconcileImportedRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "refundPaymentAttemptId", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "x-idempotency-key", "in": "header", "description": "Required idempotency key. Reuse the same key and body to resume a partially converged reconciliation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileBookingGroupRefundDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupRefundReconciliationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Freeze exact member allocations for an imported shared-payment refund and reconcile it into Sales.", "tags": [ "merchant-booking-groups" ] } }, "/api/v1/merchant/bookings": { "post": { "description": "DRAFT and REQUEST create no capacity or Sales state. RESERVE performs the guarded capacity claim and creates the canonical booking-linked Sales projection atomically.", "operationId": "MerchantBookingController_createBooking", "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantBookingDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a merchant-authored draft, request, or reserved booking.", "tags": [ "merchant-bookings" ] }, "get": { "description": "Returns a bounded page of bookings (newest first) plus a `nextCursor` for the following page. Pass `?limit=` (1–200, default 50) to size the page. Staff reads are always limited to bookings actively assigned through a linked tenant resource; Owner/Admin reads may opt into that scope with `?mine=true`. `#1469` — replaces the former unbounded list.", "operationId": "MerchantBookingController_getBookings", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of bookings to return. Defaults to 50.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating — the `id` of the last booking from the previous page (returned as `nextCursor`). Treat it as opaque.", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Case-insensitive search over customer name/email, service name, and Sales display number.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] } }, { "name": "bookingType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "paymentStatus", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] } }, { "name": "attention", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "NEEDS_APPROVAL", "PAYMENT_DUE", "UNASSIGNED", "SHORTAGE", "ALLOCATION_CONFLICT", "OVERRIDDEN" ] } }, { "name": "mine", "required": false, "in": "query", "description": "Owner/Admin only: when true, return bookings currently allocated to a resource linked to the signed-in member. Staff reads are always assignment-scoped regardless of this value. The member identity is derived from the authenticated session.", "schema": { "type": "boolean" } }, { "name": "from", "required": false, "in": "query", "description": "Inclusive overlap-window start. Must be supplied together with `to` and include a timezone offset.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Exclusive overlap-window end. Must be supplied together with `from` and include a timezone offset.", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List bookings for the active org (cursor-paginated).", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/availability/preflight": { "post": { "operationId": "MerchantBookingController_preflightAvailability", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingAvailabilitySearchDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingAvailabilityResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Preflight a merchant-selected booking window and capacity.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/reserve": { "post": { "operationId": "MerchantBookingController_reserve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reserve a merchant-authored draft or request through the guarded capacity and Sales boundary.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/calendar": { "get": { "description": "Returns tenant-scoped bookings plus expanded one-off/recurring blackout blockers for a positive half-open range of at most 62 days. Staff booking entries are always limited to active assignments through linked tenant resources; Owner/Admin reads may opt into that scope with `?mine=true`. No customer slots are generated.", "operationId": "MerchantBookingController_getCalendar", "parameters": [ { "name": "from", "required": true, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] } }, { "name": "bookingType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] } }, { "name": "mine", "required": false, "in": "query", "description": "Owner/Admin only: when true, return booking entries currently allocated to a resource linked to the signed-in member. Staff booking entries are always assignment-scoped regardless of this value. The member identity is derived from the authenticated session.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingCalendarDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a bounded booking operations calendar projection.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}": { "get": { "description": "Staff may read only bookings actively assigned through a linked tenant resource. An unassigned, missing, or cross-tenant id returns the same neutral 404.", "operationId": "MerchantBookingController_getBookingById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a booking by id.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/tax-addresses": { "patch": { "description": "Only DRAFT or REQUESTED singular bookings may be amended. Omitted fields retain their value; null clears a pickup address. Frozen delivery destinations remain authoritative.", "operationId": "MerchantBookingController_updateTaxAddresses", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantBookingTaxAddressesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Amend normalized shipping or billing tax input before a singular booking is reserved.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/physical-plan": { "patch": { "operationId": "MerchantBookingController_updatePhysicalPlan", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingPhysicalPlanDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update shared outbound/inbound physical-fulfillment mode and due posture for a booking.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/allocations/{allocationId}/resolve-shortage": { "post": { "operationId": "MerchantBookingController_resolveShortage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "allocationId", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveBookingShortageDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record how an approved controlled shortage was concretely resolved.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/approve": { "post": { "operationId": "MerchantBookingController_approve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Approve a requested booking and recheck capacity.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/approve-with-shortage": { "post": { "operationId": "MerchantBookingController_approveWithShortage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Approve a requested booking with an explicitly policy-enabled controlled shortage.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/decline": { "post": { "operationId": "MerchantBookingController_decline", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Decline a requested booking.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/cancel": { "post": { "operationId": "MerchantBookingController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel a booking and release capacity.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/reschedule": { "post": { "operationId": "MerchantBookingController_reschedule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleBookingDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reschedule a confirmed booking under a fresh capacity claim.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/reschedule-with-shortage": { "post": { "operationId": "MerchantBookingController_rescheduleWithShortage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleBookingDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reschedule with a policy-enabled, reasoned controlled shortage.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/change-requests/{requestId}/decline": { "post": { "operationId": "MerchantBookingController_declineChangeRequest", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "requestId", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Decline a pending customer booking change request.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/start": { "post": { "operationId": "MerchantBookingController_start", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Start a confirmed booking.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/complete": { "post": { "operationId": "MerchantBookingController_complete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Complete an active booking.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/archive": { "post": { "operationId": "MerchantBookingController_archive", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a terminal booking.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/assignments": { "get": { "description": "Returns the current live BookingAllocation fence, service requirements, eligible resources, linked tenant staff snapshots, remaining capacity, and conflict signals for one tenant-scoped booking.", "operationId": "MerchantBookingAssignmentController_getWorkspace", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingAssignmentWorkspaceDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the guarded resource and named-provider assignment workspace.", "tags": [ "merchant-booking-assignments" ] }, "post": { "description": "Normal assignment is strict: closed windows, blackouts, shared-provider overlap, pooled shortage, and exact-unit conflicts fail without modifying the current live allocation set.", "operationId": "MerchantBookingAssignmentController_replace", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceMerchantBookingAssignmentsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingAssignmentWorkspaceDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace live booking assignments through the capacity guard.", "tags": [ "merchant-booking-assignments" ] } }, "/api/v1/merchant/bookings/{id}/assignments-with-shortage": { "post": { "description": "Requires both bookings:operate and bookings:override plus the high-risk reason. The effective booking policy must allow controlled shortage. Serialized-unit conflicts are never overridable.", "operationId": "MerchantBookingAssignmentController_replaceWithShortage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceMerchantBookingAssignmentsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBookingAssignmentWorkspaceDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace assignments with an audited controlled-shortage override.", "tags": [ "merchant-booking-assignments" ] } }, "/api/v1/merchant/bookings/{id}/fulfillment-checklist": { "get": { "description": "Derives prep/load-out/return tasks from the current booking allocation cycle and positive PRODUCT Sales lines, then projects physical fulfillment and returns from their shared ledgers. Staff may read only actively assigned bookings; unassigned, missing, and cross-tenant ids return the same neutral 404. The JSON response is a bounded single-booking export; it does not copy shipment, return, condition, or restock state into Bookings.", "operationId": "MerchantBookingChecklistController_getChecklist", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFulfillmentChecklistDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a printable booking prep and fulfillment checklist.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/bookings/{id}/fulfillment-checklist/{taskKey}": { "patch": { "description": "Upserts only the operator task status, completion audit, and note. The task must still derive from the current allocation cycle or a positive PRODUCT Sales line. Archived bookings are read-only and reject checklist mutations with 409.", "operationId": "MerchantBookingChecklistController_updateTask", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskKey", "required": true, "in": "path", "description": "Stable taskKey returned by the checklist read.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingChecklistTaskDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFulfillmentChecklistDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update booking-owned checklist task state or notes.", "tags": [ "merchant-bookings" ] } }, "/api/v1/merchant/booking-reports/dimensions": { "get": { "description": "Returns only service/resource ids, names, and archive posture needed by report filters. It does not expose booking setup configuration.", "operationId": "MerchantBookingReportController_dimensions", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReportDimensionsDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List tenant-scoped booking report filter dimensions.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/booking-reports/availability": { "get": { "description": "Aggregates configured/open windows, active units, half-open hold/booking claims, blackouts, and controlled shortages for one tenant-scoped service. This is an operator diagnostic, not a public customer-slot response. Maximum range: 31 days.", "operationId": "MerchantBookingReportController_availability", "parameters": [ { "name": "from", "required": true, "in": "query", "description": "Inclusive range start. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "Exclusive range end. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "description": "Required service scope. A service outside the active tenant returns an empty report.", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityReportDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read booking availability and shortage diagnostics.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/booking-reports/fulfillment-demand": { "get": { "description": "Projects bookings whose service window overlaps the half-open report range, plus bookings with outbound/inbound shared-commerce fulfillment milestones inside it. Includes active allocations, exact assets, and canonical fulfillment state. Maximum range: 366 days.", "operationId": "MerchantBookingReportController_fulfillmentDemand", "parameters": [ { "name": "from", "required": true, "in": "query", "description": "Inclusive range start. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "Exclusive range end. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingFulfillmentDemandReportDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read booking fulfillment demand and assignment diagnostics.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/booking-reports/lifecycle-revenue": { "get": { "description": "Reports bookings by booking-start range. Revenue is explicitly one of booked order, finalized invoice, or completed cash/payment-ledger basis; it never mixes those facts. Maximum range: 366 days.", "operationId": "MerchantBookingReportController_lifecycleRevenue", "parameters": [ { "name": "from", "required": true, "in": "query", "description": "Inclusive range start. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "Exclusive range end. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "revenueBasis", "required": false, "in": "query", "schema": { "default": "BOOKED_ORDER", "type": "string", "enum": [ "BOOKED_ORDER", "FINALIZED_INVOICE", "CASH_PAYMENT" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLifecycleRevenueReportDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read booking lifecycle and explicit-basis revenue diagnostics.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/booking-reports/document-payment-aging": { "get": { "description": "Projects shared quote/invoice/contract records and open customer action links. Rows are selected by due/expiry timestamp (or sent timestamp for undated open documents). Maximum range: 366 days.", "operationId": "MerchantBookingReportController_documentPaymentAging", "parameters": [ { "name": "from", "required": true, "in": "query", "description": "Inclusive range start. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "Exclusive range end. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDocumentPaymentAgingReportDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read booking document and payment aging diagnostics.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/booking-reports/{kind}/export": { "get": { "description": "Uses the same tenant scope, range limits, filters, row cap, and revenue-basis semantics as the corresponding JSON report.", "operationId": "MerchantBookingReportController_export", "parameters": [ { "name": "kind", "required": true, "in": "path", "schema": { "enum": [ "availability", "fulfillment-demand", "lifecycle-revenue", "document-payment-aging" ], "type": "string" } }, { "name": "from", "required": true, "in": "query", "description": "Inclusive range start. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "Exclusive range end. A timezone offset is required.", "schema": { "format": "date-time", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "revenueBasis", "required": false, "in": "query", "description": "Used only by the lifecycle-revenue export.", "schema": { "default": "BOOKED_ORDER", "type": "string", "enum": [ "BOOKED_ORDER", "FINALIZED_INVOICE", "CASH_PAYMENT" ] } } ], "responses": { "200": { "description": "CSV attachment for the selected report.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Export one bounded booking report as formula-safe CSV.", "tags": [ "merchant-booking-reports" ] } }, "/api/v1/merchant/agreements/workspace": { "get": { "description": "Returns tenant-scoped requirements, native/external executions, retained artifact status, verification history, and commerce projection links without exposing action authority, storage coordinates, private actor ids, or payment mutation controls.", "operationId": "MerchantAgreementController_getWorkspace", "parameters": [ { "name": "kind", "required": true, "in": "query", "schema": { "type": "string", "enum": [ "COMMERCE_RECORD", "COMMERCE_REVISION", "BOOKING", "BOOKING_GROUP" ] } }, { "name": "targetId", "required": true, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAgreementWorkspaceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the agreement workspace for one typed merchant subject.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/requirements": { "post": { "description": "The server resolves and freezes tenant-owned applicability for the selected sale, revision, booking, or booking group. It never accepts a caller-authored subject snapshot and never reads or mutates payment state.", "operationId": "MerchantAgreementController_attachRequirement", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachMerchantAgreementRequirementDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachMerchantAgreementRequirementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Attach one immutable agreement requirement to a typed subject.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/requirements/{requirementId}/waive": { "post": { "description": "A privileged, reason-bearing exception for one tenant-scoped requirement. The immutable waiver event is the audit authority; terminal or cross-tenant requirements fail without exposing their existence.", "operationId": "MerchantAgreementController_waiveRequirement", "parameters": [ { "name": "requirementId", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaiveAgreementRequirementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementRequirementWaiverResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Waive one exact active agreement requirement.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/templates": { "get": { "operationId": "MerchantAgreementController_listTemplates", "parameters": [ { "name": "includeVersions", "required": false, "in": "query", "description": "Include every immutable template version in the list response. The default response includes only latestVersion.", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementTemplateResponseDto" } } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List tenant agreement templates.", "tags": [ "merchant-agreements" ] }, "post": { "operationId": "MerchantAgreementController_createTemplate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgreementTemplateDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTemplateResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a tenant agreement template identity.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/templates/{templateId}": { "get": { "operationId": "MerchantAgreementController_getTemplate", "parameters": [ { "name": "templateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTemplateResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a template and its immutable version history.", "tags": [ "merchant-agreements" ] }, "patch": { "operationId": "MerchantAgreementController_updateTemplate", "parameters": [ { "name": "templateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgreementTemplateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTemplateResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update template name or description only.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/templates/{templateId}/archive": { "post": { "operationId": "MerchantAgreementController_archiveTemplate", "parameters": [ { "name": "templateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTemplateResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a template identity without changing issued history.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/templates/{templateId}/versions": { "post": { "operationId": "MerchantAgreementController_appendTemplateVersion", "parameters": [ { "name": "templateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendAgreementTemplateVersionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTemplateVersionResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Append an immutable server-digested template version.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/disclosures": { "get": { "operationId": "MerchantAgreementController_listDisclosures", "parameters": [ { "name": "disclosureKey", "required": false, "in": "query", "schema": { "maxLength": 128, "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementDisclosureVersionResponseDto" } } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List immutable disclosure versions.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/disclosures/versions": { "post": { "operationId": "MerchantAgreementController_appendDisclosureVersion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendAgreementDisclosureVersionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementDisclosureVersionResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Append an immutable approved disclosure version.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/preview": { "post": { "description": "Callers cannot supply merge values; unresolved or inapplicable fields fail closed.", "operationId": "MerchantAgreementController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAgreementTemplateDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementPreviewResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Preview a template with tenant-owned subject facts.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/subjects/{subjectId}/revisions": { "get": { "operationId": "MerchantAgreementController_listRevisions", "parameters": [ { "name": "subjectId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementRevisionResponseDto" } } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List complete immutable revision history for a subject.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/revisions/{revisionId}": { "get": { "operationId": "MerchantAgreementController_getRevision", "parameters": [ { "name": "revisionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementRevisionResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read exact immutable terms for one revision.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/revisions/{revisionId}/rendered-pdf": { "post": { "operationId": "MerchantAgreementController_grantRenderedPdf", "parameters": [ { "name": "revisionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementArtifactGrantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementArtifactGrantResponseDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a short-lived grant for the verified rendered PDF.", "tags": [ "merchant-agreements" ] } }, "/api/v1/customer/account/agreement-history": { "get": { "description": "The optional booking filter is ownership-checked against the active tenant/customer. The response preserves provider provenance and exact native digests while omitting raw action authority, source external ids, storage coordinates, and private audit evidence.", "operationId": "CustomerAgreementHistoryController_list", "parameters": [ { "name": "bookingId", "required": false, "in": "query", "description": "Restrict history to one booking owned by the signed-in customer.", "schema": { "format": "uuid", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAgreementHistoryResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's canonical native and external agreement history.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreement-history/external/{executionId}/artifacts/{artifactId}/download": { "post": { "description": "Unknown, another customer’s, cross-tenant, pending, quarantined, destroyed, or integrity-invalid evidence fails without revealing which ownership or safety check failed. External evidence remains labeled as external and is never represented as a litecommerce-native signature.", "operationId": "CustomerAgreementHistoryController_grantExternalArtifact", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerExternalAgreementArtifactGrantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDownloadDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Authorize an owned external-agreement evidence download.", "tags": [ "customer-agreements" ] } }, "/api/v1/merchant/agreements/external": { "post": { "description": "Stores validated bytes in private quarantine and records honest outside-system provenance. Attachment and scanning do not verify evidence or satisfy a requirement, create a native signature, send mail, touch payment, or transition booking/commerce state.", "operationId": "MerchantExternalAgreementController_attach", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document", "subjectId", "sourceSystem", "externalId", "signedAt", "signersJson" ], "properties": { "document": { "type": "string", "format": "binary" }, "certificate": { "type": "string", "format": "binary" }, "subjectId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceSystem": { "type": "string", "enum": [ "booqable", "wet-signed", "docusign", "pandadoc", "authentisign", "other-external" ] }, "externalId": { "type": "string", "minLength": 1, "maxLength": 500 }, "displayNumber": { "type": "string", "maxLength": 200 }, "signedAt": { "type": "string", "format": "date-time" }, "countersignedAt": { "type": "string", "format": "date-time" }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "signersJson": { "type": "string", "minLength": 2, "maxLength": 20000 }, "notes": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "413": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Attach an externally executed agreement PDF.", "tags": [ "merchant-agreements" ] }, "get": { "operationId": "MerchantExternalAgreementController_list", "parameters": [ { "name": "subjectId", "required": false, "in": "query", "description": "Filter to one exact agreement subject.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementListDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List tenant-scoped external agreement evidence.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}": { "get": { "operationId": "MerchantExternalAgreementController_get", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch external agreement evidence metadata.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}/decisions": { "post": { "description": "Verification is a separate audited decision and succeeds only after every retained evidence artifact has a scanner-owned SAFE disposition.", "operationId": "MerchantExternalAgreementController_decide", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDecisionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Verify, reject, or mark external evidence insufficient.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}/satisfactions": { "post": { "operationId": "MerchantExternalAgreementController_satisfy", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SatisfyExternalAgreementRequirementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Use current verified evidence for one exact compatible requirement.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}/decisions/{verificationId}/revoke": { "post": { "description": "Revokes active satisfactions first and appends a forward-remediation exception. It never rewinds a completed payment, booking, fulfillment, or commerce command.", "operationId": "MerchantExternalAgreementController_revoke", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "verificationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeExternalAgreementVerificationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revoke an incorrect external-evidence verification.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}/artifacts/{artifactId}/destroy": { "post": { "description": "Records an authorized retention/offboarding/privacy disposition before deleting private bytes, then retains an immutable DESTROYED tombstone and completion event. It never changes payment, booking, fulfillment, or signature state.", "operationId": "MerchantExternalAgreementController_destroyArtifact", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestroyExternalAgreementArtifactDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementArtifactDestructionDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Govern destruction of one retained external-agreement artifact.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/external/{executionId}/artifacts/{artifactId}/download": { "get": { "description": "Returns the same neutral 404 for missing, cross-tenant, pending, quarantined, rejected, or destroyed evidence. An integrity mismatch returns 409 and temporary private-storage failure returns 503. Storage bucket/key metadata is never returned.", "operationId": "MerchantExternalAgreementController_download", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgreementDownloadDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Authorize a short-lived private evidence download.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions": { "post": { "description": "Server-issues one immutable revision from the exact template/disclosure versions, then binds one customer signer, an optional merchant countersigner, and an optional exact requirement. Optional digest expectations fail closed on drift; the server returns authoritative revision/digests and no action token.", "operationId": "MerchantNativeAgreementController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNativeAgreementExecutionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a draft native agreement execution.", "tags": [ "merchant-agreements" ] }, "get": { "description": "Cursor-paginated and tenant-scoped. Projections omit tokens, recipient email, audit IP/user-agent evidence, private actor ids, and storage coordinates.", "operationId": "MerchantNativeAgreementController_list", "parameters": [ { "name": "subjectId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "ISSUED", "IN_PROGRESS", "EXECUTED", "DECLINED", "EXPIRED", "VOIDED", "REPLACED" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List tenant-scoped native agreement executions.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}": { "get": { "description": "Unknown and cross-tenant execution identities return the same neutral 404.", "operationId": "MerchantNativeAgreementController_get", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read one tenant-scoped native execution.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/issue": { "post": { "description": "DRAFT→ISSUED only after revalidating the exact revision, rendered artifact, disclosure, participants, expiry, and optional requirement binding. This does not send authority or touch money.", "operationId": "MerchantNativeAgreementController_issue", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementReasonedCommandDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Issue one immutable draft execution.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/send": { "post": { "description": "Mints hashed, expiring, participant-scoped action authority inside the transaction and queues delivery. Raw authority is never returned by this merchant API.", "operationId": "MerchantNativeAgreementController_send", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementReasonedCommandDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Send an issued native agreement through the durable outbox.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/resend": { "post": { "description": "Revocation, replacement authority, lifecycle event, and durable outbox intent are one transaction. A resend never returns the raw token.", "operationId": "MerchantNativeAgreementController_resend", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementReasonedCommandDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revoke prior action authority and resend a fresh scoped link.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/presentation": { "post": { "description": "Persists an immutable shown event bound to the exact revision, content digest, disclosure identity/version/digest, participant, and actor. Server-observed request evidence is retained with the resulting assent; the response contains no private audit fields.", "operationId": "MerchantNativeAgreementController_present", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementPresentationResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Present exact terms to the authenticated merchant countersigner.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/countersign": { "post": { "description": "Requires the exact presentation event plus affirmative agreement/disclosure acceptance and a typed signer identity. It cannot sign for a different tenant, user, participant, revision, digest, or disclosure.", "operationId": "MerchantNativeAgreementController_countersign", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCountersignNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Countersign after exact presentation and explicit assent.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/decline": { "post": { "description": "Records a forward-only participant/execution decline. It never cancels or refunds a payment and never rewinds booking or commerce state.", "operationId": "MerchantNativeAgreementController_decline", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantDeclineNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Decline as the authenticated merchant countersigner.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/void": { "post": { "description": "Records a forward-only VOIDED disposition and revokes live action authority without erasing predecessor evidence or touching payment, booking, commerce, or fulfillment state.", "operationId": "MerchantNativeAgreementController_void", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementReasonedCommandDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Void a non-executed native agreement request.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/reissue": { "post": { "description": "Creates immutable predecessor/successor lineage and requires a fresh exact revision, disclosure, participants, and assent. Prior authority and assent are never reused.", "operationId": "MerchantNativeAgreementController_reissue", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReissueNativeAgreementExecutionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace an unexecuted request with a newly bound execution.", "tags": [ "merchant-agreements" ] } }, "/api/v1/merchant/agreements/native/executions/{executionId}/artifacts/{artifactId}/download": { "post": { "description": "Only retained safe EXECUTED_PDF and EXECUTION_CERTIFICATE artifacts are eligible. Missing, cross-tenant, unavailable, destroyed, or other-kind artifacts use the same neutral 404; storage coordinates never leave the service.", "operationId": "MerchantNativeAgreementController_grantArtifact", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Authorize a short-lived executed PDF or certificate download.", "tags": [ "merchant-agreements" ] } }, "/api/v1/customer/account/agreements": { "get": { "description": "Ownership comes only from the authenticated customer session and active tenant. The response never exposes raw action authority, recipient email, private audit evidence, storage coordinates, or merchant-only metadata.", "operationId": "CustomerNativeAgreementController_list", "parameters": [ { "name": "state", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "ISSUED", "IN_PROGRESS", "EXECUTED", "DECLINED", "EXPIRED", "VOIDED", "REPLACED" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's native agreements.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreements/{executionId}": { "get": { "description": "Unknown, cross-tenant, and another customer’s execution return the same neutral 404.", "operationId": "CustomerNativeAgreementController_get", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read one native agreement owned by the signed-in customer.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreements/{executionId}/presentation": { "post": { "description": "Creates an immutable shown event bound to this customer, participant, revision/content digest, and disclosure identity/version/digest. A later Sign call must name this exact presentation event; server-observed request evidence is retained with the resulting assent.", "operationId": "CustomerNativeAgreementController_present", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementPresentationResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Present exact immutable terms to the signed-in customer.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreements/{executionId}/sign": { "post": { "description": "Requires true agreement and disclosure acceptance, typed signer identity, and the exact presentation/revision/digests. Wrong customer, tenant, participant, stale presentation, changed terms, or changed disclosure fail without revealing which check failed.", "operationId": "CustomerNativeAgreementController_sign", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Sign after exact presentation and explicit affirmative assent.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreements/{executionId}/decline": { "post": { "description": "Records a forward-only decline and revokes live action authority. Decline does not cancel, refund, authorize, or otherwise mutate payment, booking, commerce, or fulfillment state.", "operationId": "CustomerNativeAgreementController_decline", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Decline an owned native agreement request.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/account/agreements/{executionId}/artifacts/{artifactId}/download": { "post": { "description": "Only retained safe execution artifacts belonging to an owned agreement are eligible. Unknown, cross-tenant, another customer’s, unavailable, destroyed, or wrong-kind artifacts return the same neutral 404.", "operationId": "CustomerNativeAgreementController_grantArtifact", "parameters": [ { "name": "executionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Authorize an owned executed PDF or certificate download.", "tags": [ "customer-agreements" ] } }, "/api/v1/customer/agreement-actions/{token}": { "get": { "description": "Pure read: does not consume the token or record disclosure shown. The response is a whitelist without the token, recipient email, audit IP/user-agent evidence, private actor ids, or storage coordinates.", "operationId": "ActionNativeAgreementController_get", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Raw `a`-family native-agreement participant action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Preview one participant-scoped native agreement action.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/context": { "get": { "description": "Requires the same participant-scoped token as the agreement preview. Booking-group context comes from the immutable subject member snapshot and exposes only a non-authorizing public reference; raw intent, customer ids, internal group/member ids, and payment capabilities are excluded.", "operationId": "ActionNativeAgreementController_context", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAgreementActionContextResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read customer-safe subject context for a native agreement action.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/presentation": { "post": { "description": "Persists an immutable shown event bound to the token recipient, participant, exact revision/content digest, and exact disclosure identity/version/digest. Server-observed request evidence is retained with the resulting assent; the action remains unconsumed until a successful terminal participant action.", "operationId": "ActionNativeAgreementController_present", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementPresentationResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Present the exact agreement and disclosure for this action.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/sign": { "post": { "description": "Requires the exact presentation event, revision and disclosure digests, explicit true agreement/disclosure acceptance, and typed signer identity. Successful completion consumes this authority idempotently; stale or mismatched authority fails neutrally.", "operationId": "ActionNativeAgreementController_sign", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Sign through exact participant-scoped action authority.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/decline": { "post": { "description": "Records a forward-only decline and consumes the action authority idempotently. It never cancels or refunds payment and never rewinds booking, commerce, or fulfillment state.", "operationId": "ActionNativeAgreementController_decline", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineNativeAgreementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Decline through participant-scoped action authority.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/artifacts/{artifactId}/download": { "post": { "description": "The action token must still authorize the exact participant/execution and the artifact must be retained and safe. A successfully consumed token may read its exact completed result until expiry/revocation; unknown, expired, revoked, wrong-target, cross-tenant, unavailable, destroyed, or wrong-kind cases return the same neutral 404.", "operationId": "ActionNativeAgreementController_grantArtifact", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "artifactId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeAgreementArtifactGrantResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Authorize a scoped executed PDF or certificate download.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/public/customer/auth/request-link": { "post": { "description": "Sends a one-click sign-in link (and a fallback OTP) to the email if it belongs to a customer of this tenant. Always returns a neutral 200 — the response never reveals whether an account exists. Throttled per-email and per-IP. An optional account-local return target may be carried into the emailed magic link after server-side validation.", "operationId": "PublicCustomerAuthController_requestLink", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLinkDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestChallengeResponseDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a passwordless magic-link login email.", "tags": [ "public-customer-auth" ] } }, "/api/v1/public/customer/auth/request-otp": { "post": { "description": "Identical neutral, throttled issuance to request-link: the email always carries BOTH the magic link and the numeric OTP. The only difference is a shorter challenge TTL. Always returns a neutral 200. An optional account-local return target may be carried into the emailed magic link after server-side validation.", "operationId": "PublicCustomerAuthController_requestOtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLinkDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestChallengeResponseDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a passwordless one-time-code login email.", "tags": [ "public-customer-auth" ] } }, "/api/v1/public/customer/auth/verify": { "post": { "description": "Accepts `{ token }` (magic link) OR `{ email, code }` (OTP). On success mints a FRESH session: sets an httpOnly Secure cookie (hosted litecheckout) AND returns a bearer token in the body (BYO frontends). Proof consumption, the eligible Customer claim, and session issuance commit atomically (E28, `DR-3340-08-C`). The session enforces a 6-hour idle / 24-hour absolute window by default; `persistSession: true` — an affirmative \"keep me signed in\" choice — mints 30-day idle / 365-day absolute windows instead (`DR-3340-10-C`). Any failure is a neutral 401.", "operationId": "PublicCustomerAuthController_verify", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDto" } } } }, "responses": { "200": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySessionResponseDto" } } } }, "401": { "description": "Invalid or expired challenge (neutral — cause not disclosed).", "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Verify a magic-link token or OTP and start a session.", "tags": [ "public-customer-auth" ] } }, "/api/v1/public/customer/auth/order-recovery/request-link": { "post": { "operationId": "OrderRecoveryController_requestLink", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRecoveryRequestDto" } } } }, "responses": { "202": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRecoveryRequestResponseDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a neutral Order-recovery sign-in link.", "tags": [ "public-customer-auth" ] } }, "/api/v1/public/customer/auth/order-recovery/request-otp": { "post": { "operationId": "OrderRecoveryController_requestOtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRecoveryRequestDto" } } } }, "responses": { "202": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRecoveryRequestResponseDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Response varies only by trusted tenant selection.", "schema": { "type": "string", "example": "x-organization-slug" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a neutral Order-recovery one-time code.", "tags": [ "public-customer-auth" ] } }, "/api/v1/customer/auth/logout": { "post": { "description": "Revokes the session presented via cookie or bearer and clears the hosted session cookie. Idempotent. Tenant-scoped — a session can only be revoked within its own organization.", "operationId": "CustomerAuthController_logout", "parameters": [], "responses": { "204": { "description": "Session revoked (or already gone)." }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Revoke the current customer session (logout).", "tags": [ "customer-auth" ] } }, "/api/v1/public/booking-services": { "get": { "description": "Tenant-scoped, bounded keyset list. Draft, archived, and foreign-tenant services are never returned. Responses carry evaluated pricing context and are served with Cache-Control: private, no-store (ADR-043).", "operationId": "PublicBookingAvailabilityController_listServices", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 24, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingServiceListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List ACTIVE public booking services.", "tags": [ "public-booking-availability" ] } }, "/api/v1/public/booking-services/{slug}": { "get": { "description": "Unknown, draft, archived, and cross-tenant slugs are the same neutral 404. Responses carry evaluated pricing context and are served with Cache-Control: private, no-store (ADR-043).", "operationId": "PublicBookingAvailabilityController_getService", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingServiceDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch an ACTIVE booking service by slug.", "tags": [ "public-booking-availability" ] } }, "/api/v1/public/booking-availability/search": { "post": { "description": "Derives candidates from recurring service/resource rules, then subtracts blackouts, live holds, and capacity-holding bookings. Slots are generated on demand and are not durable claims; create a hold before checkout. An unpriceable requested duration is a distinct 400 PRICING_POLICY_INCOMPATIBLE pricing failure (reason DURATION_OUTSIDE_POLICY carries maxElapsedMinutes recovery), never presented as unavailable inventory. Served with Cache-Control: private, no-store (ADR-043).", "operationId": "PublicBookingAvailabilityController_search", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingAvailabilitySearchDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingAvailabilityResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Generate currently available booking slots.", "tags": [ "public-booking-availability" ] } }, "/api/v1/public/booking-holds": { "post": { "description": "Validates pickup/delivery server-side (including transient geocoding and an inclusive radius-band match), then rechecks delivery configuration and the exact window under deterministic locks before creating a durable 30-minute hold. The response carries the frozen delivery selection plus serverTime and expiresInSeconds; checkout reuses that snapshot instead of repricing the route. Pricing failures are typed no-quote 400s (PRICING_POLICY_INCOMPATIBLE with a reason code; DURATION_OUTSIDE_POLICY carries maxElapsedMinutes recovery) evaluated before any capacity write, so a failed quote never consumes a hold. A contended tenant configuration fence returns retryable 409 BOOKING_CONFIGURATION_BUSY. Served with Cache-Control: private, no-store (ADR-043).", "operationId": "PublicBookingAvailabilityController_createHold", "parameters": [ { "name": "x-idempotency-key", "in": "header", "description": "8-255 character caller-generated key. Same key + same canonical intent replays the original hold; a different intent returns 409.", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicBookingHoldDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingHoldResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Transactionally claim temporary booking capacity.", "tags": [ "public-booking-availability" ] } }, "/api/v1/public/booking-holds/{id}": { "delete": { "description": "Idempotent for cancelled/expired holds. Unknown, cross-tenant, and wrong-key holds are the same neutral 404; consumed holds return 409.", "operationId": "PublicBookingAvailabilityController_releaseHold", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } }, { "name": "x-idempotency-key", "in": "header", "description": "The same caller-generated key used to create the hold. Retain it as a possession check; it is not a substitute for customer authentication.", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } ], "responses": { "204": { "description": "Released or already terminal." }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Release a temporary booking hold early.", "tags": [ "public-booking-availability" ] } }, "/api/v1/merchant/booking-delivery/config": { "get": { "description": "Returns the merchant-entered origin, provider place id, verification timestamp, revision, and ordered integer-meter/integer-cent radius bands. A tenant with no saved setup receives a stable disabled empty state.", "operationId": "MerchantBookingDeliveryController_getConfiguration", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDeliveryConfigurationResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active tenant's booking-delivery origin and radius bands.", "tags": [ "merchant-booking-delivery" ] }, "put": { "description": "Atomically replaces the merchant origin and full ordered radius-band set. The origin is geocoded server-side with the tenant-owned credential; coordinates are transient and only the merchant input plus provider place id are stored. Bands must have strictly increasing meter bounds. A disabled null-origin/empty-band payload clears setup without calling the provider.", "operationId": "MerchantBookingDeliveryController_replaceConfiguration", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingDeliveryConfigurationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDeliveryConfigurationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace booking-delivery setup (bookings operations permission required).", "tags": [ "merchant-booking-delivery" ] } }, "/api/v1/merchant/booking-delivery/provider": { "get": { "description": "Owner/Admin-only masked read. The API key is write-only and never returned; this response carries only its last-four fingerprint and connection health timestamps.", "operationId": "MerchantBookingDeliveryController_getProviderStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGeocodingProviderStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active tenant's Google geocoding connection status.", "tags": [ "merchant-booking-delivery" ] }, "put": { "description": "Owner/Admin-only reasoned high-risk action. The key is checked against Google live before encrypted storage. It is write-only and never appears in logs, audit metadata, or responses.", "operationId": "MerchantBookingDeliveryController_connectProvider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectBookingGeocodingProviderDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGeocodingProviderStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Connect or replace the tenant's Google Geocoding API key.", "tags": [ "merchant-booking-delivery" ] } }, "/api/v1/merchant/booking-delivery/provider/test": { "post": { "description": "Returns HTTP 200 with a coarse, sanitized result. Provider/cipher failures never expose the key, address, or provider response body.", "operationId": "MerchantBookingDeliveryController_testProvider", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestBookingGeocodingProviderResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Live-test the stored Google geocoding credential.", "tags": [ "merchant-booking-delivery" ] } }, "/api/v1/merchant/booking-delivery/provider/disconnect": { "post": { "description": "Owner/Admin-only reasoned high-risk action. Hard-deletes the encrypted credential; saved delivery setup remains but cannot be used until a credential is reconnected.", "operationId": "MerchantBookingDeliveryController_disconnectProvider", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGeocodingProviderStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Disconnect the tenant's Google geocoding credential.", "tags": [ "merchant-booking-delivery" ] } }, "/api/v1/merchant/checkout/sessions": { "get": { "description": "Newest sessions first. Supports status, email, limit, and cursor filters for support workbench triage. Returns a latest payment-attempt summary, but no raw processor payload.", "operationId": "MerchantCheckoutSupportController_listCheckoutSessions", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of rows to return.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Currently the row id.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ] } }, { "name": "customerEmail", "required": false, "in": "query", "description": "Case-insensitive customer email contains filter, scoped inside the active org.", "schema": { "maxLength": 320, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMerchantCheckoutSessionsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List checkout sessions for the active org.", "tags": [ "merchant-checkout-support" ] } }, "/api/v1/merchant/checkout/sessions/{id}": { "get": { "description": "Returns the tenant-scoped checkout session detail, repriced lines, session lifecycle events, payment attempts, and processor event summaries. Raw processor webhook payloads are intentionally omitted.", "operationId": "MerchantCheckoutSupportController_getCheckoutSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSupportSessionDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Inspect a checkout session with support timeline.", "tags": [ "merchant-checkout-support" ] } }, "/api/v1/merchant/payments": { "get": { "description": "Newest payment attempts first. Supports status, kind, checkoutSessionId, limit, and cursor filters. Includes the related checkout session summary and recent processor event summaries for support triage.", "operationId": "MerchantCheckoutSupportController_listPayments", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of rows to return.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Currently the row id.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "REQUIRES_PAYMENT_METHOD", "REQUIRES_ACTION", "PROCESSING", "REQUIRES_CAPTURE", "SUCCEEDED", "FAILED", "CANCELLED" ] } }, { "name": "kind", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PAYMENT", "AUTHORIZATION", "SETUP", "REFUND" ] } }, { "name": "checkoutSessionId", "required": false, "in": "query", "description": "Filter payment attempts to a specific checkout session id.", "schema": { "maxLength": 100, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMerchantPaymentsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List checkout payment attempts for the active org.", "tags": [ "merchant-checkout-support" ] } }, "/api/v1/customer/checkout/sessions/{token}": { "get": { "description": "Returns the normal checkout session summary. Captured customer contact and shipping address are populated only when the signed-in customer matches the session's captured email; otherwise those fields are null.", "operationId": "CustomerCheckoutSessionController_getSession", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "Session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read a checkout session as the authenticated customer.", "tags": [ "customer-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/payment-session": { "post": { "description": "Resolves the binding CheckoutSession by its opaque token, creates a PaymentAttempt + a Stripe PaymentIntent for the server-authoritative charge-now amount (the session `amountDueNowInCents` — the full total for a cart / full payment, the smaller deposit for a booking deposit), and returns the client secret for the Payment Element. For an ordinary one-time checkout, payment-session replay identity is the current binding semantic digest and payment generation, not the charge-now amount alone: re-calling while both remain current reuses the same healthy intent, and an exact semantic bind replay preserves that intent and generation. Any semantic bind change — even when the charge-now amount is unchanged — invalidates every linked prepared PaymentIntent. All linked prepared intents, if any, must be provider-proven canceled before bind commits; an attempt-free semantic change can advance without provider I/O. Once that gate succeeds, bind advances the generation and the client must request a fresh payment session and client secret. The service also re-evaluates the current checkout email before issuing or reusing an intent. If that email currently belongs to a verified customer, the request must carry a live CustomerSession for the same organization and normalized email. BYO and cross-origin hosted clients supply it as bearer authority; a cookie scoped to another hosted origin does not cross to this API. An earlier identity `proceed` result does not grant payment authority. For an ordinary checkout already in `PENDING_PAYMENT`, a live successor CustomerSession may replace an effectively expired or revoked frozen session only when organization, normalized email, identity version, and Customer all match. A missing or still-live predecessor remains behind the neutral identity fence without payment mutation. The server first fences the exact old payment generation and provider-proves every linked intent canceled; processing, requires-capture, succeeded, ambiguous, or contended money does not rotate identity or create a new generation. A successful transition preserves the checkout/commercial snapshot and immutable old PaymentAttempt identity, advances the payment generation, and continues this same request against the successor session. Booking and booking-group handoffs retain their separately scoped authorization, due-now amount, and replay contracts. The client secret is never persisted.", "operationId": "PublicCheckoutPaymentController_createPaymentSession", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSessionResponseDto" } } } }, "400": { "description": "Session total is not yet binding (bind first), the bound amount must use `confirm-free`, or an ordinary one-time checkout lacks a current complete canonical billing address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "Session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The booking delivery snapshot is not ready for payment, or the checkout session is already paid because the existing PaymentIntent succeeded, or the current verified checkout email lacks a live matching CustomerSession. `CHECKOUT_ALREADY_PAID` means the linked PaymentIntent has succeeded, including an idempotent create replay. No client secret is returned. Discard payment controls and poll `GET /public/checkout/sessions/{token}` for authoritative confirmation, even while its status remains OPEN or PENDING_PAYMENT. Present payment received / order finalizing; do not prepare, submit, or invite another payment. If bounded polling is exhausted, retain that posture and offer a non-payment recheck or support path. Only authoritative CONFIRMED state establishes the order outcome; this response does not create an order or replace webhook/reconciliation authority. A generic 409 or RESOURCE_CONFLICT does not establish that payment succeeded. `CHECKOUT_IDENTITY_VERIFICATION_REQUIRED` requires that live matching session; `CHECKOUT_IDENTITY_CHANGED` requires refresh and a new bind unless the server can prove the bounded same-customer successor transition described above. Prepared-payment conflicts remain fail-closed and issue no new payment session.\n\n`CHECKOUT_PREPARED_PAYMENT_CONFLICT`: the requested checkout mutation was not persisted. This does not guarantee that the previous prepared PaymentIntent remains usable; discard any held client secret. Branch on the scalar `details.reason`. `PREPARED_PAYMENT_SESSION_MOVED` and `PREPARED_PAYMENT_CANCEL_CONTENDED` can each represent either permanent legacy NULL-digest quarantine or a current lineage whose generation was already invalidated/admitted or moved concurrently. The envelope exposes neither digest nor generation and adds no discriminator, detail field, or reason. For either value, refresh and follow current state and discard any prior secret. If refreshed state is CONFIRMED, render/follow the durable completed order or status; do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon the session and start a new checkout. If it is active, follow the current binding and server-bound zero-vs-positive path: re-bind only if needed, retry `confirm-free` for zero, or request `payment-session` for positive, with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard any prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope. `PREPARED_PAYMENT_LINKAGE_CONTENDED` means refresh checkout state, bind if needed, and follow the server-bound zero-vs-positive path; `PREPARED_PAYMENT_LINKAGE_CONVERGED` is a benign concurrent convergence and means retry the matching completion flow after refresh; `PREPARED_PAYMENT_IN_FLIGHT` means freeze editing and wait for payment status; `PREPARED_PAYMENT_CANCEL_AMBIGUOUS` means refresh state and retry the checkout operation. The scalar `details.preparedPaymentReleased` is a boolean and is true only when cancellation of the exact PaymentIntent was confirmed by the payment provider. False means release was not proven; on the zero-total `confirm-free` compatibility path, it can also mean no PaymentIntent existed for that operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "sessionMoved": { "summary": "Session moved during checkout completion", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed during completion. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_SESSION_MOVED", "preparedPaymentReleased": false } } }, "linkageContended": { "summary": "Prepared-payment linkage was contended", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while completion was in progress. Refresh checkout state, bind if needed, then retry confirm-free for a zero total or request payment-session for a positive total.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONTENDED", "preparedPaymentReleased": false } } }, "linkageConverged": { "summary": "Concurrent preparation converged safely", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "Another completion attempt for this checkout already converged safely. Refresh checkout state and retry the matching completion flow.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONVERGED", "preparedPaymentReleased": false } } }, "paymentInFlight": { "summary": "Payment is already in flight", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "A payment for this checkout is already being processed, so the total cannot change. Wait for it to complete before editing.", "details": { "reason": "PREPARED_PAYMENT_IN_FLIGHT", "preparedPaymentReleased": false } } }, "cancellationAmbiguous": { "summary": "Prepared-payment cancellation was not proven", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "We could not release the payment already prepared for this checkout. Refresh and try again.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_AMBIGUOUS", "preparedPaymentReleased": false } } }, "cancellationContended": { "summary": "Prepared-payment cancellation lost a linkage race", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while its prepared payment was being released. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_CONTENDED", "preparedPaymentReleased": false } } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "Payment processor unavailable / not configured, or the persisted PaymentIntent is in an unusable state (e.g. amount/currency mismatch with the binding total, or an unhandled status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Ordinary one-time checkout activation is temporarily unavailable. No PaymentAttempt or provider operation was started; retry after the service becomes ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "summary": "Create or refresh the Stripe payment session for a checkout.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions": { "post": { "description": "Runs an initial server-authoritative reprice over the submitted cart and persists the session + repriced lines + totals + discount snapshot. Returns the RAW token exactly once (store it client-side; the server keeps only its hash) plus the repriced summary. `isBinding` is false — call bind before requesting a payment session. Before persisting, checks server-resolved SALE quantities against catalog stock, including expanded package components. This read reserves nothing and is not a stock guarantee: confirmation remains authoritative and callers must handle every checkout error path.", "operationId": "PublicCheckoutSessionController_createSession", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionResponseDto" } } } }, "400": { "description": "A line references a non-purchasable item/variant. An item that becomes inactive, archived or missing between repricing and admission returns VALIDATION_FAILED with details: {field: \"lines\", itemId, variantId}. At admission, a selected SALE variant that is no longer live on its item returns VALIDATION_FAILED with details: {field: \"lines.variantId\", itemId, variantId}. Both catalog refusals have no stock reason or counts. An item-level SALE target with any variant history returns VALIDATION_FAILED with details.reason: ITEM_LEVEL_INVENTORY_REQUIRES_NO_VARIANTS and field: \"lines.variantId\" at either repricing or admission; select an exact variant. These are catalog validation errors, not INSUFFICIENT_INVENTORY shortfalls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "A line references an item sold through booking availability; choose a booking window before checkout. A measured SALE stock shortfall also returns RESOURCE_CONFLICT with details.reason: INSUFFICIENT_INVENTORY and details.lines[] naming every offending exact item/variant target. Each entry has {itemId, variantId, name, requested?, available?}, the same per-line shape as confirm-free details.line. Repeated targets are grouped: requested is their summed quantity and name joins their names. Counts are published only together and only when requested > available; absent counts never mean zero. Missing inventory rows, ambiguous duplicate rows, and malformed stock evidence cannot establish a shortfall and do not cause this refusal. A null variantId means the item-level target, allowed only for an item with no variant history (including archived variants); invalid catalog targets remain 400 validation errors. No session is created on refusal: correct the quantity in the originating storefront and submit create again. This check applies regardless of reserveDuringCheckout, creates no hold, and does not change token resume or confirmation authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "insufficientInventory": { "summary": "Correct the short quantities before creating a checkout", "value": { "code": "RESOURCE_CONFLICT", "message": "Items in this checkout are no longer available", "details": { "reason": "INSUFFICIENT_INVENTORY", "lines": [ { "itemId": "2f0d9a6c-6e2f-4a71-9a63-0f2f1a5b7c31", "variantId": null, "name": "Facial Serum Unscented 30ml", "requested": 2, "available": 1 }, { "itemId": "a0d1cb48-dd2e-408f-9b45-b6fd767e75bc", "variantId": "1f60dcbb-db69-4527-83d9-dc49a2ddfa1a", "name": "Hand Cream — Unscented", "requested": 1, "available": 0 } ] } } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Create a checkout session (mints the opaque session token).", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/reprice": { "post": { "description": "Recomputes lines + totals + discount snapshot from the submitted cart and persists them. `isBinding` stays false — this is a mutable estimate, not a commitment.\n\nA reprice never rejects the shipping selection: an unresolvable `shippingRateId` (stale/rotated live rate, destination change, subtotal floor) degrades the preview to no shipping (`200`, shipping dropped) and the refreshed `availableShippingOptions` re-drive selection. Only **bind** rejects it (`400` with a stable `details.reason`) — a preview will NOT reveal a dead selection, so drive recovery from the bind failure.", "operationId": "PublicCheckoutSessionController_reprice", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepriceCheckoutSessionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "Session not found, expired, or not OPEN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "A line references an item sold through booking availability; choose a booking window before checkout.\n\n`CHECKOUT_PREPARED_PAYMENT_CONFLICT`: the requested checkout mutation was not persisted. This does not guarantee that the previous prepared PaymentIntent remains usable; discard any held client secret. Branch on the scalar `details.reason`. `PREPARED_PAYMENT_SESSION_MOVED` and `PREPARED_PAYMENT_CANCEL_CONTENDED` can each represent either permanent legacy NULL-digest quarantine or a current lineage whose generation was already invalidated/admitted or moved concurrently. The envelope exposes neither digest nor generation and adds no discriminator, detail field, or reason. For either value, refresh and follow current state and discard any prior secret. If refreshed state is CONFIRMED, render/follow the durable completed order or status; do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon the session and start a new checkout. If it is active, follow the current binding and server-bound zero-vs-positive path: re-bind only if needed, retry `confirm-free` for zero, or request `payment-session` for positive, with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard any prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope. `PREPARED_PAYMENT_LINKAGE_CONTENDED` means refresh checkout state, bind if needed, and follow the server-bound zero-vs-positive path; `PREPARED_PAYMENT_LINKAGE_CONVERGED` is a benign concurrent convergence and means retry the matching completion flow after refresh; `PREPARED_PAYMENT_IN_FLIGHT` means freeze editing and wait for payment status; `PREPARED_PAYMENT_CANCEL_AMBIGUOUS` means refresh state and retry the checkout operation. The scalar `details.preparedPaymentReleased` is a boolean and is true only when cancellation of the exact PaymentIntent was confirmed by the payment provider. False means release was not proven; on the zero-total `confirm-free` compatibility path, it can also mean no PaymentIntent existed for that operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "sessionMoved": { "summary": "Session moved during checkout completion", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed during completion. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_SESSION_MOVED", "preparedPaymentReleased": false } } }, "linkageContended": { "summary": "Prepared-payment linkage was contended", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while completion was in progress. Refresh checkout state, bind if needed, then retry confirm-free for a zero total or request payment-session for a positive total.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONTENDED", "preparedPaymentReleased": false } } }, "linkageConverged": { "summary": "Concurrent preparation converged safely", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "Another completion attempt for this checkout already converged safely. Refresh checkout state and retry the matching completion flow.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONVERGED", "preparedPaymentReleased": false } } }, "paymentInFlight": { "summary": "Payment is already in flight", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "A payment for this checkout is already being processed, so the total cannot change. Wait for it to complete before editing.", "details": { "reason": "PREPARED_PAYMENT_IN_FLIGHT", "preparedPaymentReleased": false } } }, "cancellationAmbiguous": { "summary": "Prepared-payment cancellation was not proven", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "We could not release the payment already prepared for this checkout. Refresh and try again.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_AMBIGUOUS", "preparedPaymentReleased": false } } }, "cancellationContended": { "summary": "Prepared-payment cancellation lost a linkage race", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while its prepared payment was being released. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_CONTENDED", "preparedPaymentReleased": false } } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "Ordinary one-time checkout activation is temporarily unavailable. No checkout mutation or provider operation was started; retry after the service becomes ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Reprice a checkout session (cart/coupon changed).", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/bind": { "post": { "description": "Re-reprices the submitted cart server-side and locks the result as binding (`isBinding = true`) so the total reflects live prices at the moment of commitment. `status` stays OPEN. This is the step #604 depends on — a payment session can only be created once bound.\n\nUnlike create/reprice, bind is the pay step, so `customer` is REQUIRED here and `customer.name` must be non-blank: a CONFIRMED order must carry a real customer name (#741). A non-blank `customer.email` is likewise required before payment (#605). Either may have been supplied at create or an earlier reprice; a bind that would commit without a usable name or email is rejected with a `400`. When the tenant public config reports `phoneRequired: true`, the same effective-value rule applies to `customer.phone` for ordinary cart checkout; omission is rejected with a field-keyed `400`. Subscription and booking checkout are excluded.\n\nFor an ordinary one-time checkout, the binding semantic identity covers normalized line identity, variant, quantity, and pricing references; discount attribution and snapshot; recipient and fulfillment/tax address facts; shipping method/rate/package basis; tax basis and snapshot; amount; and currency. An exact semantic bind replay preserves a healthy prepared PaymentIntent and its payment generation. Any semantic change — even when the total is equal — invalidates every linked prepared PaymentIntent. All linked prepared intents, if any, must be provider-proven canceled before the new bind commits; an attempt-free semantic change can advance without provider I/O. Once that gate succeeds, the bind advances the generation and requires a fresh payment-session/client secret. If the effective checkout email currently belongs to a verified customer, bind also requires a live CustomerSession for that same organization and normalized email. BYO and cross-origin hosted clients supply it as bearer authority; only a client on the API origin can send the API-scoped `__Host-` cookie, because a cookie scoped to another hosted origin never crosses to this API. Checkout remains guest-capable for an unverified email, and an earlier identity `proceed` result never waives this live re-check. An ambiguous or contended release returns `CHECKOUT_PREPARED_PAYMENT_CONFLICT` without persisting the requested bind.\n\nAfter the current binding lineage is verified under the session lock, bind rechecks server-repriced SALE/component stock before persistence. A measured shortfall returns RESOURCE_CONFLICT / INSUFFICIENT_INVENTORY with details.lines[] in the create-time shape. The session stays OPEN and re-bindable: correct the quantity or retry after stock is replenished. Every bind request, including an exact semantic replay, rechecks stock. A refused exact replay preserves the existing binding and any prepared PaymentIntent; it does not cancel that payment or refresh the session TTL. A semantic correction still requires the cancellation proof described above. Missing inventory is not zero, and this advisory read creates no hold. Confirmation remains authoritative.", "operationId": "PublicCheckoutSessionController_bind", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindCheckoutSessionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "400": { "description": "Shipping rejection (`code: BAD_REQUEST` with a scalar `details.reason`) — bind is the commitment, so an unresolvable shipping selection fails here and ONLY here: the same causes silently degrade a reprice to no shipping (`200`, shipping dropped) so a preview never reveals them. Branch on `details.reason`, never on `message`: `SHIPPING_RATE_NOT_QUOTABLE` (the selected rate cannot be re-quoted — for live carrier rates the quote-scoped `rateId` may simply have rotated past its quote), `SHIPPING_RATE_NOT_APPLICABLE_TO_DESTINATION` (no active zone serves the captured destination), `SHIPPING_RATE_BELOW_SUBTOTAL_MINIMUM` (the cart no longer meets the rate's configured minimum), and `SHIPPING_DELIVERY_PROMISE_UNAVAILABLE` (the selected delivery promise can no longer be presented) all share one recovery: re-quote via reprice, replace the entire option set from `availableShippingOptions`, require the shopper to explicitly reconfirm a delivery method from the fresh set (never auto-restore a prior selection by label and never bind an unconfirmed substitute), then bind again. `SHIPPING_ADDRESS_REQUIRED` (a rate was selected before any shipping/billing address) and `SHIPPING_ADDRESS_INVALID` (carriers rejected the address) instead require the shopper to complete or correct the address before re-quoting.\n\nValidation failed (e.g. missing/blank `customer.name`), or the effective customer name / email is still blank, the effective customer phone is blank when the tenant requires it. Every ordinary one-time checkout also requires a complete canonical billing address (`billingAddress`) before binding, regardless of tax-provider configuration; a fulfillment-required cart must also satisfy its shipping-address and shipping-method rules. Catalog-target refusals remain VALIDATION_FAILED without stock counts: a missing, inactive or archived item identifies lines; an unavailable selected SALE variant identifies lines.variantId. An item-level SALE target with any variant history identifies lines.variantId with ITEM_LEVEL_INVENTORY_REQUIRES_NO_VARIANTS. These validation errors must not render a numeric shortfall sentence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "rateNotQuotable": { "summary": "Selected rate can no longer be quoted", "value": { "code": "BAD_REQUEST", "message": "the selected shipping rate is not available", "details": { "reason": "SHIPPING_RATE_NOT_QUOTABLE" } } }, "rateNotQuotableProviderOutage": { "summary": "Live quotes unavailable while a selection was supplied", "value": { "code": "BAD_REQUEST", "message": "live shipping rates are temporarily unavailable — please double-check the delivery address or try again in a moment", "details": { "reason": "SHIPPING_RATE_NOT_QUOTABLE" } } }, "rateNotQuotableExcludedByPresentation": { "summary": "Every quoted service excluded while a selection was supplied", "value": { "code": "BAD_REQUEST", "message": "no shipping methods are currently available for this destination — please contact the store", "details": { "reason": "SHIPPING_RATE_NOT_QUOTABLE" } } }, "rateNotQuotableShippingUnconfigured": { "summary": "Shipping zones deactivated while a selection was supplied", "value": { "code": "BAD_REQUEST", "message": "this order requires shipping, but the store has not set up shipping yet", "details": { "reason": "SHIPPING_RATE_NOT_QUOTABLE" } } }, "rateNotApplicableToDestination": { "summary": "Selected rate does not serve this destination", "value": { "code": "BAD_REQUEST", "message": "the selected shipping rate is not available for this destination", "details": { "reason": "SHIPPING_RATE_NOT_APPLICABLE_TO_DESTINATION" } } }, "rateNotApplicableUnservedDestination": { "summary": "No active zone serves the destination while a selection was supplied", "value": { "code": "BAD_REQUEST", "message": "we do not ship to the selected destination", "details": { "reason": "SHIPPING_RATE_NOT_APPLICABLE_TO_DESTINATION" } } }, "rateBelowSubtotalMinimum": { "summary": "Cart fell below the selected rate's minimum", "value": { "code": "BAD_REQUEST", "message": "the selected shipping rate is not available for this order subtotal", "details": { "reason": "SHIPPING_RATE_BELOW_SUBTOTAL_MINIMUM" } } }, "deliveryPromiseUnavailable": { "summary": "Selected delivery promise can no longer be presented", "value": { "code": "BAD_REQUEST", "message": "The selected delivery promise is no longer available.", "details": { "reason": "SHIPPING_DELIVERY_PROMISE_UNAVAILABLE" } } }, "addressRequired": { "summary": "Rate selected before an address exists", "value": { "code": "BAD_REQUEST", "message": "a shipping or billing address is required to apply a shipping rate", "details": { "reason": "SHIPPING_ADDRESS_REQUIRED" } } }, "addressInvalid": { "summary": "Carriers rejected the delivery address", "value": { "code": "BAD_REQUEST", "message": "the delivery address could not be verified — please double-check it and try again", "details": { "reason": "SHIPPING_ADDRESS_INVALID" } } } } } } }, "404": { "description": "Session not found, expired, or not OPEN at initial resolution. A same-lineage session that becomes terminal or expires before the locked write also returns 404; a successor binding detected after resolution returns 409 PREPARED_PAYMENT_SESSION_MOVED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "A line references an item sold through booking availability; choose a booking window before checkout. RESOURCE_CONFLICT with details.reason CHECKOUT_TAX_POLICY_CHANGED requires a fresh bind because the stored tax policy changed during this request. TENANT_TAX_NOT_CONFIGURED means the stored manual tax acknowledgement is invalid, or a stored Stripe Tax policy has a tax base but its connected payment account or Tax settings are incomplete. A fully discounted cart with no charged shipping needs no connected-account Tax calculation, but still requires platform tax availability for stored Stripe Tax. `CHECKOUT_IDENTITY_VERIFICATION_REQUIRED` requires a live CustomerSession matching the current organization and normalized email; `CHECKOUT_IDENTITY_CHANGED` requires refresh and a new bind against the current identity version. A measured SALE stock shortfall returns RESOURCE_CONFLICT with details.reason INSUFFICIENT_INVENTORY and details.lines[] containing every short target: {itemId, variantId, name, requested, available}. Counts are units of the exact item/variant stock target; composed selections use expanded component units, not package quantities. Both counts appear together only for requested > available. The session remains recoverable. A successor binding lineage wins over an obsolete stock result: CHECKOUT_PREPARED_PAYMENT_CONFLICT with PREPARED_PAYMENT_SESSION_MOVED requires refresh and following current state, without a shortfall line or counts. Every bind request, including an exact semantic replay, rechecks stock. A refused exact replay rolls back this request's session, TTL and coupon changes while preserving the existing binding and any prepared PaymentIntent; it does not cancel that payment. A semantic correction still follows the cancellation-proof path and can separately return PREPARED_PAYMENT_CANCEL_AMBIGUOUS or PREPARED_PAYMENT_IN_FLIGHT. Confirmation remains authoritative.\n\n`CHECKOUT_PREPARED_PAYMENT_CONFLICT`: the requested checkout mutation was not persisted. This does not guarantee that the previous prepared PaymentIntent remains usable; discard any held client secret. Branch on the scalar `details.reason`. `PREPARED_PAYMENT_SESSION_MOVED` and `PREPARED_PAYMENT_CANCEL_CONTENDED` can each represent either permanent legacy NULL-digest quarantine or a current lineage whose generation was already invalidated/admitted or moved concurrently. The envelope exposes neither digest nor generation and adds no discriminator, detail field, or reason. For either value, refresh and follow current state and discard any prior secret. If refreshed state is CONFIRMED, render/follow the durable completed order or status; do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon the session and start a new checkout. If it is active, follow the current binding and server-bound zero-vs-positive path: re-bind only if needed, retry `confirm-free` for zero, or request `payment-session` for positive, with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard any prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope. `PREPARED_PAYMENT_LINKAGE_CONTENDED` means refresh checkout state, bind if needed, and follow the server-bound zero-vs-positive path; `PREPARED_PAYMENT_LINKAGE_CONVERGED` is a benign concurrent convergence and means retry the matching completion flow after refresh; `PREPARED_PAYMENT_IN_FLIGHT` means freeze editing and wait for payment status; `PREPARED_PAYMENT_CANCEL_AMBIGUOUS` means refresh state and retry the checkout operation. The scalar `details.preparedPaymentReleased` is a boolean and is true only when cancellation of the exact PaymentIntent was confirmed by the payment provider. False means release was not proven; on the zero-total `confirm-free` compatibility path, it can also mean no PaymentIntent existed for that operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "sessionMoved": { "summary": "Session moved during checkout completion", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed during completion. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_SESSION_MOVED", "preparedPaymentReleased": false } } }, "linkageContended": { "summary": "Prepared-payment linkage was contended", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while completion was in progress. Refresh checkout state, bind if needed, then retry confirm-free for a zero total or request payment-session for a positive total.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONTENDED", "preparedPaymentReleased": false } } }, "linkageConverged": { "summary": "Concurrent preparation converged safely", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "Another completion attempt for this checkout already converged safely. Refresh checkout state and retry the matching completion flow.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONVERGED", "preparedPaymentReleased": false } } }, "paymentInFlight": { "summary": "Payment is already in flight", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "A payment for this checkout is already being processed, so the total cannot change. Wait for it to complete before editing.", "details": { "reason": "PREPARED_PAYMENT_IN_FLIGHT", "preparedPaymentReleased": false } } }, "cancellationAmbiguous": { "summary": "Prepared-payment cancellation was not proven", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "We could not release the payment already prepared for this checkout. Refresh and try again.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_AMBIGUOUS", "preparedPaymentReleased": false } } }, "cancellationContended": { "summary": "Prepared-payment cancellation lost a linkage race", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while its prepared payment was being released. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_CONTENDED", "preparedPaymentReleased": false } } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "Tax provider error (#875). When the tenant has Stripe Tax enabled (ADR-008), an upstream tax-calculation failure during bind surfaces as a 502 — `computeTaxForBind` is fail-closed, so the bind did NOT commit and no total was locked. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when stored taxMode is stripe_tax (including the default persisted by an ordinary Checkout settings save) but the connected tax provider is unavailable; contact litecommerce support. This includes fully discounted carts. No binding total, order or payment is committed. A separate 503 may indicate ordinary one-time checkout activation is temporarily unavailable; in that case no checkout mutation or provider operation was started. Retry after the service becomes ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Bind a checkout session to its authoritative total.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{checkoutToken}/identity/next-action": { "post": { "description": "Evaluates the submitted checkout email for the session identified by the opaque checkout token and returns exactly one of two ordinary outcomes: `verify` when the tenant/email customer is already verified, otherwise `proceed`. Both use this same status and schema; the response never states whether an account exists and carries no customer identifier, verification timestamp, or profile data.\n\nThe email is normalized server-side (trim + lowercase). Repeating a normalization-equivalent email is idempotent and returns the durable cached outcome for the current server-owned identity version; a meaningful change advances that version by one and invalidates the prior server-side continuation. Each new version is admitted through durable per-tenant evaluation windows (5 per 15 minutes per normalized email, 100 per 15 minutes per trusted client IP, reserved atomically); when a window is exhausted the version durably resolves to the ordinary `proceed` — never a throttle-shaped response — and an already evaluated version always keeps its cached outcome.\n\nThe result is a non-authoritative hint that drives the checkout UI: it grants no authentication, payment, account, or account-history authority, and no later checkout step derives authority from this response. Requires the valid current checkout credential; `Origin`, CORS, and headers are not authority.", "operationId": "PublicCheckoutSessionController_identityNextAction", "parameters": [ { "name": "checkoutToken", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutIdentityNextActionRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutIdentityNextActionResponseDto" } } } }, "400": { "description": "Validation failed (missing or malformed `email`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "Session not found, expired, or not OPEN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Resolve the neutral identity next action for the checkout email.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/confirm-free": { "post": { "description": "Completes a *binding* checkout session whose server-computed total cannot be charged, into a CONFIRMED order with no Stripe payment.\n\n**Do not decide between this endpoint and `payment-session` by inspecting the total yourself.** Branch on the bound session summary's `requiresFreeConfirmation` flag: `true` means use this endpoint, `false` means use `POST …/{token}/payment-session`. The threshold is a payment-provider fact that varies by currency and changes on the provider's schedule, so a client-side comparison will drift from the server (#3263).\n\nTwo kinds of total qualify: exactly `0` (e.g. a 100%-off or fixed-amount-≥-subtotal coupon — #873, the free-order path ADR-006 deferred), and a total above `0` but below the provider's per-currency minimum, which the provider rejects and which therefore surfaced as an unactionable `500` before #3263. Both are RE-VERIFIED server-side from the bound session at confirm time: a chargeable total is rejected with a `400` and must pay through `payment-session` instead — a client can never opt a priced cart into a free completion.\n\nBooking, booking-group, and subscription checkouts have no no-charge completion path and are refused here regardless of total; `requiresFreeConfirmation` is always `false` for them.\n\nAt the final atomic gate, the server re-checks current checkout identity authority before creating an order, reserving inventory, redeeming a coupon, or making any terminal mutation. If the effective email is now verified, the request must carry a live CustomerSession for the same organization and normalized email. BYO and cross-origin hosted clients supply it as bearer authority; a cookie scoped to another hosted origin does not cross to this API. An earlier identity `proceed` result does not waive this check.\n\nFor an ordinary one-time checkout already in `PENDING_PAYMENT` and frozen to verified CustomerSession A, an expired or revoked A may be renewed to live successor B only when B matches the same organization, normalized email, identity version, and Customer. The server first admits and fences A's exact payment generation, proves every linked provider object cannot produce successful or ambiguous money, then installs B and advances exactly one generation before the no-charge order gate runs. An attempt-free no-charge generation performs no provider call and creates no PaymentAttempt, PaymentIntent, client secret, or replacement payment money. A missing or still-live predecessor, a wrong-tenant/email/customer successor, or an ambiguous, processing, requires-capture, succeeded, or contended old payment fails closed without rotating identity or creating a no-charge order. If the exact A payment has succeeded, paid finalization remains authoritative and converges on exactly one A-linked order. Concurrent renewal/confirmation retries converge only from the durable confirmed checkout and never let stale A regain authority.\n\nRuns the same confirmation machinery as the webhook-authoritative paid path (atomic exactly-one-order gate, inventory reservation, coupon redemption, confirmation email), so the call is idempotent: repeating it (or racing a duplicate) returns the same CONFIRMED summary and never creates a second order. On success the returned summary is already `status: CONFIRMED` — surfaces should render their confirmed state from it directly (no webhook wait, no polling).\n\nAn ordinary one-time session whose legacy binding has no semantic digest, whose current payment generation is already invalidated, or whose binding lineage moves during the final locked order-link gate fails closed with `CHECKOUT_PREPARED_PAYMENT_CONFLICT`, `details.reason: PREPARED_PAYMENT_SESSION_MOVED`, and `details.preparedPaymentReleased: false`. This request's transaction commits no order, but refresh may reveal that another lineage already confirmed and linked one. The wire envelope exposes neither digest nor generation, so it cannot distinguish permanent legacy quarantine from a current lineage whose generation was already invalidated or moved in a race, and it adds no new discriminator, detail field, or reason. Refresh and follow current state and discard any prior secret. If state is CONFIRMED, render/follow the durable completed order/status and do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon it and start a new checkout. If it is active, follow the current binding and server-bound total: re-bind only if needed, then follow `requiresFreeConfirmation` on the refreshed summary — retry `confirm-free` when it is `true`, or request payment-session when it is `false` — with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively dead/nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard every prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope.", "operationId": "PublicCheckoutSessionController_confirmFree", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "400": { "description": "Session is not yet binding (reprice/bind first), the bound total is chargeable (use the payment session), the session lacks the customer email/name bind normally enforces, or an ordinary one-time checkout lacks a current complete canonical billing address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "Session not found, expired, or in a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`CHECKOUT_IDENTITY_VERIFICATION_REQUIRED` requires a live CustomerSession matching the current organization and normalized email; `CHECKOUT_IDENTITY_CHANGED` requires refresh and a new bind against the current identity version. A bounded verified successor renewal also fails closed when the frozen predecessor is missing or still live, the successor does not exactly match tenant and identity authority, or old-generation money is ambiguous, in flight, successful, or contended; no successor generation or no-charge order is created by this request in those cases, while exact successful A money remains authoritative for paid finalization. Items could not be reserved (no longer available); the session is cancelled and a fresh checkout is required. That arm is published as `RESOURCE_CONFLICT` with `details.reason: INSUFFICIENT_INVENTORY` and a `details.line` naming the offending item (`itemId`, `variantId`, `name`) and, for a measured shortfall, the `requested` and `available` quantities. The engine stops at the FIRST short line, so exactly one line is reported even when several are short. Every `details.line` field is nullable or absent: `itemId`, `variantId` and `name` may each be `null` (the envelope degrades to nulls when the engine's failure details cannot be read, while `details.reason` still classifies it), and `requested`/`available` are OMITTED when the reservation failed for a missing item, a vanished inventory row, or an item-level catalog target that became invalid after variants were added rather than a measured shortfall, so read them defensively. The session is already CANCELLED when this response is returned — it is terminal: a later `confirm-free` or `payment-session` call on the token is the neutral 404, while the session read still returns the CANCELLED summary, and the remedy is a NEW checkout at the corrected quantity, never a retry of this one. `CHECKOUT_PREPARED_PAYMENT_CONFLICT` with `details.reason: PREPARED_PAYMENT_SESSION_MOVED` means the ordinary one-time binding has no trustworthy current semantic lineage; this request's transaction commits no order, while refreshed state may already be CONFIRMED after another lineage won. `details.preparedPaymentReleased` is `false`. The envelope exposes neither digest nor generation and adds no new discriminator, detail field, or reason, so permanent legacy quarantine cannot be distinguished from a current lineage whose generation was already invalidated or moved in a race. Refresh and follow current state and discard any prior secret. If state is CONFIRMED, render/follow the durable completed order/status and do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon it and start a new checkout. If it is active, follow the current binding and server-bound total: re-bind only if needed, retry `confirm-free` for zero, or request payment-session for positive, with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively dead/nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard every prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope.\n\n`CHECKOUT_PREPARED_PAYMENT_CONFLICT`: the requested checkout mutation was not persisted. This does not guarantee that the previous prepared PaymentIntent remains usable; discard any held client secret. Branch on the scalar `details.reason`. `PREPARED_PAYMENT_SESSION_MOVED` and `PREPARED_PAYMENT_CANCEL_CONTENDED` can each represent either permanent legacy NULL-digest quarantine or a current lineage whose generation was already invalidated/admitted or moved concurrently. The envelope exposes neither digest nor generation and adds no discriminator, detail field, or reason. For either value, refresh and follow current state and discard any prior secret. If refreshed state is CONFIRMED, render/follow the durable completed order or status; do not retry or start a new checkout. If it is definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable, abandon the session and start a new checkout. If it is active, follow the current binding and server-bound zero-vs-positive path: re-bind only if needed, retry `confirm-free` for zero, or request `payment-session` for positive, with at most one appropriate retry. If the same conflict persists, refresh once more. Latest CONFIRMED state still wins and must be followed; a latest definitively CANCELLED, EXPIRED, ABANDONED, or otherwise nonpayable state may restart. If latest state remains active, stop automatic retry and automatic restart, discard any prior secret, keep following durable checkout/payment status, and surface a blocked recovery state for explicit safe resolution. Do not infer legacy quarantine from this envelope. `PREPARED_PAYMENT_LINKAGE_CONTENDED` means refresh checkout state, bind if needed, and follow the server-bound zero-vs-positive path; `PREPARED_PAYMENT_LINKAGE_CONVERGED` is a benign concurrent convergence and means retry the matching completion flow after refresh; `PREPARED_PAYMENT_IN_FLIGHT` means freeze editing and wait for payment status; `PREPARED_PAYMENT_CANCEL_AMBIGUOUS` means refresh state and retry the checkout operation. The scalar `details.preparedPaymentReleased` is a boolean and is true only when cancellation of the exact PaymentIntent was confirmed by the payment provider. False means release was not proven; on the zero-total `confirm-free` compatibility path, it can also mean no PaymentIntent existed for that operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "examples": { "sessionMoved": { "summary": "Session moved during checkout completion", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed during completion. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_SESSION_MOVED", "preparedPaymentReleased": false } } }, "insufficientInventory": { "summary": "A line could not be reserved; the session is cancelled", "value": { "code": "RESOURCE_CONFLICT", "message": "Items in this checkout are no longer available", "details": { "reason": "INSUFFICIENT_INVENTORY", "line": { "itemId": "2f0d9a6c-6e2f-4a71-9a63-0f2f1a5b7c31", "variantId": null, "name": "Facial Serum Unscented 30ml", "requested": 2, "available": 1 } } } }, "linkageContended": { "summary": "Prepared-payment linkage was contended", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while completion was in progress. Refresh checkout state, bind if needed, then retry confirm-free for a zero total or request payment-session for a positive total.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONTENDED", "preparedPaymentReleased": false } } }, "linkageConverged": { "summary": "Concurrent preparation converged safely", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "Another completion attempt for this checkout already converged safely. Refresh checkout state and retry the matching completion flow.", "details": { "reason": "PREPARED_PAYMENT_LINKAGE_CONVERGED", "preparedPaymentReleased": false } } }, "paymentInFlight": { "summary": "Payment is already in flight", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "A payment for this checkout is already being processed, so the total cannot change. Wait for it to complete before editing.", "details": { "reason": "PREPARED_PAYMENT_IN_FLIGHT", "preparedPaymentReleased": false } } }, "cancellationAmbiguous": { "summary": "Prepared-payment cancellation was not proven", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "We could not release the payment already prepared for this checkout. Refresh and try again.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_AMBIGUOUS", "preparedPaymentReleased": false } } }, "cancellationContended": { "summary": "Prepared-payment cancellation lost a linkage race", "value": { "code": "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "message": "This checkout changed while its prepared payment was being released. Refresh and follow current checkout status before at most one eligible completion retry.", "details": { "reason": "PREPARED_PAYMENT_CANCEL_CONTENDED", "preparedPaymentReleased": false } } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "Ordinary one-time checkout activation is temporarily unavailable. This request committed no order; retry after the service becomes ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Confirm a checkout whose total cannot be charged — no payment taken.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}": { "get": { "description": "Returns the persisted status, isBinding, lines, totals, discount snapshot, currency, and expiry. Does NOT reprice — a read never mutates the binding total. `expiresAt` (+ `reservationExpiresAt` when a Mode-B hold exists; null under the live Mode A) are the hosted/BYO storefront countdown source. Reading a session whose `expiresAt` has passed terminalizes it to EXPIRED lazily (no cron) and returns the same 404 as any other miss.", "operationId": "PublicCheckoutSessionController_getSession", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "404": { "description": "Session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read a checkout session (for client polling / countdown).", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/account-switch/admit": { "post": { "description": "Only a live verified Account A on the same ordinary one-time PENDING_PAYMENT checkout can admit a switch. The server fences its old payment generation, proves every linked old intent nonchargeable on the exact connected account, and only then returns an admitted unbound epoch. A stalled or ambiguous cancellation remains fenced; do not reuse the old client secret. The client must preserve the original requestId across reloads and retry that same request; a new requestId cannot take over a fenced epoch. An admitted B branch cannot start another email switch. A 409 with reason PREPARED_PAYMENT_SWITCH_REQUEST_MISMATCH means a fenced switch needs its original requestId; PREPARED_PAYMENT_SWITCH_ALREADY_ACTIVE means continue the admitted switch; PREPARED_PAYMENT_SWITCH_ALREADY_USED means a second B switch is unavailable.", "operationId": "PublicCheckoutAccountSwitchController_admit", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccountSwitchAdmitRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccountSwitchAdmissionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Safely release Account A payment before changing checkout email.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/account-switch/{epochId}/identify": { "post": { "description": "Claims exactly one durable branch and evaluates its email through the neutral two-action identity contract at the assigned switch version. RETURN_TO_A requires current verified A authority; SWITCH_TO_B requires the frozen A server session to be stale. The response grants no payment, Customer or account-existence authority. Replaying the same branch/email returns the cached action.", "operationId": "PublicCheckoutAccountSwitchController_identify", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "epochId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccountSwitchBranchRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccountSwitchBranchResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Claim one Account A or different-email B branch after safe release.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/account-switch/{epochId}/reprice": { "post": { "description": "Reprices current lines, coupon and delivery inputs for the latest admitted, claimed PENDING_PAYMENT switch epoch. An initial unbound preview grants no charging authority. On a bound switched checkout, this mutation first cancels the current prepared payment, advances the payment generation and returns the checkout unbound; do not reuse that payment client secret. The ordinary reprice route stays OPEN-only; use the dedicated rebind route after the shopper confirms Contact, Delivery and Billing.", "operationId": "PublicCheckoutAccountSwitchController_reprice", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "epochId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepriceCheckoutSessionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Preview the claimed account-switch branch before rebind.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/account-switch/{epochId}/rebind": { "post": { "description": "Reprices the shopper-supplied current lines, coupon and addresses through the ordinary server-authoritative bind machinery. This PENDING_PAYMENT exception requires the latest admitted, claimed epoch and a current payment/identity generation at or after that epoch's admitted generation floor. It cannot replay A money or bind another physical checkout. After a successful bind, request a fresh payment session; no old client secret survives.", "operationId": "PublicCheckoutAccountSwitchController_rebind", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "epochId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindCheckoutSessionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionSummaryDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Rebind the claimed account-switch branch on this same checkout.", "tags": [ "public-checkout" ] } }, "/api/v1/public/checkout/sessions/{token}/account-switch/{epochId}": { "get": { "description": "Root-locked read of only the latest epoch on this same checkout. A fencing or unsafe old-attempt set reports recoveryRequired and does not issue charging authority.", "operationId": "PublicCheckoutAccountSwitchController_status", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "epochId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccountSwitchStatusResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read the current switch and payment-recovery gate.", "tags": [ "public-checkout" ] } }, "/api/v1/public/subscription-checkouts/{token}/handoff": { "post": { "description": "Resolves the tenant-scoped shared CheckoutSession by its opaque token and safely resumes its existing Billing handoff. PAYMENT refreshes the first-invoice PaymentIntent, SETUP resumes card authorization and can continue Billing creation after setup succeeds, and NONE carries no client confirmation. The request cannot replace checkout input and never confirms fulfillment; invoice.paid plus reconciliation remain authoritative.", "operationId": "PublicSubscriptionCheckoutHandoffController_resume", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCheckoutHandoffResponseDto" } } } }, "404": { "description": "Checkout token not found in this tenant or not a subscription checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The checkout is cancelled, expired, abandoned, awaiting reconciliation, or pinned to a different connected account. Confirmed checkouts return their terminal NONE handoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "Payment processing is unavailable or the subscription handoff cannot be verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Resume a hosted subscription checkout handoff.", "tags": [ "public-subscription-checkout" ] } }, "/api/v1/public/subscription-checkouts": { "post": { "description": "Creates a recurring-aware shared CheckoutSession and connected-account Stripe Billing flow. A tenant-scoped customer session is required so an email address can never select another customer’s saved/default payment context. The response handoff is PAYMENT, SETUP, or NONE. SETUP must be confirmed and this exact request replayed with the same idempotency key. No client callback confirms fulfillment: invoice.paid plus the reconciliation sweep are authoritative.", "operationId": "PublicSubscriptionCheckoutController_start", "parameters": [ { "name": "x-idempotency-key", "in": "header", "description": "Stable key for the complete start/continuation attempt. A card-upfront SETUP is continued by replaying the same body and key after setup succeeds.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionCheckoutDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionCheckoutResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "A selected public plan or price is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The idempotency key was already used for different checkout input, or the selected plans cannot share one subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "A required live shipping quote is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "CustomerSession": [], "OrganizationSlug": [] } ], "summary": "Start or safely continue a public subscription checkout.", "tags": [ "public-subscription-checkout" ] } }, "/api/v1/public/booking-groups/{publicRef}/checkout": { "post": { "description": "Authorizes with the group proof, atomically converts every held member into its booking-linked Sales projection, binds at most one CheckoutSession, freezes the complete member allocation plan, and returns the authoritative aggregate pricing plus any Stripe handoff. Pay-Later groups remain approval-only and never receive a payment handoff; CheckoutSession and hold capabilities are never exposed.", "operationId": "PublicBookingGroupCheckoutController_checkout", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^b[a-z0-9]{25}$" } }, { "name": "x-idempotency-key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "booking-group-resume-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^g[a-z0-9]{25}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPriceConfirmationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupPaymentSessionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_PRICE_CONFIRMATION_REQUIRED returns the typed two-phase confirmation challenge. Other operation-specific conflicts use the canonical API error envelope. TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BookingPriceConfirmationRequiredErrorDto" }, { "$ref": "#/components/schemas/ApiErrorDto" } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "PLATFORM_TAX_UNAVAILABLE when a stored stripe_tax policy requires tax pricing but the connected provider is unavailable or its mode cannot be confirmed. This also blocks free priced commitments. Unpriced draft/request capture, legacy unset policies, and valid audited manual_no_tax retain their existing behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Bind and resume one aggregate booking payment.", "tags": [ "public-booking-groups" ] } }, "/api/v1/public/orders/token/{token}": { "get": { "description": "#606 — the read contract behind the hosted litecheckout `/order/o.../status` page. The `o`-family token (minted with the order-confirmation email, hashed at rest per ADR-007) is the credential; no customer session is required, but the tenant slug is still required and must match the token tenant. Pure read — the token is never consumed and stays valid until it expires. Unknown, expired, revoked, malformed, and cross-tenant tokens are all the same 404, and the projection carries no customer PII and no database ids. #1656: when the current customer-action config selects a distinct trusted BYO origin, `customerActionRedirectUrl` carries the equivalent token route for hosted litecheckout to redirect to; blank, rejected, hosted, or loop-producing config returns `null`.", "operationId": "PublicOrderController_getOrderStatusByToken", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Raw `o`-family order-status token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch the status-safe order projection by opaque `o` token.", "tags": [ "public-orders" ] } }, "/api/v1/public/orders/by-reference/{orderReference}/confirmation": { "get": { "description": "The order reference is only a tenant-scoped locator. Authorization comes from the live x-checkout-session-token header, which must belong to this tenant and be bound to the exact final order. The response never looks up or exposes an order-status capability redirect.", "operationId": "PublicOrderController_getOrderConfirmationByReference", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$" } }, { "name": "x-checkout-session-token", "required": true, "in": "header", "description": "The live tenant-bound checkout-session credential whose final order is being confirmed.", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmationByReferenceDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Tenant and checkout-credential dimensions for this response.", "schema": { "type": "string", "example": "x-organization-slug, x-checkout-session-token" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch the immediate confirmation projection by order reference.", "tags": [ "public-orders" ] } }, "/api/v1/public/orders/number/{num}": { "get": { "deprecated": true, "description": "Deprecated compatibility lookup retained only through ADR-046 evidence-gated retirement. Order numbers are sequential and therefore guessable, so the number alone is not sufficient: the caller must also supply the customer email used at checkout (case-folded match). A wrong/absent email is indistinguishable from an unknown order number (both 404) so the endpoint cannot be used to enumerate which order numbers exist or to confirm the email on a given order. Returns the confirmation-safe projection only.", "operationId": "PublicOrderController_getOrderByNumber", "parameters": [ { "name": "num", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "email", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicOrderDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch an order by order number + the checkout email.", "tags": [ "public-orders" ] } }, "/api/v1/public/orders/{id}": { "get": { "deprecated": true, "description": "Deprecated UUID compatibility lookup retained only through ADR-046 evidence-gated retirement. New customer account and return flows use the authenticated by-reference routes. Returns the confirmation-safe projection only.", "operationId": "PublicOrderController_getOrderById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicOrderDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch an order by id (opaque, unguessable).", "tags": [ "public-orders" ] } }, "/api/v1/public/orders": { "post": { "deprecated": true, "description": "Legacy quote-intake path: creates an **unpaid** `PENDING` order for the merchant compatibility queue with `taxInCents: 0`. It does not reserve inventory, create payment or Customer lineage, enter the Sales or fulfillment backbone, or enqueue a customer email. Merchant acceptance is required before the request may become operational. It predates the hosted checkout-session flow and is retained only for the reference storefronts until the hosted-checkout flip (#786/#845) and the BYO/IPG migration (#789). New integrations MUST use the checkout-session flow (`POST …/sessions` → reprice → bind → pay), which is the server-authoritative payment/tax/shipping model — do not treat this as the canonical order-creation endpoint.", "operationId": "PublicOrderController_createOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicOrderDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — **partial success. The order WAS created and committed**; only the response projection failed, and this error carries no order id. DO NOT blind-retry: a retry creates a SECOND order. Recover by reading the order back (`GET /public/orders/number/{num}` with the customer email, or the order-status token from the confirmation email) before taking any further action. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, because the generic branch reads as \"nothing happened\" and here something did. This legacy endpoint is deprecated — the checkout-session flow is the supported path and does not have this shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Submit a PENDING quote request — LEGACY storefront path.", "tags": [ "public-orders" ] } }, "/api/v1/merchant/orders": { "get": { "description": "Returns a bounded page of orders (newest first) plus a `nextCursor` for the following page. Pass `?status=` to filter server-side and `?limit=` (1–200, default 50) to size the page. `#1469` — replaces the former unbounded list that returned every order + line item.", "operationId": "MerchantOrderController_getOrders", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of orders to return. Defaults to 50.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating — the `id` of the last order from the previous page (returned as `nextCursor`). Treat it as opaque.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter to orders in this status.", "schema": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List orders for the active org (cursor-paginated).", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/number/{num}": { "get": { "description": "Returns the order, or a neutral 404 (`RESOURCE_NOT_FOUND`) when no order in the active org matches the number (#1288).", "operationId": "MerchantOrderController_getOrderByNumber", "parameters": [ { "name": "num", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch an order by order number.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{id}": { "get": { "description": "Returns the order, or a neutral 404 (`RESOURCE_NOT_FOUND`) when no order in the active org matches the id (#1288).", "operationId": "MerchantOrderController_getOrderById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch an order by id.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{id}/status": { "patch": { "description": "State-machine enforced for ordinary Staff-capable progress: PENDING → CONFIRMED → PROCESSING → COMPLETED. PENDING → CONFIRMED acceptance atomically reserves available inventory and creates the durable Sales bridge intent; insufficient inventory leaves the quote PENDING. This lifecycle command remains gated by `orders:operate`; the reservation is its atomic system-side consequence, not a direct `inventory:adjust` operation. Whole-order cancellation is deliberately rejected here and must use the dedicated Owner/Admin cancellation command so fulfillment and paid-label work cannot be stranded.", "operationId": "MerchantOrderController_updateOrderStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderStatusDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Transition an order to the next status.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{id}/notes": { "patch": { "description": "Pass `null` to clear the existing note. Customer-visible communication is a separate channel (planned in a later epic).", "operationId": "MerchantOrderController_updateOrderNotes", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderNotesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set or clear the merchant-side notes scratchpad.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{id}/fulfillment-status": { "patch": { "deprecated": true, "description": "#1962 — retained only for wire compatibility and returns 409 for every existing Order. A missing Sales record is not a safe write boundary: durable bridge delivery or historical backfill can materialize one later. Existing aggregate values remain readable, but physical progress must use explicit Sales line and quantity fulfillment commands.", "operationId": "MerchantOrderController_updateOrderFulfillmentStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderFulfillmentStatusDto" } } } }, "responses": { "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Retired aggregate fulfillment-status compatibility endpoint.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{id}/shipment-tracking": { "patch": { "description": "#1562/#1962 — edits merchant-entered carrier, tracking number/URL, and shipped/delivered timestamps on one existing historical manual aggregate row or the sole existing line-managed fulfillment. It never creates a line-less fulfillment or new allocation, consumes inventory, or originates a shipment notification. It may correct existing shipped/delivered timestamps and advance an existing SHIPPED fulfillment to DELIVERED. A line-managed edit recomputes both order/Sales mirrors from the unchanged exact ledger and may repair stale projections; a historical aggregate edit leaves them untouched. `notify` remains required for wire compatibility; existing SEND/SUPPRESS evidence is immutable, and a pre-evidence historical row catches up conservatively as SUPPRESS. New and mixed/ambiguous orders return 409 and must use the canonical line/package workflow. Existing PLANNED/READY fulfillments must use the canonical idempotent carrier-handoff command instead of this compatibility endpoint. Carrier/service values backed by attached or legacy order-scoped purchased-label evidence cannot be rewritten here; the route may only correct tracking/timestamps on that shipment.", "operationId": "MerchantOrderController_updateOrderShipmentTracking", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderShipmentTrackingDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantOrderDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Edit tracking on one existing fulfillment compatibility record.", "tags": [ "merchant-orders" ] } }, "/api/v1/merchant/orders/{orderId}/cancel": { "post": { "description": "Owner/Admin-only, reasoned, idempotent cancellation. Goods already handed to a carrier are rejected and must use Returns. Label-free unshipped fulfillments cancel atomically with the parent order. Paid outbound labels are voided through durable provider compensation first; the order, Sales record, fulfillment allocations, and inventory reservation remain active until every exact label result is authoritative. This command never refunds the customer and never sends an order-cancellation email.", "operationId": "MerchantOrderCancellationController_cancelOrder", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Stable operation key. Matching retries return the same durable parent cancellation; reuse with another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel a whole order and every active unshipped fulfillment safely.", "tags": [ "merchant-orders" ] } }, "/api/v1/customer/payment-methods": { "get": { "description": "Also self-heals recent saved-card setups whose setup_intent.succeeded webhook was missed: pending SetupIntents are re-checked against Stripe and, when confirmed, the card is persisted and included in this response (#1387).", "operationId": "CustomerPaymentMethodsController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPaymentMethodResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the customer’s saved payment methods.", "tags": [ "customer-payment-methods" ] } }, "/api/v1/customer/payment-methods/setup-intent": { "post": { "description": "Returns a client secret for Stripe Payment Element confirmation. The resulting card is persisted after the setup_intent.succeeded webhook, or by the read-time reconcile on the list endpoint when that delivery is missed (#1387).", "operationId": "CustomerPaymentMethodsController_createSetupIntent", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSetupIntentResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Create a Stripe SetupIntent for adding a saved card.", "tags": [ "customer-payment-methods" ] } }, "/api/v1/customer/payment-methods/{id}/default": { "patch": { "operationId": "CustomerPaymentMethodsController_setDefault", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentMethodResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Make a saved payment method the default.", "tags": [ "customer-payment-methods" ] } }, "/api/v1/customer/payment-methods/{id}": { "delete": { "operationId": "CustomerPaymentMethodsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Payment method detached." }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Removal blocked by an active subscription, deposit/preauth, unpaid balance, or future required payment context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Detach a saved payment method when no active dependency blocks it.", "tags": [ "customer-payment-methods" ] } }, "/api/v1/merchant/coupons": { "get": { "description": "Optional `status` filter narrows by lifecycle state. Newest first by `createdAt`. Reads are open to any org member.", "operationId": "MerchantCouponController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CouponResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List coupons for the active org.", "tags": [ "merchant-coupons" ] }, "post": { "description": "Codes are trimmed + upper-cased before write. PERCENTAGE.value is basis points (1-10000); FIXED_AMOUNT.value is cents off subtotal (>=0); FREE_SHIPPING.value is ignored. `expiresAt` must be strictly after `startsAt` when both are set.", "operationId": "MerchantCouponController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCouponDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a coupon (permission required).", "tags": [ "merchant-coupons" ] } }, "/api/v1/merchant/coupons/{id}": { "get": { "operationId": "MerchantCouponController_getById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a coupon by id.", "tags": [ "merchant-coupons" ] }, "patch": { "description": "Patch-style: provided fields overwrite, omitted fields are left alone. Nullable fields (`startsAt`, `expiresAt`, `maxUses`, `internalNotes`) accept explicit `null` to clear. The resulting lifecycle window + (type, value) pair are re-validated.", "operationId": "MerchantCouponController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCouponDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a coupon (permission required).", "tags": [ "merchant-coupons" ] }, "delete": { "description": "Sets `status = DISABLED`. The row stays in the DB so audit history is preserved and the storefront apply (slice 2C) can cleanly reject attempts to use the code. Requires a reason for the high-risk audit record. Idempotent — already-DISABLED rows are returned unchanged.", "operationId": "MerchantCouponController_softDisable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Soft-disable a coupon (permission required).", "tags": [ "merchant-coupons" ] } }, "/api/v1/public/cart/apply-coupon": { "post": { "description": "Customer-entered code lookup with all storefront-apply validation gates: ACTIVE status, lifecycle window, minimum subtotal, max uses. Returns either a structured discount or a `valid: false` result with neutral public rejection copy. Does NOT increment the usage counter — that happens at order placement (M3 litecheckout).", "operationId": "PublicCouponController_apply", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCouponDto" } } } }, "responses": { "200": { "description": "Always returned for valid auth + payload. The body carries the apply result discriminated by `valid: true | false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCouponResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Preview a coupon code against the current cart subtotal.", "tags": [ "public-coupons" ] } }, "/api/v1/public/auto-discounts/calculate": { "post": { "description": "Returns every ACTIVE auto-discount that matches the supplied cart (by scope, lifecycle window, and minimum-subtotal gate), with the per-discount saving and the post-discount cart total. Pure calculation — no persistence, no usageCount increment. The storefront cart + PDP both consume this endpoint.", "operationId": "PublicAutoDiscountController_calculate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculateAutoDiscountsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculateAutoDiscountsResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Calculate auto-discounts applicable to a cart snapshot.", "tags": [ "public-auto-discounts" ] } }, "/api/v1/merchant/auto-discounts": { "get": { "description": "Optional `status` filter narrows by lifecycle state. Newest first by `createdAt`. Reads are open to any org member.", "operationId": "MerchantAutoDiscountController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AutoDiscountResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List auto-discounts for the active org.", "tags": [ "merchant-auto-discounts" ] }, "post": { "description": "PERCENTAGE.value is basis points (1-10000); FIXED_AMOUNT.value is cents off subtotal (>=0); FREE_SHIPPING.value is ignored. scope=ITEMS_BY_COLLECTION requires scopeCollectionId; ALL_ITEMS / ORDER_TOTAL require it to be null. `expiresAt` must be strictly after `startsAt` when both are set.", "operationId": "MerchantAutoDiscountController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutoDiscountDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoDiscountResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create an auto-discount (permission required).", "tags": [ "merchant-auto-discounts" ] } }, "/api/v1/merchant/auto-discounts/{id}": { "get": { "operationId": "MerchantAutoDiscountController_getById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoDiscountResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch an auto-discount by id.", "tags": [ "merchant-auto-discounts" ] }, "patch": { "description": "Patch-style: provided fields overwrite, omitted fields are left alone. Nullable fields (`scopeCollectionId`, `startsAt`, `expiresAt`, `internalNotes`) accept explicit `null` to clear. The resulting (scope, scopeCollectionId), (type, value), and (startsAt, expiresAt) pairs are re-validated.", "operationId": "MerchantAutoDiscountController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoDiscountDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoDiscountResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update an auto-discount (permission required).", "tags": [ "merchant-auto-discounts" ] }, "delete": { "description": "Sets `status = DISABLED`. The row stays in the DB so audit history is preserved and the storefront apply (slice 3B) skips it cleanly. Requires a reason for the high-risk audit record. Idempotent — already-DISABLED rows are returned unchanged.", "operationId": "MerchantAutoDiscountController_softDisable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoDiscountResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Soft-disable an auto-discount (permission required).", "tags": [ "merchant-auto-discounts" ] } }, "/api/v1/merchant/bundles": { "get": { "description": "Optional `status` filter narrows by lifecycle state (ACTIVE / DISABLED / EXPIRED). Newest first by `createdAt`. Reads are open to any org member. Each row includes its component items so the admin list never needs a secondary round-trip.", "operationId": "MerchantBundleController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BundleResponseDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List bundles for the active org (with items).", "tags": [ "merchant-bundles" ] }, "post": { "description": "PERCENTAGE.value is basis points (1-10000); FIXED_AMOUNT.value is cents off subtotal (>=0); FREE_SHIPPING.value is ignored. Requires at least 2 component items — a \"bundle\" of one item isn't a bundle. Each item must belong to the active org; variant slots (when set) must reference a variant of the supplied item. `expiresAt` must be strictly after `startsAt` when both are set.", "operationId": "MerchantBundleController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBundleDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a bundle (permission required).", "tags": [ "merchant-bundles" ] } }, "/api/v1/merchant/bundles/{id}": { "get": { "operationId": "MerchantBundleController_getById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a bundle by id (with items).", "tags": [ "merchant-bundles" ] }, "patch": { "description": "Patch-style: provided fields overwrite, omitted fields are left alone. Nullable fields (`startsAt`, `expiresAt`) accept explicit `null` to clear. When `items` is supplied, it REPLACES the bundle's composition wholesale (still subject to the 2-item minimum). The resulting (type, value) and (startsAt, expiresAt) pairs are re-validated against the merged row state.", "operationId": "MerchantBundleController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBundleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a bundle (permission required).", "tags": [ "merchant-bundles" ] }, "delete": { "description": "Sets `status = DISABLED`. The row stays in the DB so audit history is preserved and the storefront apply (slice 5B) skips it cleanly. Requires a reason for the high-risk audit record. Idempotent — already-DISABLED rows are returned unchanged.", "operationId": "MerchantBundleController_softDisable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Soft-disable a bundle (permission required).", "tags": [ "merchant-bundles" ] } }, "/api/v1/public/cart/check-bundles": { "post": { "description": "Returns one entry per matching bundle with the per-bundle saving in cents. Bundles match when every component slot is satisfied: the cart has at least `minQuantity` of the slot's (itemId, variantId) tuple. Item-only slots (variantId NULL) accept any variant of the item; variant-specific slots require an exact match. Stacked additively when multiple bundles match — matches the coupon + auto-discount stacking convention. Pure detection — no persistence, no usage counter.", "operationId": "PublicBundleController_checkBundles", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBundlesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBundlesResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Detect every ACTIVE bundle the supplied cart satisfies.", "tags": [ "public-bundles" ] } }, "/api/v1/public/items/{slug}/bundles": { "get": { "description": "Proactive merchandising read keyed by item slug. Returns every ACTIVE bundle (lifecycle-window-gated, tenant-scoped) whose composition includes the item, with the full slot list (each slot's itemId / variantId / minQuantity plus the slot item's slug / name / price, and variant name / options / price when the slot is variant-narrowed) and `discountInCents` — the MINIMUM qualifying saving at current catalog prices times minQuantity. Actual cart savings (which scale with quantity) come from POST /public/cart/check-bundles. Bundles referencing draft / archived catalog rows are omitted. Unknown / unpublished slug → 404. Each bundle's `id` is resolvable on its own with GET /api/v1/public/bundles/{id} (#3402), which is how a surface holding only a bundle id addresses it — a bundle belongs to many items and has no canonical parent item, so this slug route is an entry point rather than a bundle's address. Each bundle and each slot also carries `availability` (#3648) — the stock-eligibility verdict an upsell needs so it stops recommending a set whose component cannot be bought. Presentation eligibility only: checkout revalidates and stays authoritative, and stock never omits a bundle from this list.", "operationId": "PublicItemBundleController_getBundlesForItem", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBundlesResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List ACTIVE bundles that contain an item (public).", "tags": [ "public-bundles" ] } }, "/api/v1/public/bundles/{id}": { "get": { "description": "Resolves the `id` published by `GET /api/v1/public/items/{slug}/bundles` and by `POST /api/v1/public/cart/check-bundles`. Returns the same `ItemBundleDto` shape a caller already parses from the slug read — name, discount type and value, the minimum qualifying `discountInCents`, and the full component slot list. Use this when a surface holds only a bundle id: a bundle belongs to MANY items, so it has no canonical parent item and cannot be addressed through any one item's slug. Actual cart savings still come from `POST /api/v1/public/cart/check-bundles`, since they scale with quantity. Gating is identical to the slug read: tenant-scoped to `x-organization-slug`, `ACTIVE` only, inside the lifecycle window only, and omitted entirely when any component slot references a draft or archived catalog row — so an unlaunched or expired promotion is never published. Every failure THIS ROUTE handles returns ONE identical 404: unknown, another tenant's, not ACTIVE, outside its window, composition-gated, or an id shaped so it could not be queried at all are deliberately indistinguishable.\n\nThat promise is bounded to a DECODED path parameter, which is the honest limit rather than a caveat. A path the HTTP layer cannot turn into a parameter never reaches this route: an undecodable percent-escape (`/bundles/%`, `/bundles/%ZZ`) returns a `400` with `Failed to decode param`, and a missing segment (`/bundles/`) returns a `404` reading `Cannot GET …` rather than `Bundle not found`. Both happen before routing selects this handler, both are uniform across every route on the platform, and neither depends on whether any bundle exists — so they disclose nothing the identical-404 rule exists to hide. A percent-encoded NUL (`%00`) DOES decode and reach this route, and is rejected here with the ordinary 404.\n\nA published id is NOT permanently resolvable, and a bundle page must not assume otherwise. Archiving any single component item removes the bundle from this read AND from the slug read, because a partially archived composition would misrepresent what unlocks the saving. So this route gives a bundle a stable public ADDRESS; it does not give it a stable lifetime. Treat 404 as an ordinary outcome.\n\n#3648 — stock eligibility (`availability`, per slot and on the bundle) is computed by the same shared projection as the slug read, so the two surfaces agree. Stock never changes WHETHER a bundle resolves: an out-of-stock bundle still returns 200 and is labelled, because a 404 would be indistinguishable from the gated states above.", "operationId": "PublicBundleByIdController_getBundleById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBundleDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch one ACTIVE bundle by its published id (public).", "tags": [ "public-bundles" ] } }, "/api/v1/public/shipping/zones": { "get": { "description": "Returns zones where `archivedAt IS NULL`, each with its non-archived rates inlined. Ordered by `sortOrder ASC, name ASC` at both levels. This response describes CONFIGURATION and zone-level ELIGIBILITY, NOT current checkout availability.\n\n#3272 — read `rates` and `liveRatesEnabled` together. Empty `rates` establishes only that the zone has no active flat rate. The boolean then distinguishes whether live-rate eligibility is paused or enabled; it does not promise a carrier option. A non-empty `rates` array publishes active flat-rate configuration, with each rate still subject to its own `minimumSubtotalInCents` floor. Both flat and live eligibility apply only to destinations matched by `countries`; an empty `countries` array matches no destination.\n\nFor an ordinary checkout, resolve the current option set with `POST /api/v1/public/checkout/sessions/{token}/reprice` and read `availableShippingOptions`. Physical subscription checkout has no public equivalent for resolving its current shipping options. Do not derive a checkout outcome from this configuration read.\n\nAn EMPTY top-level array means the tenant has no ACTIVE zones — including when every zone is archived — so shipping is unconfigured, not unrestricted. That is a configuration statement, not a checkout outcome.", "operationId": "PublicShippingController_listZones", "parameters": [], "responses": { "200": { "description": "Active zones (each with its active rates inlined), ordered by `sortOrder ASC, name ASC` at both levels. Empty when the tenant has no ACTIVE zones — which includes a tenant whose zones are all archived, not only one that never configured any. Either way shipping is unconfigured rather than unrestricted; this read does not state a checkout outcome (#3272).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicShippingZoneDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List active shipping zones with their active rates.", "tags": [ "public-shipping" ] } }, "/api/v1/merchant/shipping/zones": { "get": { "description": "Returns zones with their rates inlined. Includes archived rows by default; pass `?archived=false` to hide soft-deleted zones.", "operationId": "MerchantShippingController_listZones", "parameters": [ { "name": "archived", "required": false, "in": "query", "description": "When `false`, only zones where `archivedAt IS NULL` are returned. Omitting the param includes archived rows.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List shipping zones for the active org.", "tags": [ "merchant-shipping" ] }, "post": { "operationId": "MerchantShippingController_createZone", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertShippingZoneDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a shipping zone (permission required).", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/zones/{id}": { "get": { "operationId": "MerchantShippingController_getZone", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a single shipping zone with its rates.", "tags": [ "merchant-shipping" ] }, "patch": { "operationId": "MerchantShippingController_updateZone", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShippingZoneDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The zone revision is stale while replacing delivery-promise rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a shipping zone (permission required).", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/zones/{id}/archive": { "post": { "description": "Sets `archivedAt = now()`. Idempotent — archiving an already-archived zone returns the same row. The zone disappears from the public read while remaining visible to the merchant.", "operationId": "MerchantShippingController_archiveZone", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive (soft-delete) a shipping zone.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/zones/{id}/restore": { "post": { "description": "Clears `archivedAt`. Idempotent on an active zone.", "operationId": "MerchantShippingController_restoreZone", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingZoneResponseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted shipping zone.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/zones/{zoneId}/rates": { "post": { "operationId": "MerchantShippingController_createRate", "parameters": [ { "name": "zoneId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertShippingRateDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a shipping rate on a zone (permission required).", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/rates/{rateId}": { "patch": { "operationId": "MerchantShippingController_updateRate", "parameters": [ { "name": "rateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShippingRateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a shipping rate (permission required).", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/rates/{rateId}/archive": { "post": { "operationId": "MerchantShippingController_archiveRate", "parameters": [ { "name": "rateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateResponseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a shipping rate.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/rates/{rateId}/restore": { "post": { "operationId": "MerchantShippingController_restoreRate", "parameters": [ { "name": "rateId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateResponseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted shipping rate.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/box-presets": { "get": { "description": "Includes active and inactive presets in deterministic merchant preference order.", "operationId": "MerchantShippingBoxPresetController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List current shipping package presets for the active org.", "tags": [ "merchant-shipping-box-presets" ] }, "post": { "description": "Creates revision 1. This saves reusable configuration only and does not choose a box for any order.", "operationId": "MerchantShippingBoxPresetController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShippingBoxPresetDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create an active shipping package preset.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/{presetId}": { "get": { "operationId": "MerchantShippingBoxPresetController_get", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read one current shipping package preset.", "tags": [ "merchant-shipping-box-presets" ] }, "put": { "description": "Supersedes the observed revision and writes a complete immutable successor snapshot.", "operationId": "MerchantShippingBoxPresetController_replace", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceShippingBoxPresetDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace the authored fields of a package preset.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/order": { "put": { "description": "Requires every current preset and its observed revision. Changed positions create new revisions atomically.", "operationId": "MerchantShippingBoxPresetController_reorder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderShippingBoxPresetsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Replace the deterministic package-preset preference order.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/{presetId}/activate": { "post": { "operationId": "MerchantShippingBoxPresetController_activate", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetRevisionCommandDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Activate an inactive package preset.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/{presetId}/deactivate": { "post": { "operationId": "MerchantShippingBoxPresetController_deactivate", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetRevisionCommandDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Deactivate a package preset without deleting its history.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/{presetId}/default": { "post": { "description": "Revisions the previous default off before revisioning this preset on. Default is a merchant preference, not an automatic recommendation.", "operationId": "MerchantShippingBoxPresetController_setDefault", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetRevisionCommandDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Make one active package preset the organization default.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping/box-presets/{presetId}/default/clear": { "post": { "description": "Creates a new non-default revision. The active package preset remains available.", "operationId": "MerchantShippingBoxPresetController_clearDefault", "parameters": [ { "name": "presetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetRevisionCommandDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingBoxPresetResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Clear the organization default without deactivating the preset.", "tags": [ "merchant-shipping-box-presets" ] } }, "/api/v1/merchant/shipping-provider": { "get": { "description": "Returns the connection read-model: connected/disabled flags, sandbox flag, masked key fingerprint, connect/verify timestamps, the cached carrier snapshot, and whether credential encryption is configured on this environment. The API key is write-only and never returned — reads carry a masked fingerprint only.", "operationId": "MerchantShippingProviderController_getStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingProviderStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active org's shipping-provider connection status.", "tags": [ "merchant-shipping-provider" ] }, "put": { "description": "High-risk, reasoned action. Validates the key with a live carrier listing against the provider, then stores it ENCRYPTED at rest along with the carrier snapshot. Idempotent per org: a second connect replaces the stored key and re-arms a disabled connection. The key is write-only — it is never returned by any read; responses carry only a masked fingerprint. Returns 400 when the key is malformed, missing a `reason`, or rejected by the provider; 502 when the provider is unreachable/misbehaving; 503 when credential encryption is not configured on this environment. Returns 409 while any label purchase for the organization is still in flight; wait for it to finish or reconcile its outcome before replacing the connection.", "operationId": "MerchantShippingProviderController_connect", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectShippingProviderDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingProviderStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Connect (or replace) the org's ShipEngine API key.", "tags": [ "merchant-shipping-provider" ] } }, "/api/v1/merchant/shipping-provider/services": { "get": { "description": "#1863 — the connected carriers' rateable services (real `service_code`s with carrier + domestic/international flags), so admins pick services from a catalog instead of typing slugs (live-rate curation) and can buy labels without knowing carrier codes (#1872). Attempts a bounded live refresh, then returns a usable stored snapshot with explicit source/freshness metadata when the provider fails. A successful live empty response stays authoritative. 400 when no/disabled connection, 502 when the provider fails and no usable snapshot exists, 503 when credential encryption is unconfigured, the stored credential can no longer be decrypted (reconnect required), or an authoritative live-empty result cannot durably invalidate an older snapshot.", "operationId": "MerchantShippingProviderController_listServices", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingProviderServicesDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List the tenant's carrier-catalog services for the admin pickers.", "tags": [ "merchant-shipping-provider" ] } }, "/api/v1/merchant/shipping-provider/test": { "post": { "description": "Runs a live provider check with the stored (decrypted in-memory) key. Always 200: provider or cipher failures are reported in the body (`ok: false` + code/message), never thrown. A passing check refreshes the cached carrier snapshot and `lastVerifiedAt`. The key itself is never returned. Returns 400 when no provider is connected.", "operationId": "MerchantShippingProviderController_testConnection", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestShippingProviderConnectionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Re-check the stored provider key with a live carrier listing.", "tags": [ "merchant-shipping-provider" ] } }, "/api/v1/merchant/shipping-provider/disconnect": { "post": { "description": "High-risk, reasoned action. Hard-deletes the connection row so the encrypted credential leaves the database entirely; live rate quoting stops immediately and checkout falls back to flat rates. Reconnect by submitting a key again. Returns 400 when a `reason` is missing or no provider is connected. Returns 409 while any label purchase for the organization is still in flight; wait for it to finish or reconcile its outcome before disconnecting.", "operationId": "MerchantShippingProviderController_disconnect", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingProviderStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Disconnect the org's shipping provider.", "tags": [ "merchant-shipping-provider" ] } }, "/api/v1/merchant/orders/{orderId}/delivery-promise-recommendations": { "post": { "description": "Read-only Owner/Admin comparison. The API tenant-validates the selected order lines and merchant-confirmed loaded package, then rates the immutable order destination and current authoritative origin against one server-derived ship date. The original quote service is re-rated as the reference; cheaper candidates are classified as same-or-faster or, separately, meets-promise. Missing ETA/reference evidence, stale settings or zone rules, incompatible currency/route/capabilities, and unsupported international customs fail closed. This operation never buys or selects a label, allocates inventory, mutates fulfillment/order state, creates a notification intent, or implies carrier handoff.", "operationId": "MerchantDeliveryPromiseRecommendationController_recommend", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fresh-rate safe fulfillment alternatives for a delivery-promise order.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/rates": { "post": { "description": "Read-only full-rate comparison for the immutable destination, confirmed parcel and one planned ship date, signature and carrier-insurance basis. Returns eligible merchant-paid postage with provider-authored estimated dates; partial and unknown results stay explicit. A separate exact quote is required before the reasoned high-risk label purchase command. Requires BearerAuth, OrganizationSlug tenant scope, and Owner/Admin membership.", "operationId": "MerchantShippingLabelController_shopRates", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingRatesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingRatesResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Shop connected carrier rates for one confirmed order parcel.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-package/recommendation": { "post": { "description": "Read-only ADR-029 package planning. Uses immutable order-line parcel evidence and current active box presets, or reuses the frozen checkout plan for the exact full-order selection. A recommendation includes a bounded placement witness; uncertainty returns an explicit no-recommendation reason and never guesses.", "operationId": "MerchantShippingLabelController_recommendPackage", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageRecommendationRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageRecommendationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Recommend the smallest proven-fit active package preset.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/fulfillments/{fulfillmentId}/cancel-prepared-shipment": { "post": { "description": "High-risk, reasoned package-local cancellation. Label-free PLANNED/READY work cancels immediately through the canonical fulfillment-cancellation primitive. When the READY shipment carries current paid OUTBOUND postage, the command durably records one cancellation intent and queues the exact provider void before returning. The fulfillment stays READY and carrier handoff remains blocked until authoritative void evidence retires the postage; only then does the stored intent complete cancellation. Provider void approval never promises a customer refund or carrier-account credit. After a mixed whole-order cancellation denial, the same command may release one exact parent-aborted READY allocation only for Owner/Admin, only after re-proving the terminal denied parent and immutable void proof, and without another provider call or changing the parent, siblings, payment, or notification state.", "operationId": "MerchantShippingLabelController_cancelPreparedShipment", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable operation key. Matching retries return the same durable cancellation intent; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPreparedShipmentDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPreparedShipmentResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel one prepared shipment, safely voiding paid outbound postage first.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/fulfillments/{fulfillmentId}/cancel-prepared-shipment/retry-carrier-check": { "post": { "description": "Owner/Admin-only, reasoned #2126 recovery. The server reuses the frozen label and provider credential generation from the original cancellation, records an attributable request, and performs exactly one provider GET. It never sends another void request, buys postage, resets provider-attempt history, or accepts operator evidence as provider proof. A provider-confirmed void completes the prepared-shipment cancellation; a provider-confirmed active label leaves the READY shipment usable; ambiguous results remain blocked. A different recovery key receives 409 while another check has a live 15-minute claim. If that claim never records a result, the next request may supersede it after the lease while preserving the abandoned request as immutable evidence.", "operationId": "MerchantShippingLabelController_retryPreparedShipmentCancellationCarrierCheck", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable recovery key. Matching retries resume or replay the attributed check. Keep the key through transient 409 responses; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPreparedShipmentCancellationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPreparedShipmentResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Retry one exact carrier-label check after cancellation recovery is exhausted.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/{purchaseId}/reconciliation-status": { "get": { "description": "Returns a reload-safe, server-derived action mode and the latest immutable safe event. Credentials, generation identifiers, lookup hashes, request payloads, raw bodies, and artifact URLs are never included; bounded non-secret evidence such as label and request identifiers plus tracking presence may be returned.", "operationId": "MerchantShippingLabelController_getReconciliationStatus", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "purchaseId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLabelReconciliationStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read safe reconciliation certainty and currently allowed action.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/quote": { "post": { "description": "Read-only #2447 confirmation step. Recomputes the delivery-promise recommendation evidence when applicable, classifies the merchant-selected service, and performs one exact non-funded provider preflight. Returns the exact cost plus an opaque fingerprint; it allocates no lines, buys no label, and changes no fulfillment, inventory, order, or notification state.", "operationId": "MerchantShippingLabelController_quoteLabelSelection", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteShippingLabelSelectionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteShippingLabelSelectionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Quote and classify one exact carrier service before buying postage.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label": { "post": { "description": "High-risk, reasoned preparation action. It allocates the selected original-order line quantities to one server-owned physical package. Every funded request must carry the opaque fingerprint returned by the matching reviewed read-only exact selection quote for the same lines, loaded parcel, destination, carrier, service, settings, zone, and provider connection. The server freshly recomputes and exactly preflights that selected carrier/service before the durable spend claim; stale or mismatched evidence fails before funding. A captured carrier service remains the ordinary fallback. Manual/free methods and orders with no captured carrier service instead require an explicit actual-postage confirmation and `overrideReason`, recorded as OVERRIDE without any recommendation, equivalence, savings, or promise claim. A non-recommended captured-service choice requires a distinct explicit acknowledgement and `overrideReason`; both reasons remain separate from the high-risk spend reason. If that contract requires or rejects a recipient phone, `recipientPhone` provides an explicit correction for this label only and never mutates the order snapshot. It then buys through the tenant ShipEngine key. On success the label, tracking, exact rating evidence, and package binding are durable and the fulfillment becomes READY. Buying, printing, or reprinting the label never marks carrier handoff, consumes inventory, adds handed-off quantity, or enqueues a shipped notification. READY contributes zero handed-off quantity; its shared recompute may repair pre-existing projection drift from an otherwise exact ledger. Physical handoff effects belong only to the later explicit handoff action. Never auto-funds — funding is operator-driven (#1802). Sandbox (`TEST_`) keys produce a free test label. Returns 400 for a missing method/address/weight or a fixable provider rejection; 409 when a timeout, network interruption, provider 5xx, or opaque/malformed response leaves label creation uncertain and requires ShipEngine reconciliation before retry; 502 for an authoritative upstream refusal such as rate limiting; and 503 when credentials or another authoritative provider gate reject the request. Authoritative no-label failures are durably retryable after correction and fresh selection review.", "operationId": "MerchantShippingLabelController_buyLabel", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "#1809/#1904 — required operation key. A retry carrying the same key and canonical line/package payload replays the existing package-bound label; reusing the key with a different payload is rejected before provider spend.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyShippingLabelDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Prepare selected order lines and buy a native ShipEngine label (spends tenant money).", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/reconcile": { "post": { "description": "For an exact package-bound PURCHASING attempt older than the DB-clock safety window, first parks only that unchanged claim as reconciliation-required. It then performs a non-funded ShipEngine GET using the exact provider identity and credential generation persisted before the original spend. A matching completed outbound label is adopted and moves only the prepared fulfillment to READY. A first 404 remains blocked; release to FAILED requires a second explicit lookup after both the 30-minute claim grace and a five-minute separated-not-found window. Provider errors, evidence mismatches, credential changes, cancellation, and legacy rows remain blocked. Every outcome is idempotent and append-only.", "operationId": "MerchantShippingLabelController_reconcileLabel", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required operation key. Replays the exact prior reconciliation event; reuse with different reason or action is rejected.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileShippingLabelDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Safely reconcile an ambiguous package-bound label purchase.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/accept-actual-cost": { "post": { "description": "#3956 — for a package-bound attempt parked because the provider completed the label at a cost other than the merchant-approved fresh quote, re-verifies the exact label at ShipEngine with a non-funded GET under the same locks as reconciliation, then adopts the existing purchase at its actual cost and moves only the prepared fulfillment to READY. Price-only: tenant/order/package/fulfillment/provider-generation binding, exact label identity, outbound and non-voided status, the approved carrier/service, a valid amount in the approved currency, and a printable completed artifact remain required; missing or invalid amounts, currency differences, and identity or artifact conflicts stay blocked. The approved quote is preserved beside the actual cost and their signed difference. It never buys another label, records carrier handoff, consumes inventory, or sends a shipped notification. Idempotent and append-only.", "operationId": "MerchantShippingLabelController_acceptActualCost", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required operation key. Replays the exact prior acceptance event; reuse with a different reason or action is rejected.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptShippingLabelActualCostDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Accept a parked completed label at its actual provider cost.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/fulfillments/{fulfillmentId}/retire-postage": { "post": { "description": "#4050 / PC-13 — for a handoff recorded by mistake while the parcel is still with the merchant. This is NOT cancel-prepared-shipment with a relaxed guard: that command cancels the fulfillment and releases its allocation on success, which must never happen after goods leave. Eligibility is server-derived and narrow: a line-managed handed-off shipment (SHIPPED or DELIVERED) with an exact physical package whose named, current outbound ShipEngine purchase is PURCHASED with an exact label and provider connection generation, on a non-terminal parent, with no void already requested for that label. The named purchase must be the current postage; a newer replacement label is never substituted. The command durably records one idempotent intent and append-only attempt evidence before any provider I/O, then queues the exact provider void outside the database transaction. On authoritative carrier approval the exact purchase is retired and NOTHING else changes: no unship, no fulfillment or order cancellation, no allocation release, no restock, no payment or return change, no customer refund, and no new customer email. Denial leaves the postage live and usable. An ambiguous result reconciles through bounded exact-label lookups rather than blind retries. Provider acceptance never promises a carrier-account credit, and retired postage is never evidence about whether the goods were delivered. A DELIVERED shipment is eligible on purpose: a merchant may print a label here and then ship by another route — hand delivery, customer pickup, a different courier — so a delivered order can still carry entirely unused postage. Only the carrier knows whether a given label was scanned, so the request is recorded and the provider adjudicates rather than the platform guessing from its own fulfillment status.", "operationId": "MerchantShippingLabelController_retirePostHandoffPostage", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable operation key. Matching retries return the same durable retirement intent; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirePostHandoffPostageDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirePostHandoffPostageResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Ask the carrier to retire the postage on an already handed-off shipment, without cancelling it.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/fulfillments/{fulfillmentId}/retire-postage/retry-carrier-check": { "post": { "description": "#4050 — Owner/Admin-only, reasoned #2126-style recovery for a post-handoff postage retirement. The server reuses the frozen label and provider credential generation from the original request, records an attributable request, and performs exactly one provider GET. It never sends another void request, buys postage, resets provider-attempt history, or accepts operator evidence as provider proof. A provider-confirmed void retires the postage and leaves the shipment exactly as it is; a provider-confirmed active label leaves the postage live and usable; ambiguous results remain unresolved rather than being relabelled as denial.", "operationId": "MerchantShippingLabelController_retryPostHandoffPostageRetirementCarrierCheck", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable recovery key. Matching retries resume or replay the attributed check. Keep the key through transient 409 responses; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPostHandoffPostageRetirementCheckDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirePostHandoffPostageResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Retry one exact carrier-label check after a postage retirement exhausted recovery.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/void-parked-label": { "post": { "description": "#3956 — the refusal alternative to accept-actual-cost. For a package-bound attempt parked because ShipEngine completed the label at a cost other than the merchant-approved fresh quote, durably records one void intent and queues the exact provider void before returning, exactly as a prepared-shipment cancellation does for paid postage (#1803). Eligibility is server-derived and narrow: a PLANNED line-managed package whose current outbound ShipEngine purchase is RECONCILIATION_REQUIRED with the cost-mismatch diagnostic, a completed printable label whose valid same-currency cost differs from the approved quote, a provider generation and exact label identity, and no void of that label already requested. No READY transition is manufactured: a confirmed void retires the purchase as VOIDED and then cancels the planned package through the same #1933 kernel a prepared-shipment cancellation uses, releasing its items for a fresh preparation with a new quote; a denial leaves the label parked and acceptable at its actual cost; an ambiguous result reconciles through bounded exact-label lookups. Acceptance is excluded while a void of the label exists. Provider void approval never promises carrier-account credit.", "operationId": "MerchantShippingLabelController_voidParkedLabel", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable operation key. Matching retries return the same durable void intent; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidParkedShippingLabelDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidParkedShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Void a parked completed label at the provider instead of accepting its actual cost.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/void-parked-label/retry-carrier-check": { "post": { "description": "#3956 — Owner/Admin-only, reasoned #2126-style recovery for a parked-label void. The server reuses the frozen label and provider credential generation from the original void, records an attributable request, and performs exactly one provider GET. It never sends another void request, buys postage, resets provider-attempt history, or accepts operator evidence as provider proof. A provider-confirmed void retires the label and cancels the planned package, releasing its items; a provider-confirmed active label leaves it parked and acceptable at its actual cost; ambiguous results remain blocked.", "operationId": "MerchantShippingLabelController_retryParkedLabelVoidCarrierCheck", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable recovery key. Matching retries resume or replay the attributed check. Keep the key through transient 409 responses; reuse for another payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryParkedShippingLabelVoidCheckDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidParkedShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Retry one exact carrier-label check after a parked-label void exhausted recovery.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/orders/{orderId}/shipping-label/legacy-disposition": { "post": { "description": "Records the operator reason, bounded evidence note, and conclusion in immutable history. It never calls the provider, never changes fulfillment state, and never grants automatic retry permission. Current package-bound attempts with safe lookup identity must use the reconcile endpoint instead.", "operationId": "MerchantShippingLabelController_recordLegacyDisposition", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required operation key. Reuse with a different disposition, reason, or evidence is rejected.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordLegacyShippingLabelDispositionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileShippingLabelResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record an attributable disposition for a legacy ambiguous label.", "tags": [ "merchant-shipping-label" ] } }, "/api/v1/merchant/shipping/warehouse-outputs": { "get": { "description": "Returns one tenant-scoped physical fulfillment row per shipment, with packing-slip lines/address and server-derived label eligibility. Defaults to READY rows. A label is eligible only when the latest package-bound OUTBOUND purchase is durably PURCHASED, completed, and has a safe PDF artifact.", "operationId": "MerchantWarehouseOutputController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum fulfillment rows to return. Defaults to 50.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque next-page cursor returned by the previous response. Treat it as opaque.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Shipment lifecycle to show. Defaults to READY.", "schema": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseOutputListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "413": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List bounded shipment fulfillments for warehouse output.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/warehouse-outputs/csv": { "post": { "description": "Exports exactly 1–50 selected, tenant-owned shipment fulfillments in the request order. The bounded read does not buy postage or change any fulfillment/handoff state. Spreadsheet-formula prefixes are neutralized.", "operationId": "MerchantWarehouseOutputController_exportCsv", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseOutputSelectionDto" } } } }, "responses": { "200": { "description": "CSV attachment containing the selected rows.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "413": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Export selected fulfillment/shipment rows as CSV.", "tags": [ "merchant-shipping" ] } }, "/api/v1/merchant/shipping/warehouse-outputs/labels": { "post": { "description": "Downloads and locally merges the already-purchased PDF artifact for each selected fulfillment, in request order. This makes no authenticated ShipEngine API call, sends no label-purchase request, buys no postage, and performs no fulfillment or handoff mutation. Downloads use bounded concurrency and a batch deadline, and the final PDF stays below a 4 MiB deployment-safe response ceiling. Any stale, voided, missing, invalid, oversized, slow, or unavailable artifact fails the whole request rather than silently omitting a label.", "operationId": "MerchantWarehouseOutputController_combineLabels", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseOutputSelectionDto" } } } }, "responses": { "200": { "description": "One combined PDF containing every selected label page.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Combine existing purchased labels into one printable PDF.", "tags": [ "merchant-shipping" ] } }, "/api/v1/public/subscription-plans": { "get": { "description": "Returns cursor-paginated ACTIVE CUSTOMER plans published to PUBLIC_STOREFRONT with at least one ACTIVE recurring price synced to the tenant's current VERIFIED connected Stripe account. Draft, archived, API-only, merchant-created-only, stale-account, unsynced, and catalog-ineligible plans are omitted. Stripe ids, tenant ids, metadata, and entitlement internals are never exposed.", "operationId": "PublicSubscriptionPlanController_list", "parameters": [ { "name": "priceLimit", "required": false, "in": "query", "description": "Maximum recurring prices to include per returned plan.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 20, "type": "integer" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum public plans to return.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 24, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque plan cursor from a previous response (`nextCursor`). Treat it as opaque and pass it back unchanged.", "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSubscriptionPlanListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List purchasable public subscription plans.", "tags": [ "public-subscriptions" ] } }, "/api/v1/public/subscription-plans/{slug}": { "get": { "description": "Resolves PUBLIC_STOREFRONT and API_BYO_ONLY plans. API_BYO_ONLY slugs are intentionally non-enumerable but are not bearer secrets. Every unpublished, merchant-only, stale-account, unsynced, cross-tenant, or catalog-ineligible state is masked as the same neutral 404.", "operationId": "PublicSubscriptionPlanController_getBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "priceLimit", "required": false, "in": "query", "description": "Maximum recurring prices to include per returned plan.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 20, "type": "integer" } }, { "name": "priceCursor", "required": false, "in": "query", "description": "Opaque price cursor from a prior plan response (`nextPriceCursor`). Treat it as opaque and pass it back unchanged.", "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSubscriptionPlanDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No purchasable public/BYO subscription plan matches the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch a purchasable subscription plan by known slug.", "tags": [ "public-subscriptions" ] } }, "/api/v1/merchant/subscription-plans": { "get": { "description": "Optional `status` filter narrows by lifecycle state. Newest first.", "operationId": "MerchantSubscriptionPlanController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlanResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List subscription plans for the active org.", "tags": [ "merchant-subscription-plans" ] }, "post": { "description": "Plans are born DRAFT. `channelVisibility` defaults to MERCHANT_CREATED_ONLY (orthogonal to status). Add a price, then publish.", "operationId": "MerchantSubscriptionPlanController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionPlanDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a subscription plan (permission required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}": { "get": { "operationId": "MerchantSubscriptionPlanController_getById", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanDetailResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a plan with its prices and entitlement rules.", "tags": [ "merchant-subscription-plans" ] }, "patch": { "description": "Patch-style: provided fields overwrite, omitted are left alone, explicit null clears nullable fields. Lifecycle status is changed via publish/archive, not here.", "operationId": "MerchantSubscriptionPlanController_update", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionPlanDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a subscription plan (permission required).", "tags": [ "merchant-subscription-plans" ] }, "delete": { "description": "Soft-archive: sets status ARCHIVED + archivedAt. The plan and its prices stay (existing subscriptions keep referencing them). Idempotent.", "operationId": "MerchantSubscriptionPlanController_archive", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a plan (elevated permission + reason required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}/publish": { "post": { "description": "Requires at least one ACTIVE price synced to a connected Stripe account. Idempotent-ish: an already-ACTIVE plan re-publishes cleanly.", "operationId": "MerchantSubscriptionPlanController_publish", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Publish a plan → ACTIVE (permission required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}/prices": { "post": { "description": "Mints a backing Stripe Product (once per plan) + Price on the tenant connected account. If the org has no verified account the price is stored unsynced (Stripe ids null) and the plan cannot be published yet.", "operationId": "MerchantSubscriptionPriceController_create", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionPriceDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPriceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Add a recurring price to a plan (permission required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}/prices/{priceId}": { "patch": { "description": "Only `isDefault` and `metadata` are patchable — Stripe Prices are immutable, so amount/currency/interval cannot change here.", "operationId": "MerchantSubscriptionPriceController_update", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "priceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionPriceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPriceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a price’s local fields (permission required).", "tags": [ "merchant-subscription-plans" ] }, "delete": { "description": "Flips local status to ARCHIVED and archives the backing Stripe Price (active:false). Existing subscriptions keep it (grandfathering). Idempotent.", "operationId": "MerchantSubscriptionPriceController_archive", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "priceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPriceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a price (elevated permission + reason required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}/entitlements": { "post": { "description": "Unique per (plan, key). All five entitlement types are accepted; the `value` payload shape is validated by the projection consumer (#631).", "operationId": "MerchantSubscriptionEntitlementController_create", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionEntitlementDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntitlementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Define an entitlement rule on a plan (permission required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/subscription-plans/{planId}/entitlements/{entitlementId}": { "patch": { "description": "`key` and `entitlementType` are identity and not patchable — delete + recreate to change them.", "operationId": "MerchantSubscriptionEntitlementController_update", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "entitlementId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionEntitlementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntitlementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update an entitlement rule’s value/metadata (permission required).", "tags": [ "merchant-subscription-plans" ] }, "delete": { "description": "Hard delete of the rule DEFINITION. (No customer grants exist yet — grant projection is #631.)", "operationId": "MerchantSubscriptionEntitlementController_remove", "parameters": [ { "name": "planId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "entitlementId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete an entitlement rule (permission required).", "tags": [ "merchant-subscription-plans" ] } }, "/api/v1/merchant/dashboard/summary": { "get": { "description": "Returns the total item count, active-booking count, order count, and COMPLETED-order revenue for the active org in a single server-side aggregate — so the dashboard no longer fetches the full item/booking/order tables to compute them client-side.", "operationId": "MerchantDashboardController_getSummary", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardSummaryDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Aggregate metrics for the admin dashboard.", "tags": [ "merchant-dashboard" ] } }, "/api/v1/public/pages": { "get": { "description": "Always filters to `status = PUBLISHED` and excludes archived rows. DRAFT and archived pages are never visible to public storefront callers regardless of query params.", "operationId": "PublicPageController_getPages", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPageSummaryDto" } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List PUBLISHED pages for the tenant (public).", "tags": [ "public-pages" ] } }, "/api/v1/public/pages/{slug}": { "get": { "description": "DRAFT or archived pages are masked as 404 so storefronts cannot probe for unpublished slugs.", "operationId": "PublicPageController_getPageBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The PUBLISHED page matching the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPageSummaryDto" } } } }, "404": { "description": "No PUBLISHED page matches the slug (unknown, DRAFT, or archived) — neutral `RESOURCE_NOT_FOUND` (#1221).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch a PUBLISHED page by slug (public).", "tags": [ "public-pages" ] } }, "/api/v1/merchant/pages": { "get": { "description": "Returns PUBLISHED + DRAFT pages by default in createdAt-desc order. Pass `?archived=true` to include archived rows, optionally with `?status=ARCHIVED` to see only archived. Pass `?search=...` for substring search across title + content.", "operationId": "MerchantPageController_listPages", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by page status. On the public route this is forced to PUBLISHED. On the merchant route the default is \"any non-archived\".", "schema": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "ARCHIVED" ] } }, { "name": "search", "required": false, "in": "query", "description": "Substring search over title and content.", "schema": { "type": "string" } }, { "name": "archived", "required": false, "in": "query", "description": "Merchant-only. When true, soft-deleted (`archivedAt != null`) pages are included. Public reads ignore this. Accepts `true`/`1`/`yes` (case-insensitive) for true, `false`/`0`/`no` for false. Any other value is rejected as 400.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPageDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List pages for the active org.", "tags": [ "merchant-pages" ] }, "post": { "operationId": "MerchantPageController_createPage", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePageDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a page (permission required).", "tags": [ "merchant-pages" ] } }, "/api/v1/merchant/pages/by-slug/{slug}": { "get": { "operationId": "MerchantPageController_getPageBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a page by slug (merchant — includes DRAFT + archived).", "tags": [ "merchant-pages" ] } }, "/api/v1/merchant/pages/{id}": { "get": { "operationId": "MerchantPageController_getPageById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a page by id (merchant — includes DRAFT + archived).", "tags": [ "merchant-pages" ] }, "patch": { "operationId": "MerchantPageController_updatePage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePageDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a page (permission required).", "tags": [ "merchant-pages" ] } }, "/api/v1/merchant/pages/{id}/archive": { "post": { "description": "Sets `archivedAt = now()` and `status = ARCHIVED`. Idempotent — archiving an already-archived page returns the same row.", "operationId": "MerchantPageController_archivePage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive (soft-delete) a page.", "tags": [ "merchant-pages" ] } }, "/api/v1/merchant/pages/{id}/restore": { "post": { "description": "Clears `archivedAt` and sets `status = DRAFT` (conservative — merchant must republish to make it visible). Idempotent.", "operationId": "MerchantPageController_restorePage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore a soft-deleted page.", "tags": [ "merchant-pages" ] } }, "/api/v1/public/storefront/site-config": { "get": { "description": "Server-driven storefront configuration derived from the org record (ADR-003). `storefrontOrigin` is env-aware: a production API deployment (`VERCEL_ENV=production`) resolves the production custom domain; every other serving environment — preview/staging deployments, and equally local development or CI where `VERCEL_ENV` is unset — resolves the staging domain, so only production can ever advertise the production origin. `null` when no origin is configured for the serving environment. Storefronts should prefer this over a per-deploy site-URL env var (keep the env var as an explicit override / build-time fallback only). The response also exposes only customer-facing support contact, the three http(s)-guarded policy URLs, the default-off ordinary-cart checkout phone requirement, and derived trust proof: the verified/attested storefront origin and the effective origins selected by the API checkout, customer-action, and newsletter resolvers; raw organization settings are never returned. `orderProcessing` (#3275) carries the tenant-wide order-processing timing a shipping-policy page needs — effective processing business days, the effective local order cutoff, and the timezone both are evaluated in — resolved from the same inputs that produce `shipByDate` on a checkout session. That timezone is usually an IANA name but is NOT guaranteed to be one: the gate is what `Intl.DateTimeFormat` accepts, so a tenant storing a fixed offset such as `+05:00` has it published verbatim. Do not reject the response or attempt an IANA lookup on that basis — see the field description for the full contract. Read `mode` first: `description` means the two timing values are not configured rather than zero. Per-rate transit windows and the free-text per-rate estimate remain on `GET /api/v1/public/shipping/zones`.", "operationId": "PublicStorefrontSiteConfigController_getSiteConfig", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSiteConfigDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Fetch the tenant's storefront site config and destination trust proof.", "tags": [ "public-site-config" ] } }, "/api/v1/merchant/domain-verification": { "get": { "description": "Returns the verified signal + any active DNS challenge for the production and staging custom-domain hosts.", "operationId": "DomainVerificationController_getStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Per-env custom-domain verification status for the active org.", "tags": [ "merchant-domain-verification" ] } }, "/api/v1/merchant/domain-verification/{environment}/challenge": { "post": { "description": "Returns the TXT record the tenant must publish. Supersedes any prior pending challenge for this environment. A host that is already trusted stays trusted while re-verification runs.", "operationId": "DomainVerificationController_createChallenge", "parameters": [ { "name": "environment", "required": true, "in": "path", "schema": { "enum": [ "production", "staging" ], "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Issue a DNS-TXT ownership challenge (permission required).", "tags": [ "merchant-domain-verification" ] } }, "/api/v1/merchant/domain-verification/{environment}/verify": { "post": { "description": "Resolves the TXT record; on a match flips the per-env status to VERIFIED. A DNS miss returns `verified: false` (not an error) so the tenant can retry while DNS propagates.", "operationId": "DomainVerificationController_verifyChallenge", "parameters": [ { "name": "environment", "required": true, "in": "path", "schema": { "enum": [ "production", "staging" ], "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Check the active DNS-TXT challenge (permission required).", "tags": [ "merchant-domain-verification" ] } }, "/api/v1/merchant/domain-verification/{environment}/revoke": { "post": { "description": "Resets the per-env status to UNVERIFIED (fail closed) and fails any active challenge. Use when a domain changes hands or a later check fails.", "operationId": "DomainVerificationController_revoke", "parameters": [ { "name": "environment", "required": true, "in": "path", "schema": { "enum": [ "production", "staging" ], "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revoke verification for an environment (permission required).", "tags": [ "merchant-domain-verification" ] } }, "/api/v1/merchant/api-keys": { "get": { "description": "By default returns only non-revoked keys. Pass `?includeRevoked=true` to include revoked rows for audit review.", "operationId": "ApiKeysController_list", "parameters": [ { "name": "includeRevoked", "required": false, "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List API keys for the active org.", "tags": [ "merchant-api-keys" ] }, "post": { "description": "The returned `secret` is shown ONCE. There is no way to retrieve it again — only revoke + recreate. Surface a \"copy now\" affordance in the admin UI before navigating away from the post-create state.", "operationId": "ApiKeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWithSecretDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a new API key (permission required).", "tags": [ "merchant-api-keys" ] } }, "/api/v1/merchant/api-keys/{id}/revoke": { "post": { "description": "Idempotent: revoking an already-revoked key is a no-op. The row is retained for audit history — we never delete API key rows.", "operationId": "ApiKeysController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revoke an API key (permission required).", "tags": [ "merchant-api-keys" ] } }, "/api/v1/merchant/audit-logs": { "get": { "description": "Returns the most recent audit events for this tenant in `createdAt DESC` order. Supports filtering by action substring, targetType, targetId, actorUserId, and a time range (`since` / `until`). Cursor pagination via the returned `nextCursor`. Requires an OWNER or ADMIN membership; any other role receives 403.", "operationId": "MerchantAuditController_list", "parameters": [ { "name": "action", "required": false, "in": "query", "description": "Action namespace prefix or full action string. e.g. `item.` matches `item.created`, `item.updated`; `collection.archived` matches exactly. Substring match on the action column.", "schema": { "type": "string" } }, { "name": "targetType", "required": false, "in": "query", "description": "Filter by target entity type — `item`, `variant`, `collection`, `page`, etc. Exact match.", "schema": { "type": "string" } }, { "name": "targetId", "required": false, "in": "query", "description": "Filter to a specific target id (combine with `targetType` for best results — different entities can share an id space in theory). Accepts canonical UUIDs and historical/imported text identities.", "schema": { "type": "string" } }, { "name": "actorUserId", "required": false, "in": "query", "description": "Filter to actions performed by a specific user.", "schema": { "type": "string" } }, { "name": "since", "required": false, "in": "query", "description": "ISO-8601 timestamp; only audit events created at or after this instant are returned. Useful for \"since I last checked\" polling.", "schema": { "type": "string" } }, { "name": "until", "required": false, "in": "query", "description": "ISO-8601 timestamp; only audit events created strictly before this instant are returned.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of rows to return.", "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (the `nextCursor` field). Currently a stringified row id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAuditLogPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List audit log entries for the active org.", "tags": [ "merchant-audit" ] } }, "/api/v1/merchant/audit-logs/export": { "get": { "description": "Streams the FULL set of audit events matching the given filters (`action`, `targetType`, `targetId`, `actorUserId`, `since`, `until` — the same filters as the list endpoint) as `text/csv`, in the same `createdAt DESC` order, with NO pagination or row cap. Columns: timestamp (ISO), actorUserId, actorEmail, action, targetType, targetId, metadata (JSON-encoded). Served as an attachment download; an empty result still returns a header-only CSV. Same auth/tenancy as the list — OWNER or ADMIN only, org-scoped.", "operationId": "MerchantAuditController_export", "parameters": [ { "name": "action", "required": false, "in": "query", "description": "Action namespace prefix or full action string. e.g. `item.` matches `item.created`, `item.updated`; `collection.archived` matches exactly. Substring match on the action column.", "schema": { "type": "string" } }, { "name": "targetType", "required": false, "in": "query", "description": "Filter by target entity type — `item`, `variant`, `collection`, `page`, etc. Exact match.", "schema": { "type": "string" } }, { "name": "targetId", "required": false, "in": "query", "description": "Filter to a specific target id (combine with `targetType` for best results — different entities can share an id space in theory). Accepts canonical UUIDs and historical/imported text identities.", "schema": { "type": "string" } }, { "name": "actorUserId", "required": false, "in": "query", "description": "Filter to actions performed by a specific user.", "schema": { "type": "string" } }, { "name": "since", "required": false, "in": "query", "description": "ISO-8601 timestamp; only audit events created at or after this instant are returned. Useful for \"since I last checked\" polling.", "schema": { "type": "string" } }, { "name": "until", "required": false, "in": "query", "description": "ISO-8601 timestamp; only audit events created strictly before this instant are returned.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV stream of the matching audit events (attachment).", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Export audit log entries as CSV.", "tags": [ "merchant-audit" ] } }, "/api/v1/merchant/settings": { "get": { "description": "Returns the full `organization_settings` row for the org bound to the request (resolved by `x-organization-slug`). On first call, the service materializes an empty row with all category JSONB columns set to `{}` so the client never has to handle a 404.\n\nOpen to any authenticated member of the org.", "operationId": "MerchantSettingsController_getSettings", "parameters": [], "responses": { "200": { "description": "Settings row plus the active organization timezone used by tenant-local settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch the active org's settings.", "tags": [ "merchant-settings" ] }, "patch": { "description": "Partial update. Each category in the body — `businessProfile`, `checkoutSettings`, `apiSettings`, `notifications`, `shippingSettings` — is SHALLOW-MERGED into the existing JSONB column at the top level only. Omitted categories are left alone. To clear a nullable key inside a category, set it to `null` in the payload (the spread preserves explicit null).\n\nEmits `settings.updated` to the audit log; metadata records only the category names that were touched, never the values themselves.", "operationId": "MerchantSettingsController_updateSettings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsDto" } } } }, "responses": { "200": { "description": "Updated settings row plus the active organization timezone used by tenant-local settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The delivery-promise catalog revision is stale; refresh before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update the active org's settings (permission required).", "tags": [ "merchant-settings" ] } }, "/api/v1/merchant/settings/tax-readiness": { "get": { "description": "Read-only, server-derived status for the active organization resolved by x-organization-slug. Requires settings:manage (Owner/Admin or delegated Staff). Returns only safe states and mode; never account identifiers, settings values or provider errors. Does not configure Stripe or establish legal tax obligations.", "operationId": "MerchantTaxReadinessController_getReadiness", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxReadinessDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Check connected Stripe Tax readiness.", "tags": [ "merchant-settings" ] } }, "/api/v1/merchant/limits": { "get": { "description": "Returns `{ plan, limits, usage }` for the active org. `limits` is the canonical `PLAN_LIMITS[plan]` table; `usage` has matching keys with the org's current counts. The admin Plan & Usage page renders progress bars off these.\n\nOpen to any authenticated member of the org.", "operationId": "LimitsController_getLimits", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantLimitsDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch the active org's plan, soft limits, and current usage.", "tags": [ "merchant-limits" ] } }, "/api/v1/merchant/uploads/signed-url": { "post": { "description": "Validates the caller's org owns the target item/collection and returns a short-lived signed PUT URL plus the eventual public URL and bucket-relative storage path. The admin app uploads the bytes directly to the signed URL, then POSTs to the matching `/merchant/items/:id/images` or `/merchant/collections/:id/images` endpoint to write the metadata row.", "operationId": "MerchantUploadsController_signUploadUrl", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUploadUrlDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUploadResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Mint a signed upload URL for a catalog image.", "tags": [ "merchant-uploads" ] } }, "/api/v1/merchant/uploads/checkout-logo/signed-url": { "post": { "description": "Records and mints an immutable path under the current tenant branding namespace. Static JPEG, PNG, WebP, and AVIF are accepted up to 5 MiB; SVG and animation are rejected. Replacements are checked against storage limits using the full candidate byte count while the prior immutable logo remains retained.", "operationId": "MerchantUploadsController_signCheckoutLogoUpload", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignCheckoutLogoUploadDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUploadResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Mint a tenant-scoped signed upload URL for the checkout logo.", "tags": [ "merchant-uploads" ] } }, "/api/v1/merchant/uploads/checkout-logo/confirm": { "post": { "description": "Downloads and fully decodes the object server-side, verifies its exact tenant-owned mint intent, MIME, byte size, and dimensions, then atomically sets the server-derived environment-matched media reference. The authoritative storage-limit check charges the full candidate bytes while any prior immutable logo remains retained for non-destructive reconciliation.", "operationId": "MerchantUploadsController_confirmCheckoutLogo", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmCheckoutLogoUploadDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLogoAssetDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Validate and attach an uploaded checkout logo.", "tags": [ "merchant-uploads" ] } }, "/api/v1/merchant/uploads/checkout-logo": { "delete": { "description": "Clears both the active upload-backed asset and any retained legacy external URL. When media quarantine is enabled, detached Storage objects enter its bounded, exact-path, non-destructive flow.", "operationId": "MerchantUploadsController_removeCheckoutLogo", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLogoRemovalResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove the current or legacy checkout logo setting.", "tags": [ "merchant-uploads" ] } }, "/api/v1/merchant/email-suppression/status": { "get": { "description": "Authenticated organization membership is required. This status contains no recipient identity, provider account, internal attempt, or cross-tenant data. It cannot activate enforcement, authorize recovery, or send email.", "operationId": "MerchantEmailSuppressionStatusController_get", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSuppressionStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read this organization’s redacted transactional-email suppression signal.", "tags": [ "merchant-email-suppression" ] } }, "/api/v1/merchant/support-provider-connections/intercom": { "get": { "description": "Returns an identifier-free tenant projection of surface eligibility, connection, capability, resource, cleanup, and action availability. Routine tenant/runtime/global-switch ineligibility returns HTTP 200 with surfaceAvailable false; 5xx responses are reserved for genuine faults. It never returns provider workspace/resource identifiers, token or credential identifiers, canonical provider configuration, secret material, or operator-only controls.", "operationId": "MerchantIntercomConnectionController_getStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntercomMerchantLifecycleStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the masked Intercom connection lifecycle.", "tags": [ "merchant-support-provider-connections" ] } }, "/api/v1/merchant/support-provider-connections/intercom/connect": { "post": { "description": "Available only to a database-enrolled tenant in canonical staging and requires customers:support plus a human reason. The same route performs an initial connect or a same-owner reconnect after cleanup completes. The client may propose only US, EU, or AU; it cannot supply a hostname, workspace, runtime, tenant, or return URL. The callback revalidates enrollment and persists no authority until hard-allowlisted GET /me attests the same region and exact workspace. Production and general-availability activation remain disabled.", "operationId": "MerchantIntercomConnectionController_start", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartIntercomConnectionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartIntercomConnectionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Begin or reconnect a staging-pilot Intercom OAuth connection.", "tags": [ "merchant-support-provider-connections" ] } }, "/api/v1/merchant/support-provider-connections/intercom/disconnect": { "post": { "description": "Immediately disables litecommerce authority, tombstones customer subjects, and starts provider-credential retirement. The response is the same identifier-free lifecycle projection as GET status. Reconnect remains unavailable until cleanup is complete, and operator-only recovery stays outside this tenant route.", "operationId": "MerchantIntercomConnectionController_disconnect", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectIntercomConnectionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntercomMerchantLifecycleStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Disconnect the tenant Intercom connection.", "tags": [ "merchant-support-provider-connections" ] } }, "/api/v1/merchant/email-sending-domain": { "get": { "description": "Returns the configured domain, its provider verification status, the DNS records that must be published, the candidate sender address, and the current closed-default sender-policy selection for new tenant-authored production deliveries. A stable VERIFIED domain may be selected only when the independent sender-resolution switch and production admission configuration are ready. Platform-authored mail retains the platform sender, and retries retain the exact sender pinned on first admission. Any authenticated member can read this surface.", "operationId": "MerchantEmailSendingDomainController_get", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendingDomainDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read this organization’s sending-domain configuration.", "tags": [ "merchant-email-sending-domain" ] }, "post": { "description": "Durably queues provider registration before any provider call. The response may be CONFIGURING while the reconciliation drain obtains the SPF/DKIM records; later reads return the canonical lifecycle. Configuring a domain never starts sending on it. Verification establishes eligibility; only the separately gated sender policy may select it for future tenant-authored production deliveries, while existing retries retain their admission-time sender. When a different domain is already configured this returns 409; remove it first so the swap is explicit and separately audited. Re-posting the same domain with a new `fromLocalPart` updates the sender name without disturbing verification.", "operationId": "MerchantEmailSendingDomainController_configure", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureEmailSendingDomainDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendingDomainDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Configure the sending domain for this organization.", "tags": [ "merchant-email-sending-domain" ] }, "delete": { "description": "Durably records removal and fences sender eligibility before provider I/O. The response may be REMOVING until the exact provider object and local projection converge. New tenant-authored admissions select the platform default immediately; existing retries retain their immutable sender pin. Removing when nothing is configured is a no-op and still returns 200.", "operationId": "MerchantEmailSendingDomainController_remove", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendingDomainDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove the configured sending domain.", "tags": [ "merchant-email-sending-domain" ] } }, "/api/v1/merchant/email-sending-domain/verify": { "post": { "description": "Records a verification intent, fences sender eligibility immediately, and returns the canonical lifecycle, which may be VERIFYING while the provider performs its asynchronous check. The durable drain polls until the provider reports a terminal status. Rate limited per organization — DNS propagation takes minutes, and the provider account is shared across tenants. If the domain no longer exists at the provider, the drain clears the exact bound local configuration and a later read reports it as unconfigured.", "operationId": "MerchantEmailSendingDomainController_verify", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendingDomainDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Re-check verification for the configured sending domain.", "tags": [ "merchant-email-sending-domain" ] } }, "/api/v1/merchant/notices": { "get": { "description": "Returns every currently active published notice that has not been dismissed by the active organization, newest first.", "operationId": "MerchantNoticesController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantNoticeDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List active, non-dismissed platform notices for the active org.", "tags": [ "merchant-notices" ] } }, "/api/v1/merchant/notices/read": { "patch": { "description": "Marks up to 1000 active notices read for the active organization while preserving each notice first-read timestamp.", "operationId": "MerchantNoticesController_markReadBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkMerchantNoticesReadDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationNoticeStateDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Mark a bounded batch of platform notices read.", "tags": [ "merchant-notices" ] } }, "/api/v1/merchant/notices/{id}/read": { "patch": { "operationId": "MerchantNoticesController_markRead", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationNoticeStateDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Mark a platform notice read for the active organization.", "tags": [ "merchant-notices" ] } }, "/api/v1/merchant/notices/{id}/dismiss": { "patch": { "operationId": "MerchantNoticesController_dismiss", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationNoticeStateDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Dismiss a platform notice for the whole organization (Owner/Admin).", "tags": [ "merchant-notices" ] } }, "/api/v1/public/contact": { "post": { "description": "Public-facing capture for a storefront contact form. Persists the message for the merchant to read and triage in admin; nothing is emailed. Carries a honeypot field (`website`) that real submitters never see. The response is constant — `{ ok: true }` regardless of whether the message was stored or discarded as spam — so it cannot be used as a delivery or storage oracle.", "operationId": "PublicContactController_submit", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitContactMessageDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSubmitResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Submit a contact-form message to a tenant.", "tags": [ "public-contact" ] } }, "/api/v1/merchant/contact/messages": { "get": { "description": "Newest first. Filter by triage state: `all` (default), `unread`, `read`, or `archived`. Cursor-paginated via `limit` (default 50, max 200) plus the returned `nextCursor`. Rows carry a truncated `preview` rather than the full body — fetch a single message for that. Requires the `customers:support` permission group (Owner and Admin always pass).", "operationId": "MerchantContactController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over name, email, subject, and body.", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "Triage filter: `all` (default — the whole inbox), `unread`, `read`, or `archived`.", "schema": { "type": "string", "enum": [ "unread", "read", "archived", "all" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of messages to return.", "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (the `nextCursor` field). Currently a stringified message id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContactMessagePageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List contact-form messages for the active org.", "tags": [ "merchant-contact" ] } }, "/api/v1/merchant/contact/messages/{id}": { "get": { "description": "Scoped to the active org: an id belonging to another tenant 404s exactly like one that does not exist. Reading does NOT mark the message read — that is an explicit PATCH, so opening a message to check it cannot silently clear a colleague's unread queue. Requires the `customers:support` permission group (Owner and Admin always pass).", "operationId": "MerchantContactController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContactMessageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a single contact-form message, including the full body.", "tags": [ "merchant-contact" ] }, "patch": { "description": "Moves the message between `UNREAD`, `READ`, and `ARCHIVED`. `readAt` and `archivedAt` are stamped the first time the message enters each state and are retained afterwards, so marking a message unread again restores the queue without rewriting the history. Returns the updated message with its full body, so it carries the same `customers:support` requirement as the reads (Owner and Admin always pass).", "operationId": "MerchantContactController_updateStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactMessageStatusDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContactMessageDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a contact message's triage state.", "tags": [ "merchant-contact" ] } }, "/api/v1/public/orders/{orderId}/returns": { "post": { "deprecated": true, "description": "Caller must supply the customer email used at checkout. Server validates email match and that requested quantities do not exceed the original order line minus any already-claimed returns. This raw Order-id/email compatibility route is a measured retirement target; new clients use the authenticated by-reference route.", "operationId": "PublicReturnController_request", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReturnDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReturnResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Email mismatch is a documented #1475 UX/security exception: the public return flow returns 403 so legitimate customers can correct the email, while org scoping, rate limiting, and no extra order detail bound probing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a return on an order (customer-initiated).", "tags": [ "public-returns" ] }, "get": { "deprecated": true, "description": "Requires the same email that placed the order. Returns are newest-first. This raw Order-id/email compatibility route is a measured retirement target.", "operationId": "PublicReturnController_list", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "email", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReturnResponseDto" } } } } }, "403": { "description": "Email mismatch is a documented #1475 UX/security exception: the public return flow returns 403 so legitimate customers can correct the email, while org scoping, rate limiting, and no extra order detail bound probing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List the calling customer's returns on this order.", "tags": [ "public-returns" ] } }, "/api/v1/public/orders/{orderId}/returns/{returnId}/cancel": { "post": { "deprecated": true, "description": "Customer-side cancellation. After the package is in transit, cancellation routes through the merchant's status endpoint. This raw Order-id/email compatibility route is a measured retirement target.", "operationId": "PublicReturnController_cancel", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "returnId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelReturnDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReturnResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Email mismatch is a documented #1475 UX/security exception: the public return flow returns 403 so legitimate customers can correct the email, while org scoping, rate limiting, and no extra order detail bound probing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Cancel a return while still REQUESTED or APPROVED.", "tags": [ "public-returns" ] } }, "/api/v1/merchant/returns": { "get": { "description": "Optional `status` filter narrows by lifecycle state. Newest-first by `requestedAt`.", "operationId": "MerchantReturnController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnListItemDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List returns for the active org.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/order-evidence/{orderId}": { "get": { "description": "Reports whether authoritative line-level handoff evidence is already rebuildable, can be normalized from a versioned machine-owned import manifest, or remains insufficient. Aggregate fulfilled status, tracking, and ordered quantity never make an item returnable.", "operationId": "MerchantReturnController_classifyOrderEvidence", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnEvidenceDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Classify exact return-eligibility evidence for an imported order.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/order-evidence/{orderId}/reconcile": { "post": { "description": "Owner/Admin only. Requires explicit confirmation, the current evidence fingerprint, and an idempotency key. The command writes exact canonical fulfillment-line evidence plus an immutable before/after audit record. It does not create a Return, issue/refund money, mutate inventory or rollups, call a provider, or notify a customer.", "operationId": "MerchantReturnController_reconcileOrderEvidence", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "description": "Stable command key. Matching retries replay; reuse with another order or evidence fingerprint returns 409.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileMerchantReturnEvidenceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnEvidenceDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Normalize exact imported handoff evidence for physical returns.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}": { "get": { "operationId": "MerchantReturnController_getById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch a return by id with full details.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/status": { "patch": { "description": "State-machine enforced. REQUESTED → {APPROVED, REJECTED, CANCELLED}; APPROVED → {IN_TRANSIT, CANCELLED}; IN_TRANSIT → {RECEIVED, CANCELLED}; RECEIVED → COMPLETED. COMPLETED, REJECTED, CANCELLED are terminal. For a positive cash refund, HTTP 200 acknowledges the command but the canonical Return may remain RECEIVED; consume `status` and the redacted `refundWorkflow` rather than inferring completion from the HTTP status.", "operationId": "MerchantReturnController_updateStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-return-refund-prior-generation", "in": "header", "description": "Required with a fresh idempotency key when retrying a deterministic no-money rejection. Pins the command to the exact failed generation.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "x-idempotency-key", "in": "header", "description": "Optional for the first refund command; required to explicitly authorize a new provider generation after a deterministic no-money rejection. Reusing a key replays only the generation it originally authorized.", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnStatusDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Transition a return to the next status.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/intake": { "patch": { "description": "Records terminal RESELLABLE, DAMAGED, or WRITE_OFF outcomes and optional merchant notes while the return is APPROVED or IN_TRANSIT. PENDING → terminal is forward-only; changing one terminal outcome to another or editing a received return is rejected with 409. To apply outcomes and receive atomically, send the same item shape with PATCH /merchant/returns/{id}/status and status RECEIVED.", "operationId": "MerchantReturnController_updateIntake", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnIntakeDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record return-item intake outcomes before receipt.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/refund-allocation-preparation": { "get": { "description": "Returns the exact cents each return item can absorb, so an operator can author `allocations` for PATCH :id/refund-amount. That endpoint requires allocations for any positive refund and never derives the split server-side. A zero-amount refund still sends `allocations: []`.", "operationId": "MerchantReturnController_getRefundAllocationPreparation", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRefundAllocationPreparationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read per-item refundable cents for a return (#3057).", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/refund-amount": { "patch": { "description": "Records the refund (in cents) to issue when the return reaches COMPLETED. Validated <= the refundable cap (sum of returned line totals + attributed order tax); free entry below the cap is allowed (e.g. a restocking-fee deduction), and 0 records that no cash refund will be issued when the return is later completed. Settable only while the return is active — a COMPLETED, REJECTED, or CANCELLED return is rejected with 409. The Stripe refund is issued on the COMPLETED transition, not by this endpoint.", "operationId": "MerchantReturnController_setRefundAmount", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnRefundAmountDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set the intended cash refund amount for a return.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/refund-exception/claim": { "post": { "description": "Assigns the case to the current operator. Claiming changes no ledger, Return, customer notification, provider, tax, shipping, fulfillment, or inventory state.", "operationId": "MerchantReturnController_claimRefundException", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Claim a post-success refund exception for remediation.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/refund-exception/reimbursements": { "post": { "description": "High-risk, idempotent operator attestation. Appends an ordinary Sales REFUND and reserves its Stripe Tax reversal intent, but performs no provider call and cannot issue customer money. Full coverage advances notification resolution; partial coverage leaves the balance owed visible.", "operationId": "MerchantReturnController_recordRefundReimbursement", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "description": "Stable operation key. Exact retries replay; reuse with different reimbursement facts returns 409.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordReturnRefundRemediationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record alternative reimbursement already made to the customer.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/returns/{id}/notes": { "patch": { "description": "Pass `null` to clear; pass a string up to 4000 chars to set. Customer-visible communication is a separate channel. Returns the full return detail (items joined to their order lines, the order context, and `refundableCapInCents`) — the same shape as the status and refund-amount writes and the by-id read.", "operationId": "MerchantReturnController_updateNotes", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReturnNotesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantReturnDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set or clear the merchant-only internal notes.", "tags": [ "merchant-returns" ] } }, "/api/v1/merchant/commerce/contracts": { "post": { "operationId": "MerchantCommerceContractController_createContract", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContractPacketDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContractPacketDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a DRAFT contract/signature packet on a commerce record.", "tags": [ "merchant-commerce" ] }, "get": { "operationId": "MerchantCommerceContractController_listContracts", "parameters": [ { "name": "recordId", "required": false, "in": "query", "description": "Filter to packets on a single commerce record.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by packet status.", "schema": { "type": "string", "enum": [ "DRAFT", "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor — the `id` of the last packet from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractPacketListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List contract/signature packets (newest-first, cursor-paginated).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/contracts/{id}/send": { "post": { "operationId": "MerchantCommerceContractController_sendContract", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendContractPacketDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendContractResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Send a DRAFT packet — allocate the C- number, mint the customer signature link, DRAFT→SENT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/contracts/{id}/countersign": { "post": { "operationId": "MerchantCommerceContractController_countersignContract", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendContractPacketDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContractPacketDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Countersign a SENT packet (merchant/first-party) — completes to SIGNED once every signature is signed.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/contracts/{id}/void": { "post": { "operationId": "MerchantCommerceContractController_voidContract", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendContractPacketDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantContractPacketDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Void a SENT contract packet — SENT→VOIDED; withdraws the signature request.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/payment-term-presets": { "get": { "description": "The read surface behind the Sales header payment-term picker. Returns the active (non-archived) presets for the org, default-first then by name, so the UI can offer `paymentTermPresetId` choices for a DRAFT. Tenant-scoped; unpaginated (the per-org preset set is small and bounded).", "operationId": "MerchantCommercePaymentTermsController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePaymentTermPresetListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List the org's reusable payment-term presets (#1418).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce": { "get": { "description": "Cursor-paginated, newest-first. Each item projects a type-aware primary status: linked orders use the Order processing lifecycle while quotes, invoices, and unlinked orders use the commercial lifecycle. Filter by that primary status or the independent commercial/payment/fulfillment axes, plus type, source, customer, external id, and created-date range; `search` matches display number, customer name/email, and company name.", "operationId": "MerchantCommerceController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over display number, customer name/email, and company name, plus a prefix match on the record id (matches the `Draft · ` tag — the first 8 characters of the record id — shown for un-issued drafts, as well as a full record id).", "schema": { "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating large lists — the `id` of the last record from the previous page (returned as `nextCursor`). Treat it as opaque.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by document type.", "schema": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] } }, { "name": "source", "required": false, "in": "query", "description": "Filter by source/origin.", "schema": { "type": "string", "enum": [ "ONLINE", "MANUAL", "POS", "WHOLESALE", "BOOKING", "SUBSCRIPTION", "RENEWAL" ] } }, { "name": "commercialStatus", "required": false, "in": "query", "description": "Filter by commercial status.", "schema": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] } }, { "name": "primaryStatus", "required": false, "in": "query", "description": "Filter by the same type-aware lifecycle projected as primaryStatus. A tenant-owned linked ORDER matches its Order processing status; quotes, invoices, and unlinked orders match commercialStatus. CANCELLED can match either lifecycle. Composes with type and cursor pagination.", "schema": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED", "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED" ] } }, { "name": "paymentStatus", "required": false, "in": "query", "description": "Filter by payment status.", "schema": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] } }, { "name": "fulfillmentStatus", "required": false, "in": "query", "description": "Filter by fulfillment status.", "schema": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ] } }, { "name": "customerId", "required": false, "in": "query", "description": "Filter to a single customer id.", "schema": { "type": "string" } }, { "name": "customerEmail", "required": false, "in": "query", "description": "Filter to records for a customer email. Matched on the normalized (`lower(trim(...))`) form against the index-backed `customerEmailNormalized` column, so casing/whitespace do not matter. Independent of `customerId` (a record may carry an email without a linked customer account).", "schema": { "maxLength": 320, "type": "string" } }, { "name": "externalSource", "required": false, "in": "query", "description": "Filter by the external source system (with `externalId`).", "schema": { "type": "string" } }, { "name": "externalId", "required": false, "in": "query", "description": "Filter by external id (scoped to `externalSource`).", "schema": { "type": "string" } }, { "name": "createdFrom", "required": false, "in": "query", "description": "Only records created at or after this ISO-8601 timestamp.", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdTo", "required": false, "in": "query", "description": "Only records created at or before this ISO-8601 timestamp.", "schema": { "format": "date-time", "type": "string" } }, { "name": "totalMin", "required": false, "in": "query", "description": "Only records with total ≥ this (cents).", "schema": { "minimum": 0, "format": "int32", "type": "integer" } }, { "name": "totalMax", "required": false, "in": "query", "description": "Only records with total ≤ this (cents).", "schema": { "minimum": 0, "format": "int32", "type": "integer" } }, { "name": "balanceDueMin", "required": false, "in": "query", "description": "Only records with balance due ≥ this (cents).", "schema": { "minimum": 0, "format": "int32", "type": "integer" } }, { "name": "balanceDueMax", "required": false, "in": "query", "description": "Only records with balance due ≤ this (cents).", "schema": { "minimum": 0, "format": "int32", "type": "integer" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort axis. Each is index-backed; defaults to newest-first by creation.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "updatedAt", "total", "balanceDue" ] } }, { "name": "order", "required": false, "in": "query", "description": "Sort direction.", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Master Sales list/search across commerce documents.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/payment-transactions": { "get": { "description": "Read-only active-organization ledger ordered by transaction business timestamp then id, both descending. Supports direction, status, method, payable record type, and full ISO-8601 occurrence bounds. Each row includes safe linked Sales-record/customer display context; processor and idempotency internals are not exposed.", "operationId": "MerchantCommerceController_listPaymentTransactionsAcrossRecords", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque `(occurredAt,id)` seek cursor returned by the previous cross-record ledger page.", "schema": { "maxLength": 1024, "type": "string" } }, { "name": "direction", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PAYMENT", "REFUND", "REFUND_REVERSAL" ] } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "COMPLETED", "FAILED", "VOIDED" ] } }, { "name": "method", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "CARD", "OTHER" ] } }, { "name": "recordType", "required": false, "in": "query", "description": "Filter to invoice or order transactions.", "schema": { "type": "string", "enum": [ "INVOICE", "ORDER" ] } }, { "name": "occurredFrom", "required": false, "in": "query", "description": "Inclusive lower bound on the transaction business timestamp. Must be a full ISO-8601 timestamp.", "schema": { "format": "date-time", "type": "string" } }, { "name": "occurredTo", "required": false, "in": "query", "description": "Inclusive upper bound on the transaction business timestamp. Must be a full ISO-8601 timestamp.", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePaymentLedgerListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List commerce payment/refund transactions across Sales records.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/customers": { "get": { "description": "Tenant-scoped customer search over the org `customers`. A blank `search` returns the most-recent customers as a default list; otherwise matches name or (normalized) email case-insensitively. Capped, newest-first, unpaginated — feeds a filter-bar picker that resolves a chosen customer to its `customerId`.", "operationId": "MerchantCommerceController_searchCustomers", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Typeahead term — matches customer name or email (case-insensitive).", "schema": { "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum matches to return.", "schema": { "minimum": 1, "maximum": 25, "format": "int32", "default": 10, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceCustomerOptionListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Customer typeahead for the Sales-list customer picker (#1346).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}": { "get": { "operationId": "MerchantCommerceController_getQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCommerceRecordReadDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a quote record by id (with revisions + lines).", "tags": [ "merchant-commerce" ] }, "patch": { "operationId": "MerchantCommerceWriteController_updateQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceRecordDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update editable fields on a DRAFT quote.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}": { "get": { "operationId": "MerchantCommerceController_getInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCommerceRecordReadDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read an invoice record by id (with revisions + lines).", "tags": [ "merchant-commerce" ] }, "patch": { "operationId": "MerchantCommerceWriteController_updateInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceRecordDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update editable fields on a DRAFT invoice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}": { "get": { "operationId": "MerchantCommerceController_getOrder", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCommerceRecordReadDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read an order record by id (with revisions + lines).", "tags": [ "merchant-commerce" ] }, "patch": { "operationId": "MerchantCommerceWriteController_updateOrder", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceRecordDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update editable fields on a DRAFT manual order.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/contracts/{id}": { "get": { "operationId": "MerchantCommerceController_getContract", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceContractPacketDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a contract/signature packet by id (with signature requests).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/payments": { "get": { "operationId": "MerchantCommerceController_listInvoicePayments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor — the `id` of the last entry from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePaymentTransactionListDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read an invoice's payment/refund ledger entries (#1336), newest-first.", "tags": [ "merchant-commerce" ] }, "post": { "operationId": "MerchantCommercePaymentController_recordInvoicePayment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": false, "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommercePaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record a manual/offline payment against an issued invoice (SENT/ACCEPTED).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/payments": { "get": { "operationId": "MerchantCommerceController_listOrderPayments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor — the `id` of the last entry from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePaymentTransactionListDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read an order's payment/refund ledger entries (#1336), newest-first.", "tags": [ "merchant-commerce" ] }, "post": { "operationId": "MerchantCommercePaymentController_recordOrderPayment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": false, "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommercePaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record a manual/offline payment against an issued order (SENT/ACCEPTED).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/activity": { "get": { "description": "Cursor-paginated `commerce_activity_events` for the record — the customer-visible / money-moving / status-changing / permission-sensitive axes, actor, status transition, reason, and diagnostic metadata. Type-agnostic; a cross-tenant id returns a neutral 404.", "operationId": "MerchantCommerceController_listActivity", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor — the `id` of the last event from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActivityEventListDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read a record's activity timeline (#598), newest-first.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}": { "get": { "description": "Type-agnostic detail read. Returns a neutral 404 (`RESOURCE_NOT_FOUND`) when no record in the active org matches the id.", "operationId": "MerchantCommerceController_getRecord", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCommerceRecordReadDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read any commerce record by id (with revisions + lines).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes": { "post": { "description": "Requires minimum context: at least one of `customerId`, `customerName`, `customerEmail`, `customerPhone`, `companyName`, or `externalId` must be a non-blank string — a fully blank create is rejected with 400 `VALIDATION_FAILED` (#1463).", "operationId": "MerchantCommerceWriteController_createQuote", "parameters": [ { "name": "x-idempotency-key", "required": false, "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceRecordDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a DRAFT quote.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices": { "post": { "description": "Requires minimum context: at least one of `customerId`, `customerName`, `customerEmail`, `customerPhone`, `companyName`, or `externalId` must be a non-blank string — a fully blank create is rejected with 400 `VALIDATION_FAILED` (#1463).", "operationId": "MerchantCommerceWriteController_createInvoice", "parameters": [ { "name": "x-idempotency-key", "required": false, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceRecordDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a DRAFT invoice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders": { "post": { "description": "Manual order creation is secondary to quote/invoice flows; gated on `orders:operate` pending a dedicated shared-commerce orders permission. Requires minimum context: at least one of `customerId`, `customerName`, `customerEmail`, `customerPhone`, `companyName`, or `externalId` must be a non-blank string — a fully blank create is rejected with 400 `VALIDATION_FAILED` (#1463).", "operationId": "MerchantCommerceWriteController_createOrder", "parameters": [ { "name": "x-idempotency-key", "required": false, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceRecordDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a DRAFT manual order.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{recordId}/fulfillment-rollup/rebuild": { "post": { "description": "Recomputes the tenant-scoped Commerce and linked legacy Order projections from exact PRODUCT-line quantities on SHIPPED and DELIVERED fulfillments. PLANNED, READY, and CANCELLED work contributes zero handed-off quantity. Safe materialized drift is corrected atomically; historical line-less or otherwise ambiguous evidence fails closed with 409 and requires explicit reconciliation. A cross-tenant or missing ORDER record returns 404.", "operationId": "MerchantCommerceFulfillmentController_rebuildRollup", "parameters": [ { "name": "recordId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Rebuild one order fulfillment rollup from its line ledger.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{recordId}/fulfillments/{fulfillmentId}/cancel": { "post": { "description": "Moves one PLANNED or READY fulfillment to CANCELLED while retaining its line history and the active order stock reservation. Matching retries are read-only. SHIPPED or DELIVERED work must use returns, and any active or ambiguous postage fails closed until its label is reconciled or voided.", "operationId": "MerchantCommerceFulfillmentController_cancel", "parameters": [ { "name": "recordId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel one unshipped fulfillment with no active or ambiguous postage.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{recordId}/fulfillments/{fulfillmentId}/acknowledge-external-label-retirement": { "post": { "description": "Owner/Admin-only, reasoned package-local acknowledgement for exact external tracking or legacy already-retired label evidence. The merchant explicitly accepts responsibility for any external carrier void and carrier-account refund. The server snapshots the retained evidence and then invokes canonical fulfillment cancellation in one transaction. This is not provider proof, never rewrites label history as provider-confirmed retirement, and cannot bypass current or ambiguous native postage. It does not refund the customer, promise carrier credit, consume inventory, or send customer email.", "operationId": "MerchantCommerceFulfillmentController_acknowledgeExternalLabelRetirement", "parameters": [ { "name": "recordId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "description": "Required stable acknowledgement key. Matching retries replay the recorded cancellation; reuse for another actor, reason, or target returns 409.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeExternalLabelRetirementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeExternalLabelRetirementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Acknowledge externally managed label retirement and cancel one prepared shipment.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{recordId}/fulfillments/{fulfillmentId}/handoff": { "post": { "description": "Moves exactly one READY shipment to SHIPPED after the merchant confirms physical carrier custody. The command consumes only that fulfillment's line reservations, recomputes fulfillment rollups from SHIPPED/DELIVERED evidence, and durably records whether the customer shipment notification was sent or suppressed. Requires a stable `x-idempotency-key` for safe retries.", "operationId": "MerchantCommerceFulfillmentController_handoff", "parameters": [ { "name": "recordId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "description": "Required stable handoff key. Matching retries replay; reuse with a different fulfillment, notification decision, or tracking number returns 409.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffCommerceFulfillmentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record carrier handoff for one prepared shipment.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{recordId}/fulfillments/{fulfillmentId}/deliver": { "post": { "description": "Moves exactly one SHIPPED shipment to DELIVERED on the merchant's own assertion that the recipient received it. A carrier pickup scan is not required; a valid recorded handoff is. The command durably stores the authenticated actor, a required reason, the asserted delivery time, the server-recorded time, and an explicit MERCHANT_CONFIRMED provenance that must never be presented as carrier confirmation. It moves no inventory, changes no fulfillment rollup (SHIPPED and DELIVERED are the same rollup class), and creates no email, return, refund, or label effect. Requires a stable `x-idempotency-key` for safe retries.", "operationId": "MerchantCommerceFulfillmentController_deliver", "parameters": [ { "name": "recordId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fulfillmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "description": "Required stable delivery key. Matching retries replay read-only; reuse with a different fulfillment, asserted time, or reason returns 409.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverCommerceFulfillmentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record merchant-confirmed delivery for one exact shipment.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/fulfillments": { "post": { "description": "Creates one outbound CommerceFulfillment in SHIPPED status with explicit positive PRODUCT line quantities. SERVICE, CUSTOM, FEE, DEPOSIT, and ADJUSTMENT lines are not shipment-eligible. The command serializes concurrent writes, prevents cumulative over-fulfillment, consumes linked inventory reservations exactly once, and derives both shared-commerce and linked legacy Order rollups. Explicit REPLACEMENT_GOODS commands require matching ReturnItem and original handed-off allocation links, consume replacement stock separately, and never inflate the original order rollup. Optional tracking fields use the same fulfillment row. The mode defaults to SHIPMENT. The required `notify` field durably records SEND or SUPPRESS; non-shipment modes require suppression. Requires a stable `x-idempotency-key` for safe retries.", "operationId": "MerchantCommerceFulfillmentController_create", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required stable key. Matching retries replay; reuse with a different record, line quantity, notification decision, or tracking payload returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceFulfillmentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fulfill explicit line quantities on an ORDER commerce record.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/composed-products": { "post": { "description": "Revision-guarded, atomic expansion into one typed PACKAGE/KIT group and its ordered component lines. Current Catalog, Inventory, and BookingService authorities are validated before any write; fixed-price component money uses commercial quantity one while frozen effectiveQuantity remains operational truth.", "operationId": "MerchantCommerceLinesController_selectComposedProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectComposedProductDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Select one catalog package/kit into an editable DRAFT record.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/composed-products/{groupId}": { "delete": { "description": "Deletes the generated group and all of its component lines atomically, then reprices the remaining bespoke and composed Sales content.", "operationId": "MerchantCommerceLinesController_removeComposedProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "groupId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove one generated package/kit selection from an editable DRAFT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/lines": { "post": { "operationId": "MerchantCommerceLinesController_addLine", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceLineDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Add a line to a DRAFT record.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/lines/{lineId}": { "patch": { "operationId": "MerchantCommerceLinesController_updateLine", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceLineDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a line on a DRAFT record.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceLinesController_removeLine", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove a line from a DRAFT record.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/groups": { "post": { "operationId": "MerchantCommerceLinesController_addGroup", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceLineGroupDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Add a line group to a DRAFT record.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/groups/{groupId}": { "patch": { "operationId": "MerchantCommerceLinesController_updateGroup", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "groupId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceLineGroupDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a line group on a DRAFT record.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceLinesController_removeGroup", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "groupId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove a line group from a DRAFT record (ungroups its lines).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/reprice": { "post": { "description": "Builds a pricing context from the persisted lines and freezes a priced snapshot via the shared pricing engine, then syncs the record + line rollups. Persisted manual overrides (#1349 price/discount/tax) are re-applied as reasoned engine inputs on every reprice. An action on an existing record (200), not a creation. Document-level shipping inputs are a follow-up.", "operationId": "MerchantCommerceLinesController_reprice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reprice a DRAFT record from its current lines.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/lines/{lineId}/price-override": { "put": { "operationId": "MerchantCommerceOverridesController_setLinePriceOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLinePriceOverrideDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set a reasoned manual unit-price override on a line of a DRAFT record and reprice.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceOverridesController_clearLinePriceOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceOverrideActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Clear the line price override (restores the pre-override unit price) and reprice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/lines/{lineId}/discount-override": { "put": { "operationId": "MerchantCommerceOverridesController_setLineDiscountOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDiscountOverrideDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set a reasoned manual discount (fixed cents or percent) on a line of a DRAFT record and reprice.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceOverridesController_clearLineDiscountOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "lineId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceOverrideActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove the manual line discount and reprice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/discount-override": { "put": { "operationId": "MerchantCommerceOverridesController_setDocumentDiscountOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDiscountOverrideDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set a reasoned manual document-level discount (allocated across lines) on a DRAFT record and reprice.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceOverridesController_clearDocumentDiscountOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceOverrideActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Remove the manual document-level discount and reprice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/tax-override": { "put": { "operationId": "MerchantCommerceOverridesController_setTaxOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTaxOverrideDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set a reasoned document tax-treatment override on a DRAFT record and reprice.", "tags": [ "merchant-commerce" ] }, "delete": { "operationId": "MerchantCommerceOverridesController_clearTaxOverride", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceOverrideActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Clear the tax override (restores the pre-override tax treatment) and reprice.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/send": { "post": { "operationId": "MerchantCommerceLifecycleController_sendQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCommerceRecordDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCommerceResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Send a DRAFT quote — freeze the revision, allocate the display number, DRAFT→SENT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/send": { "post": { "operationId": "MerchantCommerceLifecycleController_sendInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCommerceRecordDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCommerceResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Send a DRAFT invoice / payment request — freeze, allocate the display number, DRAFT→SENT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/accept": { "post": { "operationId": "MerchantCommerceLifecycleController_acceptQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Accept a SENT quote on behalf of the customer — SENT→ACCEPTED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/void": { "post": { "operationId": "MerchantCommerceLifecycleController_voidQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Void an issued quote — SENT|ACCEPTED→VOIDED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/void": { "post": { "operationId": "MerchantCommerceLifecycleController_voidInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Void an issued invoice — SENT|ACCEPTED→VOIDED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/cancel": { "post": { "operationId": "MerchantCommerceLifecycleController_cancelQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel a quote not yet accepted — DRAFT|SENT→CANCELLED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/cancel": { "post": { "operationId": "MerchantCommerceLifecycleController_cancelInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel an invoice not yet accepted — DRAFT|SENT→CANCELLED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/revise": { "post": { "operationId": "MerchantCommerceLifecycleController_reviseQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revise a SENT|ACCEPTED quote — supersede the customer-visible revision and open a new DRAFT clone, record→DRAFT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/revise": { "post": { "operationId": "MerchantCommerceLifecycleController_reviseInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Revise a SENT|ACCEPTED invoice — supersede the customer-visible revision and open a new DRAFT clone, record→DRAFT.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/quotes/{id}/convert": { "post": { "operationId": "MerchantCommerceLifecycleController_convertQuote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Convert an ACCEPTED quote into a committed order — spawns the order (carrying the accepted snapshot), quote→CONVERTED.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/terminal/connection-token": { "post": { "operationId": "MerchantCommercePaymentController_createInvoiceTerminalConnectionToken", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceTerminalRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceTerminalConnectionTokenDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a Stripe Terminal connection token for collecting an invoice balance in person.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/terminal/payment-intent": { "post": { "operationId": "MerchantCommercePaymentController_createInvoiceTerminalPaymentIntent", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required idempotency key for safe Terminal retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceTerminalRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceTerminalPaymentIntentDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "COMMERCE_PAYMENT_INVALID: an unresolved capture case, evidence conflict (including closed cases), unreconciled missing signed amount, unreconciled refund evidence before a capture case, or open signed-currency payment exception blocks Terminal creation, replacement and reusable credential handoff with details.reason CAPTURE_RECONCILIATION_REQUIRED. Reconcile the payment before further collection; another operation key does not bypass the hold. Other existing payment conflicts also return 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Terminal collection is temporarily unavailable, including when capture schema readiness cannot be confirmed. Retry with the same idempotency key after availability recovers; do not start a replacement payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a Stripe Terminal card-present PaymentIntent for the invoice's balance due.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/terminal/connection-token": { "post": { "operationId": "MerchantCommercePaymentController_createOrderTerminalConnectionToken", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceTerminalRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceTerminalConnectionTokenDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a Stripe Terminal connection token for collecting an order balance in person.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/terminal/payment-intent": { "post": { "operationId": "MerchantCommercePaymentController_createOrderTerminalPaymentIntent", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required idempotency key for safe Terminal retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommerceTerminalRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceTerminalPaymentIntentDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "COMMERCE_PAYMENT_INVALID: an unresolved capture case, evidence conflict (including closed cases), unreconciled missing signed amount, unreconciled refund evidence before a capture case, or open signed-currency payment exception blocks Terminal creation, replacement and reusable credential handoff with details.reason CAPTURE_RECONCILIATION_REQUIRED. Reconcile the payment before further collection; another operation key does not bypass the hold. Other existing payment conflicts also return 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Terminal collection is temporarily unavailable, including when capture schema readiness cannot be confirmed. Retry with the same idempotency key after availability recovers; do not start a replacement payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a Stripe Terminal card-present PaymentIntent for the order's balance due.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/refunds": { "post": { "operationId": "MerchantCommercePaymentController_recordInvoiceRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": false, "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommercePaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record a manual/offline refund against an invoice — cannot exceed net paid.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/refunds/stripe": { "post": { "operationId": "MerchantCommercePaymentController_issueInvoiceStripeRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required idempotency key for safe refund retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueCommerceStripeRefundDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Issue a Stripe refund to the original card for an online invoice payment (#1630).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/invoices/{id}/refunds/stripe/preparation": { "get": { "description": "Returns the exact LINE/SHIPPING components an operator may allocate a Stripe refund across. Author `allocations` from this projection: the issue endpoint requires it and never derives the split server-side.", "operationId": "MerchantCommercePaymentController_prepareInvoiceStripeRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundAllocationPreparationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the refundable components and remaining cents for an invoice card refund (#3056).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/refunds/stripe/preparation": { "get": { "description": "Returns the exact LINE/SHIPPING components an operator may allocate a Stripe refund across. Author `allocations` from this projection: the issue endpoint requires it and never derives the split server-side.", "operationId": "MerchantCommercePaymentController_prepareOrderStripeRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundAllocationPreparationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the refundable components and remaining cents for an order card refund (#3056).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/refunds/stripe": { "post": { "operationId": "MerchantCommercePaymentController_issueOrderStripeRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Required idempotency key for safe refund retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueCommerceStripeRefundDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Issue a Stripe refund to the original card for an online order payment (#1630).", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/orders/{id}/refunds": { "post": { "operationId": "MerchantCommercePaymentController_recordOrderRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": false, "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommercePaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Record a manual/offline refund against an order — cannot exceed net paid.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/capture-cases": { "get": { "description": "Same tenant-qualified membership read boundary as Sales record payment detail. Whitelisted evidence only; no raw webhook or provider-account identities.", "operationId": "MerchantCommerceCaptureController_list", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque nextCursor from this record’s preceding page. Omit for the newest page. On acceptance, controls only the returned page; it grants no action authority.", "schema": { "maxLength": 1024, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceCaptureCaseListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Capture reconciliation is temporarily unavailable while required schema readiness cannot be confirmed. No new money is created; retry the same read after readiness recovers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read prospective capture reconciliation cases.", "tags": [ "merchant-commerce" ] } }, "/api/v1/merchant/commerce/{id}/capture-cases/{caseId}/accept": { "post": { "description": "Evidence-only, idempotent on the capture. Requires manual-payment and record-type permissions plus high-risk reason. Posts the full signed amount once only after current currency, identity, status, cap and zero-successful-refund checks. A durable refusal returns the still-open case with its structured reason. Performs no provider operation.", "operationId": "MerchantCommerceCaptureController_accept", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "caseId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque nextCursor from this record’s preceding page. Omit for the newest page. On acceptance, controls only the returned page; it grants no action authority.", "schema": { "maxLength": 1024, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptCommerceCaptureDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceCaptureCaseListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Retryable conflict: COMMERCE_PAYMENT_INVALID/CONCURRENT_UPDATE or an in-progress idempotency operation. Reload the case and retry the same evidence-bound acceptance; never start a replacement payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Capture reconciliation is temporarily unavailable while required schema readiness cannot be confirmed. Reload the case and retry the same evidence-bound acceptance after readiness recovers; never start a replacement payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Accept the exact captured payment into the ledger.", "tags": [ "merchant-commerce" ] } }, "/api/v1/customer/commerce/quotes/{tokenOrId}": { "get": { "operationId": "CustomerCommerceController_getQuote", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family quote action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceDocumentDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The addressed revision was superseded by a newer version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read a customer-scoped quote revision by action token. Pure read — never consumes the token.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/invoices/{tokenOrId}": { "get": { "operationId": "CustomerCommerceController_getInvoice", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family invoice action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceDocumentDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The addressed revision was superseded by a newer version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read a customer-scoped invoice / payment request by action token. Pure read.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/invoices/{tokenOrId}/pay": { "post": { "operationId": "CustomerCommerceController_payInvoice", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family invoice action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInvoicePaymentDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The invoice is not payable (already paid, not open, or superseded).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "502": { "description": "Payments are not available for this document (merchant account not ready).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Start an online card payment for an invoice balance — returns the Stripe PaymentIntent client secret.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/quotes/{tokenOrId}/accept": { "post": { "operationId": "CustomerCommerceController_acceptQuote", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family quote action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceDocumentDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The quote is no longer open (already accepted/declined/voided) or was superseded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Accept a quote by action token (SENT→ACCEPTED). Single-use; idempotent on replay.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/quotes/{tokenOrId}/decline": { "post": { "operationId": "CustomerCommerceController_declineQuote", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family quote action token.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineCommerceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceDocumentDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The quote is no longer open, expired, or was superseded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Decline a quote by action token (SENT→DECLINED, record-only). Single-use; idempotent on replay.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/contracts/{tokenOrId}": { "get": { "operationId": "CustomerCommerceController_getContract", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family contract action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerContractPacketDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read a customer-scoped contract/signature packet by action token. Pure read.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/commerce/contracts/{tokenOrId}/sign": { "post": { "operationId": "CustomerCommerceController_signContract", "parameters": [ { "name": "tokenOrId", "required": true, "in": "path", "description": "Raw `a`-family contract action token.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignContractDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerContractPacketDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The contract is not open for signature (signed/declined/voided/expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "First-party sign a contract by action token. Single-use; idempotent on replay. Captures signer IP/UA.", "tags": [ "customer-commerce" ] } }, "/api/v1/customer/account/commerce": { "get": { "description": "Documents the merchant has SENT to this buyer (drafts never appear), newest-first, offset-paginated, projected from the latest customer-visible revision. A document being revised shows `stale: true` until the updated version is sent. Empty when the tenant has disabled the account commerce surface.", "operationId": "CustomerCommerceAccountController_list", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "Filter to one document type; both when omitted.", "schema": { "type": "string", "enum": [ "QUOTE", "INVOICE" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "format": "int32", "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 50, "format": "int32", "default": 20, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's quotes and invoices (#598).", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/commerce/{displayNumber}": { "get": { "description": "Detail of the latest customer-visible revision (summary + lines). Neutral 404 for anything that isn’t this buyer’s sent document.", "operationId": "CustomerCommerceAccountController_detail", "parameters": [ { "name": "displayNumber", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCommerceDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the quote/invoice carries package pricing that can no longer be displayed safely. THE DOCUMENT IS UNAFFECTED and remains valid; only this presentation of it is withheld, and no order is involved. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch. Do not treat it as a document defect, do not re-issue or duplicate the document, and do not apply order-recovery behaviour — re-read once the composition is republished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read one of the customer’s documents by its public number (#598).", "tags": [ "customer-account" ] } }, "/api/v1/merchant/pos/session": { "post": { "operationId": "MerchantPosSessionController_register", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPosSessionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSessionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Register or resume a revocable litecommerce POS session.", "tags": [ "merchant-pos" ] }, "delete": { "operationId": "MerchantPosSessionController_revoke", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSessionRevocationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Revoke the current litecommerce POS session.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/session/organization": { "put": { "operationId": "MerchantPosSessionController_selectOrganization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectPosOrganizationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSessionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Select an authorized organization for this POS session.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/customers": { "get": { "description": "Requires a live POS session. The server-owned POS session selects the active organization; an x-organization-slug header, when supplied, must match it and cannot switch tenants. Searches canonical Customer name and normalized email only. Results use fixed createdAt/id descending keyset order and exclude archived Customers by default.", "operationId": "MerchantPosCustomerController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Case-insensitive substring search over canonical Customer name and normalized email only.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum customers to return, newest first.", "schema": { "minimum": 1, "maximum": 50, "format": "int32", "default": 25, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque server-owned cursor returned by the previous page. Bound to this route, tenant, search value, fixed ordering, and caller capability set.", "schema": { "maxLength": 500, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosCustomerListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "List tenant Customers for selection in litecommerce POS.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/customers/{customerId}": { "get": { "description": "Requires a live POS session. The server-owned POS session selects the active organization; an x-organization-slug header, when supplied, must match it and cannot switch tenants. Archived Customers remain addressable. Unknown and cross-tenant ids return the same neutral 404.", "operationId": "MerchantPosCustomerController_detail", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosCustomerIdentityDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Read one tenant Customer identity profile for litecommerce POS.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/catalog/items": { "get": { "operationId": "MerchantPosController_listCatalog", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Case-insensitive product search over name and description.", "schema": { "maxLength": 120, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum products to return.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosCatalogPageDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "List active sellable catalog items for litecommerce POS.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/preflight": { "get": { "operationId": "MerchantPosController_preflight", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosPreflightResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify that the tenant can create and collect a POS sale.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/sales": { "post": { "operationId": "MerchantPosController_createSale", "parameters": [ { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Stable key for one sale intent. A matching retry returns the original order/invoice pair.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePosSaleDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSaleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Atomically create a server-priced POS order and issued invoice.", "tags": [ "merchant-pos" ] }, "get": { "operationId": "MerchantPosController_listSales", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum sales to return, newest first.", "schema": { "minimum": 1, "maximum": 50, "default": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor returned as nextCursor by the previous page. Server-owned; never constructed by the client.", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSaleListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "List this tenant POS sales history, newest first, anchored on the order.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/sales/{orderId}": { "get": { "operationId": "MerchantPosController_getSale", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosSaleResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Read the authoritative POS order and linked invoice state.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/invoices/{invoiceId}/terminal/connection-token": { "post": { "operationId": "MerchantPosController_createInvoiceTerminalConnectionToken", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosTerminalConnectionTokenDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a connected-account Terminal token for litecommerce POS Tap to Pay.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/pos/invoices/{invoiceId}/terminal/payment-intent": { "post": { "operationId": "MerchantPosController_createInvoiceTerminalPaymentIntent", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "required": true, "in": "header", "description": "Stable operation key for safe Tap to Pay retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosTerminalPaymentIntentDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "COMMERCE_PAYMENT_INVALID with details.reason CAPTURE_RECONCILIATION_REQUIRED blocks Terminal creation, replacement and reusable credential handoff while the invoice has unresolved capture evidence, including closed-case conflicts, unreconciled missing signed amounts, unreconciled refund evidence before a capture case, or an open signed-currency payment exception. Reconcile the payment before further collection; another operation key does not bypass the hold. Other existing payment conflicts also return 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a card-present PaymentIntent for a POS invoice's full balance.", "tags": [ "merchant-pos" ] } }, "/api/v1/merchant/customers": { "get": { "description": "Charter §3 fixed operational directory: name and normalized-email search, stable keyset pagination, three fixed sorts, and the verification / date / domain-presence / archive filters. The `DR-3032-20-A` account-status facet replaces the former Unlinked-purchasers queue — there is no separate queue surface. Archived customers are hidden unless explicitly requested. Excluded by charter: customizable views, saved segments, scoring, first-time/returning classification, arbitrary exports, phone search, and \"needs attention\" logic. API `displayName` is `name ?? \"Guest\"`: only `null` selects the fallback; empty and whitespace-only names pass through unchanged. For presentation, preserve the API value for a nonblank canonical name, regardless of account status. Otherwise, `REGISTERED` rows display `Unnamed customer`; `GUEST` rows keep a nonblank API display value or use `Unnamed customer` if it is blank. Use `name` to identify the fallback; a stored name of `Guest` is preserved. An unverified Customer may still carry canonical name/phone. Name search uses the canonical name, never an order-only name. ADR-047 adds only a permission-aware accepted-order PRESENCE result: an authorized `false` supports “No accepted orders yet.” and never implies a failed payment, purchaser status, spend, LTV, AOV, conversion, verification, consent, or marketing membership. Tombstoned Customers are not active directory identities and are never returned.", "operationId": "MerchantCustomerDirectoryController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search over canonical name and normalized email. Case-insensitive substring match, regardless of account status. An unverified Customer is searchable by its stored canonical name. Order-only names are not searched (`DR-3032-24-A`); rows with null or blank names remain searchable by normalized email. Phone search is excluded by charter §3.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of customers to return.", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque keyset cursor from the previous page `nextCursor`. Treat it as opaque: its encoding is not part of this contract and changes with the sort. A cursor is bound to the sort, the organization, the caller's capability set and the filter set it was issued under; replaying it under a different one is rejected with `VALIDATION_FAILED` rather than silently returning a wrong page. Re-request the first page.", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order. Charter §3 fixes these three. `NAME` compares stored canonical names A–Z with `null` names last; empty and whitespace-only names participate as stored.", "schema": { "default": "CREATED", "type": "string", "enum": [ "CREATED", "NAME", "LAST_ACTIVITY" ] } }, { "name": "accountStatus", "required": false, "in": "query", "description": "Account-status facet (`DR-3032-20-A`), which replaces the Unlinked-purchasers queue. Also serves as charter §3 verification filter: under `DR-3032-22-A` verification promotes the same row in place, so the two are one predicate. Account status does not determine whether canonical name/phone are present.", "schema": { "type": "string", "enum": [ "GUEST", "REGISTERED" ] } }, { "name": "archived", "required": false, "in": "query", "description": "Archive posture. Defaults to `ACTIVE`: archived customers are hidden from the default result set and surfaced only when explicitly asked for. They remain addressable by id at all times.", "schema": { "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED", "ALL" ] } }, { "name": "domainPresence", "required": false, "in": "query", "description": "Restrict to customers with at least one authoritative record in this domain. Presence comes from a tenant-qualified link only — generalized email equality is never relationship authority (charter §8).", "schema": { "type": "string", "enum": [ "COMMERCE", "BOOKING", "SUBSCRIPTION" ] } }, { "name": "createdAfter", "required": false, "in": "query", "description": "Only customers created at or after this instant (ISO 8601).", "schema": { "type": "string" } }, { "name": "createdBefore", "required": false, "in": "query", "description": "Only customers created at or before this instant (ISO 8601).", "schema": { "type": "string" } }, { "name": "lastActivityAfter", "required": false, "in": "query", "description": "Only customers whose last authoritative activity is at or after this instant (ISO 8601). Customers with NO authoritative activity are excluded by this filter — absence is not a date, and treating it as one would silently rewrite \"unknown\" into \"old\".", "schema": { "type": "string" } }, { "name": "lastActivityBefore", "required": false, "in": "query", "description": "Only customers whose last authoritative activity is at or before this instant (ISO 8601). Customers with NO authoritative activity are excluded, for the same reason as `lastActivityAfter`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDirectoryListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Customer directory for the active org (cursor-paginated).", "tags": [ "merchant-customer-directory" ] } }, "/api/v1/merchant/customers/{id}": { "get": { "description": "`DR-3032-08-A` hybrid model: the list is a projection, this detail is read live. API `displayName` is `name ?? \"Guest\"`: only `null` selects the fallback; empty and whitespace-only names pass through unchanged. For presentation, preserve the API value for a nonblank canonical name, regardless of account status. Otherwise, `REGISTERED` rows display `Unnamed customer`; `GUEST` rows keep a nonblank API display value or use `Unnamed customer` if it is blank. Use `name` to identify the fallback; a stored name of `Guest` is preserved. An unverified Customer may still carry canonical name/phone. Carries every distinct order-derived name / phone / address variant for the customer (`DR-3032-24-A`), reached ONLY through the accepted `CommerceRecord` association from #3233 and its owning order — never by email equality, which charter §8 forbids as relationship authority. Snapshots are read, never rewritten. #3519 also carries a per-currency payment reconciliation sourced from completed litecommerce commerce-ledger rows on those tenant-qualified links. It explicitly marks Stripe Customer Insights as non-authoritative for money truth; it is not a net-sales or LTV summary. The accepted-order presence object follows the commerce capability; a restricted or unavailable result is unknown, never “no orders.” Addressable regardless of archive posture. Returns a neutral 404 for an unknown id and for an id belonging to another tenant, so the route cannot be used to probe for cross-tenant existence.", "operationId": "MerchantCustomerDirectoryController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDirectoryDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read one customer, including identity and payment reconciliation.", "tags": [ "merchant-customer-directory" ] } }, "/api/v1/public/items/{itemId}/reviews": { "post": { "description": "Public-facing capture for a storefront product-review form. Creates a PENDING review and returns immediately — the review is NOT visible on the storefront until a merchant approves it. Anyone can submit; reviews from an email matching a paid order for this item carry a verified-purchase badge (it never gates submission). Idempotent + enumeration-safe: the same author submitting twice for the same item gets the same response shape rather than a duplicate or an error revealing the prior review.", "operationId": "PublicProductReviewController_submit", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewDto" } } } }, "responses": { "201": { "description": "Review accepted for moderation. Returns a constant `{ ok: true }` — no review state or verified-purchase signal is echoed to the public caller (those surface only on approved reviews + the merchant queue).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Submit a product review (created PENDING; moderated).", "tags": [ "public-product-reviews" ] }, "get": { "description": "Returns only approved (PUBLISHED) reviews, newest first, with the display name only — an author email is NEVER returned. Includes the denormalized rating aggregate (`ratingAverage`, null when there are no reviews, + `ratingCount`). Cursor paginated via `nextCursor`. An unknown item id returns an empty list + a zero aggregate (same as \"no reviews yet\").", "operationId": "PublicProductReviewController_list", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of reviews to return.", "schema": { "minimum": 1, "maximum": 100, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating. Pass back the `nextCursor` value returned by the previous page. Currently a stringified review id; treat it as opaque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicItemReviewsResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "List PUBLISHED reviews + the rating aggregate for an item.", "tags": [ "public-product-reviews" ] } }, "/api/v1/merchant/reviews": { "get": { "description": "Newest first. Filter by status: `pending` (default — the moderation queue), `published` (approved + visible), `hidden` (approved but merchant-hidden), `rejected` (declined), `all` (every row). Includes the author email (a merchant surface — moderators need it to judge a review).", "operationId": "MerchantProductReviewController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "pending", "published", "hidden", "rejected", "all" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReviewModerationItemDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List product reviews for moderation.", "tags": [ "merchant-product-reviews" ] } }, "/api/v1/merchant/reviews/{id}/approve": { "post": { "description": "Publishes the review (makes it visible on the storefront) and adds its rating into the item aggregate, transactionally. Only valid from PENDING — an already-published or rejected review is a 409.", "operationId": "MerchantProductReviewController_approve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProductReviewDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Approve a PENDING review → PUBLISHED.", "tags": [ "merchant-product-reviews" ] } }, "/api/v1/merchant/reviews/{id}/reject": { "post": { "description": "Valid from PENDING (decline an un-moderated review) or PUBLISHED (true post-approval moderation rejection). When the review was PUBLISHED + visible, its rating is subtracted back out of the item aggregate transactionally. Use hide/show for non-punitive storefront visibility changes.", "operationId": "MerchantProductReviewController_reject", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProductReviewDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Reject a review → REJECTED.", "tags": [ "merchant-product-reviews" ] } }, "/api/v1/merchant/reviews/{id}/hide": { "post": { "description": "Valid only from PUBLISHED + visible. The moderation status remains PUBLISHED, visibility flips to HIDDEN, and the rating is removed from the public item aggregate transactionally.", "operationId": "MerchantProductReviewController_hide", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProductReviewDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Hide an approved review without rejecting it.", "tags": [ "merchant-product-reviews" ] } }, "/api/v1/merchant/reviews/{id}/show": { "post": { "description": "Valid only from PUBLISHED + hidden. The moderation status remains PUBLISHED, visibility flips to VISIBLE, and the rating is restored to the public item aggregate transactionally.", "operationId": "MerchantProductReviewController_show", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProductReviewDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Show a hidden approved review.", "tags": [ "merchant-product-reviews" ] } }, "/api/v1/customer/account/orders/by-reference/{orderReference}": { "get": { "description": "Requires a live tenant-bound CustomerSession and an existing durable ownership label for the exact referenced Order. Responses are private and non-cacheable.", "operationId": "CustomerOrderReferenceController_getOrder", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "description": "Stable customer-safe Order address. A reference never grants access by itself.", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128 } } ], "responses": { "200": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderByReferenceDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Get an owned order by its customer-safe reference.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders/by-reference/{orderReference}/returns": { "get": { "description": "Requires the live CustomerSession and exact durable Order ownership. Every return carries the stable parent reference.", "operationId": "CustomerOrderReferenceController_listReturns", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "description": "Stable customer-safe Order address. A reference never grants access by itself.", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128 } } ], "responses": { "200": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReturnListByReferenceResponseDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List returns for an owned reference-addressed order.", "tags": [ "customer-account" ] }, "post": { "description": "Customer identity comes from the live session and durable ownership; the request deliberately carries no customer email credential.", "operationId": "CustomerOrderReferenceController_createReturn", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "description": "Stable customer-safe Order address. A reference never grants access by itself.", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReturnByReferenceDto" } } } }, "responses": { "201": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReferenceReturnDto" } } } }, "400": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Create a return for an owned reference-addressed order.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders/by-reference/{orderReference}/returns/{returnId}/cancel": { "post": { "description": "The Return must belong to the exact tenant and referenced parent Order and remain in a customer-cancellable state.", "operationId": "CustomerOrderReferenceController_cancelReturn", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "description": "Stable customer-safe Order address. A reference never grants access by itself.", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128 } }, { "name": "returnId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReferenceReturnDto" } } } }, "400": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Cancel a return on an owned reference-addressed order.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders/by-reference/{orderReference}/return-actions": { "post": { "description": "Requires exact durable ownership. The issued token retains the existing seven-day tenant, Order, and purpose binding.", "operationId": "CustomerOrderReferenceController_issueReturnAction", "parameters": [ { "name": "orderReference", "required": true, "in": "path", "description": "Stable customer-safe Order address. A reference never grants access by itself.", "schema": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueReturnActionDto" } } } }, "responses": { "201": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueReturnActionByReferenceResponseDto" } } } }, "400": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } }, "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "headers": { "Cache-Control": { "description": "Private response; never store in a browser or intermediary.", "schema": { "type": "string", "example": "private, no-store" } }, "Pragma": { "description": "HTTP/1.0-compatible no-cache directive.", "schema": { "type": "string", "example": "no-cache" } }, "Vary": { "description": "Credential and tenant dimensions used by this response.", "schema": { "type": "string", "example": "x-organization-slug, Authorization, Cookie" } } }, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Issue a purpose-bound return action for an owned order.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/profile": { "get": { "description": "Email, name, phone, and email-verification timestamp.", "operationId": "CustomerAccountController_getProfile", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Get the authenticated customer’s profile.", "tags": [ "customer-account" ] }, "patch": { "description": "Only `name` and `phone` are editable — email (the identity key) and organization are never mutable here.", "operationId": "CustomerAccountController_updateProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Update the authenticated customer’s name and/or phone.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/addresses": { "get": { "operationId": "CustomerAccountController_listAddresses", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAddressResponseDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the customer’s saved addresses (newest first).", "tags": [ "customer-account" ] }, "post": { "description": "Setting `isDefaultShipping` / `isDefaultBilling` clears the prior default of that kind (at most one default of each per customer).", "operationId": "CustomerAccountController_createAddress", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAddressDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Add an address to the customer’s address book.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/addresses/{id}": { "get": { "operationId": "CustomerAccountController_getAddress", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Get one of the customer’s addresses by id.", "tags": [ "customer-account" ] }, "patch": { "description": "Patch any subset of fields. Promoting to a default clears the prior default of that kind.", "operationId": "CustomerAccountController_updateAddress", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAddressDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Update one of the customer’s addresses.", "tags": [ "customer-account" ] }, "delete": { "operationId": "CustomerAccountController_deleteAddress", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Address deleted." }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Delete one of the customer’s addresses.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders": { "get": { "description": "Scoped to checkout-origin orders carrying durable ownership authorized by a live matching customer session within this tenant. Captured order email alone never grants account-history access.", "operationId": "CustomerAccountController_listOrders", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "1-based page number.", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Page size.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the customer’s orders (newest first, paginated).", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders/{orderNumber}": { "get": { "description": "Addressed by the public `orderNumber` (never a raw DB id). A foreign order number is a soft 404.", "operationId": "CustomerAccountController_getOrder", "parameters": [ { "name": "orderNumber", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`COMPOSITION_REVISION_STALE` — the order carries package pricing that can no longer be displayed safely. The ORDER IS UNAFFECTED and remains valid; only this presentation of it is withheld. Clients that fail closed on an undocumented `409` should match this code BEFORE that generic branch, so a recoverable staleness is not mistaken for a contract violation — on an order read the generic branch discards the one fact that matters, and a client that loses it is one step from creating a replacement order for an order that is fine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Get one of the customer’s orders by its public order number.", "tags": [ "customer-account" ] } }, "/api/v1/customer/account/orders/{orderNumber}/returns": { "get": { "description": "The order is addressed by public orderNumber and scoped to the session customer.", "operationId": "CustomerActionsController_listReturns", "parameters": [ { "name": "orderNumber", "required": true, "in": "path", "description": "Public order number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReturnListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List returns for one of the authenticated customer’s orders.", "tags": [ "customer-actions" ] } }, "/api/v1/customer/account/orders/{orderNumber}/return-actions": { "post": { "description": "Creates a short-lived action token that can preview and then submit the return request exactly once.", "operationId": "CustomerActionsController_issueReturnAction", "parameters": [ { "name": "orderNumber", "required": true, "in": "path", "description": "Public order number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueReturnActionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueReturnActionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Issue a scoped return-action token for one customer order.", "tags": [ "customer-actions" ] } }, "/api/v1/customer/actions/{token}": { "get": { "description": "The action token itself is the credential. The tenant slug is still required and must match the token tenant.", "operationId": "CustomerActionsController_previewAction", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Raw customer action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReturnActionPreviewDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Preview a scoped customer action token without consuming it.", "tags": [ "customer-actions" ] }, "post": { "description": "Consumes the token once. Repeating the same consume call returns the original result without performing the action again.", "operationId": "CustomerActionsController_consumeAction", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Raw customer action token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionConsumeResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Consume a scoped customer action token.", "tags": [ "customer-actions" ] } }, "/api/v1/merchant/payment-account": { "get": { "description": "Returns status, masked connected-account id, provider, connectedAt, and a nullable safe Stripe connected-account identity/requirements summary when available. Live charges require `status = VERIFIED`; everything else fails closed at the charge boundary (#930). The account id is masked and no Stripe secret/token, external account, person/company object, or submitted requirement value is ever returned.", "operationId": "MerchantPaymentAccountController_getStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccountStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active org's Stripe payment-account status.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/connect": { "post": { "description": "Mints a single-use, hashed-at-rest CSRF state bound to this org and returns the Stripe authorize URL to redirect the merchant to. After the merchant authorizes, Stripe redirects to the public callback which links the connected account. Returns 503 when Connect is not configured — missing `STRIPE_CONNECT_CLIENT_ID` / redirect URI, OR a missing `STRIPE_SECRET_KEY` (the callback code exchange needs it, so the start fails fast before minting state).", "operationId": "MerchantPaymentAccountController_startConnect", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartConnectResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Begin Stripe Connect (Standard) OAuth onboarding.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/refresh": { "post": { "description": "Interim manual re-check (until the durable `account.updated` webhook in #934): re-retrieves the connected account and re-derives `paymentAccountStatus`. Returns 400 when no account is linked, 503 when Stripe is not configured.", "operationId": "MerchantPaymentAccountController_refresh", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccountStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Re-check the connected account's status from Stripe.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/terminal-locations": { "get": { "description": "Returns one bounded page from the active tenant connected account, the current provider-verified default, and a nullable organization-address prefill suggestion. The suggestion is never applied implicitly. Fails closed unless the connected account is VERIFIED with card_payments active.", "operationId": "MerchantPaymentAccountController_listTerminalLocations", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "format": "int32", "default": 25, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque Stripe page cursor from `nextCursor`. Pass it back unchanged.", "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalLocationSetupResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List Stripe Terminal Locations and POS setup status.", "tags": [ "merchant-payment-account" ] }, "post": { "description": "Reasoned high-risk action that creates a location from the explicit merchant-supplied physical address on the active tenant connected account, re-retrieves it in that exact account, and atomically makes it the sole active default. Replacing an existing default follows the same high-risk controls and audit semantics as selecting an existing location. Organization and Stripe account identifiers are server-owned and cannot be supplied.", "operationId": "MerchantPaymentAccountController_createTerminalLocation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTerminalLocationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultTerminalLocationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Conflict reasons are machine-readable in details.reason. Correct PAYMENT_ACCOUNT_NOT_VERIFIED or CARD_PAYMENTS_NOT_ACTIVE before retrying. Retry CREATION_IN_PROGRESS after waiting, and PAYMENT_ACCOUNT_CHANGED or TERMINAL_LOCATION_MAPPING_CHANGED after refreshing. TERMINAL_LOCATION_UNAVAILABLE is not retryable for this organization and requires operator intervention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create and select a Stripe Terminal Location (high risk).", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/tap-to-pay/apple-account-link": { "post": { "description": "Reasoned high-risk action for the active tenant only. The server uses the tenant's exact connected Stripe account as `on_behalf_of`, uses the organization name as the merchant display name, and always enables Apple Account relinking. The short-lived HTTPS onboarding URL is returned once and is never persisted or included in audit metadata.", "operationId": "MerchantPaymentAccountController_createTapToPayAppleAccountLink", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TapToPayAppleAccountLinkResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Tap to Pay setup is not ready. `details.reason` is `PAYMENT_ACCOUNT_NOT_VERIFIED`, `CARD_PAYMENTS_NOT_ACTIVE`, or `PAYMENT_ACCOUNT_CHANGED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a Stripe-generated Tap to Pay Apple Account setup or relink URL.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/terminal-locations/default": { "put": { "description": "Reasoned high-risk adoption/switch. Re-retrieves the supplied location under the exact active tenant connected account before atomically making it the sole active default. Never accepts a Stripe account or organization id.", "operationId": "MerchantPaymentAccountController_adoptTerminalLocation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptTerminalLocationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultTerminalLocationResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Conflict reasons are machine-readable in details.reason. Correct PAYMENT_ACCOUNT_NOT_VERIFIED or CARD_PAYMENTS_NOT_ACTIVE before retrying. Retry PAYMENT_ACCOUNT_CHANGED or TERMINAL_LOCATION_MAPPING_CHANGED after refreshing. TERMINAL_LOCATION_UNAVAILABLE is not retryable for this organization and requires operator intervention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Verify and select an existing Stripe Terminal Location.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/merchant/payment-account/disconnect": { "post": { "description": "High-risk, reasoned action (#1445). Fails closed FIRST: clears the account linkage and sets `paymentAccountStatus = NONE` locally, so card payments and payment links stop immediately, THEN attempts best-effort Stripe OAuth deauthorization (outcome reported in the response and audit event; a Stripe-side failure never leaves the local state connected). `paymentAccountConnectedAt` is retained as historical first-connected metadata. Reconnect via the existing connect flow. Returns 400 when a `reason` is missing or no account is linked. Returns 409 when the linked Stripe account changes while disconnecting.", "operationId": "MerchantPaymentAccountController_disconnect", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighRiskReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectPaymentAccountResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "The linked Stripe account changed while disconnecting. Refresh and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Disconnect the active Stripe payment account.", "tags": [ "merchant-payment-account" ] } }, "/api/v1/public/csp-report": { "post": { "description": "Sink for the `report-uri` directive emitted by every litecommerce app-class CSP (and the API’s own policies). Accepts the legacy `application/csp-report` body and the Reporting API `application/reports+json` batch. Anonymous and fire-and-forget: the browser dispatches reports without tenant headers or credentials and ignores the response, so this endpoint always returns 204 — malformed or unrecognized payloads are absorbed, not rejected. `?app=` self-identifies the reporting app class; unknown values are recorded as `unknown`. Not an integrator surface — there is nothing to read back.", "operationId": "CspReportController_report", "parameters": [ { "name": "app", "required": false, "in": "query", "description": "App-class hint baked into each policy’s `report-uri` (a `@litecommerce/security-headers` CSP preset, or `api`).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Report accepted (or absorbed)." } }, "summary": "Collect a browser CSP violation report.", "tags": [ "public-csp-report" ] } }, "/api/v1/storefront/context": { "get": { "description": "The canonical \"verify my key + which tenant am I\" call for an external storefront backend. Requires the `storefront:read` scope. Returns the tenant org (id/slug/name/status/currency/timezone) plus the granted scopes. Authenticate with `x-api-key: .` — server-side only.", "operationId": "StorefrontController_getContext", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontContextResponseDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks the required scope, or org is suspended/archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Resolve the authenticated tenant storefront context.", "tags": [ "storefront" ] } }, "/api/v1/storefront/items": { "get": { "description": "Server-to-server catalog read for SSR/server caches. Requires `storefront:read` via `x-api-key` (server-side only). The tenant is resolved from the key, not from `x-organization-slug`. Reuses the browser-safe `PublicItemDto` projection and forces ACTIVE, non-archived items with the same bounded keyset pagination as `/public/items`.", "operationId": "StorefrontCatalogController_listItems", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Substring search over name, description, tags.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor for paginating large lists — the `id` of the last item from the previous page. The merchant paginated list returns this value as `nextCursor`; the public list endpoint returns a flat array, so use the `id` of the last item you received. Treat it as opaque.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by item type.", "schema": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List ACTIVE items for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/storefront/items/search": { "get": { "description": "Server-to-server item search for SSR/server caches. Requires `storefront:read` via `x-api-key` (server-side only). Results are tenant-scoped by the authenticated key, bounded server-side, and reuse the browser-safe `PublicItemDto` projection.", "operationId": "StorefrontCatalogController_searchItems", "parameters": [ { "name": "q", "required": true, "in": "query", "description": "Search term for active public catalog items.", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of search results to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Search ACTIVE items for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/storefront/items/{slug}": { "get": { "description": "Server-to-server PDP read. Requires `storefront:read` via `x-api-key` (server-side only). Missing, DRAFT, or archived slugs are masked as 404. The response reuses `PublicItemDto`, including public media, variants, prices, ratings, collection ids, and merchandising fields.", "operationId": "StorefrontCatalogController_getItemBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicItemDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No ACTIVE item matches the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Fetch one ACTIVE item by slug for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/storefront/collections": { "get": { "description": "Server-to-server navigation/collection-card read. Requires `storefront:read` via `x-api-key` (server-side only). The tenant is resolved from the key and the response reuses the browser-safe `PublicCollectionDto` projection.", "operationId": "StorefrontCatalogController_getCollections", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCollectionDto" } } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List ACTIVE collections for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/storefront/collections/{slug}/items": { "get": { "description": "Server-to-server collection-page read. Requires `storefront:read` via `x-api-key` (server-side only). DRAFT/archived parent collections return an empty array, matching `/public/collections/:slug/items`; DRAFT or archived items are hidden. Reuses `PublicItemDto`.", "operationId": "StorefrontCatalogController_getCollectionItems", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemDto" } } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List ACTIVE items in an ACTIVE collection for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/storefront/collections/{slug}": { "get": { "description": "Server-to-server collection read. Requires `storefront:read` via `x-api-key` (server-side only). Missing, DRAFT, or archived slugs are masked as 404. The response reuses `PublicCollectionDto`.", "operationId": "StorefrontCatalogController_getCollectionBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCollectionDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `storefront:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No ACTIVE collection matches the slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Fetch one ACTIVE collection by slug for an external storefront backend.", "tags": [ "storefront" ] } }, "/api/v1/import/catalog": { "post": { "description": "Server-to-server catalog import. Requires `import:catalog` via `x-api-key` (server-side only). Batch-first: one authenticated request carries many rows, each one of five target shapes discriminated by `target` (`product` when omitted, `collection`, `variant`, `membership`, `composition`). Rows process in submitted order, so one batch can carry products/collections first and the variant/membership rows that reference them by external id after (an unresolved reference is a typed per-row `IMPORT_ROW_UNRESOLVED_REFERENCE` error). Product, collection, and variant rows are idempotent on the `(sourceSystem, externalId)` triple; membership rows use the resolved collection+item pair, and composition rows use the resolved parent Item plus `expectedRevision` (their `externalId` is job-row lineage only). Thus re-running an identical batch is a no-op-equivalent (never duplicates). Per-row continue-on-error: a bad row fails that row and the job proceeds; the terminal job may be `PARTIALLY_SUCCEEDED`. Set `dryRun: true` to validate a mapping without writing anything. Validation is the SAME as the merchant catalog write paths. A batch within the sync row ceiling returns 201 with the terminal job + per-row results; a larger batch (up to the async cap) returns 202 with a `QUEUED` job processed out-of-band — poll `GET /import/jobs/:id` (+ `/rows`) for progress and per-row results. Per-row errors live on the rows, not the audit log.", "operationId": "ImportController_importCatalogBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCatalogBatchDto" } } } }, "responses": { "201": { "description": "Sync fast-path: the terminal job + per-row results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResultDto" } } } }, "202": { "description": "Async path (batch over the sync row ceiling): the job was accepted as `QUEUED` with `rows: []`; the cron runner processes it out-of-band. Poll `GET /import/jobs/:id`. Also returned when `idempotencyKey` matches an existing not-yet-terminal job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResultDto" } } } }, "400": { "description": "Malformed batch / over the row cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `import:catalog`, or the org is suspended/archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key import rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Idempotent batch upsert of catalog products, collections, variants, collection membership, and Item compositions.", "tags": [ "import" ] } }, "/api/v1/import/content": { "post": { "description": "Server-to-server content import. Requires `import:content` via `x-api-key` (server-side only). Batch-first: one authenticated request carries many page rows (`target: \"page\"`, or omitted — the only content target today). Rows are idempotent on the `(sourceSystem, externalId)` triple, so re-running an identical batch is a no-op-equivalent (never duplicates a page). Per-row continue-on-error: a bad row fails that row and the job proceeds; the terminal job may be `PARTIALLY_SUCCEEDED`. Set `dryRun: true` to validate a mapping without writing anything. Validation is the SAME as the merchant page write path — including that `status` accepts only `PUBLISHED`/`DRAFT` (`ARCHIVED` stays reserved for the merchant archive endpoint) and that an already-archived page cannot be written until it is restored. Optional fields are omit-preserves on update; send `excerpt: null` to clear it. A batch within the sync row ceiling returns 201 with the terminal job + per-row results; a larger batch (up to the async cap) returns 202 with a `QUEUED` job processed out-of-band — poll `GET /import/jobs/:id` (+ `/rows`). Per-row errors live on the rows, not the audit log. NOTE: the 2 MB request-body cap is enforced by the JSON parser before any of this runs, so for pages — whose bodies may reach 1 MB each — it is usually the binding limit rather than the row cap, and an oversized submission returns a bare `413`. Chunk by bytes, not by row count; see the `rows` field description for the size/row tradeoff.", "operationId": "ImportController_importContentBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportContentBatchDto" } } } }, "responses": { "201": { "description": "Sync fast-path: the terminal job + per-row results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResultDto" } } } }, "202": { "description": "Async path (batch over the sync row ceiling): the job was accepted as `QUEUED` with `rows: []`; the cron runner processes it out-of-band. Poll `GET /import/jobs/:id`. Also returned when `idempotencyKey` matches an existing not-yet-terminal job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResultDto" } } } }, "400": { "description": "Malformed batch / over the row cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key lacks `import:content`, or the org is suspended/archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key import rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Idempotent batch upsert of CMS pages.", "tags": [ "import" ] } }, "/api/v1/import/jobs/{id}": { "get": { "description": "Fetch an import job by id, scoped to the authenticated tenant. Requires the `import:*` scope matching the job's own family — a job is only readable by a key that could have written it. Missing / cross-tenant / wrong-family ids are all masked as 404.", "operationId": "ImportController_getJob", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResultDto" } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key holds no live `import:*` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No such job readable by this key in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Read an import job (with its per-row results).", "tags": [ "import" ] } }, "/api/v1/import/jobs/{id}/rows": { "get": { "description": "The per-row reconciliation surface for a job (source lineage, terminal per-row status, target entity, typed per-row errors). Requires the `import:*` scope matching the job's own family. Missing / cross-tenant / wrong-family ids are all masked as 404.", "operationId": "ImportController_getJobRows", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobRowResultDto" } } } } }, "401": { "description": "Missing/invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Key holds no live `import:*` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No such job readable by this key in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Read just the per-row results of an import job.", "tags": [ "import" ] } }, "/api/v1/merchant/booking-services": { "get": { "operationId": "MerchantBookingServicesController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List bookable services for the active organization.", "tags": [ "merchant-booking-services" ] }, "post": { "description": "Configures the service period, duration or fixed slots, buffers, pricing posture, payment/security-deposit posture, approval, and booking window. PRICING_STRUCTURE is reserved for M4-18.", "operationId": "MerchantBookingServicesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingServiceDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "A BookingService conflict, including uniqueness, active Item linkage, or concurrent configuration conflicts. An item-linked ACTIVE service with unmapped source pricing returns PRICING_POLICY_INCOMPATIBLE with details.reason = STRUCTURE_EVIDENCE_UNMAPPED; that refusal writes no BookingService row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a bookable service (booking operations permission required).", "tags": [ "merchant-booking-services" ] } }, "/api/v1/merchant/booking-services/{id}": { "get": { "operationId": "MerchantBookingServicesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one bookable service.", "tags": [ "merchant-booking-services" ] }, "patch": { "operationId": "MerchantBookingServicesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingServiceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "A BookingService conflict, including uniqueness, active Item linkage, or concurrent configuration conflicts. An item-linked ACTIVE service with unmapped source pricing returns PRICING_POLICY_INCOMPATIBLE with details.reason = STRUCTURE_EVIDENCE_UNMAPPED; that refusal writes no BookingService row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a bookable service (booking operations permission required).", "tags": [ "merchant-booking-services" ] } }, "/api/v1/merchant/booking-services/{id}/archive": { "post": { "operationId": "MerchantBookingServicesController_archive", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a bookable service. Idempotent.", "tags": [ "merchant-booking-services" ] } }, "/api/v1/merchant/booking-services/{id}/restore": { "post": { "operationId": "MerchantBookingServicesController_restore", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore an archived service to DRAFT. Idempotent.", "tags": [ "merchant-booking-services" ] } }, "/api/v1/merchant/booking-resources": { "get": { "operationId": "MerchantBookingResourcesController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } }, { "name": "resourceType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List booking resources and staff pools.", "tags": [ "merchant-booking-resources" ] }, "post": { "operationId": "MerchantBookingResourcesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingResourceDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a resource or staff pool.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{id}": { "get": { "operationId": "MerchantBookingResourcesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one booking resource.", "tags": [ "merchant-booking-resources" ] }, "patch": { "operationId": "MerchantBookingResourcesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingResourceDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a booking resource.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{id}/archive": { "post": { "operationId": "MerchantBookingResourcesController_archive", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a booking resource. Idempotent.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{id}/restore": { "post": { "operationId": "MerchantBookingResourcesController_restore", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore an archived resource. Idempotent.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{resourceId}/units": { "get": { "operationId": "MerchantBookingResourcesController_listUnits", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "MAINTENANCE", "LOST", "RETIRED" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List exact units for a booking resource.", "tags": [ "merchant-booking-resources" ] }, "post": { "operationId": "MerchantBookingResourcesController_createUnit", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingResourceUnitDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create an exact unit under a booking resource.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{resourceId}/units/{unitId}": { "get": { "operationId": "MerchantBookingResourcesController_getUnit", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "unitId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one exact booking resource unit.", "tags": [ "merchant-booking-resources" ] }, "patch": { "operationId": "MerchantBookingResourcesController_updateUnit", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "unitId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingResourceUnitDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update an exact booking resource unit.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{resourceId}/units/{unitId}/archive": { "post": { "operationId": "MerchantBookingResourcesController_archiveUnit", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "unitId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive an exact booking resource unit. Idempotent.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resources/{resourceId}/units/{unitId}/restore": { "post": { "operationId": "MerchantBookingResourcesController_restoreUnit", "parameters": [ { "name": "resourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "unitId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore an archived exact booking resource unit. Idempotent.", "tags": [ "merchant-booking-resources" ] } }, "/api/v1/merchant/booking-resource-requirements": { "get": { "operationId": "MerchantBookingResourceRequirementsController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceRequirementListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List service resource requirements.", "tags": [ "merchant-booking-resource-requirements" ] }, "post": { "operationId": "MerchantBookingResourceRequirementsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingResourceRequirementDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceRequirementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a service resource requirement.", "tags": [ "merchant-booking-resource-requirements" ] } }, "/api/v1/merchant/booking-resource-requirements/{id}": { "get": { "operationId": "MerchantBookingResourceRequirementsController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceRequirementResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one service resource requirement.", "tags": [ "merchant-booking-resource-requirements" ] }, "patch": { "operationId": "MerchantBookingResourceRequirementsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingResourceRequirementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceRequirementResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a service resource requirement.", "tags": [ "merchant-booking-resource-requirements" ] }, "delete": { "operationId": "MerchantBookingResourceRequirementsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceRequirementResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete a service resource requirement.", "tags": [ "merchant-booking-resource-requirements" ] } }, "/api/v1/merchant/booking-availability-rules": { "get": { "operationId": "MerchantBookingAvailabilityRulesController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "targetType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "SERVICE", "RESOURCE" ] } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityRuleListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List recurring booking availability rules.", "tags": [ "merchant-booking-availability-rules" ] }, "post": { "operationId": "MerchantBookingAvailabilityRulesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingAvailabilityRuleDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityRuleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a recurring availability rule.", "tags": [ "merchant-booking-availability-rules" ] } }, "/api/v1/merchant/booking-availability-rules/{id}": { "get": { "operationId": "MerchantBookingAvailabilityRulesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityRuleResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one recurring availability rule.", "tags": [ "merchant-booking-availability-rules" ] }, "patch": { "operationId": "MerchantBookingAvailabilityRulesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingAvailabilityRuleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityRuleResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a recurring availability rule.", "tags": [ "merchant-booking-availability-rules" ] }, "delete": { "operationId": "MerchantBookingAvailabilityRulesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAvailabilityRuleResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete a recurring availability rule.", "tags": [ "merchant-booking-availability-rules" ] } }, "/api/v1/merchant/booking-blackouts": { "get": { "operationId": "MerchantBookingBlackoutsController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "targetType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "ORGANIZATION", "SERVICE", "RESOURCE" ] } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBlackoutListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List organization, service, or resource blackouts.", "tags": [ "merchant-booking-blackouts" ] }, "post": { "description": "Instant fields require RFC 3339 offsets. Recurrence supports a bounded RRULE subset: FREQ (DAILY/WEEKLY/MONTHLY/YEARLY), INTERVAL, BYDAY, and COUNT.", "operationId": "MerchantBookingBlackoutsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingBlackoutDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBlackoutResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a booking blackout.", "tags": [ "merchant-booking-blackouts" ] } }, "/api/v1/merchant/booking-blackouts/{id}": { "get": { "operationId": "MerchantBookingBlackoutsController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBlackoutResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one booking blackout.", "tags": [ "merchant-booking-blackouts" ] }, "patch": { "operationId": "MerchantBookingBlackoutsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingBlackoutDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBlackoutResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a booking blackout.", "tags": [ "merchant-booking-blackouts" ] }, "delete": { "operationId": "MerchantBookingBlackoutsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBlackoutResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete a booking blackout.", "tags": [ "merchant-booking-blackouts" ] } }, "/api/v1/merchant/booking-policies": { "get": { "operationId": "MerchantBookingPoliciesController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPolicyListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List reusable or service-scoped booking policies.", "tags": [ "merchant-booking-policies" ] }, "post": { "operationId": "MerchantBookingPoliciesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingPolicyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPolicyResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a booking policy.", "tags": [ "merchant-booking-policies" ] } }, "/api/v1/merchant/booking-policies/{id}": { "get": { "operationId": "MerchantBookingPoliciesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPolicyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one booking policy.", "tags": [ "merchant-booking-policies" ] }, "patch": { "operationId": "MerchantBookingPoliciesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingPolicyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPolicyResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Update a booking policy.", "tags": [ "merchant-booking-policies" ] }, "delete": { "operationId": "MerchantBookingPoliciesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPolicyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Delete a booking policy.", "tags": [ "merchant-booking-policies" ] } }, "/api/v1/merchant/booking-pricing-policies": { "get": { "description": "Merchant bearer auth + x-organization-slug; one bounded page of the active organization’s policies under the shared booking-setup cursor contract (`limit`, `cursor`, `{ data, nextCursor }`). Each row carries the revision summary and the published revision, so a client never issues one revisions request per policy.", "operationId": "MerchantBookingPricingPoliciesController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List reusable duration pricing policies (bounded cursor page).", "tags": [ "merchant-booking-pricing-policies" ] }, "post": { "description": "Merchant bearer auth + x-organization-slug; the policy is created in the active organization with an immutable revision 1 DRAFT that must be published explicitly.", "operationId": "MerchantBookingPricingPoliciesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingPricingPolicyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyWithRevisionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a pricing policy with its revision 1 draft (booking operations permission required).", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/preview": { "post": { "description": "Merchant bearer auth + x-organization-slug; attended authoring preview scoped to the active organization. Evaluates the candidate duration bands through the shared booking pricing resolver without reading or writing any policy state, and independently of the customer-facing PRICING_STRUCTURE runtime gate. Returns evaluated prices, so the response is private and non-cacheable.", "operationId": "MerchantBookingPricingPoliciesController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewBookingPricingPolicyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyPreviewResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Evaluate a candidate revision against sample durations (booking operations permission required).", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/{policyId}": { "get": { "description": "Merchant bearer auth + x-organization-slug; 404 unless the policy belongs to the active organization.", "operationId": "MerchantBookingPricingPoliciesController_get", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Fetch one pricing policy.", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/{policyId}/revisions": { "get": { "description": "Merchant bearer auth + x-organization-slug; newest revision first, scoped to the active organization, paged with the shared booking-setup cursor contract (`limit`, `cursor`, `{ data, nextCursor }`). This is the per-policy detail read: the library list already carries the published revision and the revision summary.", "operationId": "MerchantBookingPricingPoliciesController_listRevisions", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of setup rows to return.", "schema": { "minimum": 1, "maximum": 200, "format": "int32", "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page. Pass back the returned nextCursor.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List the immutable revisions of one pricing policy (bounded cursor page).", "tags": [ "merchant-booking-pricing-policies" ] }, "post": { "description": "Merchant bearer auth + x-organization-slug; published revisions are immutable, so changes append the next-numbered DRAFT on the active organization’s policy.", "operationId": "MerchantBookingPricingPoliciesController_createRevision", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingPricingPolicyRevisionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Create a successor draft revision (booking operations permission required).", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/{policyId}/revisions/{revisionNumber}/publish": { "post": { "description": "Merchant bearer auth + x-organization-slug; supersedes the currently published revision of the active organization’s policy after validating every attached service against the candidate.", "operationId": "MerchantBookingPricingPoliciesController_publishRevision", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "revisionNumber", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Publish a draft revision (booking operations permission required). Idempotent.", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/{policyId}/archive": { "post": { "description": "Merchant bearer auth + x-organization-slug; conflicts while any booking service in the active organization still references the policy.", "operationId": "MerchantBookingPricingPoliciesController_archive", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Archive a detached pricing policy (booking operations permission required). Idempotent.", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-pricing-policies/{policyId}/restore": { "post": { "description": "Merchant bearer auth + x-organization-slug; scoped to the active organization.", "operationId": "MerchantBookingPricingPoliciesController_restore", "parameters": [ { "name": "policyId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPricingPolicyResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Restore an archived pricing policy (booking operations permission required). Idempotent.", "tags": [ "merchant-booking-pricing-policies" ] } }, "/api/v1/merchant/booking-services/{serviceId}/pricing-policy": { "put": { "description": "Merchant bearer auth + x-organization-slug; both rows must belong to the active organization. Conflicts with the shared reason-coded compatibility contract when the service posture or the policy’s published revision is incompatible.", "operationId": "MerchantBookingServicePricingPolicyController_attach", "parameters": [ { "name": "serviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachBookingPricingPolicyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Attach a pricing policy to a booking service (booking operations permission required). Idempotent.", "tags": [ "merchant-booking-services" ] }, "delete": { "description": "Merchant bearer auth + x-organization-slug; scoped to the active organization.", "operationId": "MerchantBookingServicePricingPolicyController_detach", "parameters": [ { "name": "serviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Detach the pricing policy from a booking service (booking operations permission required). Idempotent.", "tags": [ "merchant-booking-services" ] } }, "/api/v1/customer/account/bookings": { "get": { "description": "Ownership comes only from the authenticated customer identity and active tenant. Merchant notes, allocations, resource identities, and database document ids are excluded.", "operationId": "CustomerBookingAccountController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's bookings.", "tags": [ "customer-bookings" ] } }, "/api/v1/customer/account/bookings/{id}": { "get": { "description": "Returns a neutral 404 for unknown, cross-tenant, or another customer’s booking.", "operationId": "CustomerBookingAccountController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCustomerDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read one booking owned by the signed-in customer.", "tags": [ "customer-bookings" ] } }, "/api/v1/customer/account/bookings/{id}/cancel-request": { "post": { "operationId": "CustomerBookingAccountController_cancelRequest", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingChangeRequestResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Submit a cancellation request for an owned booking.", "tags": [ "customer-bookings" ] } }, "/api/v1/customer/account/bookings/{id}/reschedule-request": { "post": { "operationId": "CustomerBookingAccountController_rescheduleRequest", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingRescheduleRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingChangeRequestResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Submit a reschedule request for an owned booking.", "tags": [ "customer-bookings" ] } }, "/api/v1/customer/bookings/{token}": { "get": { "description": "The booking.manage action token is the credential. Preview is repeatable and remains available after a successful mutation; every miss is the same neutral 404.", "operationId": "CustomerBookingActionController_preview", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCustomerDetailDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Preview a booking through a scoped guest-management action link.", "tags": [ "customer-booking-actions" ] } }, "/api/v1/customer/bookings/{token}/checkout": { "post": { "description": "The booking.manage action token authorizes the return. When ADR-043 price confirmation is enabled, the first call returns the frozen tax-inclusive approved offer and a signed receipt; only an explicitly confirmed retry receives a checkout bearer. Accepted Commerce Quotes remain exempt.", "operationId": "CustomerBookingActionController_checkout", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPriceConfirmationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCheckoutResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "BOOKING_PRICE_CONFIRMATION_REQUIRED returns the typed two-phase confirmation challenge. Other operation-specific conflicts use the canonical API error envelope. TENANT_TAX_NOT_CONFIGURED when a stored stripe_tax policy has a tax base but its connected account or Tax settings are incomplete. A stored manual_no_tax policy with a missing or invalid responsibility acknowledgement also fails before any priced commitment, including free bookings. Unpriced draft/request capture retains its existing behavior. Concurrent tax-policy changes require retrying the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BookingPriceConfirmationRequiredErrorDto" }, { "$ref": "#/components/schemas/ApiErrorDto" } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Resume payment for a merchant-approved singular booking.", "tags": [ "customer-booking-actions" ] } }, "/api/v1/customer/bookings/{token}/cancel-request": { "post": { "description": "Uses the frozen booking policy, writes the existing BookingChangeRequest operational record, audits through the shared action/activity foundations, and consumes the action link once.", "operationId": "CustomerBookingActionController_cancelRequest", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingReasonDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingChangeRequestResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Submit a policy-checked cancellation request.", "tags": [ "customer-booking-actions" ] } }, "/api/v1/customer/bookings/{token}/reschedule-request": { "post": { "description": "This request does not claim capacity. Merchant approval performs the transactional availability recheck before the operational window moves.", "operationId": "CustomerBookingActionController_rescheduleRequest", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingRescheduleRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingChangeRequestResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Submit a policy-checked reschedule request.", "tags": [ "customer-booking-actions" ] } }, "/api/v1/customer/agreement-actions/{token}/resume": { "post": { "description": "This authority-only exchange creates no booking, capacity claim, checkout, or payment. For an OPEN group, the caller must explicitly submit the existing group request command, which re-evaluates all agreement requirements transactionally. A safe nonterminal group already advanced by that command may be replayed after a lost response. Malformed, unknown, expired, revoked, declined, incomplete, cross-tenant, wrong-customer, wrong-subject, and terminal-group actions share one neutral 404.", "operationId": "CustomerAgreementBookingGroupRecoveryController_resume", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupRecoveryProofDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Exchange a completed native agreement action for its exact booking-group proof.", "tags": [ "customer-agreement-actions" ] } }, "/api/v1/customer/account/booking-groups": { "get": { "description": "Ownership comes only from the authenticated tenant-scoped customer id, with normalized-email fallback only when the group has no durable owner. Internal group/member ids and payment capabilities are excluded.", "operationId": "CustomerBookingGroupAccountController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingGroupListResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's booking groups.", "tags": [ "customer-booking-groups" ] } }, "/api/v1/customer/account/booking-groups/{publicRef}": { "get": { "description": "Unknown, cross-tenant, and another customer’s group all return the same neutral 404.", "operationId": "CustomerBookingGroupAccountController_detail", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingGroupDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read one booking group owned by the signed-in customer.", "tags": [ "customer-booking-groups" ] } }, "/api/v1/customer/account/booking-groups/{publicRef}/resume": { "post": { "description": "The proof is response-only and stored only as a digest. It is never placed in a URL or rendered account projection.", "operationId": "CustomerBookingGroupAccountController_resume", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupRecoveryProofDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Mint a fresh scoped resume proof for an owned booking group.", "tags": [ "customer-booking-groups" ] } }, "/api/v1/customer/booking-groups/actions/exchange": { "post": { "description": "Malformed, unknown, expired, revoked, cross-tenant, consumed, and wrong-purpose actions share one neutral 404. The action remains retryable until a successful proof-authenticated read.", "operationId": "CustomerBookingGroupRecoveryController_exchange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeBookingGroupActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingGroupRecoveryProofDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Exchange a guest recovery action for a scoped group proof.", "tags": [ "customer-booking-group-recovery" ] } }, "/api/v1/customer/booking-groups/{publicRef}": { "get": { "description": "Delegates to the authoritative proof-bound group projection. Only after that read succeeds is the originating action token consumed.", "operationId": "CustomerBookingGroupRecoveryController_read", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "booking-group-resume-key", "in": "header", "description": "Scoped group resume proof. Hosted clients exchange it into an httpOnly cookie before rendering a clean URL.", "required": true, "schema": { "type": "string", "pattern": "^g[a-z0-9]{25}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read a recovered booking group and acknowledge its action link.", "tags": [ "customer-booking-group-recovery" ] } }, "/api/v1/merchant/platform-billing": { "get": { "description": "Returns a strict merchant projection of current plan and cadence, scheduled change, latest operation state, available transitions, and provider-confirmed billing-address readiness. Provider ids, platform case notes, staff identities, recovery controls, and draft history are never returned.", "operationId": "MerchantPlatformBillingController_getBillingState", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingStateDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active org's authoritative platform billing state.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/plan-change/preview": { "post": { "description": "Freshly resolves the active organization, provider subscription, published target price, scheduled intent, and provider-confirmed billing-address version. Immediate changes return Stripe-authored money and tax facts; period-end changes return `money: null`. The short-lived opaque confirmation token binds the exact preview and is accepted only in the confirm request body. The same authenticated Owner or Admin who requests the preview must submit its confirmation.", "operationId": "MerchantPlatformBillingController_previewPlanChange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPlanChangePreviewRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPlanChangePreviewDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "`PLATFORM_BILLING_PLAN_CHANGE_REJECTED` means the request is valid but cannot be quoted from the current billing state. `details.reason` is `BILLING_STATE_NOT_ELIGIBLE` or `ADDRESS_NOT_PROVIDER_CONFIRMED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Preview an ordinary Pro cadence change for the active org.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/plan-change/confirm": { "post": { "description": "Re-reads the active org, provider subscription, target publication, scheduled intent, address version, and immediate invoice preview before admission. An unlinked token that is expired, cross-org, or otherwise drifted fails closed with `REQUOTE_REQUIRED`. Once a token is linked, an exact same-actor retry is idempotent: it resumes only that linked operation or returns its current merchant-safe state without admitting another mutation. The token is also bound to the authenticated Owner or Admin who requested the preview; another user receives the same neutral `REQUOTE_REQUIRED` response. No token or provider identifier is accepted in a URL.", "operationId": "MerchantPlatformBillingController_confirmPlanChange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPlanChangeConfirmRequestDto" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingStateDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "`PLATFORM_BILLING_PLAN_CHANGE_REJECTED` with `details.reason=BILLING_STATE_NOT_ELIGIBLE` means the valid request cannot be applied from the current billing state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Confirm the exact current plan-change preview.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/plan-change/scheduled/cancel": { "post": { "description": "Cancels only the exact provider-confirmed scheduled paid cadence change identified by the opaque state reference and caller request identity. Subscription and schedule identifiers are resolved server-side. Native paid-to-Free cancellation remains on the separate reactivate contract.", "operationId": "MerchantPlatformBillingController_cancelScheduledPlanChange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantScheduledPlanChangeCancelRequestDto" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingStateDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "`PLATFORM_BILLING_PLAN_CHANGE_REJECTED` with `details.reason=BILLING_STATE_NOT_ELIGIBLE` means there is no eligible provider-confirmed scheduled cadence change to cancel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Cancel the active org's scheduled cadence change.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/address": { "get": { "description": "Returns the stored address plus whether it would satisfy the fail-closed tax gate, so the panel can explain a refusal before a subscribe attempt rather than surfacing a bare 4xx after one.", "operationId": "MerchantPlatformBillingController_getBillingAddress", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBillingAddressDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the active org's billing address and its tax usability.", "tags": [ "merchant-platform-billing" ] }, "put": { "description": "Writes the address used to determine the SaaS tax jurisdiction and atomically records its versioned propagation intent. When a platform Stripe customer exists, reconciliation updates its billing address and clears any stale shipping profile; provider failures are retried from the durable intent. A 200 confirms the local address and intent commit, not synchronous provider completion. An unsupported country is refused before the write. This is the organization's one address, which Connect onboarding also reads.", "operationId": "MerchantPlatformBillingController_updateBillingAddress", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantBillingAddressDto" } } } }, "responses": { "200": { "description": "The stored address after the write, with its refreshed usability verdict — so the panel renders the new state without a second GET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantBillingAddressDto" } } } }, "400": { "description": "The address is incomplete or malformed. `details.reason` is `BILLING_ADDRESS_REQUIRED` or `BILLING_ADDRESS_INVALID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "The billing country is outside the supported jurisdiction list. `details.reason` is `COUNTRY_NOT_SUPPORTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Set the active org's billing address.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/subscribe": { "post": { "description": "Freshly validates the submitted opaque quote, displayed currency, and amount against one sellable CURRENT price row before any Stripe subscription mutation. Active/trialing is idempotently reused. An INCOMPLETE/PAST_DUE subscription returns 409 and must be handled by the separate quote-free resume-payment endpoint, so a new public offer can never replace existing invoice terms. A new create is generation-idempotent and verifies Stripe echoed the exact resolved price. The org's plan flips to Pro only after the authoritative billing webhook confirms it; this call never grants Pro on its own.", "operationId": "MerchantPlatformBillingController_subscribe", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeResponseDto" } } } }, "400": { "description": "ADR-008 fail-closed tax gate. `details.reason` is `BILLING_ADDRESS_REQUIRED` (the organization has no billing address set) or `BILLING_ADDRESS_INVALID` (it is incomplete, not ISO 3166-1 alpha-2, or a location Stripe Tax cannot resolve). Set a usable address with `PUT /merchant/platform-billing/address`, then retry subscribe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "Includes `details.reason=COUNTRY_NOT_SUPPORTED` when the billing country is outside the supported jurisdiction list — no payload change resolves this one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "`PLATFORM_BILLING_QUOTE_STALE` when the submitted quote no longer matches the sellable CURRENT row, or `PLATFORM_BILLING_RECOVERY_REQUIRED` when an existing INCOMPLETE/PAST_DUE payment must use resume-payment. `RESOURCE_CONFLICT` with `details.reason=CONCURRENT_SUBSCRIPTION_CHANGED` means another billing generation won while the request was in flight; refresh before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Platform billing is not available in this environment. `code` is `PLATFORM_BILLING_UNAVAILABLE`; `details.reason` is `NOT_SELLABLE` (the plan is not marked sellable), `PRICE_NOT_CONFIGURED` (no CURRENT Stripe price published for the plan/cadence), `STRIPE_SKIPPED` (Stripe unavailable), or `PUBLISHABLE_KEY_UNAVAILABLE` (no browser-safe publishable key, so the Payment Element could not be rendered). `PAYMENT_TERMS_UNAVAILABLE_AFTER_START` means the subscription was already durably linked, but its invoice terms could not be safely handed off; refresh and use resume-payment rather than creating again. `AUTOMATIC_TAX_NOT_APPLIED` means Stripe did not apply automatic tax to the subscription we asked to be taxed — the platform tax configuration is wrong, and no subscription was persisted. `FLEXIBLE_BILLING_NOT_APPLIED` means Stripe did not echo the required flexible billing mode — the provider configuration is incompatible, and no subscription was persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Start a new self-serve platform Pro subscription.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/resume-payment": { "post": { "description": "Recovery-only contract for an INCOMPLETE/PAST_DUE subscription. Takes no cadence or public offer and returns authoritative current invoice terms before handing off a Payment Element client secret. This path is distinct from cancellation reversal and never changes the price.", "operationId": "MerchantPlatformBillingController_resumePayment", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Resume the exact existing platform subscription payment.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/cancel": { "post": { "description": "Sets `cancel_at_period_end` on the platform subscription. Access is retained for the period already paid for — the plan is NOT demoted here, and the org stays on Pro until the confirming webhook records CANCELLED at the boundary. **Always reconciles with Stripe**, including when the local mirror already says cancellation is scheduled: the mirror can lag or drift, so it is never trusted to skip the provider call. This request therefore depends on Stripe availability and can return 503. Idempotent — repeating it is safe and reports `unchanged: true` when nothing differed from the state you last read. Reversible before the boundary via `POST reactivate`.", "operationId": "MerchantPlatformBillingController_cancel", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCancellationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "The org has no platform subscription to cancel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Any of four conflicts, all safe to resolve by re-reading `GET /merchant/platform-billing` and retrying: the subscription is already terminal (CANCELLED/NONE) so there is nothing left to schedule — subscribing again is the recovery; Stripe itself refused the change for the subscription's current state (the mirror had not caught up yet); a concurrent resubscribe replaced the tracked subscription, so the mutation would have landed on one the org no longer bills on; or another renewal change for this organization is already in flight or landed first. Renewal changes are serialized per organization, so a second concurrent cancel/resume is refused rather than interleaved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Platform billing is unavailable. `details.reason` is `STRIPE_SKIPPED` for a transient provider failure, or `PROVIDER_OUTCOME_UNKNOWN` when a bounded call timed out — in that case the change MAY have been applied. Re-read the billing state shortly rather than issuing the opposite change; renewal control for this organization stays reserved until the outcome is reconciled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Schedule the platform subscription to end at the period end.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/reactivate": { "post": { "description": "Clears `cancel_at_period_end`. Only valid while the subscription is still live — once it has actually ended (status CANCELLED) Stripe cannot revive it and this returns 409; subscribe again instead. That 409 also covers a mirror that still reads ACTIVE while Stripe has already ended the subscription. **Always reconciles with Stripe** rather than trusting the local mirror, so it depends on Stripe availability and can return 503. Idempotent — repeating it is safe and reports `unchanged: true` when nothing differed from the state you last read.", "operationId": "MerchantPlatformBillingController_reactivate", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCancellationDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "The org has no platform subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "Any of four conflicts, all safe to resolve by re-reading `GET /merchant/platform-billing` and retrying: the subscription already ended (CANCELLED/NONE) and cannot be resumed — subscribe again instead; Stripe itself refused the change for the subscription's current state (the mirror had not caught up yet); a concurrent resubscribe replaced the tracked subscription, so the mutation would have landed on one the org no longer bills on; or another renewal change for this organization is already in flight or landed first. Renewal changes are serialized per organization, so a second concurrent cancel/resume is refused rather than interleaved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "Platform billing is unavailable. `details.reason` is `STRIPE_SKIPPED` for a transient provider failure, or `PROVIDER_OUTCOME_UNKNOWN` when a bounded call timed out — in that case the change MAY have been applied. Re-read the billing state shortly rather than issuing the opposite change; renewal control for this organization stays reserved until the outcome is reconciled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Clear a scheduled cancellation so the plan renews.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/payment-method": { "post": { "description": "Creates a SetupIntent on the platform account for this org and returns a Payment Element client secret plus the platform publishable key. Available whenever the org has a billing customer — deliberately including PAST_DUE and INCOMPLETE, which are the states a merchant needs to recover from. Saving the card is only half of it: call `POST payment-method/confirm` afterwards so the subscription is actually pointed at the new card, otherwise the next renewal still bills the old one.", "operationId": "MerchantPlatformBillingController_startPaymentMethodUpdate", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPaymentMethodUpdateDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "The org has no platform billing customer yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Start replacing the card that pays for the platform plan.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/payment-method/confirm": { "post": { "description": "Verifies the SetupIntent SERVER-side — it must have succeeded and must belong to this organization's own billing customer — then sets it as the subscription default so renewals bill it. Idempotent: safe to repeat with the same SetupIntent, which matters when a merchant closes the tab between confirming the card and returning.", "operationId": "MerchantPlatformBillingController_confirmPaymentMethodUpdate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentMethodUpdateRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentMethodUpdateDto" } } } }, "400": { "description": "The SetupIntent has not succeeded yet — confirm the card first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "No billing account, no subscription to attach the card to, or a SetupIntent that is not this organization’s. All report the same way, so the id cannot be probed for another tenant’s state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Point the subscription at the newly saved card.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/merchant/platform-billing/invoices": { "get": { "description": "Bounded, cursor-paged list of the org's own platform invoices, resolved from the org's persisted Stripe customer (never from a caller-supplied id). Each item carries Stripe-hosted invoice and PDF links. Those are SIGNED, UNAUTHENTICATED URLs — possession is access, so treat them as credentials: never log them or place them in a shared cache. Returns 404 when the org has never started a platform subscription, which is deliberately distinct from an empty list.", "operationId": "MerchantPlatformBillingController_listInvoices", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Page size (1-100).", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } }, { "name": "startingAfter", "required": false, "in": "query", "description": "Cursor from a prior response `nextStartingAfter`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInvoiceListDto" } } } }, "400": { "description": "`startingAfter` is not a valid cursor for this organization — unknown, malformed, or belonging to another customer. Deterministic: retrying the same cursor will not succeed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "The org has no platform billing customer yet (never subscribed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Read the org's platform invoice history.", "tags": [ "merchant-platform-billing" ] } }, "/api/v1/customer/account/subscriptions": { "get": { "description": "Ownership comes only from the verified customer session and active tenant. Results contain normalized lifecycle state and customer-safe public references; database and provider identifiers are never exposed.", "operationId": "CustomerSubscriptionAccountController_listAccountSubscriptions", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by the normalized subscription lifecycle state.", "schema": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Pass it back unchanged.", "schema": { "pattern": "^s[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the signed-in customer's subscriptions.", "tags": [ "customer-subscriptions" ] } }, "/api/v1/customer/account/subscriptions/{publicRef}": { "get": { "description": "Returns the same neutral 404 for malformed, unknown, cross-tenant, or another customer’s subscription reference. Raw provider state and identifiers are excluded.", "operationId": "CustomerSubscriptionAccountController_getAccountSubscription", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^s[0-9a-f]{32}$" }, "description": "Opaque customer-safe subscription handle." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionDetailDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Read one subscription owned by the signed-in customer.", "tags": [ "customer-subscriptions" ] } }, "/api/v1/customer/account/subscriptions/{publicRef}/reactivate": { "post": { "description": "Clears only a verified period-end cancellation. The command requires a stable UUID-v4 idempotency key, proves live connected-account ownership, and safely replays an already-completed result.", "operationId": "CustomerSubscriptionAccountController_reactivateAccountSubscription", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^s[0-9a-f]{32}$" }, "description": "Opaque customer-safe subscription handle." }, { "name": "x-idempotency-key", "in": "header", "description": "Stable UUID v4 for this reactivation intent. Retries replay the committed outcome.", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionReactivationDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Restore renewal for a subscription scheduled to cancel.", "tags": [ "customer-subscriptions" ] } }, "/api/v1/customer/account/subscriptions/{publicRef}/billing-periods": { "get": { "description": "Returns normalized period status, dates, and amounts only. Provider invoice identifiers, internal order ids, and metadata are never exposed.", "operationId": "CustomerSubscriptionAccountController_listAccountBillingPeriods", "parameters": [ { "name": "publicRef", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^s[0-9a-f]{32}$" }, "description": "Opaque customer-safe subscription handle." }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Pass it back unchanged.", "schema": { "pattern": "^h[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionBillingPeriodListResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List billing history for an owned subscription.", "tags": [ "customer-subscriptions" ] } }, "/api/v1/customer/subscription-payment-recoveries/actions/exchange": { "post": { "description": "Malformed, unknown, expired, revoked, consumed, wrong-purpose, terminal, and cross-tenant actions share one neutral 404. Exchange does not consume the action or initiate payment; invoice.paid is the later consumption authority.", "operationId": "CustomerSubscriptionPaymentRecoveryActionController_exchange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeSubscriptionPaymentRecoveryActionDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryProofDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Exchange a subscription recovery action for a short-lived payment proof.", "tags": [ "customer-subscription-payment-recovery-actions" ] } }, "/api/v1/customer/subscription-payment-recoveries/actions/resend": { "post": { "description": "Accepts only the action token from the prior link. It never accepts an email address, returns recovery data, or mints a payment proof. Every action state and eligibility outcome receives the same confirmation; eligible delivery is queued durably and starts only after the response finishes.", "operationId": "CustomerSubscriptionPaymentRecoveryActionController_resend", "parameters": [ { "name": "x-idempotency-key", "in": "header", "description": "Stable UUID for one customer resend intent. Retries with the same key replay the original committed outbox intent.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryResendRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryResendDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Request a replacement subscription recovery link.", "tags": [ "customer-subscription-payment-recovery-actions" ] } }, "/api/v1/customer/subscription-payment-recoveries/{recoveryId}/action": { "get": { "description": "Returns the narrow normalized recovery projection only. Provider identifiers, client secrets, raw failure details, and internal dunning vocabulary are excluded.", "operationId": "CustomerSubscriptionPaymentRecoveryActionController_read", "parameters": [ { "name": "recoveryId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-lc-subscription-recovery", "in": "header", "description": "Short-lived purpose-bound payment recovery proof. Hosted clients keep it in an httpOnly cookie and forward it only in this header.", "required": true, "schema": { "type": "string", "pattern": "^p[a-z0-9]{25}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryActionResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Read one proof-bound subscription payment recovery.", "tags": [ "customer-subscription-payment-recovery-actions" ] } }, "/api/v1/customer/subscription-payment-recoveries/{recoveryId}/payment": { "post": { "description": "Fully verifies the connected-account InvoicePayment lineage, adopts or reuses the exact existing PaymentIntent through the shared PaymentAttempt model, and returns its in-memory client secret when customer confirmation is still possible. It never creates a PaymentIntent, parallel charge, CheckoutSession, order, or fulfillment row; invoice.paid remains authoritative completion.", "operationId": "CustomerSubscriptionPaymentRecoveryActionController_preparePayment", "parameters": [ { "name": "recoveryId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-lc-subscription-recovery", "in": "header", "description": "Short-lived purpose-bound payment recovery proof. Hosted clients keep it in an httpOnly cookie and forward it only in this header.", "required": true, "schema": { "type": "string", "pattern": "^p[a-z0-9]{25}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryPaymentResponseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [] } ], "summary": "Prepare the failed subscription invoice’s existing PaymentIntent.", "tags": [ "customer-subscription-payment-recovery-actions" ] } }, "/api/v1/customer/subscription-payment-recoveries": { "get": { "description": "Requires tenant context plus a CustomerSession and returns only that authenticated customer’s normalized failed-payment cycles, next Stripe retry when known, and paid-only fulfillment eligibility. Raw provider identifiers and internal dunning event names are never exposed.", "operationId": "CustomerSubscriptionPaymentRecoveryController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by normalized payment-recovery state.", "schema": { "type": "string", "enum": [ "PAYMENT_FAILED", "RETRY_SCHEDULED", "ACTION_REQUIRED", "RECOVERED", "EXHAUSTED" ] } }, { "name": "subscriptionId", "required": false, "in": "query", "description": "Filter to one local subscription id.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Treat it as opaque and pass it back unchanged.", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "List the authenticated customer’s subscription payment recovery state.", "tags": [ "customer-subscription-payment-recovery" ] } }, "/api/v1/merchant/subscription-payment-recoveries/{recoveryId}/resend": { "post": { "description": "Mints a fresh scoped recovery link, revoking the previous one, and queues one reminder. Retrying with the same idempotency key replays the original outcome and sends no second email. Staff resends are limited to a rolling window; automatic reminders are unlimited and never consume it.", "operationId": "MerchantSubscriptionPaymentRecoveryController_resend", "parameters": [ { "name": "recoveryId", "required": true, "in": "path", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResendSubscriptionPaymentRecoveryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSubscriptionPaymentRecoveryResendDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Resend the customer payment-recovery reminder.", "tags": [ "merchant-subscription-payment-recovery" ] } }, "/api/v1/merchant/subscription-payment-recoveries": { "get": { "description": "Requires an active merchant membership in the tenant context and returns that organization’s narrow payment-recovery queue/read contract. General subscription workbench, list, and detail behavior is a separate contract.", "operationId": "MerchantSubscriptionPaymentRecoveryController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by normalized payment-recovery state.", "schema": { "type": "string", "enum": [ "PAYMENT_FAILED", "RETRY_SCHEDULED", "ACTION_REQUIRED", "RECOVERED", "EXHAUSTED" ] } }, { "name": "subscriptionId", "required": false, "in": "query", "description": "Filter to one local subscription id.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page (`nextCursor`). Treat it as opaque and pass it back unchanged.", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "description": "Filter to one local customer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSubscriptionPaymentRecoveryListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "List normalized subscription payment recovery state.", "tags": [ "merchant-subscription-payment-recovery" ] } }, "/api/v1/customer/entitlements": { "get": { "description": "Evaluates every subscription the customer holds: per-subscription posture, every current-window grant (honored or not), and the per-key effective rollup. Read/display only.", "operationId": "CustomerEntitlementsController_getOwnEntitlements", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEntitlementsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "CustomerSession": [] } ], "summary": "Get the authenticated customer’s effective entitlements.", "tags": [ "customer-entitlements" ] } }, "/api/v1/merchant/customers/{customerId}/entitlements": { "get": { "description": "Evaluates every subscription the customer holds in the active org: per-subscription posture, current-window grants, and the per-key effective rollup.", "operationId": "MerchantEntitlementsController_getCustomerEntitlements", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntitlementsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Get a customer’s effective entitlements.", "tags": [ "merchant-entitlements" ] } }, "/api/v1/merchant/subscriptions/{subscriptionId}/entitlements": { "get": { "description": "Evaluates a single subscription: its posture, current-window grants, and the per-key effective rollup for just this subscription.", "operationId": "MerchantEntitlementsController_getSubscriptionEntitlements", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntitlementsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "OrganizationSlug": [], "BearerAuth": [] } ], "summary": "Get one subscription’s effective entitlements.", "tags": [ "merchant-entitlements" ] } }, "/api/v1/storefront/customers/{customerId}/entitlements": { "get": { "description": "Evaluates every subscription the customer holds under the key’s tenant. Requires the `entitlements:read` scope. Read/display only.", "operationId": "StorefrontEntitlementsController_getCustomerEntitlements", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntitlementsResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a customer’s effective entitlements (server-to-server).", "tags": [ "storefront-entitlements" ] } }, "/api/v1/storefront/customers/{customerId}/entitlements/{key}": { "get": { "description": "The authoritative live answer a state-changing flow must take before acting on an entitlement — display tokens are NEVER accepted as proof. An unknown or un-honored key answers `honored: false` (200); only an unknown customer is a 404. Requires `entitlements:read`.", "operationId": "StorefrontEntitlementsController_checkEntitlement", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer id.", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "description": "Plan-authored entitlement key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementCheckResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reality-check one entitlement key (server truth).", "tags": [ "storefront-entitlements" ] } }, "/api/v1/storefront/customers/{customerId}/entitlement-consumptions": { "post": { "description": "The ONE entitlement mutation: evaluator-honor-gated, FOR-UPDATE cap-checked, and exactly-once per `idempotencyKey` (a replay returns the recorded outcome without spending again). Consumes from the window that expires first; one call spends within one window. Requires the `entitlements:consume` scope — `entitlements:read` credentials can never spend. Rejections are 409 `ENTITLEMENT_NOT_CONSUMABLE` with `details.reason`.", "operationId": "StorefrontEntitlementsController_consumeEntitlement", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumeEntitlementDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementConsumptionResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Consume ALLOWANCE / SERVICE_CREDIT units (guarded).", "tags": [ "storefront-entitlements" ] } }, "/api/v1/storefront/customers/{customerId}/entitlement-tokens": { "post": { "description": "Signs the customer’s effective-entitlement rollup into a compact JWS (alg EdDSA, ~10 min TTL) verifiable against `/api/v1/public/entitlement-tokens/jwks`. READ/DISPLAY ONLY — the API never accepts this token as authorization; server-side flows must re-check entitlements. Requires the `entitlements:read` scope. 503 when the environment has no signing key (plain reads keep working).", "operationId": "StorefrontEntitlementsController_mintDisplayToken", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer id.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementDisplayTokenResponseDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Mint a short-lived signed entitlement display token.", "tags": [ "storefront-entitlements" ] } }, "/api/v1/public/entitlement-tokens/jwks": { "get": { "description": "Standard JWKS document carrying the platform’s current Ed25519 public key. Match tokens by `kid`. Empty `keys` means display-token signing is not enabled in this environment.", "operationId": "PublicEntitlementTokenKeysController_getJwks", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementTokenJwksResponseDto" } } } } }, "summary": "Verification keys for entitlement display tokens (JWKS).", "tags": [ "entitlement-token-keys" ] } }, "/api/v1/public/plan-pricing": { "get": { "description": "Anonymous, cacheable. Returns the CURRENT price for each SELLABLE platform plan + cadence — display fields only (no Stripe or internal ids). A plan with no published, sellable price is omitted (consumers fall back to their own copy). Empty until an operator publishes + marks a plan sellable.", "operationId": "PublicPlanPricingController_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedPlanPriceDto" } } } } } }, "summary": "Published platform plan pricing (safe projection).", "tags": [ "public-plan-pricing" ] } }, "/api/v1/public/api-schema": { "get": { "description": "Anonymous and unauthenticated. Returns the content digest of the public OpenAPI document this deployment was built from. Compare it to `info.version` in the API reference you are reading: equal means the reference describes the public contract this runtime serves. Different means the two are out of step — the reference is either ahead of or behind this deployment, and the digest alone does not say which.", "operationId": "PublicApiSchemaController_read", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSchemaIdentityDto" } } } } }, "summary": "Schema identity of the running API build.", "tags": [ "public-api-schema" ] } }, "/api/v1/support-provider/catalog/search": { "post": { "description": "Read-only, live, and bounded to ten ACTIVE/non-archived products. The tenant, runtime, workspace, resource, and catalog_publish capability come only from the active connection credential. The response is retained-provider-safe and contains no customer proof, private context, inventory quantities, cart action, or checkout action.", "operationId": "SupportProviderPublicCatalogController_search", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSupportProviderCatalogDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportProviderCatalogSearchResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } }, "headers": { "Retry-After": { "description": "Positive whole-number seconds to wait before retrying the request.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "security": [ { "SupportProviderConnection": [] } ], "summary": "Search the connection tenant’s public catalog for Fin.", "tags": [ "support-provider-catalog" ] } } }, "info": { "title": "litecommerce API", "description": "Multi-tenant commerce API. The integrator-facing surface is:\n- `/api/v1/public/*` — anonymous storefront/customer reads + checkout (browser; `x-organization-slug` + CORS)\n- `/api/v1/merchant/*` — authenticated merchant staff (merchant JWT `Bearer` + `x-organization-slug`)\n- `/api/v1/customer/*` — authenticated customer (customer session: `Bearer` opaque session token OR `__Host-` session cookie; plus `x-organization-slug`)\n- `/api/v1/storefront/*` — external/BYO storefront SERVER-TO-SERVER calls, authenticated by a tenant API key (`x-api-key`, server-side only). The tenant is resolved from the key.\n- `/api/v1/import/*` — server-to-server catalog/data IMPORT, authenticated by a tenant API key (`x-api-key`, server-side only) with an `import:*` write scope. Idempotent, batch-first, `dryRun`-capable.\n- `/api/v1/support-provider/*` — provider-to-litecommerce callouts authenticated by an active, resource-bound `x-litecommerce-connection-token`; tenant selection is never accepted from the request.\n\nInternal platform-admin (`/api/v1/platform/*`) and service-to-service\n(`/api/v1/internal/*`) routes are intentionally excluded from this\npublic reference. Each namespace is single-mount — no dual-route\naliases.\n\n**Schema identity.** `info.version` on this document is a SCHEMA DIGEST\n(`sha256:`), not a release or package version — it is opaque, and\n\"newer\" is not decidable from it. The running API serves the same value\nfrom `GET /api/v1/public/api-schema` (public, unauthenticated). If the two\nstrings are equal, the runtime you are calling was built from the same\ngenerated public API surface this reference describes. The digest covers the\nwhole generated document except `servers` (rewritten per publication target)\nand `info.version` itself. Step-by-step comparison:\n`https://docs.litecommerce.io/concepts/environments`.", "version": "sha256:65830f33f8dce6f7acfa83d52b6cea27e12e502a11f63918cc44a782f6983cbf", "contact": { "name": "litecommerce", "url": "", "email": "" } }, "tags": [ { "name": "health", "description": "" }, { "name": "public-api-schema", "description": "" }, { "name": "public-catalog", "description": "" }, { "name": "public-inventory", "description": "" }, { "name": "public-bookings", "description": "" }, { "name": "public-orders", "description": "" }, { "name": "public-pages", "description": "" }, { "name": "public-signup", "description": "" }, { "name": "public-plan-pricing", "description": "" }, { "name": "merchant-items", "description": "" }, { "name": "merchant-collections", "description": "" }, { "name": "merchant-inventory", "description": "" }, { "name": "merchant-bookings", "description": "" }, { "name": "merchant-orders", "description": "" }, { "name": "merchant-commerce", "description": "" }, { "name": "merchant-checkout-support", "description": "" }, { "name": "merchant-pages", "description": "" }, { "name": "merchant-api-keys", "description": "" }, { "name": "merchant-uploads", "description": "" }, { "name": "customer-account", "description": "" }, { "name": "customer-actions", "description": "" }, { "name": "customer-auth", "description": "" }, { "name": "storefront", "description": "" }, { "name": "import", "description": "" }, { "name": "support-provider-catalog", "description": "" }, { "name": "webhooks", "description": "" }, { "name": "auth", "description": "" } ], "servers": [ { "url": "https://api.litecommerce.io", "description": "Production" }, { "url": "https://api.preview.litecommerce.io", "description": "Preview (staging)" } ], "components": { "securitySchemes": { "BearerAuth": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" }, "CustomerSession": { "scheme": "bearer", "bearerFormat": "opaque", "type": "http", "description": "Customer session — opaque session token (not a JWT); the __Host- session cookie is the browser-side alternative." }, "OrganizationSlug": { "type": "apiKey", "in": "header", "name": "x-organization-slug" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Tenant API key — `.` (e.g. `lcp_….lck_…`). Server-side only; never expose in browser JavaScript." }, "SupportProviderConnection": { "type": "apiKey", "in": "header", "name": "x-litecommerce-connection-token", "description": "Resource-bound support-provider connection credential. The credential fixes tenant, runtime, provider workspace, resource, and allowed capability; never expose it in browser JavaScript." } }, "schemas": { "MerchantSessionUserDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "authUserId": { "type": "string", "nullable": true, "description": "Supabase auth user id; `null` until first sign-in." }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "lastLoginAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "authUserId", "email", "firstName", "lastName", "phone", "lastLoginAt", "createdAt", "updatedAt" ] }, "MerchantMembershipDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "organizationSlug": { "type": "string" }, "organizationName": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "staff" ], "example": "owner" }, "permissionGroups": { "description": "Effective permission-group keys (preset + direct).", "type": "array", "items": { "type": "string" } }, "permissionPresetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Applied permission preset, or `null`." } }, "required": [ "id", "organizationId", "organizationSlug", "organizationName", "role", "permissionGroups", "permissionPresetId" ] }, "MerchantSessionResponseDto": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/MerchantSessionUserDto" }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMembershipDto" } } }, "required": [ "user", "memberships" ] }, "ApiErrorDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Open-ended stable string code. Branch on known codes and fall back to the HTTP status and generic error envelope for an unknown code.", "example": "VALIDATION_FAILED", "x-extensible-enum": [ "VALIDATION_FAILED", "AUTH_MISSING_TOKEN", "AUTH_INVALID_TOKEN", "MEMBERSHIP_REQUIRED", "ROLE_INSUFFICIENT", "PLATFORM_ACCESS_DENIED", "RESOURCE_NOT_FOUND", "RESOURCE_CONFLICT", "DATABASE_ERROR", "INTERNAL_ERROR", "BAD_REQUEST", "LIMIT_EXCEEDED", "RATE_LIMIT_EXCEEDED", "ORGANIZATION_SUSPENDED", "ORGANIZATION_ARCHIVED", "API_KEY_SCOPE_INSUFFICIENT", "COMMERCE_REVISION_IMMUTABLE", "COMMERCE_REVISION_STALE", "HIGH_RISK_REASON_REQUIRED", "HIGH_RISK_STEP_UP_REQUIRED", "COMMERCE_IDEMPOTENCY_CONFLICT", "COMMERCE_EXTERNAL_ID_CONFLICT", "COMMERCE_LIFECYCLE_INVALID", "COMMERCE_PAYMENT_INVALID", "COMMERCE_OVERRIDE_ACTIVE", "API_KEY_SCOPE_GATED", "IMPORT_ROW_VALIDATION_FAILED", "IMPORT_ROW_CONFLICT", "IMPORT_ROW_UNRESOLVED_REFERENCE", "IMPORT_BATCH_TOO_LARGE", "POS_NOT_READY", "POS_SESSION_INVALID", "POS_ORGANIZATION_REQUIRED", "BOOKING_CAPACITY_UNAVAILABLE", "BOOKING_IDEMPOTENCY_CONFLICT", "BOOKING_CONFIGURATION_BUSY", "BOOKING_GROUP_LIMIT_EXCEEDED", "BOOKING_GROUP_INCOMPATIBLE", "BOOKING_GROUP_SECURITY_AUTH_UNSUPPORTED", "BOOKING_GROUP_IDEMPOTENCY_CONFLICT", "BOOKING_GROUP_ACTION_REQUIRED", "BOOKING_GROUP_ACTION_INVALID", "PLATFORM_BILLING_UNAVAILABLE", "PLATFORM_BILLING_QUOTE_STALE", "PLATFORM_BILLING_RECOVERY_REQUIRED", "BOOKING_DELIVERY_INVALID", "BOOKING_DELIVERY_DESTINATION_INVALID", "BOOKING_DELIVERY_UNAVAILABLE", "BOOKING_DELIVERY_OUT_OF_RANGE", "BOOKING_DELIVERY_CONFIGURATION_CHANGED", "AGREEMENT_ACTION_REQUIRED", "AGREEMENT_POLICY_INVALID", "AGREEMENT_APPLICABILITY_INVALID", "AGREEMENT_WAIVER_REASON_REQUIRED", "AGREEMENT_REQUIREMENT_INVALID", "ENTITLEMENT_TOKENS_UNAVAILABLE", "ENTITLEMENT_NOT_CONSUMABLE", "SUBSCRIPTION_PAYMENT_RECOVERY_UNAVAILABLE", "SUBSCRIPTION_PAYMENT_RECOVERY_UNSUPPORTED", "COMPOSITION_REVISION_STALE", "COMPOSITION_INVALID", "COMPOSITION_INVENTORY_CONFLICT", "COMPOSITION_COMPONENT_MAPPING_MISSING", "COMPOSITION_COMPONENT_MAPPING_AMBIGUOUS", "SUPPORT_PROVIDER_CONFIGURATION_UNAVAILABLE", "SUPPORT_PROVIDER_CONNECTION_CONFLICT", "SUBSCRIPTION_PAYMENT_RECOVERY_RESEND_REJECTED", "CATALOG_MEDIA_QUARANTINED", "EMAIL_SENDING_DOMAIN_LIFECYCLE_UNAVAILABLE", "CHECKOUT_PREPARED_PAYMENT_CONFLICT", "PLATFORM_BILLING_PLAN_CHANGE_REJECTED", "BOOKING_PRICE_CONFIRMATION_REQUIRED", "BOOKING_PRICE_CONFIRMATION_UNAVAILABLE", "EMAIL_TEST_RECIPIENT_REJECTED", "EMAIL_TEST_DELIVERY_UNAVAILABLE", "PRICING_POLICY_INCOMPATIBLE", "CHECKOUT_IDENTITY_CHANGED", "CHECKOUT_IDENTITY_VERIFICATION_REQUIRED", "ORDER_REFERENCE_UNAVAILABLE", "ORDER_REFERENCE_SERVICE_UNAVAILABLE", "PLATFORM_TAX_UNAVAILABLE", "TENANT_TAX_NOT_CONFIGURED", "POS_SALE_REJECTED", "POS_SALE_REJECTION_PERSISTENCE_FAILED", "CHECKOUT_ALREADY_PAID" ] }, "message": { "type": "string", "description": "Human-readable explanation. Not localized.", "example": "Request body failed validation" }, "details": { "type": "object", "description": "Optional structured context. Shape varies by error code; e.g. VALIDATION_FAILED returns the per-field violation list.", "additionalProperties": true } }, "required": [ "code", "message" ] }, "UpdateMerchantProfileDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Given name. Send null (or a blank/whitespace string) to clear; omit to leave unchanged.", "nullable": true, "maxLength": 100, "example": "Robin" }, "lastName": { "type": "string", "description": "Family name. Send null (or a blank/whitespace string) to clear; omit to leave unchanged.", "nullable": true, "maxLength": 100, "example": "Vale" } } }, "MerchantProfileResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "authUserId": { "type": "string", "nullable": true, "description": "Supabase auth user id; null until the user first signs in." }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "lastLoginAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "authUserId", "email", "firstName", "lastName", "phone", "lastLoginAt", "createdAt", "updatedAt" ] }, "MerchantMembershipUserSnapshotDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "lastLoginAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "email", "firstName", "lastName", "lastLoginAt" ] }, "MerchantMembershipListItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "staff" ], "example": "staff" }, "permissionGroups": { "type": "array", "items": { "type": "string" } }, "permissionPresetId": { "type": "string", "format": "uuid", "nullable": true }, "user": { "$ref": "#/components/schemas/MerchantMembershipUserSnapshotDto" } }, "required": [ "id", "role", "permissionGroups", "permissionPresetId", "user" ] }, "MerchantPermissionPresetDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "read-only-staff", "description": "Stable preset key." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "permissionGroups": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean", "description": "True for built-in presets the merchant cannot edit." } }, "required": [ "id", "key", "name", "description", "permissionGroups", "isSystem" ] }, "CreateMembershipDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of the user to invite. If they have not yet logged in via Supabase Auth, a placeholder users row is created; on their first login MerchantAuthGuard fills in the authUserId." }, "firstName": { "type": "string", "description": "Optional first name for the invited teammate. When supplied for an existing user, it only fills an empty local profile field.", "nullable": true, "maxLength": 80 }, "lastName": { "type": "string", "description": "Optional last name for the invited teammate. When supplied for an existing user, it only fills an empty local profile field.", "nullable": true, "maxLength": 80 }, "role": { "type": "string", "description": "The role to grant.", "enum": [ "OWNER", "ADMIN", "STAFF" ] }, "permissionPresetId": { "type": "string", "description": "Optional Staff permission preset id. Ignored for Owner/Admin roles.", "nullable": true }, "permissionGroups": { "description": "Optional direct Staff permission groups. Owner/Admin roles always receive broad access and do not use group assignments.", "type": "array", "items": { "type": "string" } } }, "required": [ "email", "role" ] }, "MerchantMembershipCreateResultDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "organizationSlug": { "type": "string" }, "organizationName": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "staff" ], "example": "staff" }, "permissionGroups": { "description": "DIRECT permission-group keys stored on the new membership. If a `permissionPresetId` was assigned, the preset's groups are NOT included here — they merge into the effective set on the next `GET session` read.", "type": "array", "items": { "type": "string" } }, "permissionPresetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Applied permission preset, or `null`." } }, "required": [ "id", "organizationId", "organizationSlug", "organizationName", "role", "permissionGroups", "permissionPresetId" ] }, "UpdateMembershipDto": { "type": "object", "properties": { "role": { "type": "string", "description": "Optional role change.", "enum": [ "OWNER", "ADMIN", "STAFF" ] }, "permissionPresetId": { "type": "string", "description": "Staff permission preset id. Send null to clear the preset.", "nullable": true }, "permissionGroups": { "description": "Direct Staff permission groups. Replaces the existing direct group list.", "type": "array", "items": { "type": "string" } } } }, "MerchantMembershipUpdateResultDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "staff" ], "example": "admin" }, "permissionGroups": { "type": "array", "items": { "type": "string" } }, "permissionPresetId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "organizationId", "role", "permissionGroups", "permissionPresetId" ] }, "MerchantOnboardingStepDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "stepKey": { "type": "string", "example": "add_first_item", "description": "Stable onboarding step key." }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion time, or `null` if incomplete." }, "completedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User who completed the step, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "stepKey", "completedAt", "completedBy", "createdAt", "updatedAt" ] }, "MerchantOnboardingSummaryDto": { "type": "object", "properties": { "totalSteps": { "type": "number", "example": 6 }, "completedSteps": { "type": "number", "example": 2 }, "percent": { "type": "number", "example": 33, "description": "Completion percentage (0–100)." } }, "required": [ "totalSteps", "completedSteps", "percent" ] }, "MerchantOnboardingStateDto": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOnboardingStepDto" } }, "summary": { "$ref": "#/components/schemas/MerchantOnboardingSummaryDto" } }, "required": [ "steps", "summary" ] }, "UpdateOnboardingStepDto": { "type": "object", "properties": { "completed": { "type": "boolean", "description": "New completion state for the step. `true` stamps completedAt + completedBy with the actor; `false` clears both back to null.", "example": true } }, "required": [ "completed" ] }, "EmailTemplateSlotsDto": { "type": "object", "properties": { "subject": { "type": "string" }, "heading": { "type": "string" }, "bodyText": { "type": "string" }, "ctaLabel": { "type": "string", "nullable": true } }, "required": [ "subject", "heading", "bodyText", "ctaLabel" ] }, "EmailTemplateOverrideDto": { "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "heading": { "type": "string", "nullable": true }, "bodyText": { "type": "string", "nullable": true }, "ctaLabel": { "type": "string", "nullable": true }, "fromName": { "type": "string", "nullable": true }, "replyTo": { "type": "string", "nullable": true } }, "required": [ "subject", "heading", "bodyText", "ctaLabel", "fromName", "replyTo" ] }, "EmailTemplateVariableDto": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "sample": { "type": "string" } }, "required": [ "key", "label", "description", "sample" ] }, "EmailTemplateDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CUSTOMER_AUTH", "ORDER_CONFIRMATION", "ABANDONED_CART_RECOVERY", "BACK_IN_STOCK", "STOCK_NOTIFICATION_CONFIRMATION", "NEWSLETTER_CONFIRMATION", "RETURN_REQUESTED", "RETURN_APPROVED", "RETURN_RECEIVED", "RETURN_COMPLETED", "RETURN_REJECTED", "COMMERCE_QUOTE_SEND", "COMMERCE_INVOICE_SEND", "COMMERCE_CONTRACT_SEND", "COMMERCE_CONTRACT_COUNTERSIGNED", "COMMERCE_CONTRACT_VOIDED", "COMMERCE_QUOTE_EXPIRED", "BOOKING_NOTIFICATION", "COMMERCE_PAYMENT_RECEIVED", "ORDER_SHIPPED", "SUBSCRIPTION_PAYMENT_RECOVERY" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": [ "account", "checkout", "marketing", "returns" ] }, "defaults": { "$ref": "#/components/schemas/EmailTemplateSlotsDto" }, "override": { "$ref": "#/components/schemas/EmailTemplateOverrideDto" }, "resolved": { "$ref": "#/components/schemas/EmailTemplateSlotsDto" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateVariableDto" } }, "fromName": { "type": "string" }, "replyTo": { "type": "string", "nullable": true }, "complianceFooter": { "type": "string" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "type", "label", "description", "category", "defaults", "override", "resolved", "variables", "fromName", "replyTo", "complianceFooter", "updatedAt" ] }, "ListEmailTemplatesResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateDto" } } }, "required": [ "data" ] }, "UpdateEmailTemplateDto": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 180, "nullable": true }, "heading": { "type": "string", "maxLength": 120, "nullable": true }, "bodyText": { "type": "string", "maxLength": 2000, "nullable": true }, "ctaLabel": { "type": "string", "maxLength": 80, "nullable": true }, "fromName": { "type": "string", "maxLength": 80, "nullable": true }, "replyTo": { "type": "string", "maxLength": 254, "nullable": true } } }, "PreviewEmailTemplateDto": { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/UpdateEmailTemplateDto" } } }, "EmailTemplatePreviewDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CUSTOMER_AUTH", "ORDER_CONFIRMATION", "ABANDONED_CART_RECOVERY", "BACK_IN_STOCK", "STOCK_NOTIFICATION_CONFIRMATION", "NEWSLETTER_CONFIRMATION", "RETURN_REQUESTED", "RETURN_APPROVED", "RETURN_RECEIVED", "RETURN_COMPLETED", "RETURN_REJECTED", "COMMERCE_QUOTE_SEND", "COMMERCE_INVOICE_SEND", "COMMERCE_CONTRACT_SEND", "COMMERCE_CONTRACT_COUNTERSIGNED", "COMMERCE_CONTRACT_VOIDED", "COMMERCE_QUOTE_EXPIRED", "BOOKING_NOTIFICATION", "COMMERCE_PAYMENT_RECEIVED", "ORDER_SHIPPED", "SUBSCRIPTION_PAYMENT_RECOVERY" ] }, "label": { "type": "string" }, "subject": { "type": "string" }, "heading": { "type": "string" }, "bodyText": { "type": "string" }, "ctaLabel": { "type": "string", "nullable": true }, "fromName": { "type": "string" }, "replyTo": { "type": "string", "nullable": true }, "complianceFooter": { "type": "string" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateVariableDto" } } }, "required": [ "type", "label", "subject", "heading", "bodyText", "ctaLabel", "fromName", "replyTo", "complianceFooter", "variables" ] }, "SendTestEmailTemplateDto": { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/UpdateEmailTemplateDto" }, "recipientMode": { "type": "string", "enum": [ "SELF", "CUSTOM_ADDRESS" ], "default": "SELF", "description": "Selects the server-resolved admin email or the temporary #3358 custom-address bridge. #1744 replaces CUSTOM_ADDRESS with an opaque verified destination identifier when E15 recipient verification ships." }, "recipientEmail": { "type": "string", "maxLength": 320, "description": "Temporary #3358 custom recipient candidate. It is never treated as verified. In the non-production planes where this mode is available, centralized server email policy evaluates it before provider I/O; production rejects this mode before policy evaluation. Omit when recipientMode is SELF." } } }, "SendTestEmailTemplateResponseDto": { "type": "object", "properties": { "sent": { "type": "boolean" }, "skipped": { "type": "boolean", "deprecated": true, "description": "Retained as false for response-shape compatibility. An unavailable provider now returns EMAIL_TEST_DELIVERY_UNAVAILABLE with HTTP 503." }, "messageId": { "type": "string", "nullable": true, "deprecated": true, "description": "Retained as null for response-shape compatibility. Provider message identifiers are never exposed to the browser." } }, "required": [ "sent", "skipped", "messageId" ] }, "CreatePendingSignupDto": { "type": "object", "properties": { "contactName": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "maxLength": 254 }, "tenantName": { "type": "string", "maxLength": 120 }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ], "default": "free", "description": "Requested marketing plan. Enforcement lands in Epic 1.5.4." }, "source": { "type": "string", "maxLength": 120, "description": "Attribution string such as pricing-free or footer-signup." } }, "required": [ "contactName", "email", "tenantName" ] }, "PublicPendingSignupResponseDto": { "type": "object", "properties": { "received": { "type": "boolean", "description": "Always true when the API accepts the submission for processing. Identical for fresh and already-pending/approved emails.", "example": true } }, "required": [ "received" ] }, "CreateStockNotificationDto": { "type": "object", "properties": { "variantId": { "type": "string", "description": "Variant id when the customer selected one before signing up.", "nullable": true }, "email": { "type": "string", "description": "Customer email. Normalised lowercase before insert.", "example": "customer@example.com", "maxLength": 320 } }, "required": [ "email" ], "additionalProperties": false }, "StockNotificationResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on a 201 — the anonymous submission was acknowledged. This does not disclose whether an active subscription was created.", "example": true }, "alreadySubscribed": { "type": "boolean", "description": "Compatibility field: true for an idempotent repeat of an active pending signup. False is a neutral acknowledgement and does not imply that a new active subscription was created.", "example": false } }, "required": [ "ok", "alreadySubscribed" ] }, "StockNotificationItemRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "StockNotificationVariantRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "id", "name", "sku" ] }, "MerchantStockNotificationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "Requested variant, or `null` for item-level." }, "email": { "type": "string", "format": "email" }, "createdAt": { "format": "date-time", "type": "string" }, "notifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the back-in-stock email fired, or `null`." }, "unsubscribedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Unsubscribe time, or `null`." }, "item": { "$ref": "#/components/schemas/StockNotificationItemRefDto" }, "variant": { "nullable": true, "description": "Variant ref, or `null` for item-level requests.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/StockNotificationVariantRefDto" } ] } }, "required": [ "id", "organizationId", "itemId", "variantId", "email", "createdAt", "notifiedAt", "unsubscribedAt", "item", "variant" ] }, "MerchantStockNotificationPageDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantStockNotificationDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page, or `null` at the end." } }, "required": [ "data", "nextCursor" ] }, "SubscribeNewsletterDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Subscriber email. Normalised lowercase before insert.", "example": "customer@example.com", "maxLength": 320 }, "source": { "type": "string", "description": "Optional capture-origin tag (e.g. \"footer\", \"checkout\"). Free-form, length-capped, never trusted for control flow.", "nullable": true, "maxLength": 64 } }, "required": [ "email" ], "additionalProperties": false }, "NewsletterSubscribeResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true. Constant regardless of subscriber state so the response cannot be used to probe which addresses are already on the list.", "example": true } }, "required": [ "ok" ] }, "MerchantNewsletterSubscriberDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "UNSUBSCRIBED" ], "example": "CONFIRMED" }, "source": { "type": "string", "nullable": true, "description": "Signup source, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Double-opt-in confirmation time, or `null`." }, "unsubscribedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Unsubscribe time, or `null`." } }, "required": [ "id", "email", "status", "source", "createdAt", "confirmedAt", "unsubscribedAt" ] }, "MerchantNewsletterSubscriberPageDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantNewsletterSubscriberDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page, or `null` at the end." } }, "required": [ "data", "nextCursor" ] }, "AbandonedCartSnapshotItemDto": { "type": "object", "properties": { "itemId": { "type": "string" }, "variantId": { "type": "string" }, "name": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 1 }, "unitPriceInCents": { "type": "number", "minimum": 0, "description": "Unit price in cents at capture time." } }, "required": [ "itemId", "name", "quantity", "unitPriceInCents" ], "additionalProperties": false }, "AbandonedCartSnapshotDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AbandonedCartSnapshotItemDto" } }, "subtotalInCents": { "type": "number", "minimum": 0 }, "totalInCents": { "type": "number", "minimum": 0 } }, "required": [ "items", "subtotalInCents", "totalInCents" ], "additionalProperties": false }, "UpsertAbandonedCartDto": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Storefront-issued anonymous cart session identifier. Stable for the duration of a browse session; the upsert key for \"same customer abandoning the same cart multiple times.\"", "minLength": 8, "maxLength": 200 }, "captureToken": { "type": "string", "description": "Client-generated, high-entropy capability token for this session. The storefront generates it once, persists it in localStorage beside the sessionId, and sends it on EVERY capture. The first capture binds it (the API stores only its hash); later updates must present the same token or are rejected (403). It is a separate secret from the sessionId, so leaking the sessionId is not enough to overwrite the cart (#1208). Optional only for degraded clients that cannot generate one — such a capture creates an unprotected, still-adoptable row.", "minLength": 16, "maxLength": 128 }, "email": { "type": "string", "description": "Customer email if captured. Optional — a cart can be abandoned before the customer enters one. Normalised lowercase before insert.", "maxLength": 320 }, "snapshot": { "description": "Frozen snapshot of cart contents at capture time. Stored verbatim; recovery emails reference this, not live catalog data.", "allOf": [ { "$ref": "#/components/schemas/AbandonedCartSnapshotDto" } ] } }, "required": [ "sessionId", "snapshot" ], "additionalProperties": false }, "AbandonedCartCaptureResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on a 201 — the capture was accepted.", "example": true }, "wasCreated": { "type": "boolean", "description": "True when a new snapshot row was created; false when an existing (organizationId, sessionId) row was updated in place.", "example": true } }, "required": [ "ok", "wasCreated" ] }, "MerchantAbandonedCartDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "description": "Storefront cart session that abandoned." }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Captured email, or `null` if never provided." }, "subtotalInCents": { "type": "number", "example": 29800 }, "totalInCents": { "type": "number", "example": 31588 }, "capturedAt": { "format": "date-time", "type": "string" }, "recoveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the cart was recovered, or `null`." }, "recoveryEmailSentAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the last recovery email was sent, or `null`." }, "recoveryEmailCount": { "type": "number", "example": 0, "description": "Number of recovery emails sent." }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "sessionId", "email", "subtotalInCents", "totalInCents", "capturedAt", "recoveredAt", "recoveryEmailSentAt", "recoveryEmailCount", "updatedAt" ] }, "MerchantAbandonedCartPageDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAbandonedCartDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page, or `null` at the end." } }, "required": [ "data", "nextCursor" ] }, "SellMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION", "ONE_TIME_AND_SUBSCRIPTION" ], "description": "Merchant-configured catalog capability: one-time, subscription, or either. Variant rows carry their server-resolved effective mode separately. A subscription-capable value does not guarantee that an active, published, currently synced subscription plan exists; query the public subscription-plan endpoints for actual offer availability." }, "WeightUnit": { "type": "string", "enum": [ "OZ", "LB", "G", "KG" ] }, "DimensionUnit": { "type": "string", "enum": [ "IN", "CM" ] }, "PublicItemImageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "storagePath": { "type": "string", "description": "Structured storage path inside the catalog media bucket." }, "alt": { "type": "string" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "type": "number" }, "focalX": { "type": "number", "nullable": true, "description": "Normalised 0..1 horizontal focal point. `null` when unset." }, "focalY": { "type": "number", "nullable": true, "description": "Normalised 0..1 vertical focal point. `null` when unset." }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "bytes": { "type": "number", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "itemId", "url", "storagePath", "alt", "isPrimary", "sortOrder", "focalX", "focalY", "width", "height", "bytes", "mimeType", "createdAt", "updatedAt" ] }, "PublicItemVariantDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid", "description": "#1411 — denormalized tenant scope (always the parent item's organization; the parent item already exposes it publicly)." }, "name": { "type": "string" }, "sku": { "type": "string" }, "priceInCents": { "type": "number" }, "sellMode": { "description": "The variant's effective catalog capability. A null authoring override is resolved server-side to the parent item's mode before this public projection is returned, so storefronts never have to implement the inheritance rule themselves. A subscription-capable value does not guarantee that an active, published, currently synced subscription plan exists; resolve plan availability through the public subscription-plan endpoints.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "compareAtPriceInCents": { "type": "number", "nullable": true }, "weight": { "type": "number", "nullable": true }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "size": "M", "color": "Red" }, "description": "The variant's customer-facing option map — a flat string→string map (keys and values are both strings), matching the write contract (`CreateVariantDto.options` + the `IsStringStringMap` validator)." }, "metafields": { "type": "object", "additionalProperties": true }, "featuredImageId": { "type": "string", "nullable": true, "description": "Featured image id (a row in the parent item gallery). `null` falls back to the item's primary image." }, "sortOrder": { "type": "number" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "salePriceInCents": { "type": "number", "nullable": true, "description": "Active sale price in cents (variant window wins over the item-level one). `null` when no sale window is active." }, "saleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the active sale ends (ISO). `null` when no active sale." } }, "required": [ "id", "itemId", "organizationId", "name", "sku", "priceInCents", "sellMode", "compareAtPriceInCents", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "options", "metafields", "featuredImageId", "sortOrder", "archivedAt", "createdAt", "updatedAt", "salePriceInCents", "saleEndsAt" ] }, "PublicItemCompositionComponentDto": { "type": "object", "properties": { "name": { "type": "string" }, "variantName": { "type": "string", "nullable": true }, "itemType": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Units included per one top-level package selection." }, "intrinsicSavingsBasisPoints": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "description": "Intrinsic component savings in basis points. External promotions are not included." } }, "required": [ "name", "variantName", "itemType", "quantity", "intrinsicSavingsBasisPoints" ] }, "PublicItemCompositionDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "revision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Definition revision clients must echo when committing this selection." }, "components": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/PublicItemCompositionComponentDto" } } }, "required": [ "kind", "revision", "components" ] }, "PublicItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "shortDescription": { "type": "string" }, "type": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. Public reads only ever return `ACTIVE`; merchant collection-item reads may also return `DRAFT` / `ARCHIVED`." }, "sellMode": { "description": "Merchant-configured catalog capability: one-time, subscription, or either. Variant rows carry their server-resolved effective mode separately. A subscription-capable value does not guarantee that an active, published, currently synced subscription plan exists; query the public subscription-plan endpoints for actual offer availability.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "priceInCents": { "type": "number" }, "compareAtPriceInCents": { "type": "number", "nullable": true, "description": "Strikethrough \"compare at\" price. `null` when no sale price." }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy free-form metadata blob. `null` when unset." }, "brand": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "productFamily": { "type": "string", "nullable": true }, "weight": { "type": "number", "nullable": true }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "metafields": { "type": "object", "additionalProperties": true }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish state map." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active items." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemImageDto" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemVariantDto" } }, "salePriceInCents": { "type": "number", "nullable": true, "description": "Active item-level sale price in cents. `null` when no sale window is active (variants carry their own resolution)." }, "saleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the active item-level sale ends (ISO). `null` if none." }, "ratingAverage": { "type": "number", "nullable": true, "description": "Derived average rating (`reviewRatingSum / reviewRatingCount`). `null` when there are no published reviews (distinguishes \"unrated\" from \"0\")." }, "ratingCount": { "type": "number", "description": "Number of published reviews." }, "composition": { "nullable": true, "description": "Bounded customer-safe package/kit definition. Component and catalog ids, capacity mappings, providers, and tenant internals are omitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicItemCompositionDto" } ] }, "collectionIds": { "description": "Ids of the collections this item belongs to (#554).", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "slug", "name", "description", "shortDescription", "type", "status", "sellMode", "priceInCents", "compareAtPriceInCents", "tags", "metadata", "brand", "vendor", "productFamily", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "metafields", "channelPublishStatus", "sortOrder", "archivedAt", "createdAt", "updatedAt", "images", "variants", "salePriceInCents", "saleEndsAt", "ratingAverage", "ratingCount", "composition", "collectionIds" ] }, "ResolvePublicCartItemsDto": { "type": "object", "properties": { "slugs": { "minItems": 1, "maxItems": 200, "uniqueItems": true, "description": "Distinct tenant item slugs to resolve for saved-cart restoration.", "type": "array", "items": { "type": "string" } } }, "required": [ "slugs" ], "additionalProperties": false }, "PublicCartCatalogItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "composition": { "nullable": true, "description": "Current customer-safe package/kit definition, or null for an ordinary item.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicItemCompositionDto" } ] } }, "required": [ "id", "slug", "composition" ] }, "PublicCollectionCountDto": { "type": "object", "properties": { "collectionItems": { "type": "number", "description": "Number of items assigned to this collection.", "example": 12 } }, "required": [ "collectionItems" ] }, "PublicCollectionImageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "storagePath": { "type": "string", "description": "Structured storage path inside the catalog media bucket." }, "alt": { "type": "string" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "type": "number" }, "focalX": { "type": "number", "nullable": true, "description": "Normalised 0..1 horizontal focal point. `null` when unset." }, "focalY": { "type": "number", "nullable": true, "description": "Normalised 0..1 vertical focal point. `null` when unset." }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "bytes": { "type": "number", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "collectionId", "url", "storagePath", "alt", "isPrimary", "sortOrder", "focalX", "focalY", "width", "height", "bytes", "mimeType", "createdAt", "updatedAt" ] }, "PublicCollectionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy single-image JSON blob (pre-Epic-6). `null` when unset; the structured gallery lives in `images`." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The public read only ever returns `ACTIVE` rows." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp. Always `null` on the public read (archived collections are filtered out)." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "_count": { "$ref": "#/components/schemas/PublicCollectionCountDto" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCollectionImageDto" } } }, "required": [ "id", "organizationId", "slug", "name", "description", "image", "sortOrder", "status", "archivedAt", "createdAt", "updatedAt", "_count", "images" ] }, "MerchantItemListVariantDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid", "description": "#1411 — denormalized tenant scope (always the parent item's organization; the parent item already exposes it publicly)." }, "name": { "type": "string" }, "sku": { "type": "string" }, "priceInCents": { "type": "number" }, "compareAtPriceInCents": { "type": "number", "nullable": true }, "weight": { "type": "number", "nullable": true }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "size": "M", "color": "Red" }, "description": "The variant's customer-facing option map — a flat string→string map (keys and values are both strings), matching the write contract (`CreateVariantDto.options` + the `IsStringStringMap` validator)." }, "metafields": { "type": "object", "additionalProperties": true }, "featuredImageId": { "type": "string", "nullable": true, "description": "Featured image id (a row in the parent item gallery). `null` falls back to the item's primary image." }, "sortOrder": { "type": "number" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "salePriceInCents": { "type": "number", "nullable": true, "description": "Active sale price in cents (variant window wins over the item-level one). `null` when no sale window is active." }, "saleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the active sale ends (ISO). `null` when no active sale." }, "sellMode": { "nullable": true, "description": "The merchant-editable variant override; `null` inherits the parent item's mode. Public catalog reads resolve this to a non-null mode.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] } }, "required": [ "id", "itemId", "organizationId", "name", "sku", "priceInCents", "compareAtPriceInCents", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "options", "metafields", "featuredImageId", "sortOrder", "archivedAt", "createdAt", "updatedAt", "salePriceInCents", "saleEndsAt", "sellMode" ] }, "MerchantItemListItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "shortDescription": { "type": "string" }, "type": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. Public reads only ever return `ACTIVE`; merchant collection-item reads may also return `DRAFT` / `ARCHIVED`." }, "sellMode": { "description": "Merchant-configured catalog capability: one-time, subscription, or either. Variant rows carry their server-resolved effective mode separately. A subscription-capable value does not guarantee that an active, published, currently synced subscription plan exists; query the public subscription-plan endpoints for actual offer availability.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "priceInCents": { "type": "number" }, "compareAtPriceInCents": { "type": "number", "nullable": true, "description": "Strikethrough \"compare at\" price. `null` when no sale price." }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy free-form metadata blob. `null` when unset." }, "brand": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "productFamily": { "type": "string", "nullable": true }, "weight": { "type": "number", "nullable": true }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "metafields": { "type": "object", "additionalProperties": true }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish state map." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active items." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicItemImageDto" } }, "salePriceInCents": { "type": "number", "nullable": true, "description": "Active item-level sale price in cents. `null` when no sale window is active (variants carry their own resolution)." }, "saleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the active item-level sale ends (ISO). `null` if none." }, "ratingAverage": { "type": "number", "nullable": true, "description": "Derived average rating (`reviewRatingSum / reviewRatingCount`). `null` when there are no published reviews (distinguishes \"unrated\" from \"0\")." }, "ratingCount": { "type": "number", "description": "Number of published reviews." }, "composition": { "nullable": true, "description": "Bounded customer-safe package/kit definition. Component and catalog ids, capacity mappings, providers, and tenant internals are omitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicItemCompositionDto" } ] }, "collectionIds": { "description": "Ids of the collections this item belongs to (#554).", "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantItemListVariantDto" } } }, "required": [ "id", "organizationId", "slug", "name", "description", "shortDescription", "type", "status", "sellMode", "priceInCents", "compareAtPriceInCents", "tags", "metadata", "brand", "vendor", "productFamily", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "metafields", "channelPublishStatus", "sortOrder", "archivedAt", "createdAt", "updatedAt", "images", "salePriceInCents", "saleEndsAt", "ratingAverage", "ratingCount", "composition", "collectionIds", "variants" ] }, "MerchantItemListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantItemListItemDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor — pass back as `?cursor=` for the next page. `null` when there are no more items." } }, "required": [ "data", "nextCursor" ] }, "OrientationPolicy": { "type": "string", "enum": [ "CANONICAL_ONLY", "ANY_SIDE_RIGHT_ANGLE" ], "description": "Locked saved face or every distinct right-angle face rotation." }, "MerchantItemImageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "storagePath": { "type": "string", "description": "Structured storage path inside the catalog media bucket." }, "alt": { "type": "string" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "type": "number" }, "focalX": { "type": "number", "nullable": true, "description": "Normalised 0..1 horizontal focal point. `null` when unset." }, "focalY": { "type": "number", "nullable": true, "description": "Normalised 0..1 vertical focal point. `null` when unset." }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "bytes": { "type": "number", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "itemId", "url", "storagePath", "alt", "isPrimary", "sortOrder", "focalX", "focalY", "width", "height", "bytes", "mimeType", "createdAt", "updatedAt" ] }, "MerchantVariantDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid", "description": "#1411 — denormalized tenant scope (always the parent item's organization)." }, "name": { "type": "string" }, "sku": { "type": "string" }, "priceInCents": { "type": "number" }, "compareAtPriceInCents": { "type": "number", "nullable": true }, "sellMode": { "nullable": true, "description": "M5-3 (#628) — per-variant override of the item's sell mode; `null` inherits the parent item default.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. `null` when unset." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "nullable": true, "description": "Null inherits the item orientation policy.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "parcelMeasurementsReviewedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When a merchant last confirmed that the effective packed weight and dimensions are ready for package-fit recommendations." }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "size": "M", "color": "Red" }, "description": "The variant's customer-facing option map — a flat string→string map (keys and values are both strings), matching the write contract (`CreateVariantDto.options` + the `IsStringStringMap` validator)." }, "metafields": { "type": "object", "additionalProperties": true }, "featuredImageId": { "type": "string", "format": "uuid", "nullable": true, "description": "Featured image id (a row in the parent item gallery). `null` falls back to the item's primary image." }, "sortOrder": { "type": "number" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active variants." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "listPriceInCents": { "type": "number", "nullable": true, "description": "#3280 — the catalogued list price, echoing `priceInCents`. Named separately so a merchant surface can label the two columns without inferring which is which." }, "resolvedPriceInCents": { "type": "number", "nullable": true, "description": "#3280 / `DR-3265-20` — what this actually sells for right now, after any active sale window. Resolved through the same `SaleWindowService.resolveSalePrice` the charge path and the storefront use, so it cannot disagree with what a customer is charged. Equals the list price when no window applies, or when a window sits at or above the base — a sale window never raises a price (`DR-3265-14`).\n\n**Deterministic only.** Coupons, auto-discounts, and bundles are excluded by decision: a cart total or a typed code is not a property of a product, so this is not a quote." }, "resolvedBySaleWindowId": { "type": "string", "nullable": true, "description": "#3280 — the id of the sale window responsible for `resolvedPriceInCents`, or `null` when the list price stands. Deliberately `null` for an ACTIVE but inert window (one at or above the base): the question is which window is setting this price, and such a window is setting nothing." }, "resolvedSaleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3280 — when the responsible window ends, or `null` when no window is setting the price." }, "scheduledPriceInCents": { "type": "number", "nullable": true, "description": "#3312 — what this will sell for at the NEXT scheduled price change, or `null` when no future boundary discounts it. Every future window start AND end is evaluated through the shared resolver, so scope and never-raise apply at each instant — including an inert masking window's expiry revealing another window's discount, in which case `scheduledStartsAt` is that expiry, not the responsible window's start. Populated only when the effective price actually changes to a discount; reversion to base at an expiry is carried by `resolvedSaleEndsAt` instead. This is a SCHEDULED price, not the current one; a surface that renders it as current is wrong." }, "scheduledBySaleWindowId": { "type": "string", "nullable": true, "description": "#3312 — id of the window that will set `scheduledPriceInCents`, or `null` when none applies." }, "scheduledStartsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3312 — the boundary at which the scheduled price takes effect for this target (a window start, or a masking window's expiry), or `null` when none applies." }, "scheduledEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3312 — when the scheduled window stops applying, or `null` when none applies." } }, "required": [ "id", "itemId", "organizationId", "name", "sku", "priceInCents", "compareAtPriceInCents", "sellMode", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "orientationPolicy", "parcelMeasurementsReviewedAt", "options", "metafields", "featuredImageId", "sortOrder", "archivedAt", "createdAt", "updatedAt" ] }, "SaleWindowValueType": { "type": "string", "enum": [ "FIXED_PRICE", "AMOUNT_OFF", "PERCENT_OFF" ], "description": "#3324 / `DR-3265-27` — which value arm this window carries. Exactly one of the three arm fields is non-null: the one this names." }, "MerchantItemSaleWindowDto": { "type": "object", "properties": { "id": { "type": "string" }, "variantId": { "type": "string", "nullable": true, "description": "Target variant, or `null` for an item-level window that applies to every variant." }, "valueType": { "description": "#3324 / `DR-3265-27` — which value arm this window carries. Exactly one of the three arm fields is non-null: the one this names.", "allOf": [ { "$ref": "#/components/schemas/SaleWindowValueType" } ] }, "salePriceInCents": { "type": "number", "nullable": true, "description": "FIXED_PRICE arm — the absolute sale price in cents. `null` on the relative arms." }, "amountOffInCents": { "type": "number", "nullable": true, "description": "AMOUNT_OFF arm — cents off the live base, clamped at $0.00 at resolution. `null` unless `valueType` is AMOUNT_OFF." }, "percentOffBasisPoints": { "type": "number", "nullable": true, "description": "PERCENT_OFF arm — basis points off the live base, floor-rounded discount. `null` unless `valueType` is PERCENT_OFF." }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "variantId", "valueType", "salePriceInCents", "amountOffInCents", "percentOffBasisPoints", "startsAt", "endsAt" ] }, "MerchantItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "shortDescription": { "type": "string" }, "type": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "sellMode": { "description": "M5-3 (#628) — default purchase model for this item (`ONE_TIME` unless the merchant enables subscriptions). A variant may override it.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The merchant surface returns ACTIVE / DRAFT / ARCHIVED rows (unlike the public read, which is ACTIVE-only)." }, "priceInCents": { "type": "number" }, "compareAtPriceInCents": { "type": "number", "nullable": true, "description": "Strikethrough \"compare at\" price. `null` when no sale price." }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy free-form metadata blob. `null` when unset." }, "brand": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "productFamily": { "type": "string", "nullable": true }, "weight": { "type": "number", "nullable": true, "description": "Default physical weight, expressed in `weightUnit`. `null` when unset." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "description": "Locked saved face or every distinct right-angle face rotation.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "parcelMeasurementsReviewedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When a merchant last confirmed that the packed weight and dimensions are ready for package-fit recommendations." }, "metafields": { "type": "object", "additionalProperties": true }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish state map." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "reviewRatingSum": { "type": "number", "description": "Denormalized review-rating sum (#495). The public PDP derives `ratingAverage = reviewRatingSum / reviewRatingCount`; the merchant surface returns the raw counters." }, "reviewRatingCount": { "type": "number", "description": "Denormalized count of published reviews (#495)." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active items." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantItemImageDto" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantVariantDto" } }, "saleWindows": { "description": "#3280 — the item's non-expired sale windows, item-level and variant-scoped alike. Present on MERCHANT reads only: the public catalog strips this relation so anonymous callers cannot read upcoming sale prices and dates (Codex P1, PR #353). A merchant reading their own tenant already sees these in the sale-window admin.", "type": "array", "items": { "$ref": "#/components/schemas/MerchantItemSaleWindowDto" } }, "listPriceInCents": { "type": "number", "nullable": true, "description": "#3280 — the catalogued list price, echoing `priceInCents`. Named separately so a merchant surface can label the two columns without inferring which is which." }, "resolvedPriceInCents": { "type": "number", "nullable": true, "description": "#3280 / `DR-3265-20` — what this actually sells for right now, after any active sale window. Resolved through the same `SaleWindowService.resolveSalePrice` the charge path and the storefront use, so it cannot disagree with what a customer is charged. Equals the list price when no window applies, or when a window sits at or above the base — a sale window never raises a price (`DR-3265-14`).\n\n**Deterministic only.** Coupons, auto-discounts, and bundles are excluded by decision: a cart total or a typed code is not a property of a product, so this is not a quote." }, "resolvedBySaleWindowId": { "type": "string", "nullable": true, "description": "#3280 — the id of the sale window responsible for `resolvedPriceInCents`, or `null` when the list price stands. Deliberately `null` for an ACTIVE but inert window (one at or above the base): the question is which window is setting this price, and such a window is setting nothing." }, "resolvedSaleEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3280 — when the responsible window ends, or `null` when no window is setting the price." }, "scheduledPriceInCents": { "type": "number", "nullable": true, "description": "#3312 — what this will sell for at the NEXT scheduled price change, or `null` when no future boundary discounts it. Every future window start AND end is evaluated through the shared resolver, so scope and never-raise apply at each instant — including an inert masking window's expiry revealing another window's discount, in which case `scheduledStartsAt` is that expiry, not the responsible window's start. Populated only when the effective price actually changes to a discount; reversion to base at an expiry is carried by `resolvedSaleEndsAt` instead. This is a SCHEDULED price, not the current one; a surface that renders it as current is wrong." }, "scheduledBySaleWindowId": { "type": "string", "nullable": true, "description": "#3312 — id of the window that will set `scheduledPriceInCents`, or `null` when none applies." }, "scheduledStartsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3312 — the boundary at which the scheduled price takes effect for this target (a window start, or a masking window's expiry), or `null` when none applies." }, "scheduledEndsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "#3312 — when the scheduled window stops applying, or `null` when none applies." } }, "required": [ "id", "organizationId", "slug", "name", "description", "shortDescription", "type", "sellMode", "status", "priceInCents", "compareAtPriceInCents", "tags", "metadata", "brand", "vendor", "productFamily", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "orientationPolicy", "parcelMeasurementsReviewedAt", "metafields", "channelPublishStatus", "sortOrder", "reviewRatingSum", "reviewRatingCount", "archivedAt", "createdAt", "updatedAt", "images", "variants" ] }, "ReorderItemsDto": { "type": "object", "properties": { "orderedIds": { "description": "Full ordered list of item ids. Must include every non-archived item currently in the tenant exactly once (archived rows are excluded server-side and must not appear); any missing, extra, or foreign id causes a 400. Must be unique — duplicates are rejected.", "minItems": 1, "maxItems": 5000, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "orderedIds" ] }, "ReorderResultDto": { "type": "object", "properties": { "reordered": { "type": "number", "description": "Number of rows whose `sortOrder` was normalised.", "example": 5 } }, "required": [ "reordered" ] }, "ItemType": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "CreateItemDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "type": { "allOf": [ { "$ref": "#/components/schemas/ItemType" } ] }, "sellMode": { "description": "How this item may be purchased (default `ONE_TIME`). Authoring contract only — sell-mode enforcement and storefront/BYO filtering ship with subscription checkout (#629). A variant may override this per-variant.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "Send `null` to clear an existing value; omit to leave it alone." }, "description": { "type": "string", "maxLength": 10000 }, "shortDescription": { "type": "string", "maxLength": 500 }, "tags": { "type": "array", "items": { "type": "string" } }, "brand": { "type": "string", "maxLength": 200, "nullable": true }, "vendor": { "type": "string", "maxLength": 200, "nullable": true }, "productFamily": { "type": "string", "maxLength": 200, "nullable": true }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "description": "Packed-item orientation. Omit to keep the saved-face default; ANY_SIDE_RIGHT_ANGLE permits every distinct 90-degree face rotation of reviewed dimensions.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "confirmPackedMeasurements": { "type": "boolean", "description": "Explicit merchant adoption of the packed-unit parcel measurements. Changing any measurement without re-confirming clears the prior review." }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary key/value attributes." }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish status, e.g. `{ \"storefront\": \"published\" }`." } }, "required": [ "name", "slug", "type", "status", "priceInCents" ] }, "UpdateItemDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "type": { "allOf": [ { "$ref": "#/components/schemas/ItemType" } ] }, "sellMode": { "description": "How this item may be purchased (default `ONE_TIME`). Authoring contract only — sell-mode enforcement and storefront/BYO filtering ship with subscription checkout (#629). A variant may override this per-variant.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "Send `null` to clear an existing value; omit to leave it alone." }, "description": { "type": "string", "maxLength": 10000 }, "shortDescription": { "type": "string", "maxLength": 500 }, "tags": { "type": "array", "items": { "type": "string" } }, "brand": { "type": "string", "maxLength": 200, "nullable": true }, "vendor": { "type": "string", "maxLength": 200, "nullable": true }, "productFamily": { "type": "string", "maxLength": 200, "nullable": true }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "description": "Packed-item orientation. Omit to keep the saved-face default; ANY_SIDE_RIGHT_ANGLE permits every distinct 90-degree face rotation of reviewed dimensions.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "confirmPackedMeasurements": { "type": "boolean", "description": "Explicit merchant adoption of the packed-unit parcel measurements. Changing any measurement without re-confirming clears the prior review." }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary key/value attributes." }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish status, e.g. `{ \"storefront\": \"published\" }`." } } }, "ReorderVariantsDto": { "type": "object", "properties": { "orderedVariantIds": { "description": "Full ordered list of variant ids. Must include every non-archived variant currently on the item exactly once (archived rows are excluded server-side and must not appear); any missing, extra, or foreign id causes a 400. Must be unique — duplicates are rejected.", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "orderedVariantIds" ] }, "CreateVariantDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "description": "Inventory-side identifier. Unique within the parent item. Allowed: alphanumerics, `-`, `_`, `.`", "minLength": 1, "maxLength": 100 }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "M2 pricing rules — optional \"was\" price for storefront strikethrough. Must be strictly greater than `priceInCents` when set. Send `null` to clear an existing value on PATCH; omit to leave it alone." }, "sellMode": { "nullable": true, "description": "Per-variant override of the item's `sellMode`. Send `null` (or omit) to inherit the parent item default. Authoring contract only — enforcement is subscription checkout (#629).", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Variant-distinguishing attributes (e.g. `{ \"size\": \"M\", \"color\": \"Red\" }`). Keys and values must both be strings." }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary merchant-side attributes." }, "featuredImageId": { "type": "string", "description": "M2 / #249 — id of an `ItemImage` row to use as this variant's featured image. The referenced image must belong to the same item as the variant (enforced at the service layer). Pass `null` on PATCH to clear. Storefront swaps the PDP hero on variant select via this pointer; falls back to the item's primary image when null.", "nullable": true, "minLength": 1, "maxLength": 64 }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`. Overrides the parent item weight." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "nullable": true, "description": "Variant orientation override. Null or omitted inherits the item; otherwise choose saved-face only or every distinct 90-degree face rotation.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "confirmPackedMeasurements": { "type": "boolean", "description": "Explicit merchant adoption of this variant-level packed measurement override. Changing any measurement without re-confirming clears review." } }, "required": [ "name", "sku", "priceInCents" ] }, "UpdateVariantDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "description": "Inventory-side identifier. Unique within the parent item. Allowed: alphanumerics, `-`, `_`, `.`", "minLength": 1, "maxLength": 100 }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "M2 pricing rules — optional \"was\" price for storefront strikethrough. Must be strictly greater than `priceInCents` when set. Send `null` to clear an existing value on PATCH; omit to leave it alone." }, "sellMode": { "nullable": true, "description": "Per-variant override of the item's `sellMode`. Send `null` (or omit) to inherit the parent item default. Authoring contract only — enforcement is subscription checkout (#629).", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Variant-distinguishing attributes (e.g. `{ \"size\": \"M\", \"color\": \"Red\" }`). Keys and values must both be strings." }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary merchant-side attributes." }, "featuredImageId": { "type": "string", "description": "M2 / #249 — id of an `ItemImage` row to use as this variant's featured image. The referenced image must belong to the same item as the variant (enforced at the service layer). Pass `null` on PATCH to clear. Storefront swaps the PDP hero on variant select via this pointer; falls back to the item's primary image when null.", "nullable": true, "minLength": 1, "maxLength": 64 }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`. Overrides the parent item weight." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "nullable": true, "description": "Variant orientation override. Null or omitted inherits the item; otherwise choose saved-face only or every distinct 90-degree face rotation.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "confirmPackedMeasurements": { "type": "boolean", "description": "Explicit merchant adoption of this variant-level packed measurement override. Changing any measurement without re-confirming clears review." } } }, "MerchantCollectionWithImagesDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy single-image JSON blob (pre-Epic-6). `null` when unset; the structured gallery lives in the `images` relation (returned by the list read + the dedicated `/images` routes)." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The merchant surface returns ACTIVE / DRAFT / ARCHIVED rows (unlike the public read, which is ACTIVE-only)." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active collections." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "_count": { "$ref": "#/components/schemas/PublicCollectionCountDto" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCollectionImageDto" } } }, "required": [ "id", "organizationId", "slug", "name", "description", "image", "sortOrder", "status", "archivedAt", "createdAt", "updatedAt", "_count", "images" ] }, "MerchantCollectionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Legacy single-image JSON blob (pre-Epic-6). `null` when unset; the structured gallery lives in the `images` relation (returned by the list read + the dedicated `/images` routes)." }, "sortOrder": { "type": "number", "description": "Merchant-controlled display order within the tenant." }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The merchant surface returns ACTIVE / DRAFT / ARCHIVED rows (unlike the public read, which is ACTIVE-only)." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp; `null` for active collections." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "_count": { "$ref": "#/components/schemas/PublicCollectionCountDto" } }, "required": [ "id", "organizationId", "slug", "name", "description", "image", "sortOrder", "status", "archivedAt", "createdAt", "updatedAt", "_count" ] }, "CreateCollectionDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "description": { "type": "string", "maxLength": 10000 }, "image": { "type": "object", "additionalProperties": true, "description": "Image metadata as an open JSON object. Shape will be tightened by Epic 6 (Catalog Media). Send `null` to clear.", "nullable": true }, "sortOrder": { "type": "number", "minimum": 0, "description": "Display order — collections are listed ascending. Defaults to 0." } }, "required": [ "name", "slug", "status" ] }, "ReorderCollectionsDto": { "type": "object", "properties": { "collectionIds": { "description": "Full ordered list of collection ids. Must include every active + draft collection currently in the tenant (archived rows are excluded server-side and never need to appear); missing rows cause a 400. Must be unique — duplicates are rejected.", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "collectionIds" ] }, "UpdateCollectionDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "description": { "type": "string", "maxLength": 10000 }, "image": { "type": "object", "additionalProperties": true, "description": "Image metadata as an open JSON object. Shape will be tightened by Epic 6 (Catalog Media). Send `null` to clear.", "nullable": true }, "sortOrder": { "type": "number", "minimum": 0, "description": "Display order — collections are listed ascending. Defaults to 0." } } }, "AssignCollectionItemsDto": { "type": "object", "properties": { "itemIds": { "description": "Item ids to add. Up to 100 per call. Must be unique.", "minItems": 1, "maxItems": 100, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "itemIds" ] }, "AssignCollectionItemsResultDto": { "type": "object", "properties": { "added": { "type": "number", "description": "Number of new collection memberships created.", "example": 3 }, "skipped": { "type": "number", "description": "Number of supplied items already in the collection (skipped).", "example": 1 } }, "required": [ "added", "skipped" ] }, "CollectionItemRemovalResultDto": { "type": "object", "properties": { "removed": { "type": "number", "description": "Number of membership rows removed: `1` on success, `0` when the item was already not in the collection (idempotent no-op).", "example": 1 } }, "required": [ "removed" ] }, "ReorderCollectionItemsDto": { "type": "object", "properties": { "itemIds": { "description": "Full ordered list of item ids. Must include every item currently in the collection; missing items cause a 400. Must be unique — duplicates are rejected.", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "itemIds" ] }, "ConfirmItemImageDto": { "type": "object", "properties": { "imageId": { "type": "string", "description": "Image id returned by the signed-URL endpoint. The service writes the row with this id so it matches the storage object path. The signed-URL endpoint generates UUIDs server-side, so we re-validate as UUID here — the client should never be inventing image ids. Codex PR #117 follow-up: the storage-path check is one validator, but accepting any non-empty string for what becomes a DB primary key AND a storage path segment was too permissive. Locking back to UUID closes that gap without affecting any existing flow (signed uploads have always been UUID-only)." }, "storagePath": { "type": "string", "description": "Bucket-relative storage path the bytes landed at. Returned by the signed-URL endpoint; the client copies it through verbatim. The service re-validates it against the expected layout before write.", "minLength": 1, "maxLength": 1024 }, "alt": { "type": "string", "description": "Alt text for screen readers. Required — never default to empty.", "minLength": 1, "maxLength": 500 }, "isPrimary": { "type": "boolean", "description": "Whether this image is the primary thumbnail. The service enforces uniqueness within the item — setting `isPrimary=true` clears the flag on every other image for the same item, atomically.", "default": false }, "sortOrder": { "type": "number", "description": "Display order within the gallery. Defaults to 0; use the reorder endpoint to rewrite the whole sequence.", "minimum": 0 }, "focalX": { "type": "number", "description": "Normalized focal point x-axis (0..1).", "minimum": 0, "maximum": 1 }, "focalY": { "type": "number", "description": "Normalized focal point y-axis (0..1).", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "bytes": { "type": "number", "minimum": 1 }, "mimeType": { "type": "string", "maxLength": 100 } }, "required": [ "imageId", "storagePath", "alt", "bytes" ] }, "ReorderImagesDto": { "type": "object", "properties": { "imageIds": { "description": "Full ordered list of image ids. Must include every image currently attached to the owner; missing items cause a 400. Must be unique — duplicates are rejected.", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "required": [ "imageIds" ] }, "UpdateItemImageDto": { "type": "object", "properties": { "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "focalX": { "type": "number", "description": "Normalized focal point x-axis (0..1).", "minimum": 0, "maximum": 1 }, "focalY": { "type": "number", "description": "Normalized focal point y-axis (0..1).", "minimum": 0, "maximum": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this image is the primary thumbnail. The service enforces uniqueness within the item — setting `isPrimary=true` clears the flag on every other image for the same item, atomically." } } }, "DeleteImageResultDto": { "type": "object", "properties": { "removed": { "type": "number", "description": "Number of image rows removed (1 on success).", "example": 1 } }, "required": [ "removed" ] }, "ConfirmCollectionImageDto": { "type": "object", "properties": { "imageId": { "type": "string", "description": "Image id returned by the signed-URL endpoint. The service writes the row with this id so it matches the storage object path. The signed-URL endpoint generates UUIDs server-side, so we re-validate as UUID here — the client should never be inventing image ids. Codex PR #117 follow-up: the storage-path check is one validator, but accepting any non-empty string for what becomes a DB primary key AND a storage path segment was too permissive. Locking back to UUID closes that gap without affecting any existing flow (signed uploads have always been UUID-only)." }, "storagePath": { "type": "string", "description": "Bucket-relative storage path the bytes landed at. Returned by the signed-URL endpoint; the client copies it through verbatim. The service re-validates it against the expected layout before write.", "minLength": 1, "maxLength": 1024 }, "alt": { "type": "string", "description": "Alt text for screen readers. Required — never default to empty.", "minLength": 1, "maxLength": 500 }, "isPrimary": { "type": "boolean", "description": "Whether this image is the primary thumbnail. The service enforces uniqueness within the item — setting `isPrimary=true` clears the flag on every other image for the same item, atomically.", "default": false }, "sortOrder": { "type": "number", "description": "Display order within the gallery. Defaults to 0; use the reorder endpoint to rewrite the whole sequence.", "minimum": 0 }, "focalX": { "type": "number", "description": "Normalized focal point x-axis (0..1).", "minimum": 0, "maximum": 1 }, "focalY": { "type": "number", "description": "Normalized focal point y-axis (0..1).", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "bytes": { "type": "number", "minimum": 1 }, "mimeType": { "type": "string", "maxLength": 100 } }, "required": [ "imageId", "storagePath", "alt", "bytes" ] }, "UpdateCollectionImageDto": { "type": "object", "properties": { "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "focalX": { "type": "number", "description": "Normalized focal point x-axis (0..1).", "minimum": 0, "maximum": 1 }, "focalY": { "type": "number", "description": "Normalized focal point y-axis (0..1).", "minimum": 0, "maximum": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this image is the primary thumbnail. The service enforces uniqueness within the item — setting `isPrimary=true` clears the flag on every other image for the same item, atomically." } } }, "ItemCompositionItemSummaryDto": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ] }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "slug", "name", "type", "status", "archivedAt" ] }, "ItemCompositionVariantSummaryDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "sku", "archivedAt" ] }, "ItemCompositionComponentDto": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number", "minimum": 0 }, "componentItemId": { "type": "string" }, "componentVariantId": { "type": "string", "nullable": true }, "quantity": { "type": "number", "format": "int32", "minimum": 1, "maximum": 2147483647 }, "discountBasisPoints": { "type": "number", "minimum": 0, "maximum": 10000 }, "capacityMode": { "type": "string", "enum": [ "TRACKED", "UNTRACKED" ] }, "untrackedReason": { "type": "string", "nullable": true }, "item": { "$ref": "#/components/schemas/ItemCompositionItemSummaryDto" }, "variant": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ItemCompositionVariantSummaryDto" } ] } }, "required": [ "id", "position", "componentItemId", "componentVariantId", "quantity", "discountBasisPoints", "capacityMode", "untrackedReason", "item", "variant" ] }, "ItemCompositionDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Existing parent Item id; the composition has no parallel sellable identity." }, "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "revision": { "type": "number", "minimum": 1 }, "components": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/ItemCompositionComponentDto" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "itemId", "kind", "revision", "components", "createdAt", "updatedAt" ] }, "PutItemCompositionComponentDto": { "type": "object", "properties": { "componentItemId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Tenant-owned component Item id. Source-system ids are resolved by the import boundary and are never accepted here." }, "componentVariantId": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 255, "description": "Exact component variant id. Required when the selected component Item has variants." }, "quantity": { "type": "number", "format": "int32", "minimum": 1, "maximum": 2147483647 }, "discountBasisPoints": { "type": "number", "minimum": 0, "maximum": 10000, "description": "Intrinsic component savings in basis points. Downstream pricing owns materialization." }, "capacityMode": { "type": "string", "enum": [ "TRACKED", "UNTRACKED" ] }, "untrackedReason": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 500, "description": "Required, trimmed review reason only when capacityMode is UNTRACKED." } }, "required": [ "componentItemId", "quantity", "discountBasisPoints", "capacityMode" ] }, "PutItemCompositionDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "expectedRevision": { "type": "number", "minimum": 0, "maximum": 2147483646, "description": "Optimistic revision guard. Use 0 to create; an existing definition requires its exact current revision." }, "components": { "minItems": 2, "maxItems": 20, "description": "Whole ordered definition. Array order is authoritative; positions are derived server-side.", "type": "array", "items": { "$ref": "#/components/schemas/PutItemCompositionComponentDto" } } }, "required": [ "kind", "expectedRevision", "components" ] }, "ItemCompositionPreviewParentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED" ] }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "slug", "type", "status", "archivedAt" ] }, "ItemCompositionAppliedPricingPolicyDto": { "type": "object", "properties": { "policyId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "integer", "format": "int32", "minimum": 1 }, "bandId": { "type": "string", "maxLength": 128 }, "bandUpperBoundMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 527040 }, "factorBasisPoints": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000 }, "elapsedMinutes": { "type": "integer", "format": "int32", "minimum": 1 }, "minimumDurationMinutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 527040 }, "graceMinutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1440 }, "effectiveMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 527040 }, "derivedUnitPriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647 } }, "required": [ "policyId", "revisionId", "revisionNumber", "bandId", "bandUpperBoundMinutes", "factorBasisPoints", "elapsedMinutes", "minimumDurationMinutes", "graceMinutes", "effectiveMinutes", "derivedUnitPriceInCents" ] }, "ItemCompositionPreviewIssueDto": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "componentId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "code", "message", "componentId" ] }, "ItemCompositionComponentPreviewDto": { "type": "object", "properties": { "componentId": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "format": "int32", "minimum": 0 }, "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "itemType": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "capacityMode": { "type": "string", "enum": [ "TRACKED", "UNTRACKED" ] }, "mappingStatus": { "type": "string", "enum": [ "READY", "UNTRACKED", "MISSING", "AMBIGUOUS", "UNAVAILABLE" ] }, "priceAuthorityKind": { "type": "string", "enum": [ "CATALOG", "BOOKING_SERVICE" ], "nullable": true }, "inventoryId": { "type": "string", "format": "uuid", "nullable": true }, "bookingServiceId": { "type": "string", "format": "uuid", "nullable": true }, "appliedPricingPolicy": { "nullable": true, "description": "Exact published duration-tier evidence when this component uses PRICING_STRUCTURE; null for scalar/catalog pricing.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ItemCompositionAppliedPricingPolicyDto" } ] }, "requiresServicePeriod": { "type": "boolean" }, "definitionQuantity": { "type": "integer", "format": "int32", "minimum": 1 }, "effectiveQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "commercialQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "unitPriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "subtotalInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "intrinsicSavingsInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ItemCompositionPreviewIssueDto" } } }, "required": [ "componentId", "position", "itemId", "variantId", "itemType", "capacityMode", "mappingStatus", "priceAuthorityKind", "inventoryId", "bookingServiceId", "appliedPricingPolicy", "requiresServicePeriod", "definitionQuantity", "effectiveQuantity", "commercialQuantity", "unitPriceInCents", "subtotalInCents", "intrinsicSavingsInCents", "totalInCents", "issues" ] }, "ItemCompositionPreviewDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "revision": { "type": "integer", "format": "int32", "minimum": 1 }, "selectedQuantity": { "type": "integer", "format": "int32", "minimum": 1 }, "parent": { "$ref": "#/components/schemas/ItemCompositionPreviewParentDto" }, "currency": { "type": "string" }, "mappingReady": { "type": "boolean", "description": "True when every TRACKED/UNTRACKED component resolves the exact current operational authority." }, "salesReady": { "type": "boolean", "description": "True when the exact definition can be materialized into merchant Sales for the supplied quantity/window." }, "requiresServicePeriod": { "type": "boolean" }, "subtotalInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "intrinsicSavingsInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ItemCompositionComponentPreviewDto" } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ItemCompositionPreviewIssueDto" } } }, "required": [ "itemId", "kind", "revision", "selectedQuantity", "parent", "currency", "mappingReady", "salesReady", "requiresServicePeriod", "subtotalInCents", "intrinsicSavingsInCents", "totalInCents", "components", "issues" ] }, "ItemCompositionPreviewListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemCompositionPreviewDto" } } }, "required": [ "data" ] }, "SaleWindowResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "description": "The item the sale prices." }, "variantId": { "type": "string", "nullable": true, "format": "uuid", "description": "Optional variant scope. `null` = item-level sale (applies to the parent item price); when set, references a variant of `itemId`." }, "valueType": { "description": "#3324 / `DR-3265-27` — which value arm this window carries. Exactly one of `salePriceInCents` / `amountOffInCents` / `percentOffBasisPoints` is non-null: the one this names (database-enforced). All three arms are writable through the merchant API as of #3325.", "allOf": [ { "$ref": "#/components/schemas/SaleWindowValueType" } ] }, "salePriceInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "FIXED_PRICE arm — the absolute sale price in cents shown while the window is active. `null` when `valueType` names a relative arm." }, "amountOffInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "AMOUNT_OFF arm — cents subtracted from the live base price at resolution time, clamped at $0.00 (`DR-3265-15`). `null` unless `valueType` is AMOUNT_OFF." }, "percentOffBasisPoints": { "type": "integer", "format": "int32", "nullable": true, "description": "PERCENT_OFF arm — basis points off the live base price, with floor rounding on the computed discount (`DR-3265-10`). `null` unless `valueType` is PERCENT_OFF." }, "startsAt": { "format": "date-time", "type": "string", "description": "Inclusive start of the sale window." }, "endsAt": { "format": "date-time", "type": "string", "description": "Exclusive end of the sale window (`endsAt > startsAt`)." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "itemId", "variantId", "valueType", "salePriceInCents", "amountOffInCents", "percentOffBasisPoints", "startsAt", "endsAt", "createdAt", "updatedAt" ] }, "CreateSaleWindowDto": { "description": "Create a sale window using the legacy fixed-price shorthand or one explicit natural-unit arm. Exactly one alternative must match.", "oneOf": [ { "title": "Legacy fixed price", "description": "Backward-compatible FIXED_PRICE body with no valueType property.", "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "description": "Target item. The active org must own this item; cross-tenant references return a 404. Canonical item ids are UUIDs, while the TEXT column remains string-compatible for imported or historical identities, so validation is not constrained to a UUID. Tenant ownership is checked by the service." }, "variantId": { "type": "string", "description": "Optional target variant. When set, must belong to `itemId`. When omitted (or null), the sale window applies to the item-level price. Variant identities remain string-compatible, so this is not constrained to a UUID.", "nullable": true }, "salePriceInCents": { "type": "integer", "format": "int32", "description": "FIXED_PRICE arm: customer-visible price in cents while active. Must be 0..2,147,483,647 (the PostgreSQL INTEGER range), and the write is not blocked at or above the current price. A window never RAISES a price, though: resolution takes the lower of this value and the live base price of the item or variant being priced, so a window at or above the base is inert rather than a price increase. On an item-level window (`variantId` omitted) that comparison is made against each variant's own price.", "minimum": 0, "maximum": 2147483647 }, "startsAt": { "type": "string", "description": "ISO-8601 inclusive start. Required. The merchant admin sends local-time picker values converted to ISO via the browser; the API stores UTC.", "format": "date-time" }, "endsAt": { "type": "string", "description": "ISO-8601 exclusive end. Required. Must be strictly after `startsAt`. Two windows that touch at the boundary (one ends exactly when the next starts) are NOT considered overlapping.", "format": "date-time" } }, "required": [ "itemId", "salePriceInCents", "startsAt", "endsAt" ] }, { "title": "Explicit fixed price", "description": "FIXED_PRICE requires exactly salePriceInCents.", "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "description": "Target item. The active org must own this item; cross-tenant references return a 404. Canonical item ids are UUIDs, while the TEXT column remains string-compatible for imported or historical identities, so validation is not constrained to a UUID. Tenant ownership is checked by the service." }, "variantId": { "type": "string", "description": "Optional target variant. When set, must belong to `itemId`. When omitted (or null), the sale window applies to the item-level price. Variant identities remain string-compatible, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "FIXED_PRICE" ], "description": "Natural unit carried by this window. When omitted, the legacy fixed-price body is accepted as FIXED_PRICE. When supplied, exactly the matching arm field must be present and the other two omitted." }, "salePriceInCents": { "type": "integer", "format": "int32", "description": "FIXED_PRICE arm: customer-visible price in cents while active. Must be 0..2,147,483,647 (the PostgreSQL INTEGER range), and the write is not blocked at or above the current price. A window never RAISES a price, though: resolution takes the lower of this value and the live base price of the item or variant being priced, so a window at or above the base is inert rather than a price increase. On an item-level window (`variantId` omitted) that comparison is made against each variant's own price.", "minimum": 0, "maximum": 2147483647 }, "startsAt": { "type": "string", "description": "ISO-8601 inclusive start. Required. The merchant admin sends local-time picker values converted to ISO via the browser; the API stores UTC.", "format": "date-time" }, "endsAt": { "type": "string", "description": "ISO-8601 exclusive end. Required. Must be strictly after `startsAt`. Two windows that touch at the boundary (one ends exactly when the next starts) are NOT considered overlapping.", "format": "date-time" } }, "required": [ "itemId", "valueType", "salePriceInCents", "startsAt", "endsAt" ] }, { "title": "Explicit amount off", "description": "AMOUNT_OFF requires exactly amountOffInCents.", "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "description": "Target item. The active org must own this item; cross-tenant references return a 404. Canonical item ids are UUIDs, while the TEXT column remains string-compatible for imported or historical identities, so validation is not constrained to a UUID. Tenant ownership is checked by the service." }, "variantId": { "type": "string", "description": "Optional target variant. When set, must belong to `itemId`. When omitted (or null), the sale window applies to the item-level price. Variant identities remain string-compatible, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "AMOUNT_OFF" ], "description": "Natural unit carried by this window. When omitted, the legacy fixed-price body is accepted as FIXED_PRICE. When supplied, exactly the matching arm field must be present and the other two omitted." }, "amountOffInCents": { "type": "integer", "format": "int32", "description": "AMOUNT_OFF arm: cents subtracted from each live item or variant price at resolution time. Clamps at $0.00.", "minimum": 1, "maximum": 1000000000 }, "startsAt": { "type": "string", "description": "ISO-8601 inclusive start. Required. The merchant admin sends local-time picker values converted to ISO via the browser; the API stores UTC.", "format": "date-time" }, "endsAt": { "type": "string", "description": "ISO-8601 exclusive end. Required. Must be strictly after `startsAt`. Two windows that touch at the boundary (one ends exactly when the next starts) are NOT considered overlapping.", "format": "date-time" } }, "required": [ "itemId", "valueType", "amountOffInCents", "startsAt", "endsAt" ] }, { "title": "Explicit percent off", "description": "PERCENT_OFF requires exactly percentOffBasisPoints.", "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "description": "Target item. The active org must own this item; cross-tenant references return a 404. Canonical item ids are UUIDs, while the TEXT column remains string-compatible for imported or historical identities, so validation is not constrained to a UUID. Tenant ownership is checked by the service." }, "variantId": { "type": "string", "description": "Optional target variant. When set, must belong to `itemId`. When omitted (or null), the sale window applies to the item-level price. Variant identities remain string-compatible, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "PERCENT_OFF" ], "description": "Natural unit carried by this window. When omitted, the legacy fixed-price body is accepted as FIXED_PRICE. When supplied, exactly the matching arm field must be present and the other two omitted." }, "percentOffBasisPoints": { "type": "integer", "format": "int32", "description": "PERCENT_OFF arm in basis points (1% = 100). The computed discount is floor-rounded independently for each live item or variant price.", "minimum": 1, "maximum": 10000 }, "startsAt": { "type": "string", "description": "ISO-8601 inclusive start. Required. The merchant admin sends local-time picker values converted to ISO via the browser; the API stores UTC.", "format": "date-time" }, "endsAt": { "type": "string", "description": "ISO-8601 exclusive end. Required. Must be strictly after `startsAt`. Two windows that touch at the boundary (one ends exactly when the next starts) are NOT considered overlapping.", "format": "date-time" } }, "required": [ "itemId", "valueType", "percentOffBasisPoints", "startsAt", "endsAt" ] } ] }, "UpdateSaleWindowDto": { "description": "Patch a sale window without changing its value, or provide exactly one value arm. An omitted valueType is accepted only when that arm matches the persisted row.", "oneOf": [ { "title": "Date or scope only", "description": "Leaves the persisted valueType and value arm unchanged.", "type": "object", "additionalProperties": false, "properties": { "variantId": { "type": "string", "description": "Repoint the window to a different variant of the same item, or clear it back to item-level by passing `null`. The service asserts the resulting variant belongs to the row's item. Free-form string id — catalog ids are TEXT and seeded tenant data uses `variant_*` prefixes, so this is not constrained to a UUID.", "nullable": true }, "startsAt": { "type": "string", "description": "New inclusive start. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" }, "endsAt": { "type": "string", "description": "New exclusive end. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" } } }, { "title": "Fixed price value update", "description": "salePriceInCents is required. valueType may be omitted only when the persisted row already uses FIXED_PRICE.", "type": "object", "additionalProperties": false, "properties": { "variantId": { "type": "string", "description": "Repoint the window to a different variant of the same item, or clear it back to item-level by passing `null`. The service asserts the resulting variant belongs to the row's item. Free-form string id — catalog ids are TEXT and seeded tenant data uses `variant_*` prefixes, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "FIXED_PRICE" ], "description": "New natural unit. When supplied, exactly the matching value field must be supplied too. Omit this and all value fields for a date/scope-only patch." }, "salePriceInCents": { "type": "integer", "format": "int32", "description": "FIXED_PRICE arm: new customer-visible price in cents. Non-negative. Same rule as create — a value at or above the item / variant price is accepted rather than blocked, and is then inert: a window never raises a price, so resolution takes the lower of this value and the live base. Maximum 2,147,483,647 (the PostgreSQL INTEGER range).", "minimum": 0, "maximum": 2147483647 }, "startsAt": { "type": "string", "description": "New inclusive start. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" }, "endsAt": { "type": "string", "description": "New exclusive end. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" } }, "required": [ "salePriceInCents" ] }, { "title": "Amount off value update", "description": "amountOffInCents is required. valueType may be omitted only when the persisted row already uses AMOUNT_OFF.", "type": "object", "additionalProperties": false, "properties": { "variantId": { "type": "string", "description": "Repoint the window to a different variant of the same item, or clear it back to item-level by passing `null`. The service asserts the resulting variant belongs to the row's item. Free-form string id — catalog ids are TEXT and seeded tenant data uses `variant_*` prefixes, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "AMOUNT_OFF" ], "description": "New natural unit. When supplied, exactly the matching value field must be supplied too. Omit this and all value fields for a date/scope-only patch." }, "amountOffInCents": { "type": "integer", "format": "int32", "description": "AMOUNT_OFF arm in cents. Must be 1..1,000,000,000 and resolves no lower than $0.00.", "minimum": 1, "maximum": 1000000000 }, "startsAt": { "type": "string", "description": "New inclusive start. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" }, "endsAt": { "type": "string", "description": "New exclusive end. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" } }, "required": [ "amountOffInCents" ] }, { "title": "Percent off value update", "description": "percentOffBasisPoints is required. valueType may be omitted only when the persisted row already uses PERCENT_OFF.", "type": "object", "additionalProperties": false, "properties": { "variantId": { "type": "string", "description": "Repoint the window to a different variant of the same item, or clear it back to item-level by passing `null`. The service asserts the resulting variant belongs to the row's item. Free-form string id — catalog ids are TEXT and seeded tenant data uses `variant_*` prefixes, so this is not constrained to a UUID.", "nullable": true }, "valueType": { "type": "string", "enum": [ "PERCENT_OFF" ], "description": "New natural unit. When supplied, exactly the matching value field must be supplied too. Omit this and all value fields for a date/scope-only patch." }, "percentOffBasisPoints": { "type": "integer", "format": "int32", "description": "PERCENT_OFF arm in basis points (1% = 100). Must be 1..10,000.", "minimum": 1, "maximum": 10000 }, "startsAt": { "type": "string", "description": "New inclusive start. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" }, "endsAt": { "type": "string", "description": "New exclusive end. Service re-checks `endsAt > startsAt` against the merged state + re-runs the overlap check.", "format": "date-time" } }, "required": [ "percentOffBasisPoints" ] } ] }, "HighRiskReasonDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" } }, "required": [ "reason" ] }, "SaleWindowDeleteResponseDto": { "type": "object", "properties": { "deletedId": { "type": "string", "format": "uuid", "description": "Id of the hard-deleted sale window." } }, "required": [ "deletedId" ] }, "PublicInventoryItemSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Tallow Body Cream" }, "slug": { "type": "string", "example": "tallow-body-cream" } }, "required": [ "id", "name", "slug" ] }, "PublicInventoryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "The variant this stock row is scoped to; `null` for item-level rows." }, "totalQuantity": { "type": "number", "example": 42, "description": "Units on hand (available + reserved)." }, "availableQuantity": { "type": "number", "example": 38, "description": "Units sellable now." }, "reservedQuantity": { "type": "number", "example": 4, "description": "Units earmarked by holds." }, "lowStockThreshold": { "type": "number", "example": 0, "description": "Low-stock alarm point; `0` disables the alarm." }, "stockStatus": { "type": "string", "enum": [ "IN_STOCK", "LOW_STOCK", "OUT_OF_STOCK" ], "example": "IN_STOCK" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2026-06-21T04:19:08.000Z" }, "item": { "$ref": "#/components/schemas/PublicInventoryItemSummaryDto" } }, "required": [ "id", "organizationId", "itemId", "variantId", "totalQuantity", "availableQuantity", "reservedQuantity", "lowStockThreshold", "stockStatus", "updatedAt", "item" ] }, "CheckAvailabilityDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Item UUID to check availability for." }, "variantId": { "type": "string", "description": "Optional variant UUID. When omitted, availability is checked against the item-level booking inventory row." }, "startDate": { "type": "string", "description": "Inclusive start instant (ISO-8601 date-time with timezone offset). Availability uses a half-open interval: [startDate, endDate).", "format": "date-time" }, "endDate": { "type": "string", "description": "Exclusive end instant (ISO-8601 date-time with timezone offset), strictly after startDate. Availability uses a half-open interval: [startDate, endDate), so back-to-back bookings may touch at this instant.", "format": "date-time" } }, "required": [ "itemId", "startDate", "endDate" ] }, "AvailabilityCheckResponseDto": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether at least one unit is available across the requested range.", "example": true }, "quantity": { "type": "number", "description": "Remaining bookable quantity for the range (reservation-aware available stock minus overlapping holds), floored at 0.", "example": 3 } }, "required": [ "available", "quantity" ] }, "StockStatus": { "type": "string", "enum": [ "IN_STOCK", "LOW_STOCK", "OUT_OF_STOCK" ] }, "MerchantInventoryItemSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "example": "1d6c9085-74c6-5038-b23d-af3650468db2" }, "name": { "type": "string", "example": "Tallow Body Cream" }, "slug": { "type": "string", "example": "tallow-body-cream" } }, "required": [ "id", "name", "slug" ] }, "MerchantInventoryVariantSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "example": "variant_ekgis_tallow_unscented" }, "name": { "type": "string", "example": "Unscented" }, "sku": { "type": "string", "example": "EKG-TBC-UNS" }, "options": { "type": "object", "additionalProperties": true, "example": { "Size": "2.5 oz" }, "description": "The variant's customer-facing option map (merchant-defined). Always an object, possibly empty (`{}`); never null — the column is `ItemVariant.options Json @default(\"{}\")`." } }, "required": [ "id", "name", "sku", "options" ] }, "MerchantInventoryRowDto": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_ekgis_tallow_unscented" }, "organizationId": { "type": "string", "example": "org_ekgis_naturals" }, "itemId": { "type": "string", "example": "1d6c9085-74c6-5038-b23d-af3650468db2" }, "variantId": { "type": "string", "nullable": true, "example": "variant_ekgis_tallow_unscented", "description": "The variant this stock row is scoped to; `null` for item-level rows." }, "totalQuantity": { "type": "number", "example": 42, "description": "Units on hand (available + reserved)." }, "availableQuantity": { "type": "number", "example": 38, "description": "Units sellable now." }, "reservedQuantity": { "type": "number", "example": 4, "description": "Units earmarked by holds (reserve/release move these)." }, "lowStockThreshold": { "type": "number", "example": 0, "description": "Low-stock alarm point; `0` disables the alarm." }, "stockStatus": { "type": "string", "enum": [ "IN_STOCK", "LOW_STOCK", "OUT_OF_STOCK" ], "example": "IN_STOCK" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-06-21T04:19:08.000Z" }, "item": { "$ref": "#/components/schemas/MerchantInventoryItemSummaryDto" }, "variant": { "nullable": true, "description": "Variant summary on variant-scoped rows; `null` for item-level rows. Always present on the merchant response (the Prisma `include` returns the relation key, `null` when the row has no variant).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantInventoryVariantSummaryDto" } ] } }, "required": [ "id", "organizationId", "itemId", "variantId", "totalQuantity", "availableQuantity", "reservedQuantity", "lowStockThreshold", "stockStatus", "updatedAt", "item", "variant" ] }, "MerchantInventorySummaryDto": { "type": "object", "properties": { "inStock": { "type": "number", "example": 128, "description": "Rows with `stockStatus = IN_STOCK`." }, "lowStock": { "type": "number", "example": 6, "description": "Rows with `stockStatus = LOW_STOCK`." }, "outOfStock": { "type": "number", "example": 3, "description": "Rows with `stockStatus = OUT_OF_STOCK`." }, "total": { "type": "number", "example": 137, "description": "Sum of the three buckets (`inStock + lowStock + outOfStock`)." } }, "required": [ "inStock", "lowStock", "outOfStock", "total" ] }, "InventoryTargetDto": { "type": "object", "properties": { "kind": { "type": "string", "description": "Target discriminator.", "enum": [ "variant", "item-default" ] }, "itemId": { "type": "string", "description": "Parent item id (payload plumbing)." }, "itemName": { "type": "string", "description": "Parent item display name." }, "variantId": { "type": "string", "description": "Variant id for `kind: 'variant'`; `null` for `kind: 'item-default'` (the item-level row).", "nullable": true }, "variantName": { "type": "string", "description": "Variant display name (`kind: 'variant'` only).", "nullable": true }, "sku": { "type": "string", "description": "Variant SKU (`kind: 'variant'` only; items have no SKU).", "nullable": true }, "hasInventoryRow": { "type": "boolean", "description": "Whether the inventory row for this target already exists. `false` targets are the create-missing (#1850) population." } }, "required": [ "kind", "itemId", "itemName", "variantId", "variantName", "sku", "hasInventoryRow" ] }, "InventoryTargetListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryTargetDto" } }, "nextOffset": { "type": "integer", "description": "Offset for the next page of the merged variant + item-default list, or `null` when this page is the last. Bounded — deep paging is unsupported by design; refine the search.", "format": "int32", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "CreateInventoryDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "The tenant-owned item to create the stock row for.", "example": "1d6c9085-74c6-5038-b23d-af3650468db2" }, "variantId": { "type": "string", "nullable": true, "description": "Scope the row to a specific variant of the item. Omit (or null) for an item-level row on a variant-less product.", "example": "variant_ekgis_tallow_unscented" }, "totalQuantity": { "type": "number", "description": "Opening on-hand quantity. `availableQuantity` mirrors this on the new row (reserved starts at 0). Defaults to 0 (OUT_OF_STOCK until stocked).", "minimum": 0, "default": 0, "example": 25 }, "lowStockThreshold": { "type": "number", "description": "Low-stock alarm point for the new row. `0` (default) disables the LOW_STOCK signal.", "minimum": 0, "default": 0, "example": 5 } }, "required": [ "itemId" ] }, "EnsureInventoryResponseDto": { "type": "object", "properties": { "created": { "type": "boolean", "description": "True when a NEW row was created. False when an existing row was returned unchanged — the requested opening quantity/threshold were NOT applied (use the adjust endpoint to change an existing row).", "example": true }, "row": { "description": "The created (or pre-existing) inventory row.", "allOf": [ { "$ref": "#/components/schemas/MerchantInventoryRowDto" } ] } }, "required": [ "created", "row" ] }, "AdjustInventoryDto": { "type": "object", "properties": { "delta": { "type": "number", "description": "Signed change applied to both totalQuantity and availableQuantity. Must be non-zero — submit nothing to keep the row unchanged.", "example": 5 }, "reason": { "type": "string", "description": "Human-readable explanation for the adjustment. Captured in the audit log for traceability.", "minLength": 1, "maxLength": 200, "example": "Received PO #1234" } }, "required": [ "delta", "reason" ] }, "UpdateThresholdDto": { "type": "object", "properties": { "lowStockThreshold": { "type": "number", "description": "New low-stock threshold. `0` disables the alarm (no LOW_STOCK signal regardless of availableQuantity). Positive integers set an inclusive trip-point.", "minimum": 0, "example": 5 } }, "required": [ "lowStockThreshold" ] }, "ReserveInventoryDto": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of units to move from available to reserved.", "minimum": 1, "example": 1 }, "reason": { "type": "string", "description": "Optional explanation captured in the audit log. Suggested format: a short note describing the source of the reservation (e.g. \"booking #abc123\", \"manual hold for repair\").", "maxLength": 200 } }, "required": [ "quantity" ] }, "ReleaseInventoryDto": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of units to move from reserved back to available.", "minimum": 1, "example": 1 }, "reason": { "type": "string", "description": "Optional explanation captured in the audit log (e.g. \"booking cancelled\", \"order timeout cleanup\").", "maxLength": 200 } }, "required": [ "quantity" ] }, "PublicBookingDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "The booked item variant, or `null` for item-level bookings." }, "startDate": { "format": "date-time", "type": "string" }, "endDate": { "format": "date-time", "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ], "example": "PENDING" }, "quantity": { "type": "integer", "format": "int32", "example": 1 } }, "required": [ "id", "itemId", "variantId", "startDate", "endDate", "status", "quantity" ] }, "CreateBookingDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "UUID of the item being booked." }, "variantId": { "type": "string", "description": "Optional variant UUID." }, "startDate": { "type": "string", "description": "Booking start instant (ISO-8601 date-time with timezone offset), inclusive. Booking windows use a half-open interval: [startDate, endDate).", "format": "date-time" }, "endDate": { "type": "string", "description": "Booking end instant (ISO-8601 date-time with timezone offset), exclusive. Back-to-back bookings may share this boundary without overlapping.", "format": "date-time" }, "quantity": { "type": "number", "minimum": 1, "maximum": 1000 }, "notes": { "type": "string", "description": "Free-form customer note (max 2000 chars)." } }, "required": [ "itemId", "startDate", "endDate", "quantity" ] }, "BookingPriceConfirmationComparablePriceDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotalInCents": { "type": "integer", "format": "int32", "example": 10000 }, "discountInCents": { "type": "integer", "format": "int32", "example": 0 }, "shippingInCents": { "type": "integer", "format": "int32", "example": 0 }, "taxInCents": { "type": "integer", "format": "int32", "example": 800 }, "totalInCents": { "type": "integer", "format": "int32", "example": 10800 } }, "required": [ "currency", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents" ], "additionalProperties": false }, "BookingPriceConfirmationRequiredDetailsDto": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "CONFIRMED_PRICE_RECEIPT_MISSING", "CONFIRMED_PRICE_RECEIPT_INVALID", "CONFIRMED_PRICE_RECEIPT_EXPIRED", "PRICE_CONFIRMATION_NOT_EXPLICIT", "CONFIRMED_PRICE_CHANGED", "CUSTOMER_CONFIRMATION_REQUIRED" ], "description": "Stable bind-time reason. Clients render currentPrice, clear stale confirmation state, and retry only with the replacement receipt when one is present." }, "acknowledgedPrice": { "nullable": true, "description": "Previously authenticated and explicitly acknowledged total, or null when no live acknowledgement exists.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" } ] }, "currentPrice": { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" }, "confirmedPriceReceipt": { "type": "string", "nullable": true, "maxLength": 32768, "description": "Short-lived signed receipt for a customer-present bind retry. Null when no customer can confirm or the binding authority has expired." }, "receiptExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry of confirmedPriceReceipt, or null when no replacement receipt is returned." } }, "required": [ "reason", "acknowledgedPrice", "currentPrice", "confirmedPriceReceipt", "receiptExpiresAt" ] }, "BookingPriceConfirmationRequiredErrorDto": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BOOKING_PRICE_CONFIRMATION_REQUIRED" ], "example": "BOOKING_PRICE_CONFIRMATION_REQUIRED" }, "message": { "type": "string", "example": "Confirm the current tax-inclusive booking total and retry." }, "details": { "$ref": "#/components/schemas/BookingPriceConfirmationRequiredDetailsDto" } }, "required": [ "code", "message", "details" ] }, "CheckoutAddressDto": { "type": "object", "properties": { "country": { "type": "string", "description": "Leading and trailing whitespace is trimmed and letters are uppercased before the normalized two-letter alphabetic country-code check.", "example": "US", "pattern": "^\\s*[A-Za-z]{2}\\s*$" }, "state": { "type": "string", "description": "State / province / region — ISO 3166-2 subdivision code when possible (e.g. `NY`, `CA`). Strongly recommended for accurate US sales tax.", "maxLength": 100 }, "city": { "type": "string", "description": "City / town.", "maxLength": 200 }, "postalCode": { "type": "string", "description": "ZIP / postal code. Recommended for local-jurisdiction tax.", "maxLength": 20 }, "line1": { "type": "string", "description": "Address line 1.", "maxLength": 300 }, "line2": { "type": "string", "description": "Address line 2.", "maxLength": 300 }, "company": { "type": "string", "description": "#998 — optional ship-to company / organization name, collected in the hosted checkout Contact step. Persisted on the address JSON; doesn't participate in tax.", "maxLength": 200 } }, "required": [ "country" ], "additionalProperties": false }, "CreateBookingCheckoutDto": { "type": "object", "properties": { "confirmedPriceReceipt": { "type": "string", "maxLength": 32768, "description": "Signed, request-bound tax-inclusive quote receipt returned by a prior BOOKING_PRICE_CONFIRMATION_REQUIRED response." }, "priceConfirmed": { "type": "boolean", "enum": [ true ], "description": "Must be literal true after the customer renders and explicitly accepts the receipt total." }, "customerName": { "type": "string", "maxLength": 200 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "customerPhone": { "type": "string", "nullable": true, "maxLength": 50 }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "shippingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" }, "billingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" } }, "required": [ "customerName", "customerEmail" ] }, "BookingDeliveryDestinationAddressResponseDto": { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 300, "example": "1120 S Rackham Way" }, "line2": { "type": "string", "maxLength": 300, "example": "Suite 300" }, "city": { "type": "string", "maxLength": 200, "example": "Meridian" }, "state": { "type": "string", "maxLength": 200, "example": "ID" }, "postalCode": { "type": "string", "maxLength": 32, "example": "83642" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "state", "postalCode", "country" ], "additionalProperties": false }, "BookingDeliverySelectionBandResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "maxDistanceMeters": { "type": "integer", "format": "int32", "minimum": 1 }, "feeInCents": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "id", "label", "maxDistanceMeters", "feeInCents" ], "additionalProperties": false }, "BookingDeliverySelectionResponseDto": { "description": "Method-discriminated browser-safe delivery evidence. DELIVERY is either pending evaluation or fully rated; distance and band become non-null together.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "method", "destinationAddress", "distanceMeters", "band" ], "properties": { "method": { "type": "string", "enum": [ "PICKUP" ] }, "destinationAddress": { "type": "object", "nullable": true, "enum": [ null ] }, "distanceMeters": { "type": "integer", "format": "int32", "nullable": true, "enum": [ null ] }, "band": { "type": "object", "nullable": true, "enum": [ null ] } } }, { "type": "object", "additionalProperties": false, "required": [ "method", "destinationAddress", "distanceMeters", "band" ], "properties": { "method": { "type": "string", "enum": [ "DELIVERY" ] }, "destinationAddress": { "$ref": "#/components/schemas/BookingDeliveryDestinationAddressResponseDto" }, "distanceMeters": { "type": "integer", "format": "int32", "nullable": true, "enum": [ null ] }, "band": { "type": "object", "nullable": true, "enum": [ null ] } } }, { "type": "object", "additionalProperties": false, "required": [ "method", "destinationAddress", "distanceMeters", "band" ], "properties": { "method": { "type": "string", "enum": [ "DELIVERY" ] }, "destinationAddress": { "$ref": "#/components/schemas/BookingDeliveryDestinationAddressResponseDto" }, "distanceMeters": { "type": "integer", "format": "int32", "minimum": 0 }, "band": { "$ref": "#/components/schemas/BookingDeliverySelectionBandResponseDto" } } } ] }, "PublicBookingLifecycleCommerceDto": { "type": "object", "properties": { "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "currency": { "type": "string" }, "totalInCents": { "type": "integer", "format": "int32" }, "amountPaidInCents": { "type": "integer", "format": "int32" }, "balanceDueInCents": { "type": "integer", "format": "int32" }, "displayNumber": { "type": "string", "nullable": true } }, "required": [ "commercialStatus", "paymentStatus", "currency", "totalInCents", "amountPaidInCents", "balanceDueInCents", "displayNumber" ] }, "PublicBookingLifecycleDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "currency": { "type": "string" }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "commerce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingLifecycleCommerceDto" } ] } }, "required": [ "id", "serviceId", "startsAt", "endsAt", "quantity", "status", "approvalStatus", "currency", "totalInCents", "archivedAt", "delivery", "commerce" ] }, "PublicBookingCheckoutResponseDto": { "type": "object", "properties": { "flow": { "type": "string", "enum": [ "PAYMENT", "REQUEST", "CONFIRMED", "TERMINAL" ], "description": "PAYMENT exposes a live hosted checkout; REQUEST awaits merchant action; CONFIRMED covers confirmed/active/completed bookings; TERMINAL covers declined, cancelled, expired, or an expired checkout awaiting sweep convergence." }, "booking": { "$ref": "#/components/schemas/PublicBookingLifecycleDto" }, "checkoutToken": { "type": "string", "nullable": true, "description": "Raw c-token; present only for PAYMENT." }, "checkoutExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "amountDueNowInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "remainingBalanceInCents": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "flow", "booking", "checkoutToken", "checkoutExpiresAt", "amountDueNowInCents", "remainingBalanceInCents" ] }, "PublicBookingGroupCartQuoteInputDto": { "type": "object", "properties": { "requestFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "acknowledgedPrice": { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" }, "cartQuoteReceipt": { "type": "string", "maxLength": 32768, "description": "Opaque, short-lived server receipt proving the preceding anonymous cart quote. It is not customer confirmation and cannot authorize checkout." } }, "required": [ "requestFingerprint", "quoteFingerprint", "acknowledgedPrice", "cartQuoteReceipt" ], "additionalProperties": false }, "PublicBookingResourceSelectionDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1 } }, "required": [ "requirementId", "resourceId", "quantity" ], "additionalProperties": false }, "BookingDeliveryDestinationAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "example": "1120 S Rackham Way", "pattern": "\\S", "description": "Required value; leading and trailing whitespace is trimmed before the normalized 300-character limit and non-empty check." }, "line2": { "type": "string", "example": "Suite 300", "description": "Optional value; leading and trailing whitespace is trimmed before the normalized 300-character limit, and whitespace-only input normalizes to the empty string." }, "city": { "type": "string", "example": "Meridian", "pattern": "\\S", "description": "Required value; leading and trailing whitespace is trimmed before the normalized 200-character limit and non-empty check." }, "state": { "type": "string", "example": "ID", "pattern": "\\S", "description": "Required value; leading and trailing whitespace is trimmed before the normalized 200-character limit and non-empty check." }, "postalCode": { "type": "string", "example": "83642", "pattern": "\\S", "description": "Required value; leading and trailing whitespace is trimmed before the normalized 32-character limit and non-empty check." }, "country": { "type": "string", "example": "US", "pattern": "^\\s*[A-Za-z]{2}\\s*$", "description": "Leading and trailing whitespace is trimmed and letters are uppercased before the normalized two-letter alphabetic country-code check." } }, "required": [ "line1", "city", "state", "postalCode", "country" ], "additionalProperties": false }, "BookingDeliverySelectionInputDto": { "description": "Method-discriminated booking delivery input. PICKUP forbids destinationAddress; DELIVERY requires it. Unknown keys are rejected.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "PICKUP" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "method", "destinationAddress" ], "properties": { "method": { "type": "string", "enum": [ "DELIVERY" ] }, "destinationAddress": { "$ref": "#/components/schemas/BookingDeliveryDestinationAddressDto" } } } ] }, "PublicBookingGroupGuestDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 64 } }, "required": [ "name" ], "additionalProperties": false }, "PublicBookingGroupIntakeAnswerDto": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "key", "value" ], "additionalProperties": false }, "CreatePublicBookingGroupMemberDto": { "type": "object", "properties": { "callerReference": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "Stable caller correlation unique within this complete group intent." }, "serviceId": { "type": "string", "format": "uuid" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1 }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Required for a package member. Must match the revision returned by the public booking-service projection." }, "resourceSelections": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingResourceSelectionDto" } }, "delivery": { "description": "Omitted or null means pickup.", "oneOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionInputDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "guest": { "$ref": "#/components/schemas/PublicBookingGroupGuestDto" }, "intake": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingGroupIntakeAnswerDto" } } }, "required": [ "callerReference", "serviceId", "startsAt", "endsAt" ], "additionalProperties": false }, "CreatePublicBookingGroupDto": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "booking.group/v1" ], "example": "booking.group/v1" }, "customerName": { "type": "string", "minLength": 1, "maxLength": 200 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "customerPhone": { "type": "string", "maxLength": 64, "nullable": true }, "shippingAddress": { "description": "Group shipping tax address. Delivery members always replace this with their frozen delivery destination; pickup members fall back to billing when omitted.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "description": "Group billing tax address, frozen independently onto every normalized member intent.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "cartQuote": { "description": "The last tax-inclusive quote rendered for this exact normalized cart. Existing clients may omit it; when present, the server re-evaluates it before any PAY_NOW capacity hold.", "allOf": [ { "$ref": "#/components/schemas/PublicBookingGroupCartQuoteInputDto" } ] }, "members": { "minItems": 1, "maxItems": 20, "description": "The complete intent. V1 accepts at most 20 submitted selections, 20 normalized members, and 100 server-expanded capacity anchors across the group. Groups containing composed selections additionally cap the complete materialized Commerce graph at 100 lines.", "type": "array", "items": { "$ref": "#/components/schemas/CreatePublicBookingGroupMemberDto" } } }, "required": [ "contractVersion", "customerName", "customerEmail", "members" ], "additionalProperties": false }, "PublicBookingAppliedPricingPolicyDto": { "type": "object", "properties": { "revisionNumber": { "type": "integer", "format": "int32", "minimum": 1 }, "bandUpperBoundMinutes": { "type": "integer", "format": "int32", "minimum": 1 }, "factorBasisPoints": { "type": "integer", "format": "int32", "minimum": 1 }, "elapsedMinutes": { "type": "integer", "format": "int32", "minimum": 1 }, "minimumDurationMinutes": { "type": "integer", "format": "int32", "minimum": 0 }, "graceMinutes": { "type": "integer", "format": "int32", "minimum": 0 }, "effectiveMinutes": { "type": "integer", "format": "int32", "minimum": 1 }, "derivedUnitPriceInCents": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "revisionNumber", "bandUpperBoundMinutes", "factorBasisPoints", "elapsedMinutes", "minimumDurationMinutes", "graceMinutes", "effectiveMinutes", "derivedUnitPriceInCents" ] }, "PublicBookingPricingLineDto": { "type": "object", "properties": { "name": { "type": "string" }, "commercialQuantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Frozen commercial line quantity. This can differ from the operational booking quantity." }, "unitPriceInCents": { "type": "integer", "format": "int32", "description": "Frozen unit price. May be negative only for an ADJUSTMENT credit line." }, "subtotalInCents": { "type": "integer", "format": "int32", "description": "Frozen line subtotal. May be negative only for an ADJUSTMENT credit line." }, "discountInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "taxInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "totalInCents": { "type": "integer", "format": "int32", "description": "Frozen line total. May be negative only for an ADJUSTMENT credit line." }, "appliedPricingPolicy": { "nullable": true, "description": "Frozen customer-safe duration-band evidence. Internal policy, revision, and band identifiers are omitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingAppliedPricingPolicyDto" } ] } }, "required": [ "name", "commercialQuantity", "unitPriceInCents", "subtotalInCents", "discountInCents", "taxInCents", "totalInCents", "appliedPricingPolicy" ] }, "PublicBookingPricingPresentationDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "pricedAt": { "type": "string", "format": "date-time" }, "elapsedMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "description": "Frozen elapsed duration when the priced lines agree on one duration-policy evaluation; null for scalar or legacy pricing." }, "operationalQuantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Operational quantity reserved by the booking, kept separate from commercial line quantities." }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingPricingLineDto" } } }, "required": [ "currency", "pricedAt", "elapsedMinutes", "operationalQuantity", "totalInCents", "lines" ] }, "PublicBookingGroupCartQuoteMemberDto": { "type": "object", "properties": { "ordinal": { "type": "integer", "format": "int32", "minimum": 0 }, "callerReference": { "type": "string" }, "serviceId": { "type": "string", "format": "uuid" }, "pricing": { "nullable": true, "description": "Customer-safe pricing presentation when the frozen pricing evidence is presentable. Null does not change the authoritative quoted money.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingPricingPresentationDto" } ] } }, "required": [ "ordinal", "callerReference", "serviceId", "pricing" ] }, "PublicBookingGroupCartQuoteResponseDto": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "booking.group/v1" ] }, "requestFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "price": { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" }, "cartQuoteReceipt": { "type": "string", "maxLength": 32768 }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingGroupCartQuoteMemberDto" } } }, "required": [ "contractVersion", "requestFingerprint", "quoteFingerprint", "price", "cartQuoteReceipt", "quoteExpiresAt", "members" ] }, "BookingCartQuoteStaleDetailsDto": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "CART_QUOTE_STALE" ] }, "acknowledgedPrice": { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" }, "currentPrice": { "$ref": "#/components/schemas/BookingPriceConfirmationComparablePriceDto" }, "requestFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "currentQuoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmedPriceReceipt": { "type": "string", "nullable": true, "example": null }, "receiptExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "example": null } }, "required": [ "reason", "acknowledgedPrice", "currentPrice", "requestFingerprint", "currentQuoteFingerprint", "confirmedPriceReceipt", "receiptExpiresAt" ] }, "BookingCartQuoteStaleErrorDto": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BOOKING_PRICE_CONFIRMATION_REQUIRED" ], "example": "BOOKING_PRICE_CONFIRMATION_REQUIRED" }, "message": { "type": "string", "example": "The tax-inclusive booking total changed. Review the current total and retry." }, "details": { "$ref": "#/components/schemas/BookingCartQuoteStaleDetailsDto" } }, "required": [ "code", "message", "details" ] }, "CheckoutTaxDisclosureDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "manual_no_tax" ], "description": "Tax posture recorded for this order/session." }, "provider": { "type": "string", "example": "manual_no_tax", "description": "Snapshot provider discriminator." }, "litecommerceCalculated": { "type": "boolean", "example": false, "description": "False when litecommerce did not calculate tax for this order." }, "taxInCents": { "type": "integer", "format": "int32", "example": 0, "description": "Tax amount recorded on the snapshot." }, "label": { "type": "string", "example": "Tax not calculated by litecommerce" }, "message": { "type": "string", "example": "litecommerce did not calculate sales tax for this order. The merchant accepted responsibility for manual tax handling." }, "warning": { "type": "string", "nullable": true, "description": "Operator-visible warning recorded on the snapshot." }, "acknowledgementVersion": { "type": "string", "nullable": true, "description": "Server acknowledgement contract version recorded at save time." }, "acknowledgedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the tenant owner/admin acknowledgement was recorded." }, "settingsRevision": { "type": "string", "format": "date-time", "nullable": true, "description": "Organization settings revision used when the manual/no-tax snapshot was written." } }, "required": [ "mode", "provider", "litecommerceCalculated", "taxInCents", "label", "message", "warning", "acknowledgementVersion", "acknowledgedAt", "settingsRevision" ] }, "PublicBookingGroupPricingSummaryDto": { "type": "object", "properties": { "subtotalInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Frozen aggregate line subtotal from the authoritative CheckoutSession or member Sales records." }, "discountInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Frozen aggregate discount allocated by the server. Clients must not infer this from total differences." }, "taxInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe aggregate manual/no-tax disclosure. Raw tax evidence and member addresses remain server-only.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Frozen commercial total: subtotal minus discount plus tax. Booking delivery is a member fee already included in subtotal, not a separate retail shipping charge." }, "amountDueNowInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Initial server-authoritative collection amount. Zero for APPROVE_PAY_LATER and zero-total groups." }, "remainingBalanceInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Frozen balance outside the initial due-now collection. It is always total minus due now; APPROVE_PAY_LATER therefore preserves the bound member Sales total while each member commerce summary separately reports its current balance." } }, "required": [ "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "totalInCents", "amountDueNowInCents", "remainingBalanceInCents" ] }, "CustomerPackageComponentDto": { "type": "object", "properties": { "name": { "type": "string" }, "commercialQuantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Commercial pricing quantity. For FIXED_PRICE booking components this intentionally remains 1." }, "includedQuantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Frozen operational quantity included in the selected package. This is the composition effective quantity." }, "unitPriceInCents": { "type": "number", "description": "Frozen unit price in minor units (cents)." }, "subtotalInCents": { "type": "number" }, "intrinsicSavingsInCents": { "type": "number", "description": "Intrinsic COMPOSED_PRODUCT savings allocated to this component." }, "promotionDiscountInCents": { "type": "number", "description": "Later coupon, automatic, bundle, or entitlement savings allocated to this component, excluding intrinsic package savings." }, "discountInCents": { "type": "number", "description": "Total component discount: intrinsic package savings plus external promotions." }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" } }, "required": [ "name", "commercialQuantity", "includedQuantity", "unitPriceInCents", "subtotalInCents", "intrinsicSavingsInCents", "promotionDiscountInCents", "discountInCents", "taxInCents", "totalInCents" ] }, "CustomerPackageGroupDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "title": { "type": "string" }, "selectedQuantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Top-level package quantity selected by the customer." }, "subtotalInCents": { "type": "number" }, "intrinsicSavingsInCents": { "type": "number" }, "promotionDiscountInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" }, "components": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageComponentDto" } } }, "required": [ "kind", "title", "selectedQuantity", "subtotalInCents", "intrinsicSavingsInCents", "promotionDiscountInCents", "discountInCents", "taxInCents", "totalInCents", "components" ] }, "PublicBookingGroupCheckoutSummaryDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ] }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "amountDueNowInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "taxInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe aggregate manual/no-tax disclosure. Raw tax evidence and member addresses remain server-only.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } } }, "required": [ "status", "totalInCents", "amountDueNowInCents", "taxInCents", "taxDisclosure", "expiresAt", "packages" ] }, "PublicBookingGroupAgreementDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NOT_REQUIRED", "ACTION_REQUIRED", "READY_TO_RESUME", "COMPLETED", "REMEDIATION_REQUIRED" ] }, "nextAction": { "type": "string", "enum": [ "COMPLETE_AGREEMENT", "RESUME_BOOKING_REQUEST" ], "nullable": true, "description": "The only agreement-specific customer action. Null once the frozen request has advanced or no booking-request agreement applies." } }, "required": [ "status", "nextAction" ] }, "PublicBookingGroupCommerceSummaryDto": { "type": "object", "properties": { "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "taxInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe manual/no-tax disclosure. Provider evidence, addresses, and calculation identifiers are never exposed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "amountPaidInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "balanceDueInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "displayNumber": { "type": "string", "nullable": true }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } } }, "required": [ "commercialStatus", "paymentStatus", "totalInCents", "taxInCents", "taxDisclosure", "amountPaidInCents", "balanceDueInCents", "displayNumber", "packages" ] }, "PublicBookingGroupMemberResponseDto": { "type": "object", "properties": { "ordinal": { "type": "integer", "format": "int32", "minimum": 0 }, "callerReference": { "type": "string" }, "serviceId": { "type": "string", "format": "uuid" }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "status": { "type": "string", "enum": [ "AGREEMENT_REQUIRED", "PENDING_REQUEST", "REQUESTED", "HELD", "PENDING_PAYMENT", "CONFIRMED", "DECLINED", "EXPIRED", "CANCELLED", "FAILED" ] }, "delivery": { "nullable": true, "description": "Frozen browser-safe delivery evidence. HELD groups read the active hold; commercially bound groups read the authoritative member Sales snapshot. Null before approval/capacity or when unavailable.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "commerce": { "nullable": true, "description": "Member-scoped shared Sales summary after aggregate commercial binding.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingGroupCommerceSummaryDto" } ] }, "pricingDetails": { "nullable": true, "description": "Frozen line, quantity, per-unit, duration-band, revision-number, and total evidence from the persisted Commerce revision. Null before commercial binding or for legacy pricing snapshots.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingPricingPresentationDto" } ] } }, "required": [ "ordinal", "callerReference", "serviceId", "startsAt", "endsAt", "quantity", "status", "delivery", "commerce", "pricingDetails" ] }, "PublicBookingGroupResponseDto": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "booking.group/v1" ] }, "publicRef": { "type": "string", "pattern": "^b[a-z0-9]{25}$", "description": "Non-authorizing correlation reference." }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_APPROVAL", "HELD", "AWAITING_PAYMENT", "CONFIRMING", "RECONCILIATION_REQUIRED", "CONFIRMED", "DECLINED", "EXPIRED", "CANCELLED", "FAILED" ] }, "settlementPosture": { "type": "string", "enum": [ "PAY_NOW", "APPROVE_THEN_PAY", "APPROVE_PAY_LATER" ] }, "currency": { "type": "string", "example": "USD" }, "expiresAt": { "format": "date-time", "type": "string" }, "serverTime": { "format": "date-time", "type": "string" }, "expiresInSeconds": { "type": "integer", "format": "int32", "minimum": 0 }, "resumeToken": { "type": "string", "nullable": true, "description": "Fresh response-only resume proof on create/recovery replay; never persisted raw and null on ordinary reads." }, "pricing": { "nullable": true, "description": "Authoritative aggregate commercial breakdown after binding. Null before pricing exists and on legacy idempotency outcomes that predate this additive projection; clients must not fabricate missing values. APPROVE_PAY_LATER has pricing without a CheckoutSession or payment handoff.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingGroupPricingSummaryDto" } ] }, "checkout": { "nullable": true, "description": "Safe aggregate collection summary. No CheckoutSession id or raw capability is exposed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingGroupCheckoutSummaryDto" } ] }, "resumeExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "agreement": { "description": "Neutral action state for the exact frozen booking-request requirement. It exposes no database, execution, participant, or verification identifiers.", "allOf": [ { "$ref": "#/components/schemas/PublicBookingGroupAgreementDto" } ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingGroupMemberResponseDto" } } }, "required": [ "contractVersion", "publicRef", "status", "settlementPosture", "currency", "expiresAt", "serverTime", "expiresInSeconds", "resumeToken", "pricing", "checkout", "resumeExpiresAt", "agreement", "members" ] }, "BookingPriceConfirmationDto": { "type": "object", "properties": { "confirmedPriceReceipt": { "type": "string", "maxLength": 32768, "description": "Signed, request-bound tax-inclusive quote receipt returned by a prior BOOKING_PRICE_CONFIRMATION_REQUIRED response." }, "priceConfirmed": { "type": "boolean", "enum": [ true ], "description": "Must be literal true after the customer renders and explicitly accepts the receipt total." } }, "additionalProperties": false }, "BookingReasonDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "reason" ] }, "RefundComponentAllocationDto": { "type": "object", "properties": { "componentKind": { "type": "string", "enum": [ "LINE", "SHIPPING" ], "description": "LINE allocates refund value to one frozen Sales line; SHIPPING allocates it to the frozen shipping component." }, "lineId": { "type": "string", "format": "uuid", "nullable": true, "description": "Required when componentKind=LINE and forbidden for SHIPPING. The id must belong to the record's frozen revision." }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000000, "description": "Gross refund cents assigned to this component, including that component's tax where applicable." } }, "required": [ "componentKind", "amountInCents" ] }, "BookingGroupRefundReconciliationAllocationDto": { "type": "object", "properties": { "callerReference": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "Stable booking-group caller reference whose original charge allocation receives this refund amount." }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000000, "description": "Exact cents from the imported provider refund to freeze against this member." }, "components": { "minItems": 1, "maxItems": 100, "description": "Exact component allocation inside this member Sales record. Gross component cents must sum to amountInCents.", "type": "array", "items": { "$ref": "#/components/schemas/RefundComponentAllocationDto" } } }, "required": [ "callerReference", "amountInCents", "components" ] }, "IssueBookingGroupRefundDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "allocations": { "minItems": 1, "maxItems": 20, "description": "Exact member allocation plan. Caller references must be unique and amounts must sum to the imported refund.", "type": "array", "items": { "$ref": "#/components/schemas/BookingGroupRefundReconciliationAllocationDto" } } }, "required": [ "reason", "allocations" ] }, "BookingGroupRefundReconciliationResultAllocationDto": { "type": "object", "properties": { "callerReference": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "Stable booking-group caller reference whose original charge allocation receives this refund amount." }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000000, "description": "Exact cents from the imported provider refund to freeze against this member." } }, "required": [ "callerReference", "amountInCents" ] }, "BookingGroupSharedRefundResponseDto": { "type": "object", "properties": { "bookingGroupId": { "type": "string", "format": "uuid" }, "refundPaymentAttemptId": { "type": "string", "format": "uuid" }, "stripeRefundId": { "type": "string", "example": "re_3N..." }, "providerStatus": { "type": "string", "enum": [ "PROCESSING", "SUCCEEDED" ] }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1 }, "currency": { "type": "string", "example": "usd" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BookingGroupRefundReconciliationResultAllocationDto" } } }, "required": [ "bookingGroupId", "refundPaymentAttemptId", "stripeRefundId", "providerStatus", "amountInCents", "currency", "allocations" ] }, "ReconcileBookingGroupRefundDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "allocations": { "minItems": 1, "maxItems": 20, "description": "Exact member allocation plan. Caller references must be unique and amounts must sum to the imported refund.", "type": "array", "items": { "$ref": "#/components/schemas/BookingGroupRefundReconciliationAllocationDto" } } }, "required": [ "reason", "allocations" ] }, "BookingGroupRefundReconciliationResponseDto": { "type": "object", "properties": { "bookingGroupId": { "type": "string", "format": "uuid" }, "refundPaymentAttemptId": { "type": "string", "format": "uuid" }, "stripeRefundId": { "type": "string", "example": "re_3N..." }, "reconciliationStatus": { "type": "string", "enum": [ "RESOLVED" ] }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1 }, "currency": { "type": "string", "example": "usd" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BookingGroupRefundReconciliationResultAllocationDto" } } }, "required": [ "bookingGroupId", "refundPaymentAttemptId", "stripeRefundId", "reconciliationStatus", "amountInCents", "currency", "allocations" ] }, "BookingResourceSelectionDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "requirementId", "resourceId", "quantity" ], "additionalProperties": false }, "CreateMerchantBookingDto": { "type": "object", "properties": { "intent": { "type": "string", "enum": [ "DRAFT", "REQUEST", "RESERVE" ] }, "serviceId": { "type": "string", "format": "uuid" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1 }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Required catalog composition revision when the selected service is sold as a package." }, "durationMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 44640 }, "resourceSelections": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceSelectionDto" } }, "delivery": { "description": "Omitted or null means pickup. Otherwise, pickup or delivery intent is evaluated when RESERVE is requested; DRAFT/REQUEST retain it for the later reserve action.", "oneOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionInputDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "customerId": { "type": "string", "format": "uuid", "description": "Existing customer in the active tenant. Mutually exclusive with inline customer fields." }, "customerName": { "type": "string", "maxLength": 200 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "customerPhone": { "type": "string", "nullable": true, "maxLength": 50 }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "shippingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" }, "billingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" } }, "required": [ "intent", "serviceId", "startsAt", "endsAt" ], "additionalProperties": false }, "BookingLifecycleCommerceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "currency": { "type": "string" }, "totalInCents": { "type": "integer", "format": "int32" }, "amountPaidInCents": { "type": "integer", "format": "int32" }, "balanceDueInCents": { "type": "integer", "format": "int32" }, "displayNumber": { "type": "string", "nullable": true } }, "required": [ "id", "commercialStatus", "paymentStatus", "currency", "totalInCents", "amountPaidInCents", "balanceDueInCents", "displayNumber" ] }, "BookingLifecycleDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "currency": { "type": "string" }, "totalInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "delivery": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "commerce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingLifecycleCommerceDto" } ] } }, "required": [ "id", "serviceId", "startsAt", "endsAt", "quantity", "status", "approvalStatus", "currency", "totalInCents", "archivedAt", "delivery", "commerce" ] }, "PublicBookingAvailabilitySearchDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid", "description": "Exactly one of serviceId or serviceSlug is required." }, "serviceSlug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Exactly one of serviceId or serviceSlug is required." }, "startsAt": { "type": "string", "format": "date-time", "description": "Inclusive search start. For EXACT_RANGE this is the requested booking start." }, "endsAt": { "type": "string", "format": "date-time", "description": "Exclusive search end. For EXACT_RANGE this is the requested booking end." }, "timezone": { "type": "string", "description": "Presentation timezone. Candidate generation remains anchored to the service/rule timezones." }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1 }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Required for a package service. Must match the revision returned by the public service projection." }, "durationMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 44640, "description": "Required when choosing a non-default FIXED_DURATION option." }, "resourceSelections": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingResourceSelectionDto" } } }, "required": [ "startsAt", "endsAt" ], "additionalProperties": false }, "PublicBookingAvailabilityDiagnosticsDto": { "type": "object", "properties": { "requestedQuantity": { "type": "integer", "format": "int32", "minimum": 1 }, "availableQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "resourceSelectionRequired": { "type": "boolean" } }, "required": [ "requestedQuantity", "availableQuantity", "resourceSelectionRequired" ] }, "PublicBookingResourceOptionDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "availableQuantity": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "requirementId", "resourceId", "slug", "name", "resourceType", "availableQuantity" ] }, "PublicBookingRequirementOptionsDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "selectionStrategy": { "type": "string", "enum": [ "ANY_AVAILABLE", "SPECIFIC_RESOURCE", "CUSTOMER_SELECTS", "MERCHANT_ASSIGN" ] }, "requiredQuantity": { "type": "integer", "format": "int32", "minimum": 1 }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingResourceOptionDto" } } }, "required": [ "requirementId", "selectionStrategy", "requiredQuantity", "options" ] }, "PublicBookingPricingHookDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "FLAT_TIME", "FIXED_PRICE", "PRICING_STRUCTURE" ] }, "basis": { "type": "string", "enum": [ "RESERVED_WINDOW", "CHARGED_DURATION", "FIXED_PRICE" ] }, "basePriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Configured base price only." }, "pricingIntervalMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "description": "Minutes represented by one base-price unit for FLAT_TIME; null for fixed pricing." }, "currency": { "type": "string", "example": "USD" }, "authoritative": { "type": "boolean", "example": false, "description": "Always false in #640: checkout/shared commerce remains authoritative for final pricing." }, "fromPriceInCents": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0, "description": "ADR-043 reachable From price: the minimum evaluated per-unit total across the actual bookable-duration domain of the service, including the published minimum-then-grace transform - never the first stored rate band merely because it exists. Null when the service has no bookable-duration domain, when the pricing configuration cannot be evaluated, or on slot-level hooks (slots name their own concrete window). Not authoritative." }, "fromDurationMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "description": "The bookable-duration-domain minutes fromPriceInCents was evaluated at. Null exactly when fromPriceInCents is null." } }, "required": [ "mode", "basis", "basePriceInCents", "pricingIntervalMinutes", "currency", "authoritative", "fromPriceInCents", "fromDurationMinutes" ] }, "PublicBookingAvailabilitySlotDto": { "type": "object", "properties": { "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "availableQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "diagnostics": { "$ref": "#/components/schemas/PublicBookingAvailabilityDiagnosticsDto" }, "resourceOptions": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingRequirementOptionsDto" } }, "pricing": { "$ref": "#/components/schemas/PublicBookingPricingHookDto" } }, "required": [ "startsAt", "endsAt", "availableQuantity", "diagnostics", "resourceOptions", "pricing" ] }, "PublicBookingAvailabilityResponseDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "timezone": { "type": "string" }, "generatedAt": { "format": "date-time", "type": "string" }, "truncated": { "type": "boolean", "description": "True when the hard candidate cap was reached; narrow the search window to continue." }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingAvailabilitySlotDto" } }, "availability": { "type": "string", "enum": [ "AVAILABLE", "LIMITED", "UNAVAILABLE" ], "description": "Top-level availability for the complete selection after all package components are reconciled." }, "availableQuantity": { "type": "integer", "format": "int32", "minimum": 0, "description": "Maximum complete-selection quantity available across the returned slots." }, "compositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true, "description": "Frozen package definition revision used for this availability result; null for an ordinary service." } }, "required": [ "serviceId", "periodMode", "timezone", "generatedAt", "truncated", "slots", "availability", "availableQuantity", "compositionRevision" ] }, "MerchantBookingServiceRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "timezone": { "type": "string", "description": "Effective service timezone (service override, else organization)." } }, "required": [ "id", "name", "slug", "bookingType", "periodMode", "timezone" ] }, "MerchantBookingCommerceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayNumber": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never a booking or payment gate." }, "currency": { "type": "string" }, "totalInCents": { "type": "integer", "format": "int32" }, "amountPaidInCents": { "type": "integer", "format": "int32" }, "refundedInCents": { "type": "integer", "format": "int32" }, "balanceDueInCents": { "type": "integer", "format": "int32" }, "orderId": { "type": "string", "format": "uuid", "nullable": true }, "outboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "physicalProductQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "physicallyAllocatedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "physicallyFulfilledQuantity": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "id", "displayNumber", "type", "commercialStatus", "paymentStatus", "fulfillmentStatus", "signatureStatus", "currency", "totalInCents", "amountPaidInCents", "refundedInCents", "balanceDueInCents", "orderId", "outboundFulfillmentMode", "outboundDueAt", "inboundFulfillmentMode", "inboundDueAt", "physicalProductQuantity", "physicallyAllocatedQuantity", "physicallyFulfilledQuantity" ] }, "MerchantBookingResourceSummaryItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "allocationCount": { "type": "integer", "format": "int32", "minimum": 1 }, "assignedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "id", "name", "resourceType", "allocationCount", "assignedQuantity", "shortageQuantity" ] }, "MerchantBookingResourceUnitRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "barcode": { "type": "string", "nullable": true } }, "required": [ "id", "identifier", "sku", "barcode" ] }, "MerchantBookingAllocationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requirementId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid" }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ] }, "resourceUnit": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingResourceUnitRefDto" } ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "shortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageReason": { "type": "string", "nullable": true }, "shortageApprovedByUserId": { "type": "string", "nullable": true }, "shortageApprovedAt": { "type": "string", "format": "date-time", "nullable": true }, "shortageResolution": { "type": "string", "enum": [ "SUBSTITUTED", "EXTERNALLY_SOURCED", "CAPACITY_ADDED" ], "nullable": true }, "shortageResolutionNote": { "type": "string", "nullable": true }, "shortageResolvedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "requirementId", "resourceId", "allocationMode", "resourceUnit", "quantity", "shortageQuantity", "shortageReason", "shortageApprovedByUserId", "shortageApprovedAt", "shortageResolution", "shortageResolutionNote", "shortageResolvedAt" ] }, "MerchantBookingResourceSummaryDto": { "type": "object", "properties": { "requirementCount": { "type": "integer", "format": "int32", "minimum": 0 }, "requiredQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "allocationCount": { "type": "integer", "format": "int32", "minimum": 0 }, "assignedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unresolvedShortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "allocationConflict": { "type": "boolean" }, "overrideCount": { "type": "integer", "format": "int32", "minimum": 0 }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingResourceSummaryItemDto" } }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingAllocationDto" } } }, "required": [ "requirementCount", "requiredQuantity", "allocationCount", "assignedQuantity", "shortageQuantity", "unresolvedShortageQuantity", "allocationConflict", "overrideCount", "resources", "allocations" ] }, "MerchantBookingAllowedActionsDto": { "type": "object", "properties": { "approve": { "type": "boolean" }, "decline": { "type": "boolean" }, "cancel": { "type": "boolean" }, "reschedule": { "type": "boolean" }, "start": { "type": "boolean" }, "complete": { "type": "boolean" }, "archive": { "type": "boolean" } }, "required": [ "approve", "decline", "cancel", "reschedule", "start", "complete", "archive" ] }, "MerchantBookingAttentionFlagsDto": { "type": "object", "properties": { "needsApproval": { "type": "boolean" }, "paymentDue": { "type": "boolean" }, "unassigned": { "type": "boolean" }, "shortage": { "type": "boolean" }, "allocationConflict": { "type": "boolean" }, "overridden": { "type": "boolean" } }, "required": [ "needsApproval", "paymentDue", "unassigned", "shortage", "allocationConflict", "overridden" ] }, "MerchantBookingChangeRequestDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "RESCHEDULE", "CANCEL" ] }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED", "WITHDRAWN" ] }, "requestedStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "requestedEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "type", "status", "requestedStartsAt", "requestedEndsAt", "reason", "createdAt" ] }, "MerchantBookingDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "startDate": { "format": "date-time", "type": "string" }, "endDate": { "format": "date-time", "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "totalPriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Compatibility total: canonical Sales total for modern bookings, legacy local total only for service-less rows." }, "notes": { "type": "string", "nullable": true }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "commerceRecordId": { "type": "string", "format": "uuid", "nullable": true }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "customerEmail": { "type": "string", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "customerPhone": { "type": "string", "nullable": true }, "timezone": { "type": "string", "description": "Effective booking timezone (booking snapshot, service override, then organization)." }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "cancellationReason": { "type": "string", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "delivery": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "shippingAddress": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "service": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingServiceRefDto" } ] }, "commerce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingCommerceDto" } ] }, "resourceSummary": { "$ref": "#/components/schemas/MerchantBookingResourceSummaryDto" }, "allowedActions": { "$ref": "#/components/schemas/MerchantBookingAllowedActionsDto" }, "attentionFlags": { "$ref": "#/components/schemas/MerchantBookingAttentionFlagsDto" }, "pendingChangeRequest": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingChangeRequestDto" } ] } }, "required": [ "id", "organizationId", "itemId", "variantId", "userId", "startDate", "endDate", "status", "quantity", "totalPriceInCents", "notes", "serviceId", "commerceRecordId", "customerId", "customerEmail", "customerName", "customerPhone", "timezone", "approvalStatus", "cancellationReason", "cancelledAt", "completedAt", "archivedAt", "createdAt", "updatedAt", "delivery", "shippingAddress", "billingAddress", "service", "commerce", "resourceSummary", "allowedActions", "attentionFlags", "pendingChangeRequest" ] }, "MerchantBookingListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "MerchantBookingCalendarEventDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable milestone key (`bookingId:start|end`)." }, "kind": { "type": "string", "enum": [ "BOOKING_START", "BOOKING_END", "DELIVERY_DUE", "CUSTOMER_PICKUP_DUE", "RETRIEVAL_DUE", "CUSTOMER_RETURN_DUE" ] }, "bookingId": { "type": "string", "format": "uuid" }, "occursAt": { "format": "date-time", "type": "string" }, "source": { "type": "string", "enum": [ "BOOKING", "SHARED_COMMERCE" ] }, "posture": { "type": "string", "enum": [ "SCHEDULED", "DUE" ] } }, "required": [ "id", "kind", "bookingId", "occursAt", "source", "posture" ] }, "MerchantBookingCalendarBlackoutDto": { "type": "object", "properties": { "occurrenceId": { "type": "string", "description": "Stable occurrence key (`blackoutId:startsAt`) for calendar rendering." }, "blackoutId": { "type": "string", "format": "uuid" }, "targetType": { "type": "string", "enum": [ "ORGANIZATION", "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "serviceName": { "type": "string", "nullable": true }, "resourceName": { "type": "string", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "reason": { "type": "string", "nullable": true } }, "required": [ "occurrenceId", "blackoutId", "targetType", "serviceId", "resourceId", "serviceName", "resourceName", "startsAt", "endsAt", "reason" ] }, "MerchantBookingStatusCountDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "count": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "status", "count" ] }, "MerchantBookingCalendarSummaryDto": { "type": "object", "properties": { "bookingCount": { "type": "integer", "format": "int32", "minimum": 0 }, "blackoutCount": { "type": "integer", "format": "int32", "minimum": 0 }, "eventCount": { "type": "integer", "format": "int32", "minimum": 0 }, "needsApprovalCount": { "type": "integer", "format": "int32", "minimum": 0 }, "paymentDueCount": { "type": "integer", "format": "int32", "minimum": 0 }, "unassignedCount": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageCount": { "type": "integer", "format": "int32", "minimum": 0 }, "overriddenCount": { "type": "integer", "format": "int32", "minimum": 0 }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingStatusCountDto" } } }, "required": [ "bookingCount", "blackoutCount", "eventCount", "needsApprovalCount", "paymentDueCount", "unassignedCount", "shortageCount", "overriddenCount", "statuses" ] }, "MerchantBookingCalendarDto": { "type": "object", "properties": { "timezone": { "type": "string", "description": "Organization IANA timezone." }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingDto" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingCalendarEventDto" } }, "blackouts": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingCalendarBlackoutDto" } }, "summary": { "$ref": "#/components/schemas/MerchantBookingCalendarSummaryDto" }, "truncated": { "type": "boolean", "description": "True when the bounded booking, recurring-source scan, or expanded-occurrence cap was reached; narrow/filter the range." } }, "required": [ "timezone", "from", "to", "bookings", "events", "blackouts", "summary", "truncated" ] }, "UpdateMerchantBookingTaxAddressesDto": { "type": "object", "properties": { "shippingAddress": { "nullable": true, "description": "Normalized shipping tax address. Omit to retain it or send null to clear it. A frozen delivery destination remains authoritative.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "nullable": true, "description": "Normalized billing tax address. Omit to retain it or send null to clear it.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] } } }, "UpdateBookingPhysicalPlanDto": { "type": "object", "properties": { "outboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ResolveBookingShortageDto": { "type": "object", "properties": { "resolution": { "type": "string", "enum": [ "SUBSTITUTED", "EXTERNALLY_SOURCED", "CAPACITY_ADDED" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "resolution", "reason" ] }, "RescheduleBookingDto": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "resourceSelections": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceSelectionDto" } }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "startsAt", "endsAt", "reason" ] }, "MerchantBookingAssignmentRequirementDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ], "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "required": { "type": "boolean" }, "selectionStrategy": { "type": "string", "enum": [ "ANY_AVAILABLE", "SPECIFIC_RESOURCE", "CUSTOMER_SELECTS", "MERCHANT_ASSIGN" ] }, "sortOrder": { "type": "integer", "minimum": 0 } }, "required": [ "id", "resourceId", "resourceType", "quantity", "required", "selectionStrategy", "sortOrder" ] }, "MerchantBookingAssignmentProviderDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "STAFF" ] } }, "required": [ "userId", "email", "firstName", "lastName", "role" ] }, "MerchantBookingCurrentAllocationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requirementId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid" }, "resourceName": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "resourceUnitId": { "type": "string", "format": "uuid", "nullable": true }, "resourceUnitIdentifier": { "type": "string", "nullable": true }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ] }, "quantity": { "type": "integer", "minimum": 1 }, "shortageQuantity": { "type": "integer", "minimum": 0 }, "shortageApprovedByUserId": { "type": "string", "format": "uuid", "nullable": true }, "shortageApprovedAt": { "type": "string", "format": "date-time", "nullable": true }, "shortageReason": { "type": "string", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "provider": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingAssignmentProviderDto" } ] } }, "required": [ "id", "requirementId", "resourceId", "resourceName", "resourceType", "resourceUnitId", "resourceUnitIdentifier", "allocationMode", "quantity", "shortageQuantity", "shortageApprovedByUserId", "shortageApprovedAt", "shortageReason", "startsAt", "endsAt", "provider" ] }, "MerchantBookingAssignmentCandidateDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "resourceName": { "type": "string" }, "resourceSlug": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ] }, "configuredCapacity": { "type": "integer", "minimum": 0 }, "activeUnitCount": { "type": "integer", "minimum": 0 }, "remainingQuantity": { "type": "integer", "minimum": 0 }, "available": { "type": "boolean" }, "blockerCodes": { "type": "array", "items": { "type": "string" } }, "provider": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantBookingAssignmentProviderDto" } ] } }, "required": [ "requirementId", "resourceId", "resourceName", "resourceSlug", "resourceType", "allocationMode", "configuredCapacity", "activeUnitCount", "remainingQuantity", "available", "blockerCodes", "provider" ] }, "MerchantBookingAssignmentWorkspaceDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "canAssign": { "type": "boolean" }, "expectedAllocationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingAssignmentRequirementDto" } }, "currentAllocations": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingCurrentAllocationDto" } }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingAssignmentCandidateDto" } }, "conflictSignals": { "type": "array", "items": { "type": "string" } } }, "required": [ "bookingId", "serviceId", "serviceName", "startsAt", "endsAt", "status", "canAssign", "expectedAllocationFingerprint", "requirements", "currentAllocations", "candidates", "conflictSignals" ] }, "MerchantBookingAssignmentSelectionDto": { "type": "object", "properties": { "requirementId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "resourceUnitIds": { "maxItems": 1000, "description": "Optional explicit serialized units. Omit to let the guarded capacity engine choose active units deterministically.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "requirementId", "resourceId", "quantity" ] }, "ReplaceMerchantBookingAssignmentsDto": { "type": "object", "properties": { "expectedAllocationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 fence returned by the latest assignment workspace read. The replacement fails if the live allocation set changed concurrently." }, "resourceSelections": { "maxItems": 100, "description": "Complete explicit resource-selection intent. Requirements that use automatic allocation remain server-selected.", "type": "array", "items": { "$ref": "#/components/schemas/MerchantBookingAssignmentSelectionDto" } }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "expectedAllocationFingerprint", "resourceSelections", "reason" ] }, "BookingChecklistTaskDto": { "type": "object", "properties": { "taskKey": { "type": "string", "description": "Stable derived task key. Allocation and commerce-line source ids remain owned by their respective ledgers." }, "phase": { "type": "string", "enum": [ "PREP", "LOAD_OUT", "RETURN" ] }, "sourceType": { "type": "string", "enum": [ "ALLOCATION", "COMMERCE_LINE", "CUSTOM" ] }, "sourceId": { "type": "string", "format": "uuid", "nullable": true }, "label": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETE", "BLOCKED" ] }, "notes": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedByUserId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "taskKey", "phase", "sourceType", "sourceId", "label", "quantity", "status", "notes", "completedAt", "completedByUserId" ] }, "BookingChecklistProgressDto": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "minimum": 0 }, "complete": { "type": "integer", "format": "int32", "minimum": 0 }, "blocked": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "total", "complete", "blocked" ] }, "BookingChecklistProductLineDto": { "type": "object", "properties": { "lineId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "plannedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "fulfilledQuantity": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "lineId", "name", "sku", "quantity", "plannedQuantity", "fulfilledQuantity" ] }, "BookingChecklistShipmentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED", "CANCELLED" ] }, "mode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ] }, "carrier": { "type": "string", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true }, "trackingUrl": { "type": "string", "nullable": true }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "status", "mode", "carrier", "trackingNumber", "trackingUrl", "shippedAt", "deliveredAt" ] }, "BookingPhysicalFulfillmentProjectionDto": { "type": "object", "properties": { "commerceRecordId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ] }, "outboundMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "productLines": { "type": "array", "items": { "$ref": "#/components/schemas/BookingChecklistProductLineDto" } }, "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/BookingChecklistShipmentDto" } } }, "required": [ "commerceRecordId", "status", "outboundMode", "outboundDueAt", "inboundMode", "inboundDueAt", "productLines", "shipments" ] }, "BookingReturnProjectionDto": { "type": "object", "properties": { "returnId": { "type": "string", "format": "uuid" }, "returnItemId": { "type": "string", "format": "uuid" }, "returnStatus": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ] }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "orderItemId": { "type": "string", "format": "uuid" }, "commerceLineId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "condition": { "type": "string", "enum": [ "PENDING", "RESELLABLE", "DAMAGED", "WRITE_OFF" ] }, "intakeNotes": { "type": "string", "nullable": true }, "restockDisposition": { "type": "string", "enum": [ "PENDING", "RESTOCKED", "NOT_ELIGIBLE", "NOT_APPLICABLE" ] }, "restockedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "returnId", "returnItemId", "returnStatus", "receivedAt", "completedAt", "orderItemId", "commerceLineId", "name", "quantity", "condition", "intakeNotes", "restockDisposition", "restockedAt" ] }, "BookingFulfillmentChecklistDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "bookingStatus": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "serviceName": { "type": "string", "nullable": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/BookingChecklistTaskDto" } }, "progress": { "$ref": "#/components/schemas/BookingChecklistProgressDto" }, "physicalFulfillment": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingPhysicalFulfillmentProjectionDto" } ] }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/BookingReturnProjectionDto" } } }, "required": [ "bookingId", "bookingStatus", "startsAt", "endsAt", "serviceName", "tasks", "progress", "physicalFulfillment", "returns" ] }, "UpdateBookingChecklistTaskDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "COMPLETE", "BLOCKED" ] }, "notes": { "type": "string", "nullable": true, "maxLength": 2000, "description": "Booking-owned staff note. Null or blank clears the note." } } }, "BookingReportDimensionOptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "archivedAt" ] }, "BookingReportDimensionsDto": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/BookingReportDimensionOptionDto" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BookingReportDimensionOptionDto" } } }, "required": [ "services", "resources" ] }, "BookingAvailabilityReportRowDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceName": { "type": "string", "nullable": true }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ], "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "configuredCapacity": { "type": "integer", "format": "int32", "minimum": 0 }, "activeUnitCapacity": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "openWindowCount": { "type": "integer", "format": "int32", "minimum": 0 }, "requirementCount": { "type": "integer", "format": "int32", "minimum": 0 }, "requiredQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "heldQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "committedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "remainingCapacity": { "type": "integer", "format": "int32", "minimum": 0 }, "blackoutCount": { "type": "integer", "format": "int32", "minimum": 0 }, "controlledShortageApprovalCount": { "type": "integer", "format": "int32", "minimum": 0 }, "blockerCodes": { "type": "array", "items": { "type": "string", "enum": [ "NO_OPEN_WINDOW", "REQUIRED_RESOURCE_UNAVAILABLE", "BLACKOUT", "CAPACITY_FULL", "CONTROLLED_SHORTAGE" ] } } }, "required": [ "serviceId", "serviceName", "resourceId", "resourceName", "resourceType", "userId", "configuredCapacity", "activeUnitCapacity", "openWindowCount", "requirementCount", "requiredQuantity", "heldQuantity", "committedQuantity", "shortageQuantity", "remainingCapacity", "blackoutCount", "controlledShortageApprovalCount", "blockerCodes" ] }, "BookingAvailabilityReportDto": { "type": "object", "properties": { "generatedAt": { "format": "date-time", "type": "string" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "rangeDimension": { "type": "string", "enum": [ "AVAILABILITY_WINDOW", "FULFILLMENT_MILESTONE", "BOOKING_START", "DOCUMENT_DUE_OR_EXPIRY" ] }, "truncated": { "type": "boolean", "description": "True when the bounded row limit was reached." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAvailabilityReportRowDto" } } }, "required": [ "generatedAt", "from", "to", "rangeDimension", "truncated", "rows" ] }, "BookingFulfillmentDemandReportRowDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "serviceName": { "type": "string", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "outboundMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ], "nullable": true }, "shipmentStatuses": { "type": "array", "items": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED", "CANCELLED" ] } }, "neededQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "assignedQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "shortageQuantity": { "type": "integer", "format": "int32", "minimum": 0 }, "assignedResources": { "type": "array", "items": { "type": "string" } }, "exactAssignedAssets": { "type": "array", "items": { "type": "string" } }, "missingAssignment": { "type": "boolean" }, "allocationConflict": { "type": "boolean" } }, "required": [ "bookingId", "serviceId", "serviceName", "customerName", "startsAt", "endsAt", "outboundMode", "outboundDueAt", "inboundMode", "inboundDueAt", "fulfillmentStatus", "shipmentStatuses", "neededQuantity", "assignedQuantity", "shortageQuantity", "assignedResources", "exactAssignedAssets", "missingAssignment", "allocationConflict" ] }, "BookingFulfillmentDemandReportDto": { "type": "object", "properties": { "generatedAt": { "format": "date-time", "type": "string" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "rangeDimension": { "type": "string", "enum": [ "AVAILABILITY_WINDOW", "FULFILLMENT_MILESTONE", "BOOKING_START", "DOCUMENT_DUE_OR_EXPIRY" ], "description": "FULFILLMENT_MILESTONE selects bookings whose service window overlaps the half-open range or whose shared outbound/inbound due milestone falls inside it." }, "truncated": { "type": "boolean" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BookingFulfillmentDemandReportRowDto" } } }, "required": [ "generatedAt", "from", "to", "rangeDimension", "truncated", "rows" ] }, "BookingCurrencyRevenueTotalDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO-4217 currency code stored on shared Sales." }, "revenueInCents": { "type": "integer", "format": "int32" } }, "required": [ "currency", "revenueInCents" ] }, "BookingLifecycleRevenueReportRowDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "serviceName": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "revenueBasis": { "type": "string", "enum": [ "BOOKED_ORDER", "FINALIZED_INVOICE", "CASH_PAYMENT" ] }, "revenueInCents": { "type": "integer", "format": "int32" }, "balanceDueInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "nullable": true }, "currency": { "type": "string", "nullable": true } }, "required": [ "bookingId", "serviceId", "serviceName", "status", "approvalStatus", "startsAt", "endsAt", "revenueBasis", "revenueInCents", "balanceDueInCents", "paymentStatus", "currency" ] }, "BookingLifecycleRevenueReportDto": { "type": "object", "properties": { "generatedAt": { "format": "date-time", "type": "string" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "rangeDimension": { "type": "string", "enum": [ "AVAILABILITY_WINDOW", "FULFILLMENT_MILESTONE", "BOOKING_START", "DOCUMENT_DUE_OR_EXPIRY" ] }, "revenueBasis": { "type": "string", "enum": [ "BOOKED_ORDER", "FINALIZED_INVOICE", "CASH_PAYMENT" ] }, "truncated": { "type": "boolean" }, "bookingCount": { "type": "integer", "format": "int32", "minimum": 0 }, "cancelledCount": { "type": "integer", "format": "int32", "minimum": 0 }, "declinedCount": { "type": "integer", "format": "int32", "minimum": 0 }, "completedCount": { "type": "integer", "format": "int32", "minimum": 0 }, "currency": { "type": "string", "nullable": true, "description": "The sole row currency when all money-bearing rows share one currency; null for empty or mixed-currency results." }, "totalRevenueInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "Safe single-currency total; null for empty or mixed-currency results. Use currencyTotals for the complete aggregate." }, "currencyTotals": { "type": "array", "items": { "$ref": "#/components/schemas/BookingCurrencyRevenueTotalDto" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BookingLifecycleRevenueReportRowDto" } } }, "required": [ "generatedAt", "from", "to", "rangeDimension", "revenueBasis", "truncated", "bookingCount", "cancelledCount", "declinedCount", "completedCount", "currency", "totalRevenueInCents", "currencyTotals", "rows" ] }, "BookingDocumentPaymentAgingReportRowDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "documentType": { "type": "string", "enum": [ "QUOTE", "INVOICE", "CONTRACT", "BOOKING_ACTION" ] }, "documentId": { "type": "string", "format": "uuid" }, "displayNumber": { "type": "string", "nullable": true }, "commerceRecordType": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ], "nullable": true }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ], "nullable": true }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "dueOrExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "ageDays": { "type": "integer", "format": "int32", "nullable": true }, "balanceDueInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "currency": { "type": "string", "nullable": true }, "agingStatus": { "type": "string", "enum": [ "OPEN", "DUE_SOON", "OVERDUE", "COMPLETE" ] }, "openActionLinkCount": { "type": "integer", "format": "int32", "minimum": 0 }, "accepted": { "type": "boolean" }, "signed": { "type": "boolean" } }, "required": [ "bookingId", "serviceId", "documentType", "documentId", "displayNumber", "commerceRecordType", "commercialStatus", "paymentStatus", "sentAt", "dueOrExpiresAt", "ageDays", "balanceDueInCents", "currency", "agingStatus", "openActionLinkCount", "accepted", "signed" ] }, "BookingDocumentPaymentAgingReportDto": { "type": "object", "properties": { "generatedAt": { "format": "date-time", "type": "string" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "rangeDimension": { "type": "string", "enum": [ "AVAILABILITY_WINDOW", "FULFILLMENT_MILESTONE", "BOOKING_START", "DOCUMENT_DUE_OR_EXPIRY" ] }, "truncated": { "type": "boolean" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BookingDocumentPaymentAgingReportRowDto" } } }, "required": [ "generatedAt", "from", "to", "rangeDimension", "truncated", "rows" ] }, "MerchantAgreementTargetResponseDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "COMMERCE_RECORD", "COMMERCE_REVISION", "BOOKING", "BOOKING_GROUP" ] }, "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "customerName": { "type": "string", "nullable": true } }, "required": [ "kind", "id", "label", "customerId", "customerName" ] }, "MerchantAgreementSubjectMemberResponseDto": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0 }, "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "ordinal", "serviceId", "serviceName", "startsAt", "endsAt", "quantity" ] }, "MerchantAgreementSatisfactionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "executionId": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "NATIVE_EXECUTION", "VERIFIED_EXTERNAL" ] }, "satisfiedAt": { "format": "date-time", "type": "string" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "executionId", "source", "satisfiedAt", "revokedAt" ] }, "MerchantAgreementRequirementResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requirementKey": { "type": "string" }, "policyVersion": { "type": "string" }, "state": { "type": "string", "enum": [ "ACTIVE", "WAIVED", "VOIDED", "EXPIRED", "REPLACED" ] }, "gateActions": { "type": "array", "items": { "type": "string", "enum": [ "QUOTE_ACCEPTANCE", "BOOKING_REQUEST", "BOOKING_APPROVAL", "BOOKING_CONFIRMATION", "FULFILLMENT_HANDOFF" ] } }, "acceptedOrigins": { "type": "array", "items": { "type": "string", "enum": [ "NATIVE", "EXTERNAL" ] } }, "requiredRoles": { "type": "array", "items": { "type": "string" } }, "satisfied": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "stateChangedAt": { "format": "date-time", "type": "string" }, "satisfactions": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementSatisfactionResponseDto" } } }, "required": [ "id", "requirementKey", "policyVersion", "state", "gateActions", "acceptedOrigins", "requiredRoles", "satisfied", "createdAt", "stateChangedAt", "satisfactions" ] }, "MerchantAgreementParticipantResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "roleKey": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "COMPLETED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "name": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "roleKey", "state", "name", "completedAt" ] }, "MerchantAgreementArtifactSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "RENDERED_PDF", "EXECUTED_PDF", "EXTERNAL_ORIGINAL", "EXECUTION_CERTIFICATE", "SAFE_PREVIEW" ] }, "safetyStatus": { "type": "string", "enum": [ "PENDING_SCAN", "SAFE", "QUARANTINED", "REJECTED", "DESTROYED" ] }, "sizeBytes": { "type": "integer", "format": "int64" }, "destroyedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "safetyStatus", "sizeBytes", "destroyedAt", "createdAt" ] }, "MerchantAgreementVerificationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "VERIFIED", "REJECTED", "INSUFFICIENT", "REVOKED" ] }, "method": { "type": "string" }, "reason": { "type": "string" }, "previousDecisionId": { "type": "string", "format": "uuid", "nullable": true }, "decidedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "decision", "method", "reason", "previousDecisionId", "decidedAt" ] }, "MerchantAgreementEventResponseDto": { "type": "object", "properties": { "eventType": { "type": "string" }, "actorType": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "occurredAt": { "format": "date-time", "type": "string" } }, "required": [ "eventType", "actorType", "reason", "occurredAt" ] }, "MerchantAgreementExecutionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "NATIVE", "EXTERNAL", "LEGACY_LITECOMMERCE" ] }, "state": { "type": "string", "enum": [ "DRAFT", "ISSUED", "IN_PROGRESS", "EXECUTED", "DECLINED", "EXPIRED", "VOIDED", "REPLACED" ] }, "agreementRevisionId": { "type": "string", "format": "uuid", "nullable": true }, "revisionNumber": { "type": "number", "nullable": true }, "title": { "type": "string", "nullable": true }, "sourceSystem": { "type": "string", "nullable": true }, "displayNumber": { "type": "string", "nullable": true }, "termsVersion": { "type": "string", "nullable": true }, "issuedAt": { "type": "string", "format": "date-time", "nullable": true }, "executedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementParticipantResponseDto" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementArtifactSummaryResponseDto" } }, "verifications": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementVerificationResponseDto" } }, "satisfactions": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementSatisfactionResponseDto" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementEventResponseDto" } } }, "required": [ "id", "origin", "state", "agreementRevisionId", "revisionNumber", "title", "sourceSystem", "displayNumber", "termsVersion", "issuedAt", "executedAt", "expiresAt", "createdAt", "participants", "artifacts", "verifications", "satisfactions", "events" ] }, "MerchantAgreementCommerceLinkResponseDto": { "type": "object", "properties": { "commerceRecordId": { "type": "string", "format": "uuid" }, "commerceRecordRevisionId": { "type": "string", "format": "uuid", "nullable": true }, "displayNumber": { "type": "string", "nullable": true } }, "required": [ "commerceRecordId", "commerceRecordRevisionId", "displayNumber" ] }, "MerchantAgreementSubjectResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "COMMERCE_RECORD", "COMMERCE_REVISION", "BOOKING", "BOOKING_GROUP" ] }, "label": { "type": "string" }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementSubjectMemberResponseDto" } }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementRequirementResponseDto" } }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementExecutionResponseDto" } }, "commerceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementCommerceLinkResponseDto" } } }, "required": [ "id", "kind", "label", "customerId", "createdAt", "members", "requirements", "executions", "commerceLinks" ] }, "MerchantAgreementWorkspaceResponseDto": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/MerchantAgreementTargetResponseDto" }, "subjects": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAgreementSubjectResponseDto" } } }, "required": [ "target", "subjects" ] }, "AttachMerchantAgreementRequirementDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "COMMERCE_RECORD", "COMMERCE_REVISION", "BOOKING", "BOOKING_GROUP" ] }, "targetId": { "type": "string", "format": "uuid" }, "requirementKey": { "type": "string", "example": "customer-terms" }, "policyVersion": { "type": "string", "example": "customer-terms/v1" }, "gateActions": { "type": "array", "description": "Named non-payment actions this requirement gates. An empty list records supporting evidence without gating a command.", "items": { "type": "string", "enum": [ "QUOTE_ACCEPTANCE", "BOOKING_REQUEST", "BOOKING_APPROVAL", "BOOKING_CONFIRMATION", "FULFILLMENT_HANDOFF" ] } }, "acceptedOrigins": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": [ "NATIVE", "EXTERNAL" ] } }, "requiredRoles": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": [ "customer", "merchant" ] } }, "acceptedTermsVersions": { "maxItems": 50, "description": "Exact lower-case terms versions accepted from outside evidence. Required when EXTERNAL is accepted.", "type": "array", "items": { "type": "string" } }, "acceptedSourceSystems": { "type": "array", "maxItems": 6, "description": "Outside systems whose verified evidence may satisfy this requirement. Required when EXTERNAL is accepted.", "items": { "type": "string", "enum": [ "booqable", "wet-signed", "docusign", "pandadoc", "authentisign", "other-external" ] } }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "targetId", "requirementKey", "policyVersion", "gateActions", "acceptedOrigins", "requiredRoles", "acceptedTermsVersions", "acceptedSourceSystems", "idempotencyKey", "reason" ] }, "AttachMerchantAgreementRequirementResponseDto": { "type": "object", "properties": { "subjectId": { "type": "string", "format": "uuid" }, "requirement": { "$ref": "#/components/schemas/MerchantAgreementRequirementResponseDto" } }, "required": [ "subjectId", "requirement" ] }, "WaiveAgreementRequirementDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "idempotencyKey", "reason" ] }, "AgreementRequirementWaiverResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subjectId": { "type": "string", "format": "uuid" }, "requirementKey": { "type": "string" }, "policyVersion": { "type": "string" }, "gateActions": { "type": "array", "items": { "type": "string", "enum": [ "QUOTE_ACCEPTANCE", "BOOKING_REQUEST", "BOOKING_APPROVAL", "BOOKING_CONFIRMATION", "FULFILLMENT_HANDOFF" ] } }, "state": { "type": "string", "enum": [ "WAIVED" ] }, "stateChangedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "subjectId", "requirementKey", "policyVersion", "gateActions", "state", "stateChangedAt" ] }, "AgreementContentSectionDto": { "type": "object", "properties": { "heading": { "type": "string", "maxLength": 500 }, "paragraphs": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 40000 } } }, "required": [ "paragraphs" ] }, "AgreementContentDto": { "type": "object", "properties": { "schemaVersion": { "type": "string", "enum": [ "agreement-content/v1" ] }, "title": { "type": "string", "maxLength": 240 }, "sections": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/AgreementContentSectionDto" } } }, "required": [ "schemaVersion", "title", "sections" ] }, "AgreementTemplateVersionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "templateId": { "type": "string", "format": "uuid" }, "versionNumber": { "type": "number" }, "contentSchemaVersion": { "type": "string" }, "content": { "$ref": "#/components/schemas/AgreementContentDto" }, "mergeFields": { "type": "array", "items": { "type": "string" } }, "templateSha256": { "type": "string" }, "reason": { "type": "object", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "templateId", "versionNumber", "contentSchemaVersion", "content", "mergeFields", "templateSha256", "createdAt" ] }, "AgreementTemplateResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "templateKey": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "object", "nullable": true }, "archivedAt": { "type": "object", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "latestVersion": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AgreementTemplateVersionResponseDto" } ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementTemplateVersionResponseDto" } } }, "required": [ "id", "templateKey", "name", "createdAt", "updatedAt" ] }, "CreateAgreementTemplateDto": { "type": "object", "properties": { "templateKey": { "type": "string", "example": "standard-rental" }, "name": { "type": "string", "example": "Standard rental agreement" }, "description": { "type": "string", "nullable": true } }, "required": [ "templateKey", "name" ] }, "UpdateAgreementTemplateDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated rental agreement" }, "description": { "type": "object", "nullable": true } } }, "AppendAgreementTemplateVersionDto": { "type": "object", "properties": { "content": { "description": "Exact agreement-content/v1 document. Only the server merge-field allowlist is accepted.", "allOf": [ { "$ref": "#/components/schemas/AgreementContentDto" } ] }, "reason": { "type": "string", "description": "Operator-authored reason for the new immutable version." } }, "required": [ "content" ] }, "AgreementDisclosureVersionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "disclosureKey": { "type": "string" }, "versionNumber": { "type": "number" }, "title": { "type": "string" }, "contentSchemaVersion": { "type": "string" }, "content": { "$ref": "#/components/schemas/AgreementContentDto" }, "disclosureSha256": { "type": "string" }, "approvedAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "disclosureKey", "versionNumber", "title", "contentSchemaVersion", "content", "disclosureSha256", "approvedAt", "createdAt" ] }, "AppendAgreementDisclosureVersionDto": { "type": "object", "properties": { "disclosureKey": { "type": "string", "example": "electronic-record-consent" }, "content": { "description": "Exact agreement-content/v1 disclosure text.", "allOf": [ { "$ref": "#/components/schemas/AgreementContentDto" } ] } }, "required": [ "disclosureKey", "content" ] }, "PreviewAgreementTemplateDto": { "type": "object", "properties": { "subjectId": { "type": "string", "format": "uuid" }, "templateVersionId": { "type": "string", "format": "uuid" } }, "required": [ "subjectId", "templateVersionId" ] }, "AgreementPreviewResponseDto": { "type": "object", "properties": { "templateVersionId": { "type": "string", "format": "uuid" }, "templateVersionNumber": { "type": "number" }, "templateSha256": { "type": "string" }, "resolvedContent": { "$ref": "#/components/schemas/AgreementContentDto" }, "contentSha256": { "type": "string" }, "contextSha256": { "type": "string" }, "resolvedMergeFields": { "type": "array", "items": { "type": "string" } }, "html": { "type": "string" } }, "required": [ "templateVersionId", "templateVersionNumber", "templateSha256", "resolvedContent", "contentSha256", "contextSha256", "resolvedMergeFields", "html" ] }, "AgreementRevisionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subjectId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "number" }, "state": { "type": "string", "enum": [ "DRAFT", "ISSUED", "SUPERSEDED", "VOIDED" ] }, "templateVersionId": { "type": "object", "format": "uuid", "nullable": true }, "templateVersionNumber": { "type": "object", "nullable": true }, "templateSha256": { "type": "object", "nullable": true }, "disclosureVersionId": { "type": "object", "format": "uuid", "nullable": true }, "disclosureVersionNumber": { "type": "object", "nullable": true }, "disclosureSha256": { "type": "object", "nullable": true }, "title": { "type": "object", "nullable": true }, "contentSchemaVersion": { "type": "string" }, "content": { "description": "Exact canonical agreement-content/v1 terms for issued native revisions; draft and imported legacy history can carry a noncanonical object.", "oneOf": [ { "$ref": "#/components/schemas/AgreementContentDto" }, { "type": "object", "additionalProperties": true } ] }, "contentSha256": { "type": "object", "nullable": true }, "contextSha256": { "type": "object", "nullable": true }, "renderSchemaVersion": { "type": "object", "nullable": true }, "renderedHtml": { "type": "object", "nullable": true }, "retentionPolicyVersion": { "type": "object", "nullable": true }, "predecessorRevisionId": { "type": "object", "format": "uuid", "nullable": true }, "reissueReason": { "type": "object", "nullable": true }, "issuedAt": { "type": "object", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "subjectId", "revisionNumber", "state", "contentSchemaVersion", "content", "createdAt" ] }, "AgreementArtifactGrantDto": { "type": "object", "properties": { "expiresInSeconds": { "type": "number", "default": 300, "minimum": 1, "maximum": 300 } } }, "AgreementArtifactGrantResponseDto": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "url", "expiresAt" ] }, "CustomerAgreementRequirementResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subjectId": { "type": "string", "format": "uuid" }, "requirementKey": { "type": "string" }, "policyVersion": { "type": "string" }, "state": { "type": "string", "enum": [ "ACTIVE", "WAIVED", "VOIDED", "EXPIRED", "REPLACED" ] }, "gateActions": { "type": "array", "items": { "type": "string", "enum": [ "QUOTE_ACCEPTANCE", "BOOKING_REQUEST", "BOOKING_APPROVAL", "BOOKING_CONFIRMATION", "FULFILLMENT_HANDOFF" ] } }, "satisfied": { "type": "boolean" }, "satisfyingExecutionId": { "type": "string", "nullable": true, "format": "uuid" }, "satisfactionSource": { "type": "string", "enum": [ "NATIVE_EXECUTION", "VERIFIED_EXTERNAL" ], "nullable": true }, "satisfiedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "subjectId", "requirementKey", "policyVersion", "state", "gateActions", "satisfied", "satisfyingExecutionId", "satisfactionSource", "satisfiedAt" ] }, "CustomerAgreementSubjectMemberResponseDto": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0 }, "serviceName": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "ordinal", "serviceName", "startsAt", "endsAt", "quantity" ] }, "CustomerAgreementSubjectResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "COMMERCE_RECORD", "COMMERCE_REVISION", "BOOKING", "BOOKING_GROUP" ] }, "label": { "type": "string" }, "bookingGroupPublicRef": { "type": "string", "nullable": true, "pattern": "^b[a-z0-9]{25}$", "description": "Non-authorizing public booking-group reference when this subject covers a group." }, "bookingGroupStatus": { "type": "string", "nullable": true }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAgreementSubjectMemberResponseDto" } } }, "required": [ "id", "kind", "label", "bookingGroupPublicRef", "bookingGroupStatus", "members" ] }, "CustomerAgreementNativeBindingResponseDto": { "type": "object", "properties": { "agreementRevisionId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "number" }, "templateSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "disclosureVersionNumber": { "type": "number" }, "disclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "agreementRevisionId", "revisionNumber", "templateSha256", "contentSha256", "disclosureVersionNumber", "disclosureSha256" ] }, "CustomerAgreementParticipantResponseDto": { "type": "object", "properties": { "roleKey": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "COMPLETED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "name": { "type": "string", "nullable": true }, "shownAt": { "type": "string", "nullable": true, "format": "date-time" }, "acceptedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "roleKey", "state", "name", "shownAt", "acceptedAt", "completedAt" ] }, "CustomerAgreementArtifactResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "RENDERED_PDF", "EXECUTED_PDF", "EXTERNAL_ORIGINAL", "EXECUTION_CERTIFICATE", "SAFE_PREVIEW" ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "format": "int64" }, "available": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "sha256", "sizeBytes", "available", "createdAt" ] }, "CustomerAgreementExecutionActionsResponseDto": { "type": "object", "properties": { "canSign": { "type": "boolean" }, "canDecline": { "type": "boolean" } }, "required": [ "canSign", "canDecline" ] }, "CustomerAgreementExecutionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "NATIVE", "EXTERNAL", "LEGACY_LITECOMMERCE" ] }, "state": { "type": "string", "enum": [ "DRAFT", "ISSUED", "IN_PROGRESS", "EXECUTED", "DECLINED", "EXPIRED", "VOIDED", "REPLACED" ] }, "title": { "type": "string" }, "subject": { "$ref": "#/components/schemas/CustomerAgreementSubjectResponseDto" }, "nativeBinding": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CustomerAgreementNativeBindingResponseDto" } ] }, "sourceSystem": { "type": "string", "nullable": true }, "sourceLabel": { "type": "string", "nullable": true }, "displayNumber": { "type": "string", "nullable": true }, "termsVersion": { "type": "string", "nullable": true }, "verificationStatus": { "type": "string", "enum": [ "NOT_APPLICABLE", "UNVERIFIED", "VERIFIED", "REJECTED", "INSUFFICIENT", "REVOKED" ] }, "issuedAt": { "type": "string", "nullable": true, "format": "date-time" }, "executedAt": { "type": "string", "nullable": true, "format": "date-time" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAgreementParticipantResponseDto" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAgreementArtifactResponseDto" } }, "satisfiesRequirementIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "actions": { "$ref": "#/components/schemas/CustomerAgreementExecutionActionsResponseDto" } }, "required": [ "id", "origin", "state", "title", "subject", "nativeBinding", "sourceSystem", "sourceLabel", "displayNumber", "termsVersion", "verificationStatus", "issuedAt", "executedAt", "expiresAt", "createdAt", "participants", "artifacts", "satisfiesRequirementIds", "actions" ] }, "CustomerAgreementHistoryResponseDto": { "type": "object", "properties": { "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAgreementRequirementResponseDto" } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAgreementExecutionResponseDto" } }, "nextCursor": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "requirements", "data", "nextCursor" ] }, "CustomerExternalAgreementArtifactGrantDto": { "type": "object", "properties": { "expiresInSeconds": { "type": "number", "default": 60, "minimum": 1, "maximum": 60 } } }, "ExternalAgreementDownloadDto": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "url", "expiresAt" ] }, "ExternalAgreementSignerDto": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "role", "name", "completedAt" ] }, "ExternalAgreementArtifactDto": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "RENDERED_PDF", "EXECUTED_PDF", "EXTERNAL_ORIGINAL", "EXECUTION_CERTIFICATE", "SAFE_PREVIEW" ] }, "safetyStatus": { "type": "string", "enum": [ "PENDING_SCAN", "SAFE", "QUARANTINED", "REJECTED", "DESTROYED" ] }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "retentionPolicyVersion": { "type": "string", "description": "Current policy version a governed destruction request must bind exactly." }, "destroyedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "safetyStatus", "sha256", "sizeBytes", "retentionPolicyVersion", "destroyedAt", "createdAt" ] }, "ExternalAgreementVerificationDto": { "type": "object", "properties": { "id": { "type": "string" }, "decision": { "type": "string", "enum": [ "VERIFIED", "REJECTED", "INSUFFICIENT", "REVOKED" ] }, "method": { "type": "string" }, "actorType": { "type": "string" }, "actorId": { "type": "string", "nullable": true }, "reason": { "type": "string" }, "decidedAt": { "format": "date-time", "type": "string" }, "previousDecisionId": { "type": "string", "nullable": true } }, "required": [ "id", "decision", "method", "actorType", "actorId", "reason", "decidedAt", "previousDecisionId" ] }, "ExternalAgreementSatisfactionDto": { "type": "object", "properties": { "id": { "type": "string" }, "requirementId": { "type": "string" }, "verificationDecisionId": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "NATIVE_EXECUTION", "VERIFIED_EXTERNAL" ] }, "satisfiedAt": { "format": "date-time", "type": "string" }, "actorType": { "type": "string" }, "actorId": { "type": "string", "nullable": true }, "reason": { "type": "string" }, "revokedAt": { "type": "string", "nullable": true, "format": "date-time" }, "revokedByType": { "type": "string", "nullable": true }, "revokedById": { "type": "string", "nullable": true }, "revocationReason": { "type": "string", "nullable": true } }, "required": [ "id", "requirementId", "verificationDecisionId", "source", "satisfiedAt", "actorType", "actorId", "reason", "revokedAt", "revokedByType", "revokedById", "revocationReason" ] }, "ExternalAgreementDto": { "type": "object", "properties": { "id": { "type": "string" }, "subjectId": { "type": "string" }, "sourceSystem": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "displayNumber": { "type": "string", "nullable": true }, "importBatchId": { "type": "string", "nullable": true }, "importRowKey": { "type": "string", "nullable": true }, "sourceStatus": { "type": "string", "nullable": true }, "termsVersion": { "type": "string", "nullable": true }, "signedAt": { "format": "date-time", "type": "string" }, "countersignedAt": { "type": "string", "nullable": true, "format": "date-time" }, "attachmentStatus": { "type": "string", "enum": [ "PENDING", "ATTACHED" ] }, "attachedAt": { "type": "string", "nullable": true, "format": "date-time" }, "attachedByType": { "type": "string", "nullable": true }, "attachedById": { "type": "string", "nullable": true }, "attachmentReason": { "type": "string", "nullable": true }, "executedAt": { "format": "date-time", "type": "string" }, "notes": { "type": "string", "nullable": true }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAgreementSignerDto" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAgreementArtifactDto" } }, "verifications": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAgreementVerificationDto" } }, "satisfactions": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAgreementSatisfactionDto" } } }, "required": [ "id", "subjectId", "sourceSystem", "externalId", "displayNumber", "importBatchId", "importRowKey", "sourceStatus", "termsVersion", "signedAt", "countersignedAt", "attachmentStatus", "attachedAt", "attachedByType", "attachedById", "attachmentReason", "executedAt", "notes", "signers", "artifacts", "verifications", "satisfactions" ] }, "ExternalAgreementListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAgreementDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "ExternalAgreementDecisionDto": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "VERIFIED", "REJECTED", "INSUFFICIENT" ] }, "method": { "type": "string", "enum": [ "manual-document-review", "provider-audit-certificate" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "decision", "method", "reason", "idempotencyKey" ] }, "SatisfyExternalAgreementRequirementDto": { "type": "object", "properties": { "requirementId": { "type": "string" }, "verificationDecisionId": { "type": "string" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "requirementId", "verificationDecisionId", "reason" ] }, "RevokeExternalAgreementVerificationDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "reason", "idempotencyKey" ] }, "DestroyExternalAgreementArtifactDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "disposition": { "type": "string", "enum": [ "RETENTION_EXPIRED", "PRIVACY_ERASURE", "TENANT_OFFBOARDING", "AUTHORIZED_EVIDENCE_DESTRUCTION" ] }, "authorizationReference": { "type": "string", "description": "Bounded case, approval, erasure, or offboarding reference authorizing this irreversible action.", "minLength": 1, "maxLength": 500 }, "expectedRetentionPolicyVersion": { "type": "string", "description": "Exact retained policy version reviewed by the authorizer. A stale value fails closed.", "minLength": 1, "maxLength": 128 } }, "required": [ "reason", "idempotencyKey", "disposition", "authorizationReference", "expectedRetentionPolicyVersion" ] }, "ExternalAgreementArtifactDestructionDto": { "type": "object", "properties": { "executionId": { "type": "string" }, "artifactId": { "type": "string" }, "safetyStatus": { "type": "string", "enum": [ "DESTROYED" ] }, "disposition": { "type": "string", "enum": [ "RETENTION_EXPIRED", "PRIVACY_ERASURE", "TENANT_OFFBOARDING", "AUTHORIZED_EVIDENCE_DESTRUCTION" ] }, "retentionPolicyVersion": { "type": "string" }, "requestedAt": { "format": "date-time", "type": "string" }, "destroyedAt": { "format": "date-time", "type": "string" } }, "required": [ "executionId", "artifactId", "safetyStatus", "disposition", "retentionPolicyVersion", "requestedAt", "destroyedAt" ] }, "NativeAgreementRevisionBindingDto": { "type": "object", "properties": { "templateVersionId": { "type": "string", "format": "uuid" }, "expectedTemplateSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optional compare-and-bind expectation. The server computes and returns the authoritative template digest." }, "disclosureVersionId": { "type": "string", "format": "uuid" }, "expectedDisclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optional compare-and-bind expectation. The server computes and returns the authoritative disclosure digest." } }, "required": [ "templateVersionId", "disclosureVersionId" ] }, "NativeAgreementCustomerSignerDto": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "participantKey": { "type": "string", "default": "customer", "maxLength": 128, "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" } }, "required": [ "customerId" ] }, "NativeAgreementMerchantCountersignerDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "description": "Tenant member user identity. The server resolves membership and snapshots the signer; the request cannot supply identity evidence." }, "participantKey": { "type": "string", "default": "merchant", "maxLength": 128, "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" } }, "required": [ "userId" ] }, "CreateNativeAgreementExecutionDto": { "type": "object", "properties": { "subjectId": { "type": "string", "format": "uuid" }, "binding": { "$ref": "#/components/schemas/NativeAgreementRevisionBindingDto" }, "customerSigner": { "$ref": "#/components/schemas/NativeAgreementCustomerSignerDto" }, "merchantCountersigner": { "$ref": "#/components/schemas/NativeAgreementMerchantCountersignerDto" }, "requirementId": { "type": "string", "format": "uuid", "description": "One exact ACTIVE requirement this execution may satisfy after complete native execution. Omission creates supporting evidence only." }, "retentionPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "expiresAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "subjectId", "binding", "customerSigner", "retentionPolicyVersion", "idempotencyKey" ] }, "NativeAgreementRevisionBindingResponseDto": { "type": "object", "properties": { "agreementRevisionId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "number" }, "templateVersionId": { "type": "string", "format": "uuid" }, "templateVersionNumber": { "type": "number" }, "templateSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "disclosureVersionId": { "type": "string", "format": "uuid" }, "disclosureVersionNumber": { "type": "number" }, "disclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "agreementRevisionId", "revisionNumber", "templateVersionId", "templateVersionNumber", "templateSha256", "contentSha256", "disclosureVersionId", "disclosureVersionNumber", "disclosureSha256" ] }, "NativeAgreementParticipantResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "participantKey": { "type": "string" }, "roleKey": { "type": "string" }, "routingOrder": { "type": "number" }, "required": { "type": "boolean" }, "state": { "type": "string", "enum": [ "PENDING", "COMPLETED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "name": { "type": "string", "nullable": true }, "authenticationMethod": { "type": "string", "nullable": true }, "shownAt": { "type": "string", "nullable": true, "format": "date-time" }, "acceptedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "participantKey", "roleKey", "routingOrder", "required", "state", "name", "authenticationMethod", "shownAt", "acceptedAt", "completedAt" ] }, "NativeAgreementArtifactResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "EXECUTED_PDF", "EXECUTION_CERTIFICATE" ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "format": "int64" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "sha256", "sizeBytes", "createdAt" ] }, "NativeAgreementLifecycleEventResponseDto": { "type": "object", "properties": { "eventType": { "type": "string" }, "actorType": { "type": "string" }, "participantId": { "type": "string", "nullable": true, "format": "uuid" }, "occurredAt": { "format": "date-time", "type": "string" } }, "required": [ "eventType", "actorType", "participantId", "occurredAt" ] }, "NativeAgreementExecutionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subjectId": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "NATIVE" ] }, "state": { "type": "string", "enum": [ "DRAFT", "ISSUED", "IN_PROGRESS", "EXECUTED", "DECLINED", "EXPIRED", "VOIDED", "REPLACED" ] }, "binding": { "$ref": "#/components/schemas/NativeAgreementRevisionBindingResponseDto" }, "predecessorExecutionId": { "type": "string", "nullable": true, "format": "uuid" }, "replacementExecutionId": { "type": "string", "nullable": true, "format": "uuid" }, "issuedAt": { "type": "string", "nullable": true, "format": "date-time" }, "executedAt": { "type": "string", "nullable": true, "format": "date-time" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/NativeAgreementParticipantResponseDto" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/NativeAgreementArtifactResponseDto" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/NativeAgreementLifecycleEventResponseDto" } } }, "required": [ "id", "subjectId", "origin", "state", "binding", "predecessorExecutionId", "replacementExecutionId", "issuedAt", "executedAt", "expiresAt", "createdAt", "participants", "artifacts", "events" ] }, "NativeAgreementExecutionListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "NativeAgreementReasonedCommandDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "idempotencyKey", "reason" ] }, "NativeAgreementPresentedTermsDto": { "type": "object", "properties": { "revisionId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "number" }, "title": { "type": "string" }, "contentSchemaVersion": { "type": "string" }, "content": { "$ref": "#/components/schemas/AgreementContentDto" }, "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "renderSchemaVersion": { "type": "string" }, "renderedHtml": { "type": "string" } }, "required": [ "revisionId", "revisionNumber", "title", "contentSchemaVersion", "content", "contentSha256", "renderSchemaVersion", "renderedHtml" ] }, "NativeAgreementPresentedDisclosureDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "disclosureKey": { "type": "string" }, "versionNumber": { "type": "number" }, "title": { "type": "string" }, "contentSchemaVersion": { "type": "string" }, "content": { "$ref": "#/components/schemas/AgreementContentDto" }, "disclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "disclosureKey", "versionNumber", "title", "contentSchemaVersion", "content", "disclosureSha256" ] }, "NativeAgreementAcceptanceRequirementsDto": { "type": "object", "properties": { "agreementAcceptanceRequired": { "type": "boolean", "enum": [ true ] }, "disclosureAcceptanceRequired": { "type": "boolean", "enum": [ true ] }, "typedSignerIdentityRequired": { "type": "boolean", "enum": [ true ] } }, "required": [ "agreementAcceptanceRequired", "disclosureAcceptanceRequired", "typedSignerIdentityRequired" ] }, "NativeAgreementPresentationResponseDto": { "type": "object", "properties": { "execution": { "$ref": "#/components/schemas/NativeAgreementExecutionResponseDto" }, "participant": { "$ref": "#/components/schemas/NativeAgreementParticipantResponseDto" }, "presentationEventId": { "type": "string", "format": "uuid" }, "presentedAt": { "format": "date-time", "type": "string" }, "agreement": { "$ref": "#/components/schemas/NativeAgreementPresentedTermsDto" }, "disclosure": { "$ref": "#/components/schemas/NativeAgreementPresentedDisclosureDto" }, "acceptanceRequirements": { "$ref": "#/components/schemas/NativeAgreementAcceptanceRequirementsDto" } }, "required": [ "execution", "participant", "presentationEventId", "presentedAt", "agreement", "disclosure", "acceptanceRequirements" ] }, "MerchantCountersignNativeAgreementDto": { "type": "object", "properties": { "presentationEventId": { "type": "string", "format": "uuid" }, "agreementRevisionId": { "type": "string", "format": "uuid" }, "agreementContentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "disclosureVersionId": { "type": "string", "format": "uuid" }, "disclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "agreementAccepted": { "type": "boolean", "enum": [ true ] }, "disclosureAccepted": { "type": "boolean", "enum": [ true ] }, "typedSignerName": { "type": "string", "minLength": 1, "maxLength": 200 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "presentationEventId", "agreementRevisionId", "agreementContentSha256", "disclosureVersionId", "disclosureSha256", "agreementAccepted", "disclosureAccepted", "typedSignerName", "idempotencyKey", "reason" ] }, "MerchantDeclineNativeAgreementDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "idempotencyKey", "reason" ] }, "ReissueNativeAgreementExecutionDto": { "type": "object", "properties": { "binding": { "$ref": "#/components/schemas/NativeAgreementRevisionBindingDto" }, "customerSigner": { "$ref": "#/components/schemas/NativeAgreementCustomerSignerDto" }, "merchantCountersigner": { "$ref": "#/components/schemas/NativeAgreementMerchantCountersignerDto" }, "requirementId": { "type": "string", "format": "uuid" }, "retentionPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "expiresAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "binding", "customerSigner", "retentionPolicyVersion", "idempotencyKey", "reason" ] }, "NativeAgreementArtifactGrantDto": { "type": "object", "properties": { "expiresInSeconds": { "type": "number", "default": 300, "minimum": 1, "maximum": 300 } } }, "NativeAgreementArtifactGrantResponseDto": { "type": "object", "properties": { "artifactId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "EXECUTED_PDF", "EXECUTION_CERTIFICATE" ] }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "artifactId", "kind", "url", "expiresAt" ] }, "SignNativeAgreementDto": { "type": "object", "properties": { "presentationEventId": { "type": "string", "format": "uuid" }, "agreementRevisionId": { "type": "string", "format": "uuid" }, "agreementContentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "disclosureVersionId": { "type": "string", "format": "uuid" }, "disclosureSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "agreementAccepted": { "type": "boolean", "enum": [ true ] }, "disclosureAccepted": { "type": "boolean", "enum": [ true ] }, "typedSignerName": { "type": "string", "minLength": 1, "maxLength": 200 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "presentationEventId", "agreementRevisionId", "agreementContentSha256", "disclosureVersionId", "disclosureSha256", "agreementAccepted", "disclosureAccepted", "typedSignerName", "idempotencyKey" ] }, "DeclineNativeAgreementDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "idempotencyKey" ] }, "CustomerAgreementActionContextResponseDto": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/CustomerAgreementSubjectResponseDto" }, "title": { "type": "string" }, "continuationStatus": { "type": "string", "enum": [ "NONE", "AWAITING_SIGNATURES", "READY_TO_RESUME", "HISTORY_ONLY" ] } }, "required": [ "subject", "title", "continuationStatus" ] }, "RequestLinkDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to send the passwordless login challenge to.", "maxLength": 254, "example": "alice@example.com" }, "returnTo": { "type": "string", "description": "Optional local return target for the emailed magic link. Only the fixed routed account destinations (`/account`, `/account/orders`, `/account/bookings`, `/account/agreements`, `/account/documents`, `/account/addresses`, `/account/payment-methods`, `/account/profile`) are honored. Order details accept only generated uppercase, dash-delimited numbers ending in a four-digit year and an at-least-three-digit sequence; an invalid detail segment normalizes to `/account/orders`. Document details accept only generated values that start with an uppercase letter, contain uppercase letters, digits, and dashes, and end in a numeric sequence; an invalid detail segment normalizes to `/account/documents`. Detail segments are limited to 128 characters. A hosted-checkout target is honored only for `/session/{token}` where the token is exactly `c` followed by 25 lowercase letters or digits; an invalid checkout-session target is omitted. The legacy `/account#bookings` anchor normalizes onto `/account/bookings`; only the routed bookings marker and bounded orders-list page are preserved from query input, while all other query and fragment state is removed server-side. Unrecognized, external, and oversized targets are omitted. Checkout-session targets are additionally dropped when the link is minted on a BYO customer-action origin (the session route only exists on the hosted origin).", "maxLength": 512, "example": "/account/orders/LC-2026-001" } }, "required": [ "email" ] }, "RequestChallengeResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Always present. Generic confirmation that, IF the address belongs to an account, a login email has been sent. Never reveals existence.", "example": "If an account exists for that email, a login link has been sent." } }, "required": [ "message" ] }, "VerifyDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Opaque magic-link token (from the emailed link).", "maxLength": 64 }, "email": { "type": "string", "description": "Email the OTP was issued to (required with `code`).", "maxLength": 254 }, "code": { "type": "string", "description": "Numeric OTP code (required with `email`).", "maxLength": 12 }, "orderReference": { "type": "string", "description": "Exact public order reference. Presence selects only the private ORDER_RECOVERY OTP lane; it never supplies authorization by itself.", "maxLength": 128, "pattern": "^or1_[0-9a-f]{32}$", "example": "or1_0123456789abcdef0123456789abcdef" }, "persistSession": { "type": "boolean", "description": "E28 (`DR-3340-10-C`) — the shopper's affirmative \"Keep me signed in on this browser\" choice. ONLY a literal `true` mints the persistent session windows (30-day idle / 365-day absolute); omitted or `false` always receives the default windows (6-hour idle / 24-hour absolute). The server never infers persistence from browser state." } }, "additionalProperties": false }, "VerifySessionResponseDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Opaque session bearer token. Send as `Authorization: Bearer ` on subsequent customer requests (BYO frontends). Also set as an httpOnly cookie for the hosted surface. Shown once; store securely." }, "expiresAt": { "type": "string", "description": "Absolute session expiry (ISO 8601), fixed at mint: 24 hours for a default session, 365 days when `persistSession: true` was accepted (`DR-3340-10-C`). The session is live only while BOTH this and `idleExpiresAt` hold.", "example": "2026-06-12T14:36:18.000Z" }, "idleExpiresAt": { "type": "string", "description": "Idle-window deadline (ISO 8601): 6 hours for a default session, 30 days when persistent. Slides forward on authenticated use, capped at `expiresAt`; the EFFECTIVE expiry is the earlier of the two.", "example": "2026-06-11T20:36:18.000Z" }, "persistent": { "type": "boolean", "description": "Whether the session was minted with the affirmative \"keep me signed in\" choice. Only a literal `persistSession: true` on verify produces `true` here." }, "customerId": { "type": "string", "description": "The authenticated customer id." } }, "required": [ "token", "expiresAt", "idleExpiresAt", "persistent", "customerId" ] }, "OrderRecoveryRequestDto": { "type": "object", "properties": { "orderReference": { "type": "string", "pattern": "^or1_[0-9a-f]{32}$", "maxLength": 128, "example": "or1_0123456789abcdef0123456789abcdef" }, "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "orderReference", "email" ], "additionalProperties": false }, "OrderRecoveryRequestResponseDto": { "type": "object", "properties": { "message": { "type": "string", "example": "If this order can be recovered, a sign-in message will be sent." } }, "required": [ "message" ] }, "PublicBookingFixedSlotDto": { "type": "object", "properties": { "label": { "type": "string", "example": "Morning" }, "startMinuteOfDay": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1439, "example": 540 }, "durationMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1440, "example": 180 } }, "required": [ "label", "startMinuteOfDay", "durationMinutes" ] }, "PublicBookingElapsedDurationRangeDto": { "type": "object", "properties": { "minimumElapsedMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 44640, "description": "Inclusive lower edge of this selectable elapsed-duration range." }, "maximumElapsedMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 44640, "description": "Inclusive upper edge of this selectable elapsed-duration range." } }, "required": [ "minimumElapsedMinutes", "maximumElapsedMinutes" ] }, "PublicBookingDurationRateTableEntryDto": { "type": "object", "properties": { "unitPriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Evaluated, non-authoritative per-unit total for every selectable elapsed-duration range in this entry." }, "elapsedDurationRanges": { "minItems": 1, "description": "Inclusive elapsed-minute ranges that select this rate. Discrete service options remain discrete rather than implying intervening durations are bookable.", "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingElapsedDurationRangeDto" } } }, "required": [ "unitPriceInCents", "elapsedDurationRanges" ] }, "PublicBookingServicePricingDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "FLAT_TIME", "FIXED_PRICE", "PRICING_STRUCTURE" ] }, "basis": { "type": "string", "enum": [ "RESERVED_WINDOW", "CHARGED_DURATION", "FIXED_PRICE" ] }, "basePriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Configured base price only." }, "pricingIntervalMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "description": "Minutes represented by one base-price unit for FLAT_TIME; null for fixed pricing." }, "currency": { "type": "string", "example": "USD" }, "authoritative": { "type": "boolean", "example": false, "description": "Always false in #640: checkout/shared commerce remains authoritative for final pricing." }, "fromPriceInCents": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0, "description": "ADR-043 reachable From price: the minimum evaluated per-unit total across the actual bookable-duration domain of the service, including the published minimum-then-grace transform - never the first stored rate band merely because it exists. Null when the service has no bookable-duration domain, when the pricing configuration cannot be evaluated, or on slot-level hooks (slots name their own concrete window). Not authoritative." }, "fromDurationMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "description": "The bookable-duration-domain minutes fromPriceInCents was evaluated at. Null exactly when fromPriceInCents is null." }, "durationRateTable": { "maxItems": 24, "description": "ADR-043 reachable duration-rate table. Each entry contains only an evaluated total and the actual bookable elapsed-duration ranges that select it; policy, revision, factor, band, minimum, and grace metadata are never exposed. Empty for scalar or unevaluable pricing.", "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingDurationRateTableEntryDto" } } }, "required": [ "mode", "basis", "basePriceInCents", "pricingIntervalMinutes", "currency", "authoritative", "fromPriceInCents", "fromDurationMinutes", "durationRateTable" ] }, "PublicBookingCheckoutPostureDto": { "type": "object", "properties": { "approvalMode": { "type": "string", "enum": [ "AUTO_CONFIRM", "MANUAL_APPROVAL" ] }, "paymentMode": { "type": "string", "enum": [ "PAY_LATER", "DEPOSIT_PERCENT", "FULL_PAYMENT" ] }, "paymentDepositPercent": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0, "maximum": 100 }, "securityDepositMode": { "type": "string", "enum": [ "NONE", "FIXED_AMOUNT", "PERCENTAGE_OF_ORDER", "PERCENTAGE_OF_RESOURCE_VALUES" ] }, "securityDepositAmountInCents": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "securityDepositPercent": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0, "maximum": 100 } }, "required": [ "approvalMode", "paymentMode", "paymentDepositPercent", "securityDepositMode", "securityDepositAmountInCents", "securityDepositPercent" ] }, "PublicBookingPackageComponentDto": { "type": "object", "properties": { "name": { "type": "string" }, "variantName": { "type": "string", "nullable": true }, "itemType": { "type": "string", "enum": [ "RENTAL", "SALE", "SERVICE" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Units included per one top-level package selection." }, "intrinsicSavingsBasisPoints": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "description": "Intrinsic package savings in basis points. External promotions are not included." } }, "required": [ "name", "variantName", "itemType", "quantity", "intrinsicSavingsBasisPoints" ] }, "PublicBookingPackageDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "revision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Definition revision clients must echo on availability and booking-group requests." }, "components": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingPackageComponentDto" } } }, "required": [ "kind", "revision", "components" ] }, "PublicBookingServiceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] }, "deliveryPosture": { "type": "string", "enum": [ "PICKUP_ONLY", "OPTIONAL", "REQUIRED" ] }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "durationMinutes": { "type": "integer", "format": "int32", "nullable": true }, "durationOptionsMinutes": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "fixedSlots": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingFixedSlotDto" } }, "timePickerIncrementMinutes": { "type": "integer", "format": "int32" }, "defaultStartMinuteOfDay": { "type": "integer", "format": "int32", "nullable": true }, "defaultEndMinuteOfDay": { "type": "integer", "format": "int32", "nullable": true }, "minPartySize": { "type": "integer", "format": "int32", "nullable": true }, "maxPartySize": { "type": "integer", "format": "int32", "nullable": true }, "timezone": { "type": "string" }, "leadTimeMinutes": { "type": "integer", "format": "int32" }, "maxAdvanceDays": { "type": "integer", "format": "int32", "nullable": true }, "pricing": { "$ref": "#/components/schemas/PublicBookingServicePricingDto" }, "checkout": { "$ref": "#/components/schemas/PublicBookingCheckoutPostureDto" }, "resourceSelectionRequired": { "type": "boolean", "description": "True when at least one requirement is explicitly customer-selectable. Options are returned per available slot." }, "package": { "nullable": true, "description": "Customer-safe package definition for one top-level selection. Capacity mappings and internal identifiers are omitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingPackageDto" } ] } }, "required": [ "id", "itemId", "slug", "name", "description", "bookingType", "deliveryPosture", "periodMode", "durationMinutes", "durationOptionsMinutes", "fixedSlots", "timePickerIncrementMinutes", "defaultStartMinuteOfDay", "defaultEndMinuteOfDay", "minPartySize", "maxPartySize", "timezone", "leadTimeMinutes", "maxAdvanceDays", "pricing", "checkout", "resourceSelectionRequired", "package" ] }, "PublicBookingServiceListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingServiceDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreatePublicBookingHoldDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "delivery": { "description": "Omitted or null means pickup.", "oneOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionInputDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1 }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "description": "Required for a package service. Must match the revision returned by the availability selection." }, "resourceSelections": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PublicBookingResourceSelectionDto" } }, "customerEmail": { "type": "string", "format": "email", "nullable": true, "maxLength": 320 }, "sessionId": { "type": "string", "nullable": true, "maxLength": 200, "description": "Non-secret storefront/checkout correlation id." } }, "required": [ "serviceId", "startsAt", "endsAt" ], "additionalProperties": false }, "PublicBookingHoldResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid" }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "delivery": { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" }, "status": { "type": "string", "enum": [ "ACTIVE", "CONSUMED", "EXPIRED", "CANCELLED" ] }, "expiresAt": { "format": "date-time", "type": "string" }, "serverTime": { "format": "date-time", "type": "string" }, "expiresInSeconds": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "id", "serviceId", "startsAt", "endsAt", "quantity", "delivery", "status", "expiresAt", "serverTime", "expiresInSeconds" ] }, "BookingDeliveryOriginAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 300, "example": "1120 S Rackham Way" }, "line2": { "type": "string", "maxLength": 300, "example": "Suite 300" }, "city": { "type": "string", "maxLength": 200, "example": "Meridian" }, "state": { "type": "string", "maxLength": 200, "example": "ID" }, "postalCode": { "type": "string", "maxLength": 32, "example": "83642" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US" } }, "required": [ "line1", "city", "state", "postalCode", "country" ] }, "BookingDeliveryRadiusBandResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "maxDistanceMeters": { "type": "number", "minimum": 1, "maximum": 1609344 }, "feeInCents": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "id", "label", "maxDistanceMeters", "feeInCents" ] }, "BookingDeliveryConfigurationResponseDto": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "revision": { "type": "number", "minimum": 0 }, "originAddress": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliveryOriginAddressDto" } ] }, "originPlaceId": { "type": "string", "nullable": true }, "originVerifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "bands": { "type": "array", "items": { "$ref": "#/components/schemas/BookingDeliveryRadiusBandResponseDto" } }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "enabled", "revision", "originAddress", "originPlaceId", "originVerifiedAt", "bands", "updatedAt" ] }, "BookingDeliveryRadiusBandInputDto": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Local delivery" }, "maxDistanceMeters": { "type": "number", "minimum": 1, "maximum": 1609344, "description": "Inclusive straight-line radius upper bound in integer meters (maximum 1,000 miles).", "example": 16093 }, "feeInCents": { "type": "number", "minimum": 0, "maximum": 1000000000, "description": "Delivery fee in integer cents. Zero creates a free-delivery band.", "example": 2500 } }, "required": [ "label", "maxDistanceMeters", "feeInCents" ] }, "UpdateBookingDeliveryConfigurationDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether booking delivery can be offered. Enabling requires a verified origin and at least one radius band." }, "originAddress": { "nullable": true, "description": "Merchant-entered delivery origin. Null is accepted only while disabled with no bands and clears the saved origin.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliveryOriginAddressDto" } ] }, "bands": { "maxItems": 50, "description": "Ordered radius bands. Bounds must be strictly increasing and unique.", "type": "array", "items": { "$ref": "#/components/schemas/BookingDeliveryRadiusBandInputDto" } } }, "required": [ "enabled", "originAddress", "bands" ] }, "BookingGeocodingProviderStatusDto": { "type": "object", "properties": { "connected": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "google" ], "example": "google" }, "keyMask": { "type": "string", "nullable": true, "example": "••••aB12" }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastVerifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "disabled": { "type": "boolean" }, "cipherConfigured": { "type": "boolean", "description": "Whether the server-side outbound-vendor credential cipher is configured." } }, "required": [ "connected", "provider", "keyMask", "connectedAt", "lastVerifiedAt", "disabled", "cipherConfigured" ] }, "ConnectBookingGeocodingProviderDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "apiKey": { "type": "string", "minLength": 20, "maxLength": 200, "writeOnly": true, "description": "The merchant's own Google Geocoding API key. Write-only; stored encrypted and never returned." } }, "required": [ "reason", "apiKey" ] }, "TestBookingGeocodingProviderResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean" }, "code": { "type": "string", "enum": [ "connection_disabled", "cipher_unavailable", "unauthorized", "rate_limit_exceeded", "timeout", "network", "provider_error", "zero_results", "ambiguous", "insufficient_precision" ], "nullable": true }, "message": { "type": "string", "nullable": true } }, "required": [ "ok" ] }, "CheckoutSupportPaymentAttemptDto": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "PAYMENT", "AUTHORIZATION", "SETUP", "REFUND" ] }, "status": { "type": "string", "enum": [ "REQUIRES_PAYMENT_METHOD", "REQUIRES_ACTION", "PROCESSING", "REQUIRES_CAPTURE", "SUCCEEDED", "FAILED", "CANCELLED" ] }, "amountInCents": { "type": "number" }, "currency": { "type": "string" }, "paymentContextType": { "type": "string", "nullable": true, "description": "Commercial context type for the attempt (for example checkout_session)." }, "paymentContextId": { "type": "string", "nullable": true, "description": "Commercial context id for the attempt. Current checkout attempts point at the checkout session id." }, "processor": { "type": "string" }, "processorObjectType": { "type": "string", "enum": [ "PAYMENT_INTENT", "CHECKOUT_SESSION", "SETUP_INTENT", "REFUND" ], "nullable": true }, "processorObjectId": { "type": "string", "nullable": true }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Connected account the provider object lives on, as persisted at create (#932). Null does NOT have a single meaning and must not be read as one. When processorObjectId is also null no provider object was ever created, so there is nowhere for it to live. When processorObjectId is present, null means the object was created on the litecommerce platform account rather than the tenant own account — possible for attempts predating the tenant connecting one, and the reason such an object is absent from the tenant provider dashboard. Use organizationHasConnectedAccount on the session detail to separate that from a tenant that has never connected an account at all, where null is simply normal." }, "processorStatus": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "status", "amountInCents", "currency", "processor", "stripeAccountId", "createdAt", "updatedAt" ] }, "CheckoutSupportSessionListItemDto": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ] }, "currency": { "type": "string" }, "customerEmail": { "type": "string", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "shippingInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "taxDisclosure": { "nullable": true, "description": "Merchant/support-safe disclosure when litecommerce did not calculate tax for this session/order (manual/no-tax mode).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "number" }, "isBinding": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "reservationExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "finalOrderId": { "type": "string", "nullable": true }, "finalOrderNumber": { "type": "string", "nullable": true }, "latestPaymentAttempt": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSupportPaymentAttemptDto" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "currency", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "taxDisclosure", "totalInCents", "isBinding", "createdAt", "updatedAt" ] }, "ListMerchantCheckoutSessionsResponseDto": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportSessionListItemDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "sessions" ] }, "CheckoutSupportSessionLineDto": { "type": "object", "properties": { "id": { "type": "string" }, "itemId": { "type": "string" }, "variantId": { "type": "string", "nullable": true }, "name": { "type": "string" }, "quantity": { "type": "number" }, "unitPriceInCents": { "type": "number" }, "totalPriceInCents": { "type": "number" }, "discountInCents": { "type": "number" } }, "required": [ "id", "itemId", "name", "quantity", "unitPriceInCents", "totalPriceInCents", "discountInCents" ] }, "CheckoutSupportSessionEventDto": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "payload": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "createdAt" ] }, "CheckoutSupportProcessorEventDto": { "type": "object", "properties": { "id": { "type": "string" }, "processor": { "type": "string" }, "eventId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "RECEIVED", "PROCESSED", "SKIPPED", "UNRESOLVED", "FAILED" ] }, "paymentAttemptId": { "type": "string", "nullable": true }, "checkoutSessionId": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "processor", "eventId", "type", "status", "receivedAt" ] }, "CheckoutSupportSessionDetailDto": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ] }, "currency": { "type": "string" }, "customerEmail": { "type": "string", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "shippingInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "taxDisclosure": { "nullable": true, "description": "Merchant/support-safe disclosure when litecommerce did not calculate tax for this session/order (manual/no-tax mode).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "number" }, "isBinding": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "reservationExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "finalOrderId": { "type": "string", "nullable": true }, "finalOrderNumber": { "type": "string", "nullable": true }, "latestPaymentAttempt": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSupportPaymentAttemptDto" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "shippingAddress": { "type": "object", "nullable": true }, "billingAddress": { "type": "object", "nullable": true }, "shippingMethod": { "type": "object", "nullable": true }, "discountSnapshot": { "type": "object", "nullable": true }, "taxSnapshot": { "type": "object", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportSessionLineDto" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportSessionEventDto" } }, "paymentAttempts": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportPaymentAttemptDto" } }, "processorEvents": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportProcessorEventDto" } }, "organizationHasConnectedAccount": { "type": "boolean", "description": "Whether the organization currently has a connected account at all. The comparison surface for an attempt stripeAccountId of null: with a connected account present, null means that object lives on the litecommerce platform account and will not be found in the tenant own dashboard; without one, null is simply normal and says nothing. A boolean rather than the account id, because only its presence is needed and this read carries no role restriction." } }, "required": [ "id", "status", "currency", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "taxDisclosure", "totalInCents", "isBinding", "createdAt", "updatedAt", "lines", "events", "paymentAttempts", "processorEvents", "organizationHasConnectedAccount" ] }, "CheckoutSupportPaymentListItemDto": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "PAYMENT", "AUTHORIZATION", "SETUP", "REFUND" ] }, "status": { "type": "string", "enum": [ "REQUIRES_PAYMENT_METHOD", "REQUIRES_ACTION", "PROCESSING", "REQUIRES_CAPTURE", "SUCCEEDED", "FAILED", "CANCELLED" ] }, "amountInCents": { "type": "number" }, "currency": { "type": "string" }, "paymentContextType": { "type": "string", "nullable": true, "description": "Commercial context type for the attempt (for example checkout_session)." }, "paymentContextId": { "type": "string", "nullable": true, "description": "Commercial context id for the attempt. Current checkout attempts point at the checkout session id." }, "processor": { "type": "string" }, "processorObjectType": { "type": "string", "enum": [ "PAYMENT_INTENT", "CHECKOUT_SESSION", "SETUP_INTENT", "REFUND" ], "nullable": true }, "processorObjectId": { "type": "string", "nullable": true }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Connected account the provider object lives on, as persisted at create (#932). Null does NOT have a single meaning and must not be read as one. When processorObjectId is also null no provider object was ever created, so there is nowhere for it to live. When processorObjectId is present, null means the object was created on the litecommerce platform account rather than the tenant own account — possible for attempts predating the tenant connecting one, and the reason such an object is absent from the tenant provider dashboard. Use organizationHasConnectedAccount on the session detail to separate that from a tenant that has never connected an account at all, where null is simply normal." }, "processorStatus": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "checkoutSession": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSupportSessionListItemDto" } ] }, "processorEvents": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportProcessorEventDto" } } }, "required": [ "id", "kind", "status", "amountInCents", "currency", "processor", "stripeAccountId", "createdAt", "updatedAt", "processorEvents" ] }, "ListMerchantPaymentsResponseDto": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSupportPaymentListItemDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "payments" ] }, "CheckoutBookingSecurityDepositDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "NONE", "FIXED_AMOUNT", "PERCENTAGE_OF_ORDER", "PERCENTAGE_OF_RESOURCE_VALUES" ] }, "amountInCents": { "type": "integer", "nullable": true, "minimum": 1 }, "percent": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 100 }, "authorizationDeferred": { "type": "boolean", "description": "True when authorization/capture is intentionally deferred beyond #641." } }, "required": [ "mode", "amountInCents", "percent", "authorizationDeferred" ] }, "CheckoutBookingContextDto": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "bookingType": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "paymentMode": { "type": "string", "enum": [ "PAY_LATER", "DEPOSIT_PERCENT", "FULL_PAYMENT" ] }, "depositPercent": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 100 }, "securityDeposit": { "$ref": "#/components/schemas/CheckoutBookingSecurityDepositDto" }, "delivery": { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" }, "requiresShipping": { "type": "boolean" } }, "required": [ "bookingId", "serviceId", "serviceName", "bookingType", "startsAt", "endsAt", "timezone", "quantity", "paymentMode", "depositPercent", "securityDeposit", "delivery", "requiresShipping" ] }, "CheckoutSubscriptionSummaryDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ], "description": "Webhook/reconciliation-authoritative subscription lifecycle state; a browser callback never promotes it." }, "trialMode": { "type": "string", "enum": [ "NONE", "CARD_UPFRONT", "NO_CARD" ], "description": "Frozen tenant-configured trial posture used when this checkout created the subscription." }, "trialDays": { "type": "integer", "nullable": true, "minimum": 1 }, "trialEndBehavior": { "type": "string", "enum": [ "CANCEL", "CREATE_INVOICE", "PAUSE" ], "nullable": true }, "trialEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "nextRenewalAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Current provider-authoritative renewal boundary. Null when no renewal is presently scheduled." }, "todayPaymentResult": { "type": "string", "enum": [ "REQUIRED", "PROCESSING", "PAID", "FAILED", "NOT_REQUIRED" ], "description": "Truthful result for this checkout origin invoice only; later renewal invoices never replace it." }, "todayPaymentFailureVersion": { "type": "string", "nullable": true, "pattern": "^[a-f0-9]{64}$", "description": "Opaque replay-stable version of today’s distinct origin-invoice payment failures. Hosted retry polling uses it only to distinguish a stale failed baseline from a later webhook; null means no durable failure event has been recorded." }, "todayOrderResult": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "NOT_CREATED", "NOT_REQUIRED" ], "description": "Fulfillment-order result for today. Itemless subscriptions need no order, and a failed initial payment never reports CONFIRMED." }, "recurringCardExplanation": { "type": "string", "description": "Customer-facing explanation of whether a card was stored today and how future recurring charges will work." }, "managementUrl": { "type": "string", "nullable": true, "description": "Tenant-trusted account or sign-in entry point for subscription management; never a provider portal URL or processor id." }, "managementRequiresAuthentication": { "type": "boolean", "description": "Always true: management requires customer authentication even when the returned URL already points at an account surface." } }, "required": [ "status", "trialMode", "trialDays", "trialEndBehavior", "trialEndsAt", "nextRenewalAt", "todayPaymentResult", "todayPaymentFailureVersion", "todayOrderResult", "recurringCardExplanation", "managementUrl", "managementRequiresAuthentication" ] }, "CheckoutSessionLineDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Catalog item id. Null only for an itemless membership/service-access subscription line.", "nullable": true }, "variantId": { "type": "string", "description": "Variant id when the line targets a specific variant.", "nullable": true }, "name": { "type": "string", "description": "Display name (item, or \"item — variant\")." }, "productName": { "type": "string", "nullable": true, "example": "Deodorant", "description": "#4017 (UAT F08) — the PRODUCT half of `name`, or `null` when the frozen line name was not segmented. `name` remains the authoritative frozen identity and is unchanged; this field and `variantName` are an additive, lossless view of it — they are non-null TOGETHER or not at all, and when present `productName + \" — \" + variantName` reconstructs `name` exactly, so a non-null value here is always a real product half and never a whole combined name. Produced by the SAME rule the order-status and account order-detail projections use: a proven pricing origin first, then both CURRENT catalog names separator-free and rebuilding the stored string exactly. The server never splits on a hyphen and never parses the stored value. `null` means render `name` as a single line — a line with no proven pricing origin, an item-level line with no variant, a product or variant renamed or deleted since purchase, or a catalog name that itself contains \" — \". Additionally `null` on every projection that is not a CONFIRMED one-time read: the pre-payment create/reprice/bind responses and the subscription projection never carry it, because the catalog names are resolved only for the paid confirmation (see `confirmedLineCatalogNames`). Legacy and unsegmentable lines therefore render exactly as they did before #4017." }, "variantName": { "type": "string", "nullable": true, "example": "Unscented", "description": "#4017 (UAT F08) — the VARIANT half of `name`, exactly as the catalog stores it (never trimmed, so the two halves rejoin losslessly). `null` whenever `productName` is `null`; the two are always resolved together." }, "imageUrl": { "type": "string", "description": "Catalog thumbnail URL for this line (#982) — the variant featured image when set, else the item primary image. `null` when the item has no image; the hosted/BYO surface renders a placeholder. Snapshotted at reprice so it stays stable for the session. Always present (required), value may be null.", "nullable": true }, "quantity": { "type": "number", "description": "Units on this line." }, "unitPriceInCents": { "type": "number", "description": "Server-resolved per-unit price (sale price when active)." }, "totalPriceInCents": { "type": "number", "description": "`unitPriceInCents * quantity`." }, "purchaseMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION" ] }, "subscriptionPlanId": { "type": "string", "format": "uuid", "nullable": true }, "subscriptionPriceId": { "type": "string", "format": "uuid", "nullable": true }, "recurringInterval": { "type": "string", "enum": [ "DAY", "WEEK", "MONTH", "YEAR" ], "nullable": true }, "recurringIntervalCount": { "type": "integer", "minimum": 1, "nullable": true }, "isPackageComponent": { "type": "boolean", "description": "True when this flat compatibility row is represented inside packages[].components." } }, "required": [ "itemId", "name", "productName", "variantName", "imageUrl", "quantity", "unitPriceInCents", "totalPriceInCents", "purchaseMode", "subscriptionPlanId", "subscriptionPriceId", "recurringInterval", "recurringIntervalCount", "isPackageComponent" ] }, "CheckoutSelectionLineDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true, "description": "Package definition revision to echo on reprice/bind; null for an ordinary catalog line." } }, "required": [ "itemId", "variantId", "quantity", "expectedCompositionRevision" ] }, "CheckoutDeliveryEstimateDto": { "type": "object", "properties": { "displayStyle": { "type": "string", "enum": [ "ship_by", "delivery_window", "both" ], "description": "How to render: `ship_by`, `delivery_window`, or `both` (tenant choice)." }, "shipByDate": { "type": "string", "description": "Local date the order is expected to ship by (ISO yyyy-MM-dd)." }, "deliveryStartDate": { "type": "string", "description": "Local delivery window start, inclusive (ISO yyyy-MM-dd)." }, "deliveryEndDate": { "type": "string", "description": "Local delivery window end, inclusive (ISO yyyy-MM-dd)." } }, "required": [ "displayStyle", "shipByDate", "deliveryStartDate", "deliveryEndDate" ] }, "CheckoutShippingMethodDto": { "type": "object", "properties": { "rateId": { "type": "string", "description": "Selected rate id — echoes the `shippingRateId` sent at bind." }, "name": { "type": "string", "description": "Customer-facing method/rate name (e.g. \"Standard\")." }, "priceInCents": { "type": "number", "description": "The rate's own price in minor units (cents). The amount actually charged is `shippingInCents` — `0` when a FREE_SHIPPING rule waived it (`freeShipping` is then true while this price keeps the rate sticker)." }, "freeShipping": { "type": "boolean", "description": "True when a FREE_SHIPPING coupon/auto-discount/bundle waived the charge: the method is still recorded but `shippingInCents` is `0`." }, "presentationMode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ], "description": "#2000 — frozen checkout presentation mode. Absent on legacy sessions." }, "description": { "type": "string", "nullable": true, "description": "Frozen customer promise description, when configured." }, "deliveryEstimate": { "nullable": true, "description": "#2000 — absolute delivery bounds frozen at bind. Present for a valid delivery promise; may also be present for structured exact-service quotes.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutDeliveryEstimateDto" } ] } }, "required": [ "rateId", "name", "priceInCents", "freeShipping" ] }, "CheckoutSessionCustomerDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Captured checkout email for the authenticated matching customer." }, "name": { "type": "string", "description": "Captured checkout name, or null when the session has none.", "nullable": true }, "phone": { "type": "string", "description": "Captured checkout phone, or null when the session has none.", "nullable": true } }, "required": [ "email", "name", "phone" ] }, "CheckoutSessionAddressDto": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "company": { "type": "string", "description": "Ship-to company." }, "state": { "type": "string", "description": "State / province / region." }, "city": { "type": "string", "description": "City / town." }, "postalCode": { "type": "string", "description": "ZIP / postal code." }, "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." } }, "required": [ "country" ] }, "CheckoutNormalizedAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "description": "Standardized address line 1." }, "line2": { "type": "string", "description": "Standardized address line 2, or null when the address has none.", "nullable": true }, "city": { "type": "string", "description": "Standardized city / town." }, "state": { "type": "string", "description": "Standardized state / province / region." }, "postalCode": { "type": "string", "description": "Standardized ZIP / postal code." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, "CheckoutAddressValidationDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "warning", "invalid", "unknown" ], "description": "Verdict on the submitted destination: `verified` (every carrier rated it clean), `warning` (deliverable but flagged — see `messages`), `invalid` (the carriers rejected it), or `unknown` (the provider could not judge it). Advisory except at bind, where an invalid address that leaves no shipping option is a 400." }, "messages": { "description": "Display-safe, shopper-actionable provider messages about the submitted destination address (deduped, at most 5). Empty when the provider offered no address detail. Provider notices about the merchant's parcel, carrier, account, or billing configuration are withheld from this list — the shopper cannot act on them — and surface only in operator diagnostics (#3375).", "type": "array", "items": { "type": "string" } }, "normalized": { "nullable": true, "description": "The carrier-standardized form of the submitted address, offered as a correction the shopper can accept. `null` when the provider returned no cleaned address OR its cleaned form is identical (case/trim-insensitively) to what was submitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutNormalizedAddressDto" } ] } }, "required": [ "status", "messages", "normalized" ] }, "CheckoutShippingOptionDto": { "type": "object", "properties": { "rateId": { "type": "string", "description": "Rate id — resend as `shippingRateId` on reprice (preview) and bind. **Quote-scoped** (#3052): treat every id as belonging to the quote it arrived on. Flat-rate ids are stable tenant configuration; live carrier ids (`se:`) wrap the provider's per-quote id and DO rotate between quotes; delivery-promise ids (`dp:`) derive from a durable promise tier, so the id is stable while that promise is still offered, though the promise itself can stop being offered and a stable id never implies a stable price (the server always charges the fresh quote). Replace the entire option set from every fresh response; never persist an id across re-quotes, infer meaning from its prefix, or re-match a prior choice by `name` (labels are neither unique nor stable). When a prior selection is no longer in the fresh set, require the shopper to explicitly reconfirm a method — a bind carrying a dead id is rejected with `400` `details.reason: SHIPPING_RATE_NOT_QUOTABLE`, while a reprice silently degrades to no shipping." }, "name": { "type": "string", "description": "Customer-facing rate name (e.g. \"Standard\")." }, "priceInCents": { "type": "number", "description": "The rate's price in minor units (cents)." }, "minimumSubtotalInCents": { "type": "number", "description": "Minimum order subtotal (cents) this rate requires — already satisfied by the current cart (options below the floor are omitted from the list)." }, "estimatedDelivery": { "type": "string", "description": "Free-text delivery estimate (e.g. \"3–5 business days\").", "nullable": true }, "freeShipping": { "type": "boolean", "description": "True when selecting THIS option charges nothing — a FREE_SHIPPING coupon/auto-discount/bundle is active AND this rate is at/below the baseline (cheapest applicable) rate it waives (#1014). A pricier upgrade stays `false` and charges its full `priceInCents`: a free-ship promo covers standard shipping, not premium upgrades. The surface renders \"Free\" when this is true so each option label matches the amount that selecting it will charge." }, "deliveryEstimate": { "nullable": true, "description": "#1103 — computed ship-by / delivery-window dates when the tenant enabled structured estimates and this rate has a transit window; null otherwise (fall back to `estimatedDelivery`).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutDeliveryEstimateDto" } ] }, "presentationMode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ], "description": "#2000 — present for live quotes. `delivery_promises` means the name is a merchant promise tier, not the hidden anchor carrier service." }, "description": { "type": "string", "nullable": true, "description": "Promise-mode customer description. Omitted for exact services/flat rates." }, "sortOrder": { "type": "integer", "minimum": 0, "description": "Promise-mode merchant display order. Omitted for exact services/flat rates." } }, "required": [ "rateId", "name", "priceInCents", "minimumSubtotalInCents", "estimatedDelivery", "freeShipping", "deliveryEstimate" ] }, "CheckoutAppliedCouponDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Canonical code of the coupon applied to this cart." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ] }, "value": { "type": "number", "description": "Configured coupon value: basis points for PERCENTAGE, minor units (cents) for FIXED_AMOUNT, and 0 for FREE_SHIPPING." }, "discountInCents": { "type": "number", "description": "Clamped amount this coupon removed from the cart subtotal, in minor units (cents). FREE_SHIPPING is represented separately and keeps this 0." }, "freeShipping": { "type": "boolean", "description": "True when this coupon waives the selected shipping charge instead of removing value from the cart subtotal." } }, "required": [ "code", "type", "value", "discountInCents", "freeShipping" ] }, "CheckoutDiscountSnapshotDto": { "type": "object", "properties": { "appliedCoupon": { "description": "Coupon applied to THIS submitted cart state. Always present within a discount snapshot; null means no coupon is applied. On an existing session, repricing or binding without `couponCode` removes any prior coupon and returns null here. A supplied but rejected code also returns null; the typed public contract does not expose a reason discriminator.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutAppliedCouponDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] } }, "required": [ "appliedCoupon" ] }, "CustomerCommunicationStatusDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "NOT_APPLICABLE", "QUEUED", "PROVIDER_ACCEPTED", "FAILED", "POLICY_DISABLED" ], "description": "Safe delivery result. `QUEUED` means the durable event is eligible under current server policy; `PROVIDER_ACCEPTED` means the provider accepted the request, not that the inbox received it. `FAILED` carries no provider/internal error detail. `POLICY_DISABLED` means delivery was prevented before provider acceptance by environment policy or configuration. `NOT_APPLICABLE` means no matching communication was queued." } }, "required": [ "state" ] }, "CheckoutSessionSummaryDto": { "type": "object", "properties": { "purchaseMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION" ] }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ], "description": "Lifecycle status. Cart sessions begin OPEN; server-priced booking sessions begin PENDING_PAYMENT; subscription sessions are advanced only by verified Billing outcomes. Confirmation/expiry moves every flow forward." }, "isBinding": { "type": "boolean", "description": "For cart checkout, false after create/reprice (mutable estimate) and true after bind. Booking checkout is server-priced and true at creation. Subscription checkout becomes true only after its provider subscription and exact first invoice are verified. #604 refuses to create an ordinary payment session unless this is true." }, "contextType": { "type": "string", "enum": [ "CART", "BOOKING" ] }, "booking": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutBookingContextDto" } ] }, "subscription": { "nullable": true, "description": "Subscription-specific payment/order/renewal truth. Present only when purchaseMode is SUBSCRIPTION.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSubscriptionSummaryDto" } ] }, "refundInitiated": { "type": "boolean", "description": "True only when this session is CANCELLED *and* it was CHARGED then auto-refunded by the webhook-authoritative confirmation path (#871) — a stale-PI reprice amount/currency mismatch or an oversell-after-charge race flipped the session to CANCELLED and enqueued the per-attempt refund (`checkout-refund:${paymentAttemptId}` outbox, idempotent). It lets the hosted/BYO surface tell a charged-then-refunded CANCELLED session apart from a plain cancelled/expired one and render honest \"payment received — your refund is on the way\" copy instead of the generic not-payable block. Scoped to CANCELLED on purpose: the confirmation path also refunds an extra duplicate charge on an already-CONFIRMED session without cancelling it, so a refunded-event check alone is not sufficient. Customer-safe by construction: a single boolean derived from the presence of the internal `checkout_session.refunded` event — it carries NO processor ids, amounts, or failure detail. `false` on every session that is not a charged-then-refunded CANCELLED one (OPEN, EXPIRED, a plain CANCELLED, and CONFIRMED — including a CONFIRMED session whose duplicate charge was refunded)." }, "currency": { "type": "string", "description": "ISO currency code (e.g. `usd`)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionLineDto" } }, "packages": { "description": "Frozen package selections with every component, operational quantity, savings, tax, and total.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "selections": { "description": "Top-level server-accepted catalog selections for exact reprice/bind retry. Package components never replace their parent here.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSelectionLineDto" } }, "subtotalInCents": { "type": "number", "description": "Sum of gross line totals. For a trial subscription this still includes the recurring sticker price; the amount deferred by the trial appears in discountInCents so the due-today equation remains exact." }, "discountInCents": { "type": "number", "description": "Amount subtracted from the gross subtotal. For subscription checkout it can include recurring value deferred from the first invoice by a trial, not only promotional discounts." }, "taxInCents": { "type": "number", "description": "Computed sales tax folded into the binding total (#449, ADR-008). `0` when no tax provider is enabled (the default) — the reference storefronts read THIS instead of their flat-8% placeholder. Non-zero cart tax is computed at `bind` from the captured address; a booking session may instead carry its persisted tax-preflight posture at creation." }, "taxDisclosure": { "nullable": true, "description": "Customer-safe tax posture disclosure. Present when the transaction used the audited manual/no-tax escape hatch, so checkout/receipt surfaces can clearly state that litecommerce did not calculate tax.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "description": "Shipping charge folded into the binding total (#854). `0` until `bind` resolves a customer-selected `shippingRateId` against the active zone matching the captured address — the price is re-derived server-side from the rate (never a client amount, ADR-006). Stays `0` when no rate is selected or a FREE_SHIPPING coupon/auto-discount/bundle waives the charge (the chosen method is still recorded on the session). The hosted/BYO surface renders THIS as the shipping line." }, "totalInCents": { "type": "number", "description": "Commercial transaction total (`subtotal - discount + tax + shipping`). For cart/full-payment checkout this is also charged now; a booking deposit charges amountDueNowInCents instead (ADR-006). For a subscription this is the verified first-invoice total only, never the lifetime value or a future renewal amount." }, "amountDueNowInCents": { "type": "number", "description": "Amount due now. Equals totalInCents for carts/full payment, may be smaller for a booking deposit, and is the verified first-invoice amount for a subscription (0 for a no-card trial)." }, "remainingBalanceInCents": { "type": "number", "description": "Commercial balance remaining after the due-now amount for this checkout. Always 0 for subscription checkout; future renewals are described by subscription.nextRenewalAt and are not a checkout balance." }, "requiresFreeConfirmation": { "type": "boolean", "description": "#3263 — `true` when this bound checkout must be completed through `POST …/sessions/:token/confirm-free` rather than `payment-session`, because its total cannot be charged: either zero, or above zero but below the payment provider's per-currency minimum (which the provider rejects, surfacing as a generic 500). Surfaces are expected to branch on THIS FLAG rather than testing the total themselves — the minimum is a provider fact that varies by currency and changes on the provider schedule, so a client-side comparison duplicates a threshold that will drift. `false` on a non-binding session, since a session that has not bound has no server-authoritative total yet. Also `false` for booking, booking-group, and subscription checkouts: they have no no-charge completion path, so a below-minimum total there is refused rather than routed." }, "shippingMethod": { "nullable": true, "description": "The customer-selected shipping method (#854/#1002), so the hosted/BYO surface can show WHICH option is chosen before payment. Populated on reprice (a preview) AND bind (the commitment) when a resolvable `shippingRateId` is selected; `null` on create, and whenever no rate is selected or the selected rate does not resolve (on reprice it simply clears the estimate; on bind an invalid rate is a `400`). The charged amount is `shippingInCents`; this carries the method label and whether a FREE_SHIPPING rule waived the charge.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutShippingMethodDto" } ] }, "customer": { "nullable": true, "description": "#1170 — captured customer contact for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer. This keeps the anonymous session-read projection PII-free; #3231 deliberately exposes only the bound email through the separate payment-session handoff.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionCustomerDto" } ] }, "shippingAddress": { "nullable": true, "description": "#1170 — captured shipping address for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionAddressDto" } ] }, "shippingAddressValidation": { "nullable": true, "description": "#1563 — provider verdict on the shipping address, produced by the live-rate quote (validation rides the rate call). Present ONLY on reprice/bind responses when a live quote ran for this org (quoted, or failed on an invalid address); absent for tenants without live rates. PII posture (#1170/#606): echoes a cleaned form of the address the caller submitted on this request and is never present on anonymous session reads. #3231 separately permits that token to obtain only the bound email through the payment-session handoff, never this address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressValidationDto" } ] }, "availableShippingOptions": { "description": "For ordinary one-time checkout, server-derived shipping options applicable to the captured destination + cart subtotal (#1002), so the hosted/BYO surface can show — and let the shopper switch between — fulfillment methods BEFORE payment. Resolved from the active zone matching the address country, filtered to rates the subtotal clears. **Populated only on ordinary reprice/bind responses and on a read of an ordinary session that is not yet binding** (#3052): its create response and any read of a BOUND session return `[]` by design (no destination resolved yet, and the picker is a pre-payment surface the confirmation poll must not re-query). Physical-subscription summaries also return `[]`: that flow has no public option preflight (#3482), so this field is not its selection source. An empty array on those responses therefore means \"not offered here\", NOT \"no rates available\" — never let one clear a rendered option set or a confirmed selection. It is also empty when no address, zone, or applicable rate exists. For ordinary checkout, select one and resend its `rateId` as `shippingRateId`: reprice previews the resulting total; bind re-resolves and commits it only if it is still valid. The charged amount is always server-derived (ADR-006). An option is current only for the response it arrived on, not a promise that a later bind will succeed.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutShippingOptionDto" } }, "discountSnapshot": { "description": "Current server-authored discount attribution, persisted verbatim and copied onto the final order for attribution. The property is always present. It is an object for server-repriced cart/subscription sessions (even when no discount applies), and null only for booking, booking-group, or legacy sessions that have no discount snapshot. Within an object, `appliedCoupon: null` is the authoritative proof that no coupon is applied; aggregate discounts or totals can still reflect other rules. Only `appliedCoupon` is modeled by this schema; any additional server-authored attribution keys are intentionally not declared as public identifiers or schema fields.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutDiscountSnapshotDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "expiresAt": { "type": "string", "description": "When an unbound session may expire before provider creation. Once a durable provider-create intent exists, this timestamp remains useful for shopper messaging but authoritative reconciliation decides the outcome instead of a token read silently expiring provider-bound work. Null only in the (not-issued-here) no-expiry case.", "nullable": true, "format": "date-time" }, "reservationExpiresAt": { "type": "string", "description": "When a Mode-B (reserve-during-checkout) pre-payment inventory hold expires — the secondary countdown source for \"your items are held for N min\". Null under Mode A (reserve-at-confirmation, the only live mode today), where the session carries no hold. #605 Slice 3 ships this as a SEAM: it is populated only once Mode B is wired (no holds are minted in M3).", "nullable": true, "format": "date-time" }, "orderReference": { "type": "string", "description": "Stable public order address. Always present as a nullable field: null before finalOrderId exists and the exact non-null Order reference afterward. The locator is never an authentication credential.", "nullable": true, "pattern": "^or1_[0-9a-f]{32}$", "example": "or1_0123456789abcdef0123456789abcdef" }, "orderNumber": { "type": "string", "description": "The resulting order number once this session is CONFIRMED (#991) — the in-flow confirmation surface renders it as the post-payment receipt reference. Joined from `CheckoutSession.finalOrderId`; `null` on every non-confirmed read and on create/reprice/bind (no order exists yet). ALWAYS PRESENT (nullable), like `returnToStoreUrl` — every summary path emits it, so it belongs in the schema `required` set. Non-PII: the same `Order.orderNumber` the #818 order-status page and the signed-in account already show. The order-status `o`-token is hash-at-rest (ADR-007) and intentionally NOT reconstructable here, so this is a reference + account next-action, not a regenerated forwardable status link.", "nullable": true }, "orderConfirmationEmail": { "description": "#1965 — server-derived, customer-safe state of the order-confirmation email. Always present. It never includes the recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "returnToStoreUrl": { "type": "string", "description": "#1116 — the resolved safe return-to-store destination for hosted/BYO checkout surfaces. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "postCheckoutRedirectUrl": { "type": "string", "description": "#1116 — the resolved safe post-checkout completion destination. Prefers trusted `checkoutSettings.postCheckoutRedirectUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. Hosted checkout may auto-redirect here only after the server read shows CONFIRMED; never from a client-side processor callback. `null` only when no safe destination exists.", "nullable": true }, "checkoutRetryUrl": { "type": "string", "description": "#1116 — the resolved safe retry/start-over checkout destination. Prefers trusted `checkoutSettings.checkoutRetryUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "checkoutCancelUrl": { "type": "string", "description": "#1116 — the resolved safe canceled/expired checkout destination. Prefers trusted `checkoutSettings.checkoutCancelUrl`, then `checkoutRetryUrl`, `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "accountUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer account URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout account origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "accountSignInUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer sign-in URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout sign-in origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "#996 — whether the tenant enabled the hosted-checkout marketing opt-in (`checkoutSettings.marketingOptInEnabled`). When true, the surface shows a DEFAULT-UNCHECKED opt-in checkbox before payment and sends the shopper's choice as the bind `marketingOptIn`. ALWAYS PRESENT (in the schema `required` set); `false` unless the tenant turned it on." }, "marketingOptInCopy": { "type": "string", "description": "#996 — the label to render beside the opt-in checkbox when `marketingOptInEnabled` is true: the tenant-configured copy, else a safe default. Plain text (no URL). `null` when the opt-in is disabled (no checkbox). ALWAYS PRESENT (nullable).", "nullable": true } }, "required": [ "purchaseMode", "status", "isBinding", "contextType", "booking", "subscription", "refundInitiated", "currency", "lines", "packages", "selections", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "totalInCents", "amountDueNowInCents", "remainingBalanceInCents", "requiresFreeConfirmation", "customer", "shippingAddress", "availableShippingOptions", "discountSnapshot", "orderReference", "orderNumber", "orderConfirmationEmail", "returnToStoreUrl", "postCheckoutRedirectUrl", "checkoutRetryUrl", "checkoutCancelUrl", "accountUrl", "accountSignInUrl", "marketingOptInEnabled", "marketingOptInCopy" ] }, "CanonicalBillingAddressResponseDto": { "type": "object", "properties": { "country": { "type": "string", "description": "Canonical uppercase ISO 3166-1 alpha-2 country code.", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "US" }, "company": { "type": "string", "description": "Canonical company or organization name. Omitted when the shopper supplied no non-blank value.", "maxLength": 200 }, "line1": { "type": "string", "description": "Canonical street-address line 1.", "maxLength": 300 }, "line2": { "type": "string", "description": "Canonical apartment, suite, or address line 2. Omitted when the shopper supplied no non-blank value.", "maxLength": 300 }, "city": { "type": "string", "description": "Canonical city or town.", "maxLength": 200 }, "state": { "type": "string", "description": "Canonical uppercase state, province, or region value.", "maxLength": 100 }, "postalCode": { "type": "string", "description": "Canonical uppercase ZIP or postal code.", "maxLength": 20 } }, "required": [ "country", "line1", "city", "state", "postalCode" ] }, "PaymentSessionResponseDto": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "Stripe PaymentIntent client secret. Render the Payment Element against this. Forwarded to the browser only — never stored." }, "publishableKey": { "type": "string", "description": "Browser-safe Stripe publishable key from the API environment that created the PaymentIntent. Initialize Stripe.js with this key and the returned `stripeAccountId` when present. This is not a secret.", "example": "pk_test_123" }, "paymentAttemptId": { "type": "string", "description": "Internal PaymentAttempt id this payment is tracked under." }, "amountInCents": { "type": "number", "description": "The server-authoritative amount (smallest currency unit) the PaymentIntent was created to charge NOW — i.e. the CheckoutSession `amountDueNowInCents`. This equals the transaction total for a cart / full-payment checkout, but is the smaller due-now amount for a booking deposit (ADR-006), NOT the full transaction total. Compare or display it as the amount being charged now." }, "currency": { "type": "string", "description": "ISO currency code (e.g. `usd`)." }, "email": { "type": "string", "format": "email", "description": "The checkout-time customer email bound to this payment session. Supply it as `payment_method_data.billing_details.email` when confirming the PaymentIntent; it is not a receipt-delivery request. Omitted only for a missing/blank legacy checkout-session snapshot; clients must then retain provider `auto` email collection.", "example": "shopper@example.com" }, "billingAddress": { "description": "The canonical order-time billing address from the current ordinary checkout bind. Supply it as `payment_method_data.billing_details.address` when confirming the PaymentIntent. Omitted for booking/legacy handoffs that do not participate in the E28 ordinary-checkout contract. This client-secret-bearing handoff is separate from the PII-free anonymous checkout-session read.", "allOf": [ { "$ref": "#/components/schemas/CanonicalBillingAddressResponseDto" } ] }, "status": { "type": "string", "description": "Stripe PaymentIntent status at creation (e.g. `requires_payment_method`). Advisory only — webhook reconciliation is authoritative." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "#932 — the tenant's connected Stripe account (`acct_…`) the PaymentIntent was created on. The client MUST initialize Stripe.js with this account (`loadStripe(pk, { stripeAccount })`) so the Payment Element renders against the connected-account intent. null when the intent is on the platform account (test/sandbox).", "example": "acct_123" } }, "required": [ "clientSecret", "publishableKey", "paymentAttemptId", "amountInCents", "currency", "status", "stripeAccountId" ] }, "RepriceLineDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Catalog item id for the requested line.", "minLength": 1 }, "variantId": { "type": "string", "description": "Variant id when the line targets a specific variant. Optional — for an item with no variants, omission or `null` prices against the item-level price. A SALE item with variants requires one exact variant id. When set, the variant must belong to `itemId` (cross-item references are rejected with a structured 400).", "nullable": true, "minLength": 1 }, "quantity": { "type": "number", "minimum": 1, "description": "Number of units requested on this line. Lines with quantity <= 0 should be omitted rather than included with a zero." }, "expectedCompositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 2147483647, "description": "Required for a package selection. Must match the public catalog composition revision." } }, "required": [ "itemId", "quantity" ] }, "CheckoutCustomerDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email for receipts / order-status links.", "maxLength": 320 }, "name": { "type": "string", "description": "Customer name.", "maxLength": 200 }, "phone": { "type": "string", "description": "Customer phone. Conditionally required at ordinary cart checkout bind when the tenant public config reports `phoneRequired: true`; it may be supplied here or persisted from create / an earlier reprice. Subscription and booking checkout are excluded.", "maxLength": 50 } } }, "CreateCheckoutSessionDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "description": "Requested catalog lines (refs + quantities, no prices).", "type": "array", "items": { "$ref": "#/components/schemas/RepriceLineDto" } }, "couponCode": { "type": "string", "description": "Coupon selection for THIS submitted full-cart state, not a patch to the prior session. On an existing checkout, OMIT this property to remove any coupon applied by an earlier create, reprice, or bind; omission does not retain the prior coupon, and no separate clear action is required. A blank or whitespace-only string follows the same no-code path as omission and clears the coupon. A supplied non-blank code is matched case-insensitively, revalidated, and applied server-side against the resolved subtotal. An invalid / expired / below-minimum / exhausted code does NOT fail the call. In the omitted, blank, or rejected-code case, the response proves that no coupon is applied with `discountSnapshot.appliedCoupon: null`. The typed public contract does not distinguish those no-coupon cases; do not depend on undeclared discount-snapshot keys. Do not infer coupon removal from aggregate discount or totals because other discounts can remain.", "maxLength": 128 }, "customer": { "description": "Optional customer contact. May be supplied at create OR progressively on reprice/bind. A non-blank `email` is REQUIRED before payment: `bind` rejects a session that still has no customer email (#605 — a CONFIRMED order must carry a real contact address that customer-facing flows match on). Provided fields are persisted onto the `CheckoutSession`; never trusted as authenticated identity.", "allOf": [ { "$ref": "#/components/schemas/CheckoutCustomerDto" } ] }, "marketingOptIn": { "type": "boolean", "description": "#996 — the shopper's marketing opt-in choice. Honored only when the tenant enabled the checkout opt-in (`marketingOptInEnabled` in checkoutSettings); persisted on the session and acted on at confirmation (a `true` subscribes the email to the tenant newsletter via double opt-in). OMITTED or false ⇒ no subscription — the server never infers consent. BYO clients pass this to collect the same consent." }, "shippingAddress": { "description": "Optional customer shipping address. May be supplied at create OR progressively on reprice/bind, and is persisted onto the `CheckoutSession`. When a tax provider is enabled (ADR-008), `bind` REQUIRES a shipping or billing address (a `400` otherwise, like the email requirement) so destination-based tax can be computed and folded into the binding total. When tax is disabled, no address is required.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "description": "Customer billing address, accepted progressively on create/reprice and persisted onto the `CheckoutSession`. An ordinary one-time checkout MUST supply a complete current billing address at bind before payment or free confirmation. Same-as-delivery callers send a second canonical snapshot equal to `shippingAddress`; distinct billing is sent independently. It is also the tax-calculation address when no shipping address is present.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "shippingRateId": { "type": "string", "description": "Optional id of the shopper-confirmed shipping option. Ignored on create. For ordinary checkout, choose a `rateId` ONLY from the latest `availableShippingOptions` for that checkout session; obtain or refresh the set with an address-bearing `POST /api/v1/public/checkout/sessions/{token}/reprice`. `GET /api/v1/public/shipping/zones` is configuration/eligibility and must not drive the ordinary-checkout picker. On reprice and bind (#1002), the server recomputes current eligibility and amount from server-owned configuration or a fresh quote, never a client amount (ADR-006). Reprice with an omitted or unresolvable selection yields no shipping and returns refreshed options. At bind, the missing-selection guard is a `400` only when the cart requires shipping and the freshly resolved option set is non-empty (#952); an all-service/digital cart is never forced to select a method. At bind, any supplied id is revalidated with the effective address; an invalid selection is a `400`. A FREE_SHIPPING coupon/auto-discount/bundle zeroes an eligible baseline-priced method; a pricier upgrade keeps its server-derived charge (#1014).", "maxLength": 100 }, "currency": { "type": "string", "description": "ISO 4217 currency for the session (lowercase, e.g. `usd`). Optional — when omitted the session adopts the currency the repricing engine priced in (`usd` today, the only currency every tenant supports). When supplied it is VALIDATED against that priced currency, not used as a preference: a mismatch (e.g. requesting `eur` for a `usd`-priced checkout) is rejected with a `400`, never silently coerced to `usd`.", "minLength": 3, "maxLength": 3, "example": "usd" } }, "required": [ "lines" ] }, "CreateCheckoutSessionResponseDto": { "type": "object", "properties": { "purchaseMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION" ] }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ], "description": "Lifecycle status. Cart sessions begin OPEN; server-priced booking sessions begin PENDING_PAYMENT; subscription sessions are advanced only by verified Billing outcomes. Confirmation/expiry moves every flow forward." }, "isBinding": { "type": "boolean", "description": "For cart checkout, false after create/reprice (mutable estimate) and true after bind. Booking checkout is server-priced and true at creation. Subscription checkout becomes true only after its provider subscription and exact first invoice are verified. #604 refuses to create an ordinary payment session unless this is true." }, "contextType": { "type": "string", "enum": [ "CART", "BOOKING" ] }, "booking": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutBookingContextDto" } ] }, "subscription": { "nullable": true, "description": "Subscription-specific payment/order/renewal truth. Present only when purchaseMode is SUBSCRIPTION.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSubscriptionSummaryDto" } ] }, "refundInitiated": { "type": "boolean", "description": "True only when this session is CANCELLED *and* it was CHARGED then auto-refunded by the webhook-authoritative confirmation path (#871) — a stale-PI reprice amount/currency mismatch or an oversell-after-charge race flipped the session to CANCELLED and enqueued the per-attempt refund (`checkout-refund:${paymentAttemptId}` outbox, idempotent). It lets the hosted/BYO surface tell a charged-then-refunded CANCELLED session apart from a plain cancelled/expired one and render honest \"payment received — your refund is on the way\" copy instead of the generic not-payable block. Scoped to CANCELLED on purpose: the confirmation path also refunds an extra duplicate charge on an already-CONFIRMED session without cancelling it, so a refunded-event check alone is not sufficient. Customer-safe by construction: a single boolean derived from the presence of the internal `checkout_session.refunded` event — it carries NO processor ids, amounts, or failure detail. `false` on every session that is not a charged-then-refunded CANCELLED one (OPEN, EXPIRED, a plain CANCELLED, and CONFIRMED — including a CONFIRMED session whose duplicate charge was refunded)." }, "currency": { "type": "string", "description": "ISO currency code (e.g. `usd`)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionLineDto" } }, "packages": { "description": "Frozen package selections with every component, operational quantity, savings, tax, and total.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "selections": { "description": "Top-level server-accepted catalog selections for exact reprice/bind retry. Package components never replace their parent here.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSelectionLineDto" } }, "subtotalInCents": { "type": "number", "description": "Sum of gross line totals. For a trial subscription this still includes the recurring sticker price; the amount deferred by the trial appears in discountInCents so the due-today equation remains exact." }, "discountInCents": { "type": "number", "description": "Amount subtracted from the gross subtotal. For subscription checkout it can include recurring value deferred from the first invoice by a trial, not only promotional discounts." }, "taxInCents": { "type": "number", "description": "Computed sales tax folded into the binding total (#449, ADR-008). `0` when no tax provider is enabled (the default) — the reference storefronts read THIS instead of their flat-8% placeholder. Non-zero cart tax is computed at `bind` from the captured address; a booking session may instead carry its persisted tax-preflight posture at creation." }, "taxDisclosure": { "nullable": true, "description": "Customer-safe tax posture disclosure. Present when the transaction used the audited manual/no-tax escape hatch, so checkout/receipt surfaces can clearly state that litecommerce did not calculate tax.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "description": "Shipping charge folded into the binding total (#854). `0` until `bind` resolves a customer-selected `shippingRateId` against the active zone matching the captured address — the price is re-derived server-side from the rate (never a client amount, ADR-006). Stays `0` when no rate is selected or a FREE_SHIPPING coupon/auto-discount/bundle waives the charge (the chosen method is still recorded on the session). The hosted/BYO surface renders THIS as the shipping line." }, "totalInCents": { "type": "number", "description": "Commercial transaction total (`subtotal - discount + tax + shipping`). For cart/full-payment checkout this is also charged now; a booking deposit charges amountDueNowInCents instead (ADR-006). For a subscription this is the verified first-invoice total only, never the lifetime value or a future renewal amount." }, "amountDueNowInCents": { "type": "number", "description": "Amount due now. Equals totalInCents for carts/full payment, may be smaller for a booking deposit, and is the verified first-invoice amount for a subscription (0 for a no-card trial)." }, "remainingBalanceInCents": { "type": "number", "description": "Commercial balance remaining after the due-now amount for this checkout. Always 0 for subscription checkout; future renewals are described by subscription.nextRenewalAt and are not a checkout balance." }, "requiresFreeConfirmation": { "type": "boolean", "description": "#3263 — `true` when this bound checkout must be completed through `POST …/sessions/:token/confirm-free` rather than `payment-session`, because its total cannot be charged: either zero, or above zero but below the payment provider's per-currency minimum (which the provider rejects, surfacing as a generic 500). Surfaces are expected to branch on THIS FLAG rather than testing the total themselves — the minimum is a provider fact that varies by currency and changes on the provider schedule, so a client-side comparison duplicates a threshold that will drift. `false` on a non-binding session, since a session that has not bound has no server-authoritative total yet. Also `false` for booking, booking-group, and subscription checkouts: they have no no-charge completion path, so a below-minimum total there is refused rather than routed." }, "shippingMethod": { "nullable": true, "description": "The customer-selected shipping method (#854/#1002), so the hosted/BYO surface can show WHICH option is chosen before payment. Populated on reprice (a preview) AND bind (the commitment) when a resolvable `shippingRateId` is selected; `null` on create, and whenever no rate is selected or the selected rate does not resolve (on reprice it simply clears the estimate; on bind an invalid rate is a `400`). The charged amount is `shippingInCents`; this carries the method label and whether a FREE_SHIPPING rule waived the charge.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutShippingMethodDto" } ] }, "customer": { "nullable": true, "description": "#1170 — captured customer contact for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer. This keeps the anonymous session-read projection PII-free; #3231 deliberately exposes only the bound email through the separate payment-session handoff.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionCustomerDto" } ] }, "shippingAddress": { "nullable": true, "description": "#1170 — captured shipping address for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionAddressDto" } ] }, "shippingAddressValidation": { "nullable": true, "description": "#1563 — provider verdict on the shipping address, produced by the live-rate quote (validation rides the rate call). Present ONLY on reprice/bind responses when a live quote ran for this org (quoted, or failed on an invalid address); absent for tenants without live rates. PII posture (#1170/#606): echoes a cleaned form of the address the caller submitted on this request and is never present on anonymous session reads. #3231 separately permits that token to obtain only the bound email through the payment-session handoff, never this address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressValidationDto" } ] }, "availableShippingOptions": { "description": "For ordinary one-time checkout, server-derived shipping options applicable to the captured destination + cart subtotal (#1002), so the hosted/BYO surface can show — and let the shopper switch between — fulfillment methods BEFORE payment. Resolved from the active zone matching the address country, filtered to rates the subtotal clears. **Populated only on ordinary reprice/bind responses and on a read of an ordinary session that is not yet binding** (#3052): its create response and any read of a BOUND session return `[]` by design (no destination resolved yet, and the picker is a pre-payment surface the confirmation poll must not re-query). Physical-subscription summaries also return `[]`: that flow has no public option preflight (#3482), so this field is not its selection source. An empty array on those responses therefore means \"not offered here\", NOT \"no rates available\" — never let one clear a rendered option set or a confirmed selection. It is also empty when no address, zone, or applicable rate exists. For ordinary checkout, select one and resend its `rateId` as `shippingRateId`: reprice previews the resulting total; bind re-resolves and commits it only if it is still valid. The charged amount is always server-derived (ADR-006). An option is current only for the response it arrived on, not a promise that a later bind will succeed.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutShippingOptionDto" } }, "discountSnapshot": { "description": "Current server-authored discount attribution, persisted verbatim and copied onto the final order for attribution. The property is always present. It is an object for server-repriced cart/subscription sessions (even when no discount applies), and null only for booking, booking-group, or legacy sessions that have no discount snapshot. Within an object, `appliedCoupon: null` is the authoritative proof that no coupon is applied; aggregate discounts or totals can still reflect other rules. Only `appliedCoupon` is modeled by this schema; any additional server-authored attribution keys are intentionally not declared as public identifiers or schema fields.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutDiscountSnapshotDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "expiresAt": { "type": "string", "description": "When an unbound session may expire before provider creation. Once a durable provider-create intent exists, this timestamp remains useful for shopper messaging but authoritative reconciliation decides the outcome instead of a token read silently expiring provider-bound work. Null only in the (not-issued-here) no-expiry case.", "nullable": true, "format": "date-time" }, "reservationExpiresAt": { "type": "string", "description": "When a Mode-B (reserve-during-checkout) pre-payment inventory hold expires — the secondary countdown source for \"your items are held for N min\". Null under Mode A (reserve-at-confirmation, the only live mode today), where the session carries no hold. #605 Slice 3 ships this as a SEAM: it is populated only once Mode B is wired (no holds are minted in M3).", "nullable": true, "format": "date-time" }, "orderReference": { "type": "string", "description": "Stable public order address. Always present as a nullable field: null before finalOrderId exists and the exact non-null Order reference afterward. The locator is never an authentication credential.", "nullable": true, "pattern": "^or1_[0-9a-f]{32}$", "example": "or1_0123456789abcdef0123456789abcdef" }, "orderNumber": { "type": "string", "description": "The resulting order number once this session is CONFIRMED (#991) — the in-flow confirmation surface renders it as the post-payment receipt reference. Joined from `CheckoutSession.finalOrderId`; `null` on every non-confirmed read and on create/reprice/bind (no order exists yet). ALWAYS PRESENT (nullable), like `returnToStoreUrl` — every summary path emits it, so it belongs in the schema `required` set. Non-PII: the same `Order.orderNumber` the #818 order-status page and the signed-in account already show. The order-status `o`-token is hash-at-rest (ADR-007) and intentionally NOT reconstructable here, so this is a reference + account next-action, not a regenerated forwardable status link.", "nullable": true }, "orderConfirmationEmail": { "description": "#1965 — server-derived, customer-safe state of the order-confirmation email. Always present. It never includes the recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "returnToStoreUrl": { "type": "string", "description": "#1116 — the resolved safe return-to-store destination for hosted/BYO checkout surfaces. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "postCheckoutRedirectUrl": { "type": "string", "description": "#1116 — the resolved safe post-checkout completion destination. Prefers trusted `checkoutSettings.postCheckoutRedirectUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. Hosted checkout may auto-redirect here only after the server read shows CONFIRMED; never from a client-side processor callback. `null` only when no safe destination exists.", "nullable": true }, "checkoutRetryUrl": { "type": "string", "description": "#1116 — the resolved safe retry/start-over checkout destination. Prefers trusted `checkoutSettings.checkoutRetryUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "checkoutCancelUrl": { "type": "string", "description": "#1116 — the resolved safe canceled/expired checkout destination. Prefers trusted `checkoutSettings.checkoutCancelUrl`, then `checkoutRetryUrl`, `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "accountUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer account URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout account origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "accountSignInUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer sign-in URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout sign-in origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "#996 — whether the tenant enabled the hosted-checkout marketing opt-in (`checkoutSettings.marketingOptInEnabled`). When true, the surface shows a DEFAULT-UNCHECKED opt-in checkbox before payment and sends the shopper's choice as the bind `marketingOptIn`. ALWAYS PRESENT (in the schema `required` set); `false` unless the tenant turned it on." }, "marketingOptInCopy": { "type": "string", "description": "#996 — the label to render beside the opt-in checkbox when `marketingOptInEnabled` is true: the tenant-configured copy, else a safe default. Plain text (no URL). `null` when the opt-in is disabled (no checkbox). ALWAYS PRESENT (nullable).", "nullable": true }, "token": { "type": "string", "description": "The raw checkout-session token (prefix `c`). Returned only on create and never again — store it client-side; the server keeps only its hash. Used as `:token` on every subsequent session call." } }, "required": [ "purchaseMode", "status", "isBinding", "contextType", "booking", "subscription", "refundInitiated", "currency", "lines", "packages", "selections", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "totalInCents", "amountDueNowInCents", "remainingBalanceInCents", "requiresFreeConfirmation", "customer", "shippingAddress", "availableShippingOptions", "discountSnapshot", "orderReference", "orderNumber", "orderConfirmationEmail", "returnToStoreUrl", "postCheckoutRedirectUrl", "checkoutRetryUrl", "checkoutCancelUrl", "accountUrl", "accountSignInUrl", "marketingOptInEnabled", "marketingOptInCopy", "token" ] }, "RepriceCheckoutSessionDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "description": "Requested catalog lines (refs + quantities, no prices).", "type": "array", "items": { "$ref": "#/components/schemas/RepriceLineDto" } }, "couponCode": { "type": "string", "description": "Coupon selection for THIS submitted full-cart state, not a patch to the prior session. On an existing checkout, OMIT this property to remove any coupon applied by an earlier create, reprice, or bind; omission does not retain the prior coupon, and no separate clear action is required. A blank or whitespace-only string follows the same no-code path as omission and clears the coupon. A supplied non-blank code is matched case-insensitively, revalidated, and applied server-side against the resolved subtotal. An invalid / expired / below-minimum / exhausted code does NOT fail the call. In the omitted, blank, or rejected-code case, the response proves that no coupon is applied with `discountSnapshot.appliedCoupon: null`. The typed public contract does not distinguish those no-coupon cases; do not depend on undeclared discount-snapshot keys. Do not infer coupon removal from aggregate discount or totals because other discounts can remain.", "maxLength": 128 }, "customer": { "description": "Optional customer contact. May be supplied at create OR progressively on reprice/bind. A non-blank `email` is REQUIRED before payment: `bind` rejects a session that still has no customer email (#605 — a CONFIRMED order must carry a real contact address that customer-facing flows match on). Provided fields are persisted onto the `CheckoutSession`; never trusted as authenticated identity.", "allOf": [ { "$ref": "#/components/schemas/CheckoutCustomerDto" } ] }, "marketingOptIn": { "type": "boolean", "description": "#996 — the shopper's marketing opt-in choice. Honored only when the tenant enabled the checkout opt-in (`marketingOptInEnabled` in checkoutSettings); persisted on the session and acted on at confirmation (a `true` subscribes the email to the tenant newsletter via double opt-in). OMITTED or false ⇒ no subscription — the server never infers consent. BYO clients pass this to collect the same consent." }, "shippingAddress": { "description": "Optional customer shipping address. May be supplied at create OR progressively on reprice/bind, and is persisted onto the `CheckoutSession`. When a tax provider is enabled (ADR-008), `bind` REQUIRES a shipping or billing address (a `400` otherwise, like the email requirement) so destination-based tax can be computed and folded into the binding total. When tax is disabled, no address is required.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "description": "Customer billing address, accepted progressively on create/reprice and persisted onto the `CheckoutSession`. An ordinary one-time checkout MUST supply a complete current billing address at bind before payment or free confirmation. Same-as-delivery callers send a second canonical snapshot equal to `shippingAddress`; distinct billing is sent independently. It is also the tax-calculation address when no shipping address is present.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "shippingRateId": { "type": "string", "description": "Optional id of the shopper-confirmed shipping option. Ignored on create. For ordinary checkout, choose a `rateId` ONLY from the latest `availableShippingOptions` for that checkout session; obtain or refresh the set with an address-bearing `POST /api/v1/public/checkout/sessions/{token}/reprice`. `GET /api/v1/public/shipping/zones` is configuration/eligibility and must not drive the ordinary-checkout picker. On reprice and bind (#1002), the server recomputes current eligibility and amount from server-owned configuration or a fresh quote, never a client amount (ADR-006). Reprice with an omitted or unresolvable selection yields no shipping and returns refreshed options. At bind, the missing-selection guard is a `400` only when the cart requires shipping and the freshly resolved option set is non-empty (#952); an all-service/digital cart is never forced to select a method. At bind, any supplied id is revalidated with the effective address; an invalid selection is a `400`. A FREE_SHIPPING coupon/auto-discount/bundle zeroes an eligible baseline-priced method; a pricier upgrade keeps its server-derived charge (#1014).", "maxLength": 100 } }, "required": [ "lines" ] }, "BindCheckoutCustomerDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email for receipts / order-status links.", "maxLength": 320 }, "name": { "type": "string", "description": "Customer name. REQUIRED and non-blank at bind — a CONFIRMED order must carry a real customer name (shown on the order / receipt). May be collected progressively before bind, but must be present by the bind call (here or persisted from create / an earlier reprice).", "maxLength": 200 }, "phone": { "type": "string", "description": "Customer phone. Conditionally required and non-blank when the tenant public config reports `phoneRequired: true` for ordinary cart checkout; it may be supplied here or persisted from create / an earlier reprice. Subscription and booking checkout are excluded.", "maxLength": 50 } }, "required": [ "name" ] }, "BindCheckoutSessionDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "description": "Requested catalog lines (refs + quantities, no prices).", "type": "array", "items": { "$ref": "#/components/schemas/RepriceLineDto" } }, "couponCode": { "type": "string", "description": "Coupon selection for THIS submitted full-cart state, not a patch to the prior session. On an existing checkout, OMIT this property to remove any coupon applied by an earlier create, reprice, or bind; omission does not retain the prior coupon, and no separate clear action is required. A blank or whitespace-only string follows the same no-code path as omission and clears the coupon. A supplied non-blank code is matched case-insensitively, revalidated, and applied server-side against the resolved subtotal. An invalid / expired / below-minimum / exhausted code does NOT fail the call. In the omitted, blank, or rejected-code case, the response proves that no coupon is applied with `discountSnapshot.appliedCoupon: null`. The typed public contract does not distinguish those no-coupon cases; do not depend on undeclared discount-snapshot keys. Do not infer coupon removal from aggregate discount or totals because other discounts can remain.", "maxLength": 128 }, "marketingOptIn": { "type": "boolean", "description": "#996 — the shopper's marketing opt-in choice. Honored only when the tenant enabled the checkout opt-in (`marketingOptInEnabled` in checkoutSettings); persisted on the session and acted on at confirmation (a `true` subscribes the email to the tenant newsletter via double opt-in). OMITTED or false ⇒ no subscription — the server never infers consent. BYO clients pass this to collect the same consent." }, "shippingAddress": { "description": "Optional customer shipping address. May be supplied at create OR progressively on reprice/bind, and is persisted onto the `CheckoutSession`. When a tax provider is enabled (ADR-008), `bind` REQUIRES a shipping or billing address (a `400` otherwise, like the email requirement) so destination-based tax can be computed and folded into the binding total. When tax is disabled, no address is required.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "billingAddress": { "description": "Customer billing address, accepted progressively on create/reprice and persisted onto the `CheckoutSession`. An ordinary one-time checkout MUST supply a complete current billing address at bind before payment or free confirmation. Same-as-delivery callers send a second canonical snapshot equal to `shippingAddress`; distinct billing is sent independently. It is also the tax-calculation address when no shipping address is present.", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressDto" } ] }, "shippingRateId": { "type": "string", "description": "Optional id of the shopper-confirmed shipping option. Ignored on create. For ordinary checkout, choose a `rateId` ONLY from the latest `availableShippingOptions` for that checkout session; obtain or refresh the set with an address-bearing `POST /api/v1/public/checkout/sessions/{token}/reprice`. `GET /api/v1/public/shipping/zones` is configuration/eligibility and must not drive the ordinary-checkout picker. On reprice and bind (#1002), the server recomputes current eligibility and amount from server-owned configuration or a fresh quote, never a client amount (ADR-006). Reprice with an omitted or unresolvable selection yields no shipping and returns refreshed options. At bind, the missing-selection guard is a `400` only when the cart requires shipping and the freshly resolved option set is non-empty (#952); an all-service/digital cart is never forced to select a method. At bind, any supplied id is revalidated with the effective address; an invalid selection is a `400`. A FREE_SHIPPING coupon/auto-discount/bundle zeroes an eligible baseline-priced method; a pricier upgrade keeps its server-derived charge (#1014).", "maxLength": 100 }, "customer": { "description": "Customer contact. REQUIRED at bind (the pay step): its `name` must be non-blank so a CONFIRMED order carries a real customer name. A non-blank `email` is likewise required before payment (bind rejects a session that still has none — #605). The name/email may have been supplied at create or on an earlier reprice; if so this object can repeat them (or omit a field to leave the persisted value intact, provided the effective name and email are non-blank). Persisted onto the `CheckoutSession`; never trusted as authenticated identity.", "allOf": [ { "$ref": "#/components/schemas/BindCheckoutCustomerDto" } ] } }, "required": [ "lines", "customer" ] }, "CheckoutIdentityNextActionRequestDto": { "type": "object", "properties": { "email": { "type": "string", "description": "The checkout email to evaluate. Normalized server-side (trim + lowercase); resubmitting a normalization-equivalent value is idempotent, while a meaningful change advances the server-owned identity version.", "maxLength": 320, "example": "shopper@example.com" } }, "required": [ "email" ] }, "CheckoutIdentityNextActionResponseDto": { "type": "object", "properties": { "nextAction": { "type": "string", "description": "The neutral next step for this checkout email. `verify` means the shopper should verify this email before payment; `proceed` means continue as-is. The value is durable per server-owned identity version: repeating the same normalized email returns the same cached action.", "enum": [ "proceed", "verify" ], "example": "proceed" } }, "required": [ "nextAction" ] }, "CheckoutAccountSwitchAdmitRequestDto": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Stable opaque retry key for one account-switch admission. Preserve the original value across reloads and retries of the same in-progress checkout; a new value cannot take over a fenced epoch.", "minLength": 16, "maxLength": 128 } }, "required": [ "requestId" ] }, "CheckoutAccountSwitchAdmissionResponseDto": { "type": "object", "properties": { "epochId": { "type": "string", "description": "Opaque durable switch epoch identifier." }, "state": { "type": "string", "enum": [ "ADMITTED" ] }, "branch": { "type": "string", "enum": [ "RETURN_TO_A", "SWITCH_TO_B" ], "nullable": true, "description": "Exclusive recovery branch. Null means the switch is admitted but no RETURN_TO_A or SWITCH_TO_B branch has been claimed yet." } }, "required": [ "epochId", "state", "branch" ] }, "CheckoutAccountSwitchBranchRequestDto": { "type": "object", "properties": { "branch": { "type": "string", "enum": [ "RETURN_TO_A", "SWITCH_TO_B" ], "description": "RETURN_TO_A resumes the same verified Customer after safe release; SWITCH_TO_B requires the frozen A CustomerSession to be stale." }, "email": { "type": "string", "maxLength": 320, "description": "Chosen checkout contact email. The server normalizes trim and lowercase." } }, "required": [ "branch", "email" ] }, "CheckoutAccountSwitchBranchResponseDto": { "type": "object", "properties": { "epochId": { "type": "string" }, "branch": { "type": "string", "enum": [ "RETURN_TO_A", "SWITCH_TO_B" ] }, "nextAction": { "type": "string", "enum": [ "proceed", "verify" ], "description": "Neutral, cached identity next action for the claimed branch." } }, "required": [ "epochId", "branch", "nextAction" ] }, "CheckoutAccountSwitchStatusResponseDto": { "type": "object", "properties": { "epochId": { "type": "string" }, "state": { "type": "string", "enum": [ "FENCING", "ADMITTED" ] }, "branch": { "type": "string", "enum": [ "RETURN_TO_A", "SWITCH_TO_B" ], "nullable": true, "description": "Exclusive recovery branch. Null means no branch is claimed: either old payment fencing is still in progress or admission completed and awaits a branch claim; state distinguishes those cases." }, "isBinding": { "type": "boolean", "description": "Whether the current branch has a current checkout binding." }, "recoveryRequired": { "type": "boolean", "description": "True when old payment proof or local lineage needs recovery; never authorizes reuse of an old client secret." } }, "required": [ "epochId", "state", "branch", "isBinding", "recoveryRequired" ] }, "SubscriptionCheckoutHandoffDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PAYMENT", "SETUP", "NONE" ] }, "clientSecret": { "type": "string", "nullable": true }, "publishableKey": { "type": "string", "nullable": true }, "stripeAccountId": { "type": "string", "nullable": true }, "amountInCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "example": "usd" }, "recurringCardExplanation": { "type": "string", "description": "Customer-facing explanation of whether and why the card is stored for recurring off-session charges." }, "requiresContinuation": { "type": "boolean", "description": "True when a SETUP handoff must be confirmed before Billing creation continues. Headless clients replay the original start body with its idempotency key; hosted clients POST the opaque-token handoff endpoint again." } }, "required": [ "type", "clientSecret", "publishableKey", "stripeAccountId", "amountInCents", "currency", "recurringCardExplanation", "requiresContinuation" ] }, "SubscriptionCheckoutHandoffResponseDto": { "type": "object", "properties": { "purchaseMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION" ] }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ], "description": "Lifecycle status. Cart sessions begin OPEN; server-priced booking sessions begin PENDING_PAYMENT; subscription sessions are advanced only by verified Billing outcomes. Confirmation/expiry moves every flow forward." }, "isBinding": { "type": "boolean", "description": "For cart checkout, false after create/reprice (mutable estimate) and true after bind. Booking checkout is server-priced and true at creation. Subscription checkout becomes true only after its provider subscription and exact first invoice are verified. #604 refuses to create an ordinary payment session unless this is true." }, "contextType": { "type": "string", "enum": [ "CART", "BOOKING" ] }, "booking": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutBookingContextDto" } ] }, "subscription": { "nullable": true, "description": "Subscription-specific payment/order/renewal truth. Present only when purchaseMode is SUBSCRIPTION.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSubscriptionSummaryDto" } ] }, "refundInitiated": { "type": "boolean", "description": "True only when this session is CANCELLED *and* it was CHARGED then auto-refunded by the webhook-authoritative confirmation path (#871) — a stale-PI reprice amount/currency mismatch or an oversell-after-charge race flipped the session to CANCELLED and enqueued the per-attempt refund (`checkout-refund:${paymentAttemptId}` outbox, idempotent). It lets the hosted/BYO surface tell a charged-then-refunded CANCELLED session apart from a plain cancelled/expired one and render honest \"payment received — your refund is on the way\" copy instead of the generic not-payable block. Scoped to CANCELLED on purpose: the confirmation path also refunds an extra duplicate charge on an already-CONFIRMED session without cancelling it, so a refunded-event check alone is not sufficient. Customer-safe by construction: a single boolean derived from the presence of the internal `checkout_session.refunded` event — it carries NO processor ids, amounts, or failure detail. `false` on every session that is not a charged-then-refunded CANCELLED one (OPEN, EXPIRED, a plain CANCELLED, and CONFIRMED — including a CONFIRMED session whose duplicate charge was refunded)." }, "currency": { "type": "string", "description": "ISO currency code (e.g. `usd`)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionLineDto" } }, "packages": { "description": "Frozen package selections with every component, operational quantity, savings, tax, and total.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "selections": { "description": "Top-level server-accepted catalog selections for exact reprice/bind retry. Package components never replace their parent here.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSelectionLineDto" } }, "subtotalInCents": { "type": "number", "description": "Sum of gross line totals. For a trial subscription this still includes the recurring sticker price; the amount deferred by the trial appears in discountInCents so the due-today equation remains exact." }, "discountInCents": { "type": "number", "description": "Amount subtracted from the gross subtotal. For subscription checkout it can include recurring value deferred from the first invoice by a trial, not only promotional discounts." }, "taxInCents": { "type": "number", "description": "Computed sales tax folded into the binding total (#449, ADR-008). `0` when no tax provider is enabled (the default) — the reference storefronts read THIS instead of their flat-8% placeholder. Non-zero cart tax is computed at `bind` from the captured address; a booking session may instead carry its persisted tax-preflight posture at creation." }, "taxDisclosure": { "nullable": true, "description": "Customer-safe tax posture disclosure. Present when the transaction used the audited manual/no-tax escape hatch, so checkout/receipt surfaces can clearly state that litecommerce did not calculate tax.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "description": "Shipping charge folded into the binding total (#854). `0` until `bind` resolves a customer-selected `shippingRateId` against the active zone matching the captured address — the price is re-derived server-side from the rate (never a client amount, ADR-006). Stays `0` when no rate is selected or a FREE_SHIPPING coupon/auto-discount/bundle waives the charge (the chosen method is still recorded on the session). The hosted/BYO surface renders THIS as the shipping line." }, "totalInCents": { "type": "number", "description": "Commercial transaction total (`subtotal - discount + tax + shipping`). For cart/full-payment checkout this is also charged now; a booking deposit charges amountDueNowInCents instead (ADR-006). For a subscription this is the verified first-invoice total only, never the lifetime value or a future renewal amount." }, "amountDueNowInCents": { "type": "number", "description": "Amount due now. Equals totalInCents for carts/full payment, may be smaller for a booking deposit, and is the verified first-invoice amount for a subscription (0 for a no-card trial)." }, "remainingBalanceInCents": { "type": "number", "description": "Commercial balance remaining after the due-now amount for this checkout. Always 0 for subscription checkout; future renewals are described by subscription.nextRenewalAt and are not a checkout balance." }, "requiresFreeConfirmation": { "type": "boolean", "description": "#3263 — `true` when this bound checkout must be completed through `POST …/sessions/:token/confirm-free` rather than `payment-session`, because its total cannot be charged: either zero, or above zero but below the payment provider's per-currency minimum (which the provider rejects, surfacing as a generic 500). Surfaces are expected to branch on THIS FLAG rather than testing the total themselves — the minimum is a provider fact that varies by currency and changes on the provider schedule, so a client-side comparison duplicates a threshold that will drift. `false` on a non-binding session, since a session that has not bound has no server-authoritative total yet. Also `false` for booking, booking-group, and subscription checkouts: they have no no-charge completion path, so a below-minimum total there is refused rather than routed." }, "shippingMethod": { "nullable": true, "description": "The customer-selected shipping method (#854/#1002), so the hosted/BYO surface can show WHICH option is chosen before payment. Populated on reprice (a preview) AND bind (the commitment) when a resolvable `shippingRateId` is selected; `null` on create, and whenever no rate is selected or the selected rate does not resolve (on reprice it simply clears the estimate; on bind an invalid rate is a `400`). The charged amount is `shippingInCents`; this carries the method label and whether a FREE_SHIPPING rule waived the charge.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutShippingMethodDto" } ] }, "customer": { "nullable": true, "description": "#1170 — captured customer contact for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer. This keeps the anonymous session-read projection PII-free; #3231 deliberately exposes only the bound email through the separate payment-session handoff.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionCustomerDto" } ] }, "shippingAddress": { "nullable": true, "description": "#1170 — captured shipping address for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionAddressDto" } ] }, "shippingAddressValidation": { "nullable": true, "description": "#1563 — provider verdict on the shipping address, produced by the live-rate quote (validation rides the rate call). Present ONLY on reprice/bind responses when a live quote ran for this org (quoted, or failed on an invalid address); absent for tenants without live rates. PII posture (#1170/#606): echoes a cleaned form of the address the caller submitted on this request and is never present on anonymous session reads. #3231 separately permits that token to obtain only the bound email through the payment-session handoff, never this address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressValidationDto" } ] }, "availableShippingOptions": { "description": "For ordinary one-time checkout, server-derived shipping options applicable to the captured destination + cart subtotal (#1002), so the hosted/BYO surface can show — and let the shopper switch between — fulfillment methods BEFORE payment. Resolved from the active zone matching the address country, filtered to rates the subtotal clears. **Populated only on ordinary reprice/bind responses and on a read of an ordinary session that is not yet binding** (#3052): its create response and any read of a BOUND session return `[]` by design (no destination resolved yet, and the picker is a pre-payment surface the confirmation poll must not re-query). Physical-subscription summaries also return `[]`: that flow has no public option preflight (#3482), so this field is not its selection source. An empty array on those responses therefore means \"not offered here\", NOT \"no rates available\" — never let one clear a rendered option set or a confirmed selection. It is also empty when no address, zone, or applicable rate exists. For ordinary checkout, select one and resend its `rateId` as `shippingRateId`: reprice previews the resulting total; bind re-resolves and commits it only if it is still valid. The charged amount is always server-derived (ADR-006). An option is current only for the response it arrived on, not a promise that a later bind will succeed.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutShippingOptionDto" } }, "discountSnapshot": { "description": "Current server-authored discount attribution, persisted verbatim and copied onto the final order for attribution. The property is always present. It is an object for server-repriced cart/subscription sessions (even when no discount applies), and null only for booking, booking-group, or legacy sessions that have no discount snapshot. Within an object, `appliedCoupon: null` is the authoritative proof that no coupon is applied; aggregate discounts or totals can still reflect other rules. Only `appliedCoupon` is modeled by this schema; any additional server-authored attribution keys are intentionally not declared as public identifiers or schema fields.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutDiscountSnapshotDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "expiresAt": { "type": "string", "description": "When an unbound session may expire before provider creation. Once a durable provider-create intent exists, this timestamp remains useful for shopper messaging but authoritative reconciliation decides the outcome instead of a token read silently expiring provider-bound work. Null only in the (not-issued-here) no-expiry case.", "nullable": true, "format": "date-time" }, "reservationExpiresAt": { "type": "string", "description": "When a Mode-B (reserve-during-checkout) pre-payment inventory hold expires — the secondary countdown source for \"your items are held for N min\". Null under Mode A (reserve-at-confirmation, the only live mode today), where the session carries no hold. #605 Slice 3 ships this as a SEAM: it is populated only once Mode B is wired (no holds are minted in M3).", "nullable": true, "format": "date-time" }, "orderReference": { "type": "string", "description": "Stable public order address. Always present as a nullable field: null before finalOrderId exists and the exact non-null Order reference afterward. The locator is never an authentication credential.", "nullable": true, "pattern": "^or1_[0-9a-f]{32}$", "example": "or1_0123456789abcdef0123456789abcdef" }, "orderNumber": { "type": "string", "description": "The resulting order number once this session is CONFIRMED (#991) — the in-flow confirmation surface renders it as the post-payment receipt reference. Joined from `CheckoutSession.finalOrderId`; `null` on every non-confirmed read and on create/reprice/bind (no order exists yet). ALWAYS PRESENT (nullable), like `returnToStoreUrl` — every summary path emits it, so it belongs in the schema `required` set. Non-PII: the same `Order.orderNumber` the #818 order-status page and the signed-in account already show. The order-status `o`-token is hash-at-rest (ADR-007) and intentionally NOT reconstructable here, so this is a reference + account next-action, not a regenerated forwardable status link.", "nullable": true }, "orderConfirmationEmail": { "description": "#1965 — server-derived, customer-safe state of the order-confirmation email. Always present. It never includes the recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "returnToStoreUrl": { "type": "string", "description": "#1116 — the resolved safe return-to-store destination for hosted/BYO checkout surfaces. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "postCheckoutRedirectUrl": { "type": "string", "description": "#1116 — the resolved safe post-checkout completion destination. Prefers trusted `checkoutSettings.postCheckoutRedirectUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. Hosted checkout may auto-redirect here only after the server read shows CONFIRMED; never from a client-side processor callback. `null` only when no safe destination exists.", "nullable": true }, "checkoutRetryUrl": { "type": "string", "description": "#1116 — the resolved safe retry/start-over checkout destination. Prefers trusted `checkoutSettings.checkoutRetryUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "checkoutCancelUrl": { "type": "string", "description": "#1116 — the resolved safe canceled/expired checkout destination. Prefers trusted `checkoutSettings.checkoutCancelUrl`, then `checkoutRetryUrl`, `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "accountUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer account URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout account origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "accountSignInUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer sign-in URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout sign-in origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "#996 — whether the tenant enabled the hosted-checkout marketing opt-in (`checkoutSettings.marketingOptInEnabled`). When true, the surface shows a DEFAULT-UNCHECKED opt-in checkbox before payment and sends the shopper's choice as the bind `marketingOptIn`. ALWAYS PRESENT (in the schema `required` set); `false` unless the tenant turned it on." }, "marketingOptInCopy": { "type": "string", "description": "#996 — the label to render beside the opt-in checkbox when `marketingOptInEnabled` is true: the tenant-configured copy, else a safe default. Plain text (no URL). `null` when the opt-in is disabled (no checkbox). ALWAYS PRESENT (nullable).", "nullable": true }, "handoff": { "$ref": "#/components/schemas/SubscriptionCheckoutHandoffDto" } }, "required": [ "purchaseMode", "status", "isBinding", "contextType", "booking", "subscription", "refundInitiated", "currency", "lines", "packages", "selections", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "totalInCents", "amountDueNowInCents", "remainingBalanceInCents", "requiresFreeConfirmation", "customer", "shippingAddress", "availableShippingOptions", "discountSnapshot", "orderReference", "orderNumber", "orderConfirmationEmail", "returnToStoreUrl", "postCheckoutRedirectUrl", "checkoutRetryUrl", "checkoutCancelUrl", "accountUrl", "accountSignInUrl", "marketingOptInEnabled", "marketingOptInCopy", "handoff" ] }, "SubscriptionCheckoutRecurringLineDto": { "type": "object", "properties": { "planSlug": { "type": "string", "description": "Public/BYO subscription plan slug.", "maxLength": 160 }, "priceId": { "type": "string", "description": "Public local subscription price id returned by the plan read. Stripe ids are never accepted.", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "planSlug", "priceId", "quantity" ] }, "SubscriptionCheckoutCustomerDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 50 } }, "required": [ "email", "name" ] }, "CreateSubscriptionCheckoutDto": { "type": "object", "properties": { "recurringLines": { "minItems": 1, "maxItems": 20, "description": "Recurring selections. Every line must resolve to the same currency, cadence, connected account, and frozen trial policy.", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionCheckoutRecurringLineDto" } }, "oneTimeLines": { "maxItems": 20, "description": "Optional ordinary catalog lines billed once on the first subscription invoice through add_invoice_items. Prices are resolved server-side.", "type": "array", "items": { "$ref": "#/components/schemas/RepriceLineDto" } }, "customer": { "$ref": "#/components/schemas/SubscriptionCheckoutCustomerDto" }, "shippingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" }, "billingAddress": { "$ref": "#/components/schemas/CheckoutAddressDto" }, "shippingRateId": { "type": "string", "description": "Server-owned flat or live shipping rate id. Required when the physical cart has applicable shipping options.", "maxLength": 100 }, "marketingOptIn": { "type": "boolean", "description": "Customer marketing choice. It is stored only when the tenant enabled checkout marketing opt-in." } }, "required": [ "recurringLines", "customer" ] }, "CreateSubscriptionCheckoutResponseDto": { "type": "object", "properties": { "purchaseMode": { "type": "string", "enum": [ "ONE_TIME", "SUBSCRIPTION" ] }, "status": { "type": "string", "enum": [ "OPEN", "PENDING_PAYMENT", "CONFIRMED", "EXPIRED", "ABANDONED", "CANCELLED" ], "description": "Lifecycle status. Cart sessions begin OPEN; server-priced booking sessions begin PENDING_PAYMENT; subscription sessions are advanced only by verified Billing outcomes. Confirmation/expiry moves every flow forward." }, "isBinding": { "type": "boolean", "description": "For cart checkout, false after create/reprice (mutable estimate) and true after bind. Booking checkout is server-priced and true at creation. Subscription checkout becomes true only after its provider subscription and exact first invoice are verified. #604 refuses to create an ordinary payment session unless this is true." }, "contextType": { "type": "string", "enum": [ "CART", "BOOKING" ] }, "booking": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutBookingContextDto" } ] }, "subscription": { "nullable": true, "description": "Subscription-specific payment/order/renewal truth. Present only when purchaseMode is SUBSCRIPTION.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSubscriptionSummaryDto" } ] }, "refundInitiated": { "type": "boolean", "description": "True only when this session is CANCELLED *and* it was CHARGED then auto-refunded by the webhook-authoritative confirmation path (#871) — a stale-PI reprice amount/currency mismatch or an oversell-after-charge race flipped the session to CANCELLED and enqueued the per-attempt refund (`checkout-refund:${paymentAttemptId}` outbox, idempotent). It lets the hosted/BYO surface tell a charged-then-refunded CANCELLED session apart from a plain cancelled/expired one and render honest \"payment received — your refund is on the way\" copy instead of the generic not-payable block. Scoped to CANCELLED on purpose: the confirmation path also refunds an extra duplicate charge on an already-CONFIRMED session without cancelling it, so a refunded-event check alone is not sufficient. Customer-safe by construction: a single boolean derived from the presence of the internal `checkout_session.refunded` event — it carries NO processor ids, amounts, or failure detail. `false` on every session that is not a charged-then-refunded CANCELLED one (OPEN, EXPIRED, a plain CANCELLED, and CONFIRMED — including a CONFIRMED session whose duplicate charge was refunded)." }, "currency": { "type": "string", "description": "ISO currency code (e.g. `usd`)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionLineDto" } }, "packages": { "description": "Frozen package selections with every component, operational quantity, savings, tax, and total.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "selections": { "description": "Top-level server-accepted catalog selections for exact reprice/bind retry. Package components never replace their parent here.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSelectionLineDto" } }, "subtotalInCents": { "type": "number", "description": "Sum of gross line totals. For a trial subscription this still includes the recurring sticker price; the amount deferred by the trial appears in discountInCents so the due-today equation remains exact." }, "discountInCents": { "type": "number", "description": "Amount subtracted from the gross subtotal. For subscription checkout it can include recurring value deferred from the first invoice by a trial, not only promotional discounts." }, "taxInCents": { "type": "number", "description": "Computed sales tax folded into the binding total (#449, ADR-008). `0` when no tax provider is enabled (the default) — the reference storefronts read THIS instead of their flat-8% placeholder. Non-zero cart tax is computed at `bind` from the captured address; a booking session may instead carry its persisted tax-preflight posture at creation." }, "taxDisclosure": { "nullable": true, "description": "Customer-safe tax posture disclosure. Present when the transaction used the audited manual/no-tax escape hatch, so checkout/receipt surfaces can clearly state that litecommerce did not calculate tax.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "description": "Shipping charge folded into the binding total (#854). `0` until `bind` resolves a customer-selected `shippingRateId` against the active zone matching the captured address — the price is re-derived server-side from the rate (never a client amount, ADR-006). Stays `0` when no rate is selected or a FREE_SHIPPING coupon/auto-discount/bundle waives the charge (the chosen method is still recorded on the session). The hosted/BYO surface renders THIS as the shipping line." }, "totalInCents": { "type": "number", "description": "Commercial transaction total (`subtotal - discount + tax + shipping`). For cart/full-payment checkout this is also charged now; a booking deposit charges amountDueNowInCents instead (ADR-006). For a subscription this is the verified first-invoice total only, never the lifetime value or a future renewal amount." }, "amountDueNowInCents": { "type": "number", "description": "Amount due now. Equals totalInCents for carts/full payment, may be smaller for a booking deposit, and is the verified first-invoice amount for a subscription (0 for a no-card trial)." }, "remainingBalanceInCents": { "type": "number", "description": "Commercial balance remaining after the due-now amount for this checkout. Always 0 for subscription checkout; future renewals are described by subscription.nextRenewalAt and are not a checkout balance." }, "requiresFreeConfirmation": { "type": "boolean", "description": "#3263 — `true` when this bound checkout must be completed through `POST …/sessions/:token/confirm-free` rather than `payment-session`, because its total cannot be charged: either zero, or above zero but below the payment provider's per-currency minimum (which the provider rejects, surfacing as a generic 500). Surfaces are expected to branch on THIS FLAG rather than testing the total themselves — the minimum is a provider fact that varies by currency and changes on the provider schedule, so a client-side comparison duplicates a threshold that will drift. `false` on a non-binding session, since a session that has not bound has no server-authoritative total yet. Also `false` for booking, booking-group, and subscription checkouts: they have no no-charge completion path, so a below-minimum total there is refused rather than routed." }, "shippingMethod": { "nullable": true, "description": "The customer-selected shipping method (#854/#1002), so the hosted/BYO surface can show WHICH option is chosen before payment. Populated on reprice (a preview) AND bind (the commitment) when a resolvable `shippingRateId` is selected; `null` on create, and whenever no rate is selected or the selected rate does not resolve (on reprice it simply clears the estimate; on bind an invalid rate is a `400`). The charged amount is `shippingInCents`; this carries the method label and whether a FREE_SHIPPING rule waived the charge.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutShippingMethodDto" } ] }, "customer": { "nullable": true, "description": "#1170 — captured customer contact for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer. This keeps the anonymous session-read projection PII-free; #3231 deliberately exposes only the bound email through the separate payment-session handoff.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionCustomerDto" } ] }, "shippingAddress": { "nullable": true, "description": "#1170 — captured shipping address for an authenticated matching customer-session read. Always `null` on anonymous public reads and on authenticated reads for a different customer.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutSessionAddressDto" } ] }, "shippingAddressValidation": { "nullable": true, "description": "#1563 — provider verdict on the shipping address, produced by the live-rate quote (validation rides the rate call). Present ONLY on reprice/bind responses when a live quote ran for this org (quoted, or failed on an invalid address); absent for tenants without live rates. PII posture (#1170/#606): echoes a cleaned form of the address the caller submitted on this request and is never present on anonymous session reads. #3231 separately permits that token to obtain only the bound email through the payment-session handoff, never this address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutAddressValidationDto" } ] }, "availableShippingOptions": { "description": "For ordinary one-time checkout, server-derived shipping options applicable to the captured destination + cart subtotal (#1002), so the hosted/BYO surface can show — and let the shopper switch between — fulfillment methods BEFORE payment. Resolved from the active zone matching the address country, filtered to rates the subtotal clears. **Populated only on ordinary reprice/bind responses and on a read of an ordinary session that is not yet binding** (#3052): its create response and any read of a BOUND session return `[]` by design (no destination resolved yet, and the picker is a pre-payment surface the confirmation poll must not re-query). Physical-subscription summaries also return `[]`: that flow has no public option preflight (#3482), so this field is not its selection source. An empty array on those responses therefore means \"not offered here\", NOT \"no rates available\" — never let one clear a rendered option set or a confirmed selection. It is also empty when no address, zone, or applicable rate exists. For ordinary checkout, select one and resend its `rateId` as `shippingRateId`: reprice previews the resulting total; bind re-resolves and commits it only if it is still valid. The charged amount is always server-derived (ADR-006). An option is current only for the response it arrived on, not a promise that a later bind will succeed.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutShippingOptionDto" } }, "discountSnapshot": { "description": "Current server-authored discount attribution, persisted verbatim and copied onto the final order for attribution. The property is always present. It is an object for server-repriced cart/subscription sessions (even when no discount applies), and null only for booking, booking-group, or legacy sessions that have no discount snapshot. Within an object, `appliedCoupon: null` is the authoritative proof that no coupon is applied; aggregate discounts or totals can still reflect other rules. Only `appliedCoupon` is modeled by this schema; any additional server-authored attribution keys are intentionally not declared as public identifiers or schema fields.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutDiscountSnapshotDto" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "expiresAt": { "type": "string", "description": "When an unbound session may expire before provider creation. Once a durable provider-create intent exists, this timestamp remains useful for shopper messaging but authoritative reconciliation decides the outcome instead of a token read silently expiring provider-bound work. Null only in the (not-issued-here) no-expiry case.", "nullable": true, "format": "date-time" }, "reservationExpiresAt": { "type": "string", "description": "When a Mode-B (reserve-during-checkout) pre-payment inventory hold expires — the secondary countdown source for \"your items are held for N min\". Null under Mode A (reserve-at-confirmation, the only live mode today), where the session carries no hold. #605 Slice 3 ships this as a SEAM: it is populated only once Mode B is wired (no holds are minted in M3).", "nullable": true, "format": "date-time" }, "orderReference": { "type": "string", "description": "Stable public order address. Always present as a nullable field: null before finalOrderId exists and the exact non-null Order reference afterward. The locator is never an authentication credential.", "nullable": true, "pattern": "^or1_[0-9a-f]{32}$", "example": "or1_0123456789abcdef0123456789abcdef" }, "orderNumber": { "type": "string", "description": "The resulting order number once this session is CONFIRMED (#991) — the in-flow confirmation surface renders it as the post-payment receipt reference. Joined from `CheckoutSession.finalOrderId`; `null` on every non-confirmed read and on create/reprice/bind (no order exists yet). ALWAYS PRESENT (nullable), like `returnToStoreUrl` — every summary path emits it, so it belongs in the schema `required` set. Non-PII: the same `Order.orderNumber` the #818 order-status page and the signed-in account already show. The order-status `o`-token is hash-at-rest (ADR-007) and intentionally NOT reconstructable here, so this is a reference + account next-action, not a regenerated forwardable status link.", "nullable": true }, "orderConfirmationEmail": { "description": "#1965 — server-derived, customer-safe state of the order-confirmation email. Always present. It never includes the recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "returnToStoreUrl": { "type": "string", "description": "#1116 — the resolved safe return-to-store destination for hosted/BYO checkout surfaces. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "postCheckoutRedirectUrl": { "type": "string", "description": "#1116 — the resolved safe post-checkout completion destination. Prefers trusted `checkoutSettings.postCheckoutRedirectUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. Hosted checkout may auto-redirect here only after the server read shows CONFIRMED; never from a client-side processor callback. `null` only when no safe destination exists.", "nullable": true }, "checkoutRetryUrl": { "type": "string", "description": "#1116 — the resolved safe retry/start-over checkout destination. Prefers trusted `checkoutSettings.checkoutRetryUrl`, then `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "checkoutCancelUrl": { "type": "string", "description": "#1116 — the resolved safe canceled/expired checkout destination. Prefers trusted `checkoutSettings.checkoutCancelUrl`, then `checkoutRetryUrl`, `returnToStoreUrl`, then the tenant storefront origin / neutral fallback. `null` only when no safe destination exists.", "nullable": true }, "accountUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer account URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout account origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "accountSignInUrl": { "type": "string", "description": "#1116/#1117 — the resolved customer sign-in URL for post-checkout and terminal-state CTAs. Built from trusted `customerActionBaseUrl` when configured, otherwise the hosted litecheckout sign-in origin. `null` only when no customer-action origin can be resolved.", "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "#996 — whether the tenant enabled the hosted-checkout marketing opt-in (`checkoutSettings.marketingOptInEnabled`). When true, the surface shows a DEFAULT-UNCHECKED opt-in checkbox before payment and sends the shopper's choice as the bind `marketingOptIn`. ALWAYS PRESENT (in the schema `required` set); `false` unless the tenant turned it on." }, "marketingOptInCopy": { "type": "string", "description": "#996 — the label to render beside the opt-in checkbox when `marketingOptInEnabled` is true: the tenant-configured copy, else a safe default. Plain text (no URL). `null` when the opt-in is disabled (no checkbox). ALWAYS PRESENT (nullable).", "nullable": true }, "handoff": { "$ref": "#/components/schemas/SubscriptionCheckoutHandoffDto" }, "token": { "type": "string", "description": "Fresh opaque shared checkout token. Only its hash is retained; safe idempotent replays mint a new resume token." } }, "required": [ "purchaseMode", "status", "isBinding", "contextType", "booking", "subscription", "refundInitiated", "currency", "lines", "packages", "selections", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "totalInCents", "amountDueNowInCents", "remainingBalanceInCents", "requiresFreeConfirmation", "customer", "shippingAddress", "availableShippingOptions", "discountSnapshot", "orderReference", "orderNumber", "orderConfirmationEmail", "returnToStoreUrl", "postCheckoutRedirectUrl", "checkoutRetryUrl", "checkoutCancelUrl", "accountUrl", "accountSignInUrl", "marketingOptInEnabled", "marketingOptInCopy", "handoff", "token" ] }, "BookingGroupPaymentSessionResponseDto": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/PublicBookingGroupResponseDto" }, "payment": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PaymentSessionResponseDto" } ] } }, "required": [ "group", "payment" ] }, "OrderShippingMethodDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Frozen customer-facing exact-method or delivery-promise name (e.g. \"UPS Ground\" or \"Standard\")." }, "priceInCents": { "type": "number", "description": "The rate's own price in minor units (cents). The amount actually charged on the order is `shippingInCents` — `0` when a FREE_SHIPPING rule waived it (`freeShipping` is then true while this keeps the rate sticker)." }, "freeShipping": { "type": "boolean", "description": "True when a FREE_SHIPPING coupon/auto-discount/bundle waived the charge: the method is still recorded but `shippingInCents` is `0`." }, "presentationMode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ], "description": "#2000 — frozen checkout presentation mode. Absent on legacy orders." }, "description": { "type": "string", "nullable": true, "description": "Frozen customer promise description, when configured." }, "deliveryEstimate": { "nullable": true, "description": "Absolute customer delivery bounds frozen at checkout bind.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutDeliveryEstimateDto" } ] }, "estimatedDelivery": { "type": "string", "description": "#3515 — the human-facing delivery-estimate text committed at checkout bind (e.g. \"2-3 business days\"), from the live carrier quote or the flat rate’s configured estimate. A checkout-time estimate, never a live carrier prediction. Omitted from this customer projection when valid structured `deliveryEstimate` bounds take precedence, even if the internal snapshot also retains the original text; otherwise absent when checkout showed none." } }, "required": [ "name", "priceInCents", "freeShipping" ] }, "OrderShipmentDeliveryEstimateDto": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "purchased_service", "carrier_tracking" ], "description": "Origin of this post-checkout estimate. Purchased-service and later carrier-tracking facts remain distinct from the checkout commitment." }, "estimatedAt": { "type": "string", "format": "date-time", "description": "When this estimate evidence was recorded." }, "deliveryDate": { "type": "string", "format": "date", "nullable": true, "description": "The PROVIDER's own projected delivery date (ISO yyyy-MM-dd), taken from label-selection evidence whose recommended carrier/service matches the service actually purchased. Null when the provider supplied no such projection — including every exact-service, manual-rate, and uncaptured-service purchase, where the provider never projects one. This field carries provider evidence ONLY and is never populated by a platform computation; see `derivedDeliveryDate` for that. Null here therefore does not mean \"no arrival date is known\"." }, "derivedDeliveryDate": { "type": "string", "format": "date", "nullable": true, "description": "#3645 — a tenant-local arrival date (ISO yyyy-MM-dd) the PLATFORM derived: the shipment's proven carrier-handoff timestamp advanced by the carrier's structured transit-day count. It is the carrier's own transit evidence expressed as a calendar date, not a provider prediction, and must be presented with that hedge. Null for three reasons a consumer does NOT need to tell apart: a provider projection is published in `deliveryDate` instead, the carrier supplied no structured transit days, or the shipment has no proven handoff time (label-selection time is never substituted — it precedes handoff and would promise an arrival the parcel cannot meet). At most one of these two date fields is ever non-null, so \"the best known arrival date\" is `deliveryDate ?? derivedDeliveryDate`, and which field carries it is itself the provenance." }, "expiresOn": { "type": "string", "format": "date", "nullable": true, "description": "Inclusive tenant-local date through which this evidence can remain current. Null means no trustworthy expiry bound was available, so post-purchase surfaces treat the wording as historical only. This is a presentation rule, not an arrival fact, and it is computed from a different anchor than `derivedDeliveryDate` on purpose: an expiry bound may fall back to label-selection time because expiring evidence EARLY is conservative, while an arrival date may not. A shipment with no proven handoff time therefore carries a bound here and no arrival date in either date field." }, "estimatedDelivery": { "type": "string", "nullable": true, "description": "Bounded provider delivery wording, or null when only `deliveryDate` is available." } }, "required": [ "source", "estimatedAt", "deliveryDate", "derivedDeliveryDate", "expiresOn", "estimatedDelivery" ] }, "OrderShipmentDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED", "CANCELLED" ], "example": "SHIPPED" }, "carrier": { "type": "string", "nullable": true, "example": "UPS", "description": "Carrier label entered by the merchant, or null when absent." }, "serviceLevel": { "type": "string", "nullable": true, "example": "Ground", "description": "Optional merchant-entered service level." }, "trackingNumber": { "type": "string", "nullable": true, "example": "1Z999AA10123456784", "description": "Carrier tracking number, or null when absent." }, "trackingUrl": { "type": "string", "nullable": true, "example": "https://www.ups.com/track?tracknum=1Z999AA10123456784", "description": "Carrier tracking URL, or null when not supplied." }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the shipment left the merchant/carrier, or null." }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the shipment was delivered, or null." }, "deliverySource": { "type": "string", "nullable": true, "description": "#4049 - how this delivery was established. Open-ended catalog: see x-extensible-enum for the known stable values and treat any unrecognized value as neither merchant- nor carrier-confirmed. MERCHANT_CONFIRMED means the seller asserted receipt; it is NOT carrier confirmation. CARRIER_CONFIRMED means a verified carrier delivery event established receipt (#4054). Null means no provenance was established, which is also not carrier confirmation. The merchant's internal reason and the acting user are deliberately absent from this customer-facing projection.", "x-extensible-enum": [ "MERCHANT_CONFIRMED", "CARRIER_CONFIRMED" ] }, "deliveryEstimate": { "nullable": true, "description": "#3515 — latest customer-safe post-checkout estimate attached to this shipment. Null when no trustworthy purchased-service or carrier tracking evidence is available.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderShipmentDeliveryEstimateDto" } ] } }, "required": [ "status", "carrier", "serviceLevel", "trackingNumber", "trackingUrl", "shippedAt", "deliveredAt", "deliverySource", "deliveryEstimate" ] }, "OrderStatusItemDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Trail Tent 2P" }, "productName": { "type": "string", "nullable": true, "example": "Deodorant", "description": "#3972 (UAT F08) — the PRODUCT half of `name`, or `null` when the frozen line name was not segmented. `name` remains the authoritative frozen purchase identity and is unchanged; this field and `variantName` are an additive, lossless view of it — they are non-null TOGETHER or not at all, and when present `productName + \" — \" + variantName` reconstructs `name` exactly. So a non-null value here is always a real product half, never a whole combined name. `null` means render `name` as a single line: a line whose `name` was NOT written by a shared-pricing writer (the legacy public quote route stores a caller-supplied label, which proves nothing about product/variant structure), an item-level line with no variant, a product OR variant renamed or deleted since purchase, or a catalog name that itself contains the \" — \" separator. The server never splits on a hyphen and never parses the stored value: it requires a proven pricing origin, then segments only when BOTH current catalog names are separator-free AND rebuild the stored string exactly, which makes the decomposition unique and therefore the historical one. No frozen product/variant halves are persisted, so any line outside that provable shape reports null rather than a guessed boundary." }, "variantName": { "type": "string", "nullable": true, "example": "Unscented", "description": "#3972 (UAT F08) — the VARIANT half of `name`, exactly as the catalog stores it (never trimmed, so the two halves rejoin losslessly). `null` whenever `productName` is `null`; the two are always resolved together." }, "imageUrl": { "type": "string", "nullable": true, "example": "https://cdn.example.com/items/trail-tent.jpg", "description": "Catalog thumbnail URL snapshotted on the order line at confirmation (#982). `null` when the item had no image — render a placeholder. A public catalog asset URL: no PII and no database id, consistent with this projection's status-safe whitelist." }, "quantity": { "type": "number", "example": 2 }, "unitPriceInCents": { "type": "number", "example": 14900 }, "totalPriceInCents": { "type": "number", "example": 29800 }, "isPackageComponent": { "type": "boolean", "description": "True when this compatibility row is represented inside packages[].components." } }, "required": [ "name", "productName", "variantName", "imageUrl", "quantity", "unitPriceInCents", "totalPriceInCents", "isPackageComponent" ] }, "OrderStatusResponseDto": { "type": "object", "properties": { "orderReference": { "type": "string", "nullable": true, "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$", "description": "Stable public order address. `null` only for a legacy status token whose Order is awaiting the measured reference backfill. This value is a locator, never an authentication credential." }, "orderNumber": { "type": "string", "example": "ACME-2026-042" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0 }, "taxInCents": { "type": "number", "example": 1788 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders with no such snapshot.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "example": 0, "description": "Shipping charged on the order in minor units (#854) — `0` when the order needed no shipping or a FREE_SHIPPING rule waived it. Already folded into `totalInCents`; exposed here so the status page can itemize it instead of hiding it in the total. Carries no PII." }, "shippingMethod": { "nullable": true, "description": "The immutable exact selection or delivery promise captured on `Order.shippingMethod` at confirmation (#1769/#2415). For orders confirmed before that snapshot was introduced, the original frozen checkout selection is returned when the Order snapshot is absent. `null` when the authoritative source has no valid recorded snapshot. Carries only customer-safe frozen presentation data — no `rateId`, original quote, actual shipment, address, other PII, or database ids — so it is safe on this forwardable token surface.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderShippingMethodDto" } ] }, "shipments": { "description": "#1562 — customer-safe handed-off and delivered shipment history. PLANNED and READY preparation is excluded; tracking fields may be null when the carrier supplied no tracking. Carries no raw database ids.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "shipmentDeliveryComplete": { "type": "boolean", "description": "True only when at least one non-cancelled fulfillment exists and every non-cancelled fulfillment is DELIVERED. This server-derived flag includes PLANNED and READY fulfillments intentionally omitted from `shipments`; an empty or all-delivered visible array alone cannot establish completion." }, "totalInCents": { "type": "number", "example": 31588 }, "createdAt": { "type": "string", "example": "2026-06-09T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-09T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatusItemDto" } }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "returnToStoreUrl": { "type": "string", "nullable": true, "example": "https://shop.example.com", "description": "#1116 — the resolved safe return-to-store destination for the hosted order-status surface. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists." }, "customerActionRedirectUrl": { "type": "string", "nullable": true, "example": "https://shop.example.com/order/oabc123abc123abc123abc123a/status", "description": "#1656 — the equivalent order-status URL on the tenant's current trusted BYO customer-action origin. Populated only when `checkoutSettings.customerActionBaseUrl` resolves through the shared trusted-origin gate to a BYO origin distinct from this tenant's hosted litecheckout origin. `null` for blank, invalid, untrusted, hosted, or self-looping configuration, so hosted litecheckout renders normally. Carries only the existing opaque order-status token; no PII or database ids." } }, "required": [ "orderReference", "orderNumber", "status", "fulfillmentStatus", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "shippingMethod", "shipments", "shipmentDeliveryComplete", "totalInCents", "createdAt", "updatedAt", "items", "packages", "returnToStoreUrl", "customerActionRedirectUrl" ] }, "OrderConfirmationByReferenceDto": { "type": "object", "properties": { "orderNumber": { "type": "string", "example": "ACME-2026-042" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0 }, "taxInCents": { "type": "number", "example": 1788 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders with no such snapshot.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "example": 0, "description": "Shipping charged on the order in minor units (#854) — `0` when the order needed no shipping or a FREE_SHIPPING rule waived it. Already folded into `totalInCents`; exposed here so the status page can itemize it instead of hiding it in the total. Carries no PII." }, "shippingMethod": { "nullable": true, "description": "The immutable exact selection or delivery promise captured on `Order.shippingMethod` at confirmation (#1769/#2415). For orders confirmed before that snapshot was introduced, the original frozen checkout selection is returned when the Order snapshot is absent. `null` when the authoritative source has no valid recorded snapshot. Carries only customer-safe frozen presentation data — no `rateId`, original quote, actual shipment, address, other PII, or database ids — so it is safe on this forwardable token surface.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderShippingMethodDto" } ] }, "shipments": { "description": "#1562 — customer-safe handed-off and delivered shipment history. PLANNED and READY preparation is excluded; tracking fields may be null when the carrier supplied no tracking. Carries no raw database ids.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "shipmentDeliveryComplete": { "type": "boolean", "description": "True only when at least one non-cancelled fulfillment exists and every non-cancelled fulfillment is DELIVERED. This server-derived flag includes PLANNED and READY fulfillments intentionally omitted from `shipments`; an empty or all-delivered visible array alone cannot establish completion." }, "totalInCents": { "type": "number", "example": 31588 }, "createdAt": { "type": "string", "example": "2026-06-09T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-09T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatusItemDto" } }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "returnToStoreUrl": { "type": "string", "nullable": true, "example": "https://shop.example.com", "description": "#1116 — the resolved safe return-to-store destination for the hosted order-status surface. Prefers trusted `checkoutSettings.returnToStoreUrl`; when blank or untrusted, falls back to the tenant storefront origin, then the operator neutral fallback. `null` only when no safe destination exists." }, "orderReference": { "type": "string", "nullable": false, "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$", "description": "The exact active Order reference resolved for this confirmation. This by-reference route is unavailable until the Order has one." } }, "required": [ "orderNumber", "status", "fulfillmentStatus", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "shippingInCents", "shippingMethod", "shipments", "shipmentDeliveryComplete", "totalInCents", "createdAt", "updatedAt", "items", "packages", "returnToStoreUrl", "orderReference" ] }, "OrderAddressSnapshotDto": { "type": "object", "properties": { "company": { "type": "string", "description": "Company or organization name captured for this destination.", "example": "litecommerce QA" }, "line1": { "type": "string", "example": "500 W Main St" }, "line2": { "type": "string", "example": "Suite 200" }, "city": { "type": "string", "example": "Boise" }, "state": { "type": "string", "description": "State, province, region, or other first-level subdivision.", "example": "ID" }, "postalCode": { "type": "string", "description": "Postal code captured verbatim, including formats such as ZIP+4 or international spaces.", "example": "83702-5920" }, "zip": { "type": "string", "deprecated": true, "description": "Legacy/import compatibility key. New checkout snapshots use `postalCode`.", "example": "83702" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code captured at checkout.", "example": "US" } } }, "PublicOrderLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "The ordered variant, or `null` for item-level lines." }, "name": { "type": "string", "description": "Display name snapshotted on the line at order time.", "example": "Trail Tent 2P" }, "quantity": { "type": "number", "example": 2 }, "unitPriceInCents": { "type": "number", "example": 14900 }, "totalPriceInCents": { "type": "number", "example": 29800 }, "isPackageComponent": { "type": "boolean" } }, "required": [ "id", "itemId", "variantId", "name", "quantity", "unitPriceInCents", "totalPriceInCents", "isPackageComponent" ] }, "PublicOrderDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "deprecated": true, "description": "Legacy persistence identifier retained during the measured compatibility window. New consumers use orderReference." }, "orderReference": { "type": "string", "nullable": true, "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$", "description": "Stable public order address. `null` only for a legacy row awaiting the measured reference backfill. Possession does not authenticate or authorize access." }, "orderNumber": { "type": "string", "description": "Human-facing, tenant-scoped order number.", "example": "ACME-2026-042" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "customerName": { "type": "string", "description": "Buyer name captured at checkout (the confirmation greeting)." }, "customerEmail": { "type": "string", "description": "Buyer email captured at checkout. Doubles as the shared-secret match for the by-number read and the account/returns flow.", "format": "email" }, "shippingAddress": { "nullable": true, "description": "The order's immutable shipping address snapshot. `null` when the order had no shipping address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "nullable": true, "description": "The order's immutable billing address snapshot. `null` when the order had no billing address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0, "description": "Total discount applied, in minor units (the scalar only — the rule-attribution `discountSnapshot` is merchant-internal)." }, "taxInCents": { "type": "number", "example": 1788 }, "totalInCents": { "type": "number", "example": 31588 }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOrderLineDto" } }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } } }, "required": [ "id", "orderReference", "orderNumber", "status", "fulfillmentStatus", "customerName", "customerEmail", "shippingAddress", "billingAddress", "subtotalInCents", "discountInCents", "taxInCents", "totalInCents", "createdAt", "updatedAt", "items", "packages" ] }, "CreateOrderItemDto": { "type": "object", "properties": { "itemId": { "type": "string" }, "variantId": { "type": "string", "nullable": true, "description": "Catalog variant selection. Omit or send `null` for the item-level selection. For SALE items, item-level selection is accepted only when the catalog item has no live or archived variants; otherwise supply a live variant ID. RENTAL and SERVICE items may remain item-level because they do not reserve stock." }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999, "description": "Quantity on this submitted raw row. Across all rows with the same `(itemId, variantId)` selection, the combined quantity must not exceed 999 units; omitted and `null` variantId values both identify the item-level selection." } }, "required": [ "itemId", "name", "quantity" ], "additionalProperties": false }, "CreateOrderDto": { "type": "object", "properties": { "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "customerPhone": { "type": "string", "nullable": true }, "items": { "minItems": 1, "maxItems": 100, "description": "The submitted quote rows before duplicate selections are grouped. A request accepts at most 100 raw rows.", "type": "array", "items": { "$ref": "#/components/schemas/CreateOrderItemDto" } }, "bookingId": { "type": "string", "nullable": true }, "notes": { "type": "string" } }, "required": [ "customerName", "customerEmail", "items" ], "additionalProperties": false }, "MerchantOrderCustomerPromiseDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "exact_service", "delivery_promise" ] }, "tierId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "chargeInCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "example": "usd" }, "pricingPolicy": { "type": "string", "enum": [ "carrier_cost" ] }, "roundingRule": { "type": "string", "enum": [ "integer_minor_units" ] }, "displayStyle": { "type": "string", "enum": [ "ship_by", "delivery_window", "both" ] }, "shipByDate": { "type": "string", "format": "date", "nullable": true }, "deliveryStartDate": { "type": "string", "format": "date", "nullable": true }, "deliveryEndDate": { "type": "string", "format": "date", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "settingsRevision": { "type": "string", "format": "date-time", "nullable": true }, "ruleRevision": { "type": "string", "format": "date-time" } }, "required": [ "kind", "tierId", "name", "description", "chargeInCents", "currency", "pricingPolicy", "roundingRule", "displayStyle", "shipByDate", "deliveryStartDate", "deliveryEndDate", "timezone", "settingsRevision", "ruleRevision" ] }, "MerchantOrderQuoteAddressInputDto": { "type": "object", "properties": { "name": { "type": "string" }, "companyName": { "type": "string" }, "phone": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "cityLocality": { "type": "string" }, "stateProvince": { "type": "string" }, "postalCode": { "type": "string" }, "countryCode": { "type": "string", "example": "US" } }, "required": [ "name", "addressLine1", "cityLocality", "stateProvince", "postalCode", "countryCode" ] }, "MerchantOrderQuotePackageDimensionsDto": { "type": "object", "properties": { "length": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "unit": { "type": "string", "enum": [ "inch", "centimeter" ] } }, "required": [ "length", "width", "height", "unit" ] }, "MerchantOrderQuotePackageInputDto": { "type": "object", "properties": { "weightValue": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "weightUnit": { "type": "string", "enum": [ "pound", "ounce", "gram", "kilogram" ] }, "dimensions": { "$ref": "#/components/schemas/MerchantOrderQuotePackageDimensionsDto" }, "packageCode": { "type": "string" } }, "required": [ "weightValue", "weightUnit" ] }, "MerchantOrderQuoteRatingInputsDto": { "type": "object", "properties": { "shipFrom": { "$ref": "#/components/schemas/MerchantOrderQuoteAddressInputDto" }, "shipTo": { "$ref": "#/components/schemas/MerchantOrderQuoteAddressInputDto" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrderQuotePackageInputDto" } }, "carrierIds": { "type": "array", "items": { "type": "string" } }, "serviceCodes": { "type": "array", "items": { "type": "string" } }, "validateAddress": { "type": "string", "enum": [ "no_validation", "validate_only", "validate_and_clean" ] } }, "required": [ "shipFrom", "shipTo", "packages", "carrierIds", "validateAddress" ] }, "MerchantOrderQuoteCostComponentDto": { "type": "object", "properties": { "sourceAmount": { "type": "number", "minimum": 0, "description": "Provider-authored amount in major currency units." }, "amountInMinorUnits": { "type": "integer", "minimum": 0 } }, "required": [ "sourceAmount", "amountInMinorUnits" ] }, "MerchantOrderQuoteCostComponentsDto": { "type": "object", "properties": { "shipping": { "$ref": "#/components/schemas/MerchantOrderQuoteCostComponentDto" }, "insurance": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderQuoteCostComponentDto" } ] }, "confirmation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderQuoteCostComponentDto" } ] }, "other": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderQuoteCostComponentDto" } ] } }, "required": [ "shipping", "insurance", "confirmation", "other" ] }, "MerchantOrderQuoteCostEvidenceDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "sourceUnit": { "type": "string", "enum": [ "major_currency_units" ] }, "minorUnitExponent": { "type": "integer", "minimum": 0, "maximum": 3 }, "roundingRule": { "type": "string", "enum": [ "round_half_up_each_component" ] }, "components": { "$ref": "#/components/schemas/MerchantOrderQuoteCostComponentsDto" }, "totalSourceAmount": { "type": "number", "minimum": 0 }, "totalInMinorUnits": { "type": "integer", "minimum": 0 } }, "required": [ "currency", "sourceUnit", "minorUnitExponent", "roundingRule", "components", "totalSourceAmount", "totalInMinorUnits" ] }, "MerchantOrderOriginalQuoteDto": { "type": "object", "properties": { "rateId": { "type": "string" }, "serviceName": { "type": "string" }, "serviceCode": { "type": "string" }, "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "priceInCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "example": "usd" }, "transitMinDays": { "type": "integer", "minimum": 0, "nullable": true }, "transitMaxDays": { "type": "integer", "minimum": 0, "nullable": true }, "estimatedDelivery": { "type": "string", "nullable": true }, "quotedAt": { "type": "string", "format": "date-time" }, "zoneId": { "type": "string", "format": "uuid" }, "settingsRevision": { "type": "string", "format": "date-time", "nullable": true }, "ruleRevision": { "type": "string", "format": "date-time" }, "ratingInputs": { "description": "#2000 / ADR-023 — normalized, secret-free request facts needed to reproduce the original carrier quote after settings change.", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderQuoteRatingInputsDto" } ] }, "costEvidence": { "description": "#2000 / ADR-023 — immutable provider component values plus the minor-unit conversion and rounding applied at quote time.", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderQuoteCostEvidenceDto" } ] } }, "required": [ "rateId", "serviceName", "serviceCode", "carrierId", "carrierName", "priceInCents", "currency", "transitMinDays", "transitMaxDays", "estimatedDelivery", "quotedAt", "zoneId", "settingsRevision", "ruleRevision", "ratingInputs", "costEvidence" ] }, "MerchantOrderShippingMethodDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer-facing method/rate name (e.g. \"Standard\")." }, "priceInCents": { "type": "number", "description": "The rate's own price in minor units (cents). The amount actually charged on the order is `shippingInCents` — `0` when a FREE_SHIPPING rule waived it (`freeShipping` is then true while this keeps the rate sticker)." }, "freeShipping": { "type": "boolean", "description": "True when a FREE_SHIPPING coupon/auto-discount/bundle waived the charge: the method is still recorded but `shippingInCents` is `0`." }, "serviceCode": { "type": "string", "description": "Live provider rates only — the carrier's stable service code the customer bought (e.g. `ups_ground`). Absent for merchant-defined flat rates and when the live quote was no longer joinable at confirmation." }, "carrierId": { "type": "string", "description": "Live provider rates only — the provider's carrier id the service was quoted on. Absent for flat rates." }, "estimatedDelivery": { "type": "string", "description": "Relative delivery wording recorded at checkout for a live provider service or configured/free method. A configured/free method can carry this text alongside `deliveryEstimate`. When both are present, prefer the validated absolute estimate; use this wording only when it is absent. Absent when no text was recorded. This is not a later carrier tracking prediction." }, "deliveryEstimate": { "description": "Validated absolute platform estimate frozen at checkout for configured/free methods, with display style, ship-by date, and inclusive arrival bounds. When present, prefer it over `estimatedDelivery` for purchase guidance. Absent when no valid frozen estimate exists; it does not represent later carrier tracking.", "allOf": [ { "$ref": "#/components/schemas/CheckoutDeliveryEstimateDto" } ] }, "presentationMode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ], "description": "#2000 — checkout presentation mode frozen on this order." }, "promiseFallback": { "type": "boolean", "description": "#3266 — `true` when checkout was in `delivery_promises` mode but produced no promise, so the customer was offered — and bought — an ordinary live carrier service as a fallback. Absent otherwise. Fulfil against the carrier service named here: there is no matched delivery promise on this order, and the customer was never shown one. `promiseFallbackReason` carries the frozen cause. Merchant-facing only; the customer-facing order-status and checkout-session projections deliberately omit it." }, "promiseFallbackReason": { "type": "string", "enum": [ "no_tier_matched", "structured_dates_unavailable" ], "description": "#3266 — why the fallback fired, frozen at checkout. `no_tier_matched`: the enabled zone promise tiers were evaluated against this quote and none qualified. `structured_dates_unavailable`: promise evaluation never ran, because the store had no structured delivery estimates (or no timezone) at quote time — so no tier-match claim is made. Present only alongside `promiseFallback`; may be absent on a fallback order whose cause was not recorded." }, "customerPromise": { "description": "#2000 — immutable customer-facing selection/promise, charge, and absolute delivery bounds. Kept separate from provider quote/purchase.", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderCustomerPromiseDto" } ] }, "originalQuote": { "description": "#2000 — immutable original provider quote anchor and rule revisions. The actual purchased label service remains on shipping-label evidence.", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderOriginalQuoteDto" } ] } }, "required": [ "name", "priceInCents", "freeShipping" ] }, "MerchantOrderShippingLabelDto": { "type": "object", "properties": { "labelId": { "type": "string", "description": "The provider's label id — the void handle (#1803)." }, "trackingNumber": { "type": "string", "nullable": true, "description": "Carrier tracking number, or null (needs-tracking) when absent." }, "labelDownloadUrl": { "type": "string", "nullable": true, "description": "Direct URL to the printable PDF label, or null." }, "shipmentCostInCents": { "type": "number", "nullable": true, "description": "Charged label cost in integer cents, or null." }, "shipmentCostCurrency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "description": "Validated lowercase ISO-4217 currency for the charged label cost, or null for legacy rows without monetary evidence.", "example": "usd" }, "carrierName": { "type": "string", "nullable": true, "description": "Friendly carrier name the label was bought against." }, "serviceCode": { "type": "string", "nullable": true, "description": "Service code the label was bought against." }, "serviceDecisionClassification": { "type": "string", "enum": [ "ORIGINAL_SERVICE", "SAME_OR_FASTER", "MEETS_PROMISE", "OVERRIDE" ], "nullable": true, "description": "Bounded classification of the merchant carrier-service decision, or null for legacy labels." }, "serviceDecisionReason": { "type": "string", "nullable": true, "description": "Merchant justification for a non-recommended service, or null for original/recommended decisions and legacy labels." }, "serviceDecisionActorUserId": { "type": "string", "format": "uuid", "nullable": true, "description": "Snapshot of the merchant user who confirmed the service decision, or null for legacy labels." }, "serviceDecisionAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the carrier-service decision was durably claimed, or null for legacy labels." }, "testLabel": { "type": "boolean", "description": "True for a non-chargeable sandbox test label." }, "needsTracking": { "type": "boolean", "description": "True when the label carries no tracking number: recorded + voidable, but the order was not stamped shipped and no email was sent." } }, "required": [ "labelId", "trackingNumber", "labelDownloadUrl", "shipmentCostInCents", "shipmentCostCurrency", "carrierName", "serviceCode", "serviceDecisionClassification", "serviceDecisionReason", "serviceDecisionActorUserId", "serviceDecisionAt", "testLabel", "needsTracking" ] }, "MerchantOrderShippingLabelFailureDto": { "type": "object", "properties": { "purchaseId": { "type": "string", "format": "uuid" }, "shipmentPackageId": { "type": "string", "format": "uuid", "nullable": true }, "outcome": { "type": "string", "enum": [ "NO_LABEL_CREATED", "UNKNOWN" ], "description": "`NO_LABEL_CREATED` is safe to retry after correction; `UNKNOWN` must be reconciled with ShipEngine before another purchase." }, "retryAllowed": { "type": "boolean", "description": "True only when the provider authoritatively rejected the request before creating a label." }, "message": { "type": "string", "description": "Sanitized, actionable provider failure message." }, "httpStatus": { "type": "number", "nullable": true }, "providerErrorType": { "type": "string", "nullable": true }, "providerErrorCode": { "type": "string", "nullable": true }, "providerErrorSource": { "type": "string", "nullable": true }, "fieldName": { "type": "string", "nullable": true, "description": "Provider field path that needs correction, when supplied. The field value is never retained." }, "requestId": { "type": "string", "nullable": true, "description": "ShipEngine request/correlation id safe to share with support." } }, "required": [ "purchaseId", "shipmentPackageId", "outcome", "retryAllowed", "message", "httpStatus", "providerErrorType", "providerErrorCode", "providerErrorSource", "fieldName", "requestId" ] }, "ParcelMeasurementSource": { "type": "string", "enum": [ "ITEM", "VARIANT" ], "description": "Catalog row that supplied the snapshotted line weight." }, "MerchantOrderLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "commercePricingRef": { "type": "string", "nullable": true, "description": "Stable reference into the order pricing snapshot. Null on ordinary/legacy lines." }, "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "The ordered variant, or `null` for item-level lines." }, "name": { "type": "string", "description": "Display name snapshotted on the line at order time.", "example": "Trail Tent 2P" }, "imageUrl": { "type": "string", "nullable": true, "description": "Image URL snapshotted at order time. `null` when none." }, "quantity": { "type": "number", "example": 2 }, "unitPriceInCents": { "type": "number", "example": 14900 }, "totalPriceInCents": { "type": "number", "example": 29800 }, "reservedInventoryId": { "type": "string", "format": "uuid", "nullable": true, "description": "Inventory row this line reserved against, or `null` if unreserved." }, "reservedQuantity": { "type": "number", "example": 0, "description": "Quantity held against the reserved inventory row." }, "weight": { "type": "number", "nullable": true, "description": "Snapshotted shippable weight, in `weightUnit`. `null` when none." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "description": "Resolved item/variant orientation policy frozen on confirmation; old lines are canonical-only.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "weightMeasurementSource": { "nullable": true, "description": "Catalog row that supplied the snapshotted line weight.", "allOf": [ { "$ref": "#/components/schemas/ParcelMeasurementSource" } ] }, "weightMeasurementReviewedAt": { "type": "string", "format": "date-time", "nullable": true }, "dimensionMeasurementSource": { "nullable": true, "description": "Catalog row that supplied the snapshotted line dimensions.", "allOf": [ { "$ref": "#/components/schemas/ParcelMeasurementSource" } ] }, "dimensionMeasurementReviewedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "orderId", "commercePricingRef", "itemId", "variantId", "name", "imageUrl", "quantity", "unitPriceInCents", "totalPriceInCents", "reservedInventoryId", "reservedQuantity", "weight", "weightUnit", "length", "width", "height", "dimensionUnit", "orientationPolicy", "weightMeasurementSource", "weightMeasurementReviewedAt", "dimensionMeasurementSource", "dimensionMeasurementReviewedAt" ] }, "MerchantOrderDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "commerceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Canonical Sales ORDER record linked through CommerceRecord.orderId, or `null` for a legacy-only checkout order. Merchant-only routing field; omitted from public/customer order projections." }, "hasCancelledShipmentHistory": { "type": "boolean", "description": "Whether this order has any cancelled shipment history. Merchant-only workflow guard; cancelled shipment details remain omitted." }, "orderNumber": { "type": "string", "description": "Human-facing, tenant-scoped order number.", "example": "ACME-2026-042" }, "userId": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked customer account, or `null` for guest orders." }, "customerName": { "type": "string", "description": "Buyer name captured at checkout." }, "customerEmail": { "type": "string", "format": "email", "description": "Buyer email captured at checkout." }, "customerPhone": { "type": "string", "nullable": true, "description": "Buyer phone, or `null` when not collected." }, "shippingAddress": { "nullable": true, "description": "The immutable order-time shipping address snapshot. `null` when the order had no shipping address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "nullable": true, "description": "The immutable order-time billing address snapshot. `null` when the order had no billing address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0, "description": "Total discount applied, in minor units." }, "discountSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Merchant-internal discount rule-attribution snapshot (free-form JSON). `null` when no discount was applied." }, "commercePricingSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen shared-pricing snapshot for a composed order. Merchant-only; null on ordinary and legacy orders." }, "taxInCents": { "type": "number", "example": 1788 }, "taxDisclosure": { "nullable": true, "description": "Merchant-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "example": 0, "description": "Shipping charged, in minor units." }, "shippingMethod": { "nullable": true, "description": "#1769 — the customer's chosen shipping method, snapshotted onto the order at checkout confirmation. `null` for orders without a method (digital-only checkouts, merchant-created orders) AND for orders confirmed before the snapshot existed — legacy orders are not back-projected from their checkout session.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingMethodDto" } ] }, "shippingLabel": { "nullable": true, "description": "#1771 — the native ShipEngine label bought for this order (reprint/void summary), or `null` when none has been purchased.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelDto" } ] }, "shippingLabelFailure": { "nullable": true, "description": "#1961 — safe diagnostics for the last rejected or ambiguous native label attempt, or `null` when no action is needed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelFailureDto" } ] }, "totalInCents": { "type": "number", "example": 31588 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Originating booking, or `null` for non-booking orders." }, "paymentAttemptId": { "type": "string", "format": "uuid", "nullable": true, "description": "Exact successful payment attempt that confirmed this order." }, "stripePaymentIntentId": { "type": "string", "nullable": true, "description": "Stripe PaymentIntent id, or `null` before payment." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Connected account the charge ran on, or `null`." }, "notes": { "type": "string", "nullable": true, "description": "Merchant-side notes scratchpad, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrderLineDto" } }, "shipments": { "description": "#1562 — merchant/Admin shipment rows projected from active `commerce_fulfillments`. May include PLANNED and READY preparation as well as SHIPPED/DELIVERED physical history; internal row ids and line allocations are omitted. Customer token/account reads use a separate public projection limited to handed-off or delivered history.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } } }, "required": [ "id", "organizationId", "commerceRecordId", "hasCancelledShipmentHistory", "orderNumber", "userId", "customerName", "customerEmail", "customerPhone", "shippingAddress", "billingAddress", "subtotalInCents", "discountInCents", "discountSnapshot", "commercePricingSnapshot", "taxInCents", "taxDisclosure", "shippingInCents", "shippingMethod", "shippingLabel", "shippingLabelFailure", "totalInCents", "status", "fulfillmentStatus", "bookingId", "paymentAttemptId", "stripePaymentIntentId", "stripeAccountId", "notes", "createdAt", "updatedAt", "items", "shipments" ] }, "MerchantOrderListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrderDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor — pass back as `?cursor=` for the next page. `null` when there are no more orders." } }, "required": [ "data", "nextCursor" ] }, "OrderCancellationOperationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "REQUESTED", "WAITING_FOR_LABEL_VOID", "RECONCILIATION_REQUIRED", "FINALIZING", "COMPLETED", "DENIED_OR_INELIGIBLE" ] }, "fulfillmentCount": { "type": "number", "example": 2 }, "paidLabelCount": { "type": "number", "example": 1 }, "problemCode": { "type": "string", "nullable": true }, "requestedAt": { "format": "date-time", "type": "string" }, "reconciliationRequiredAt": { "format": "date-time", "type": "string", "nullable": true }, "completedAt": { "format": "date-time", "type": "string", "nullable": true }, "deniedAt": { "format": "date-time", "type": "string", "nullable": true }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "status", "fulfillmentCount", "paidLabelCount", "problemCode", "requestedAt", "reconciliationRequiredAt", "completedAt", "deniedAt", "updatedAt" ] }, "OrderPaymentDisplayDto": { "type": "object", "properties": { "brand": { "type": "string", "example": "visa", "description": "Card brand captured from the exact successful provider Charge." }, "last4": { "type": "string", "example": "4242", "pattern": "^[0-9]{4}$", "description": "Last four card digits captured from the exact successful provider Charge." }, "amountInCents": { "type": "integer", "minimum": 0, "example": 1100, "description": "Amount charged by the exact successful payment attempt, in minor currency units; this is not inferred from the Order total." }, "currency": { "type": "string", "example": "usd", "pattern": "^[a-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Lowercase ISO-4217 currency of the exact successful payment attempt." }, "succeededAt": { "type": "string", "format": "date-time", "example": "2026-08-30T05:59:58.000Z", "description": "Successful PaymentIntent Event instant frozen at confirmation, not the PaymentIntent or Order insert time." } }, "required": [ "brand", "last4", "amountInCents", "currency", "succeededAt" ] }, "MerchantOrderCorrelationDto": { "type": "object", "properties": { "eligibility": { "type": "string", "enum": [ "ineligible", "eligible" ], "description": "Which correlation arm this order is on. `ineligible`: the order is deterministically outside the correlation population (see `reason`). `eligible`: exactly one durable correlation aggregate governs it (see `status`)." }, "reason": { "type": "string", "enum": [ "NON_CHECKOUT_SOURCE", "SUBSCRIPTION_CHECKOUT", "BOOKING_ORIGIN", "NO_CHARGE_REQUIRED", "NO_PAYMENT_LINEAGE" ], "nullable": true, "description": "Bounded exclusion reason. Present exactly when `eligibility` is `ineligible`; `null` on the eligible arm." }, "status": { "type": "string", "enum": [ "pending", "available", "needs_support" ], "nullable": true, "description": "Aggregate state. Present exactly when `eligibility` is `eligible`; `null` on the ineligible arm. `pending`: the provider annotation has not yet been proved (first work and every automatic retry). `available`: a provider read proved the final order description and structured order-number metadata. `needs_support`: terminal contradiction or bounded retry exhaustion — resolved through operator support, never a merchant retry. The order and its payment are complete and unaffected in every state." }, "updatedAt": { "format": "date-time", "type": "string", "nullable": true, "description": "Last aggregate transition time. Present exactly when `eligibility` is `eligible`; `null` on the ineligible arm." }, "supportCode": { "type": "string", "nullable": true, "description": "Fixed, secret-free support code for `needs_support` (never a raw provider error). `null` unless the eligible aggregate carries one." } }, "required": [ "eligibility", "reason", "status", "updatedAt", "supportCode" ] }, "MerchantOrderDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "commerceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Canonical Sales ORDER record linked through CommerceRecord.orderId, or `null` for a legacy-only checkout order. Merchant-only routing field; omitted from public/customer order projections." }, "hasCancelledShipmentHistory": { "type": "boolean", "description": "Whether this order has any cancelled shipment history. Merchant-only workflow guard; cancelled shipment details remain omitted." }, "orderNumber": { "type": "string", "description": "Human-facing, tenant-scoped order number.", "example": "ACME-2026-042" }, "userId": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked customer account, or `null` for guest orders." }, "customerName": { "type": "string", "description": "Buyer name captured at checkout." }, "customerEmail": { "type": "string", "format": "email", "description": "Buyer email captured at checkout." }, "customerPhone": { "type": "string", "nullable": true, "description": "Buyer phone, or `null` when not collected." }, "shippingAddress": { "nullable": true, "description": "The immutable order-time shipping address snapshot. `null` when the order had no shipping address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "nullable": true, "description": "The immutable order-time billing address snapshot. `null` when the order had no billing address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0, "description": "Total discount applied, in minor units." }, "discountSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Merchant-internal discount rule-attribution snapshot (free-form JSON). `null` when no discount was applied." }, "commercePricingSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen shared-pricing snapshot for a composed order. Merchant-only; null on ordinary and legacy orders." }, "taxInCents": { "type": "number", "example": 1788 }, "taxDisclosure": { "nullable": true, "description": "Merchant-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "example": 0, "description": "Shipping charged, in minor units." }, "shippingMethod": { "nullable": true, "description": "#1769 — the customer's chosen shipping method, snapshotted onto the order at checkout confirmation. `null` for orders without a method (digital-only checkouts, merchant-created orders) AND for orders confirmed before the snapshot existed — legacy orders are not back-projected from their checkout session.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingMethodDto" } ] }, "shippingLabel": { "nullable": true, "description": "#1771 — the native ShipEngine label bought for this order (reprint/void summary), or `null` when none has been purchased.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelDto" } ] }, "shippingLabelFailure": { "nullable": true, "description": "#1961 — safe diagnostics for the last rejected or ambiguous native label attempt, or `null` when no action is needed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelFailureDto" } ] }, "totalInCents": { "type": "number", "example": 31588 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Originating booking, or `null` for non-booking orders." }, "paymentAttemptId": { "type": "string", "format": "uuid", "nullable": true, "description": "Exact successful payment attempt that confirmed this order." }, "stripePaymentIntentId": { "type": "string", "nullable": true, "description": "Stripe PaymentIntent id, or `null` before payment." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Connected account the charge ran on, or `null`." }, "notes": { "type": "string", "nullable": true, "description": "Merchant-side notes scratchpad, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrderLineDto" } }, "shipments": { "description": "#1562 — merchant/Admin shipment rows projected from active `commerce_fulfillments`. May include PLANNED and READY preparation as well as SHIPPED/DELIVERED physical history; internal row ids and line allocations are omitted. Customer token/account reads use a separate public projection limited to handed-off or delivered history.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "orderConfirmationEmail": { "description": "#1965 — server-derived state of the checkout order confirmation email. Contains no recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "orderCancellation": { "nullable": true, "description": "#1934 — latest durable whole-order cancellation state. Reload-safe and merchant-safe; provider evidence, request hashes, and actor ids remain private.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderCancellationOperationDto" } ] }, "paymentDisplay": { "nullable": true, "description": "Immutable display-safe facts from the exact successful card Charge. `null` for free orders, paid orders predating snapshot capture, or while a paid order's exact provider display evidence is temporarily unavailable and bounded repair remains pending; it does not mean the order is unpaid. Detail-only: list and mutation responses deliberately omit it.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderPaymentDisplayDto" } ] }, "correlation": { "nullable": true, "description": "E28 #3602 — order-number correlation with the payment provider. `null` has exactly one meaning: the order predates correlation activation (the durable activation boundary), so no correlation contract ever applied to it — never \"unknown\" and never a transient state. Post-activation orders always carry an object: `ineligible` with a bounded reason, or `eligible` with the three-state status. Present only on the detail inspection reads — list envelopes, mutation responses (which embed `MerchantOrderMutationDetailDto`), and every public/customer surface omit it.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderCorrelationDto" } ] } }, "required": [ "id", "organizationId", "commerceRecordId", "hasCancelledShipmentHistory", "orderNumber", "userId", "customerName", "customerEmail", "customerPhone", "shippingAddress", "billingAddress", "subtotalInCents", "discountInCents", "discountSnapshot", "commercePricingSnapshot", "taxInCents", "taxDisclosure", "shippingInCents", "shippingMethod", "shippingLabel", "shippingLabelFailure", "totalInCents", "status", "fulfillmentStatus", "bookingId", "paymentAttemptId", "stripePaymentIntentId", "stripeAccountId", "notes", "createdAt", "updatedAt", "items", "shipments", "orderConfirmationEmail", "orderCancellation", "paymentDisplay", "correlation" ] }, "UpdateOrderStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "description": "Target order status. Must be a legal next state from the order's current status. Ordinary state machine: PENDING → CONFIRMED → PROCESSING → COMPLETED. CANCELLED must use the dedicated Owner/Admin whole-order cancellation command." } }, "required": [ "status" ] }, "UpdateOrderNotesDto": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true, "maxLength": 4000, "description": "Merchant-side scratchpad. Pass `null` explicitly to clear the existing note. The key MUST be present in the request body." } }, "required": [ "notes" ] }, "UpdateOrderFulfillmentStatusDto": { "type": "object", "properties": { "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "description": "Retired aggregate target retained for wire compatibility. Existing orders return 409 LINE_FULFILLMENT_REQUIRED; use explicit Sales line and quantity fulfillment commands." } }, "required": [ "fulfillmentStatus" ] }, "UpdateOrderShipmentTrackingDto": { "type": "object", "properties": { "notify": { "type": "boolean", "description": "Required for wire compatibility. This edit cannot originate a shipment notification: existing SEND/SUPPRESS evidence remains immutable, while a pre-evidence historical row derives SEND only from an existing shipNotifiedAt anchor and otherwise catches up as SUPPRESS." }, "carrier": { "type": "string", "example": "UPS", "maxLength": 80, "description": "Carrier label shown to the customer. Must match the immutable actual carrier when this fulfillment or order has purchased outbound-label evidence." }, "trackingNumber": { "type": "string", "example": "1Z999AA10123456784", "maxLength": 120, "description": "Carrier tracking number shown to the customer." }, "serviceLevel": { "type": "string", "example": "Ground", "maxLength": 80, "nullable": true, "description": "Optional service level shown with the carrier. Omission preserves the purchased-label value; attached and legacy order-scoped purchased labels cannot be rewritten here." }, "trackingUrl": { "type": "string", "example": "https://www.ups.com/track?tracknum=1Z999AA10123456784", "maxLength": 500, "nullable": true, "description": "Optional http(s) carrier tracking URL." }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the package shipped. Omitted edits preserve the existing value. A historical row without this evidence must supply the known non-null handoff time; cannot clear a recorded timestamp." }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the package was delivered. When supplied, the shipment status becomes DELIVERED. Explicit null is accepted only while unset and cannot clear a recorded timestamp." } }, "required": [ "notify", "carrier", "trackingNumber" ] }, "CancelOrderDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" } }, "required": [ "reason" ] }, "MerchantOrderMutationDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "commerceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Canonical Sales ORDER record linked through CommerceRecord.orderId, or `null` for a legacy-only checkout order. Merchant-only routing field; omitted from public/customer order projections." }, "hasCancelledShipmentHistory": { "type": "boolean", "description": "Whether this order has any cancelled shipment history. Merchant-only workflow guard; cancelled shipment details remain omitted." }, "orderNumber": { "type": "string", "description": "Human-facing, tenant-scoped order number.", "example": "ACME-2026-042" }, "userId": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked customer account, or `null` for guest orders." }, "customerName": { "type": "string", "description": "Buyer name captured at checkout." }, "customerEmail": { "type": "string", "format": "email", "description": "Buyer email captured at checkout." }, "customerPhone": { "type": "string", "nullable": true, "description": "Buyer phone, or `null` when not collected." }, "shippingAddress": { "nullable": true, "description": "The immutable order-time shipping address snapshot. `null` when the order had no shipping address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "nullable": true, "description": "The immutable order-time billing address snapshot. `null` when the order had no billing address.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0, "description": "Total discount applied, in minor units." }, "discountSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Merchant-internal discount rule-attribution snapshot (free-form JSON). `null` when no discount was applied." }, "commercePricingSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen shared-pricing snapshot for a composed order. Merchant-only; null on ordinary and legacy orders." }, "taxInCents": { "type": "number", "example": 1788 }, "taxDisclosure": { "nullable": true, "description": "Merchant-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "shippingInCents": { "type": "number", "example": 0, "description": "Shipping charged, in minor units." }, "shippingMethod": { "nullable": true, "description": "#1769 — the customer's chosen shipping method, snapshotted onto the order at checkout confirmation. `null` for orders without a method (digital-only checkouts, merchant-created orders) AND for orders confirmed before the snapshot existed — legacy orders are not back-projected from their checkout session.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingMethodDto" } ] }, "shippingLabel": { "nullable": true, "description": "#1771 — the native ShipEngine label bought for this order (reprint/void summary), or `null` when none has been purchased.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelDto" } ] }, "shippingLabelFailure": { "nullable": true, "description": "#1961 — safe diagnostics for the last rejected or ambiguous native label attempt, or `null` when no action is needed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantOrderShippingLabelFailureDto" } ] }, "totalInCents": { "type": "number", "example": 31588 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Originating booking, or `null` for non-booking orders." }, "paymentAttemptId": { "type": "string", "format": "uuid", "nullable": true, "description": "Exact successful payment attempt that confirmed this order." }, "stripePaymentIntentId": { "type": "string", "nullable": true, "description": "Stripe PaymentIntent id, or `null` before payment." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Connected account the charge ran on, or `null`." }, "notes": { "type": "string", "nullable": true, "description": "Merchant-side notes scratchpad, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrderLineDto" } }, "shipments": { "description": "#1562 — merchant/Admin shipment rows projected from active `commerce_fulfillments`. May include PLANNED and READY preparation as well as SHIPPED/DELIVERED physical history; internal row ids and line allocations are omitted. Customer token/account reads use a separate public projection limited to handed-off or delivered history.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "orderConfirmationEmail": { "description": "#1965 — server-derived state of the checkout order confirmation email. Contains no recipient, provider id, policy code, or raw outbox error.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommunicationStatusDto" } ] }, "orderCancellation": { "nullable": true, "description": "#1934 — latest durable whole-order cancellation state. Reload-safe and merchant-safe; provider evidence, request hashes, and actor ids remain private.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderCancellationOperationDto" } ] } }, "required": [ "id", "organizationId", "commerceRecordId", "hasCancelledShipmentHistory", "orderNumber", "userId", "customerName", "customerEmail", "customerPhone", "shippingAddress", "billingAddress", "subtotalInCents", "discountInCents", "discountSnapshot", "commercePricingSnapshot", "taxInCents", "taxDisclosure", "shippingInCents", "shippingMethod", "shippingLabel", "shippingLabelFailure", "totalInCents", "status", "fulfillmentStatus", "bookingId", "paymentAttemptId", "stripePaymentIntentId", "stripeAccountId", "notes", "createdAt", "updatedAt", "items", "shipments", "orderConfirmationEmail", "orderCancellation" ] }, "CancelOrderResponseDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "CANCELLED", "CANCELLATION_PENDING", "CANCELLATION_RECONCILIATION_REQUIRED", "CANCELLATION_DENIED" ] }, "replayed": { "type": "boolean" }, "message": { "type": "string" }, "operation": { "$ref": "#/components/schemas/OrderCancellationOperationDto" }, "order": { "$ref": "#/components/schemas/MerchantOrderMutationDetailDto" } }, "required": [ "outcome", "replayed", "message", "operation", "order" ] }, "CustomerPaymentMethodResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Customer-safe payment method id." }, "status": { "type": "string", "enum": [ "ACTIVE", "DETACHED" ] }, "brand": { "type": "string", "nullable": true, "example": "visa" }, "last4": { "type": "string", "nullable": true, "example": "4242" }, "expMonth": { "type": "number", "nullable": true, "example": 12 }, "expYear": { "type": "number", "nullable": true, "example": 2030 }, "funding": { "type": "string", "nullable": true, "example": "credit" }, "country": { "type": "string", "nullable": true, "example": "US" }, "isDefault": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "description": "ISO 8601.", "example": "2026-06-08T01:20:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601.", "example": "2026-06-08T01:20:00.000Z" } }, "required": [ "id", "status", "brand", "last4", "expMonth", "expYear", "funding", "country", "isDefault", "createdAt", "updatedAt" ] }, "CreateSetupIntentResponseDto": { "type": "object", "properties": { "paymentAttemptId": { "type": "string", "description": "Internal setup PaymentAttempt id." }, "setupIntentId": { "type": "string", "description": "Stripe SetupIntent id.", "example": "seti_123" }, "clientSecret": { "type": "string", "description": "Stripe SetupIntent client secret for the Payment Element. Returned once; never persisted." }, "status": { "type": "string", "description": "Raw Stripe SetupIntent status.", "example": "requires_payment_method" }, "stripeAccountId": { "type": "string", "nullable": true, "description": "#932 — the tenant's connected Stripe account (`acct_…`) the SetupIntent was created on. The client MUST initialize Stripe.js with this account so the Payment Element saves the card on the connected account. null on the platform account (test/sandbox).", "example": "acct_123" } }, "required": [ "paymentAttemptId", "setupIntentId", "clientSecret", "status", "stripeAccountId" ] }, "CouponResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "description": "Coupon code, stored upper-cased. Tenant-scoped unique (two orgs may share a code, one org may not)." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type. Drives how `value` is interpreted (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING)." }, "value": { "type": "number", "description": "Raw discount value: basis points for PERCENTAGE (1-10000), cents off for FIXED_AMOUNT, 0/ignored for FREE_SHIPPING." }, "minimumSubtotalInCents": { "type": "number", "description": "Subtotal floor in cents before the coupon applies. 0 = none." }, "maxUses": { "type": "number", "nullable": true, "description": "Usage cap. `null` = unlimited." }, "usageCount": { "type": "number", "description": "At-least-once redemption counter; incremented at apply time." }, "startsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Activation start. `null` = active immediately." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Expiry. `null` = runs until disabled / `maxUses` exhausted." }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status (ACTIVE / DISABLED / EXPIRED)." }, "internalNotes": { "type": "string", "nullable": true, "description": "Merchant-only note; never shown to the customer." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "code", "type", "value", "minimumSubtotalInCents", "maxUses", "usageCount", "startsAt", "expiresAt", "status", "internalNotes", "createdAt", "updatedAt" ] }, "CreateCouponDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Coupon code. Trimmed + upper-cased server-side before write. Allowed: ASCII alphanumerics + dash + underscore. Tenant-scoped unique — two different orgs may share a code, the same org may not.", "minLength": 1, "maxLength": 50 }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount discriminator. PERCENTAGE: value is basis points (1-10000). FIXED_AMOUNT: value is cents off subtotal (>=0). FREE_SHIPPING: value is ignored." }, "value": { "type": "number", "description": "PERCENTAGE: basis points (1-10000). FIXED_AMOUNT: cents off subtotal (>=0). FREE_SHIPPING: optional, defaults to 0 and is ignored. The service enforces per-type ranges with clearer error messages than the DTO can.", "minimum": 0 }, "minimumSubtotalInCents": { "type": "number", "description": "Floor on cart subtotal before the coupon is applicable. 0 = no minimum. Defaults to 0.", "minimum": 0 }, "maxUses": { "type": "number", "description": "Max total redemptions across all customers. `null` (or omitted) = unlimited. Must be >= 1 when provided.", "minimum": 1, "nullable": true }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp before which the coupon is not yet active. Null/omitted = active immediately.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp after which the coupon is no longer redeemable. Null/omitted = runs until manually disabled. Must be strictly after startsAt when both are provided.", "format": "date-time", "nullable": true }, "internalNotes": { "type": "string", "description": "Merchant-only scratchpad. Never surfaced to the customer. Up to 4000 chars.", "maxLength": 4000 } }, "required": [ "code", "type" ] }, "UpdateCouponDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ] }, "value": { "type": "number", "minimum": 0 }, "minimumSubtotalInCents": { "type": "number", "minimum": 0 }, "maxUses": { "type": "number", "description": "Max total redemptions; null clears the cap (unlimited). >= 1 when set to a number.", "minimum": 1, "nullable": true }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear. Must be > startsAt when both are set on the resulting row.", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status. PATCH cannot move an active or expired coupon to DISABLED; use DELETE /merchant/coupons/:id with a reason for that high-risk action. EXPIRED is a label for past-window coupons the operator wants to keep in the list." }, "internalNotes": { "type": "string", "description": "Pass `null` to clear; pass a string up to 4000 chars to set.", "nullable": true, "maxLength": 4000 } } }, "ApplyCouponDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Coupon code. Trimmed + upper-cased server-side before lookup. Customer-typed; case-insensitive match against the merchant-configured canonical form.", "minLength": 1, "maxLength": 50 }, "subtotalInCents": { "type": "number", "description": "Current cart subtotal in cents. Used for minimum-spend gating and for the PERCENTAGE / FIXED_AMOUNT discount math. Trusted for preview only — order-time discount math (future M3 litecheckout) recomputes against the server-priced cart.", "minimum": 0 } }, "required": [ "code", "subtotalInCents" ], "additionalProperties": false }, "ApplyCouponResultDto": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Discriminant. `true` = the coupon applied and the discount fields are populated; `false` = it did not apply and `message` explains why.", "example": true }, "code": { "type": "string", "description": "Normalized (upper-cased) coupon code. Present on `valid:true`.", "example": "SUMMER25" }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type. Present on `valid:true`." }, "value": { "type": "number", "description": "Raw discount value (basis points for PERCENTAGE, cents for FIXED_AMOUNT, 0 for FREE_SHIPPING). Present on `valid:true`.", "example": 2500 }, "discountInCents": { "type": "number", "description": "Computed discount to subtract from the cart subtotal, in cents (always 0 for FREE_SHIPPING — shipping is waived separately). Present on `valid:true`.", "example": 1250 }, "message": { "type": "string", "description": "Customer-facing message. Always present on `valid:false`; public rejects use neutral unavailable/cannot-apply copy and do not disclose which validation gate failed.", "example": "This coupon is unavailable or cannot be applied." } }, "required": [ "valid" ] }, "CalculateAutoDiscountsItemDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Catalog item id for the cart line." }, "variantId": { "type": "string", "description": "Variant id when the line targets a specific variant. Optional because not every catalog row has variants." }, "quantity": { "type": "number", "minimum": 1, "description": "Number of units on this line. Lines with quantity <= 0 should be omitted from the request rather than included with a zero." }, "unitPriceInCents": { "type": "number", "minimum": 0, "description": "Per-unit price in cents at calculate-time. The line total used by the matcher is `quantity * unitPriceInCents`." }, "collectionIds": { "description": "Collection ids this line's item belongs to. Used to gate ITEMS_BY_COLLECTION discounts. Empty/omitted = line belongs to no collections. Unknown ids are silently ignored by the matcher.", "type": "array", "items": { "type": "string" } } }, "required": [ "itemId", "quantity", "unitPriceInCents" ], "additionalProperties": false }, "CalculateAutoDiscountsDto": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/CalculateAutoDiscountsItemDto" } }, "subtotalInCents": { "type": "number", "minimum": 0, "description": "Cart subtotal in cents. Drives the `minimumSubtotalInCents` gate and the `ORDER_TOTAL` math directly. Expected to equal `sum(items[].quantity * unitPriceInCents)` but accepted verbatim." } }, "required": [ "items", "subtotalInCents" ], "additionalProperties": false }, "AppliedAutoDiscountDto": { "type": "object", "properties": { "autoDiscountId": { "type": "string", "description": "Auto-discount id." }, "name": { "type": "string", "description": "Merchant-facing auto-discount name." }, "scope": { "type": "string", "enum": [ "ALL_ITEMS", "ITEMS_BY_COLLECTION", "ORDER_TOTAL" ], "description": "What the discount applies to (ALL_ITEMS / ITEMS_BY_COLLECTION / ORDER_TOTAL)." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING)." }, "appliedToInCents": { "type": "number", "description": "Base in cents the percentage/fixed math ran against (subtotal, matching line totals, or order total per scope)." }, "discountInCents": { "type": "number", "description": "Cents saved by this discount." } }, "required": [ "autoDiscountId", "name", "scope", "type", "appliedToInCents", "discountInCents" ] }, "CalculateAutoDiscountsResponseDto": { "type": "object", "properties": { "appliedDiscounts": { "description": "Every ACTIVE auto-discount that matched the supplied cart. Empty array when none apply.", "type": "array", "items": { "$ref": "#/components/schemas/AppliedAutoDiscountDto" } }, "totalDiscountInCents": { "type": "number", "description": "Sum of all applied discount amounts in cents." }, "finalSubtotalInCents": { "type": "number", "description": "Cart subtotal in cents after the applied discounts." } }, "required": [ "appliedDiscounts", "totalDiscountInCents", "finalSubtotalInCents" ] }, "AutoDiscountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Merchant-facing label (no customer-visible code)." }, "scope": { "type": "string", "enum": [ "ALL_ITEMS", "ITEMS_BY_COLLECTION", "ORDER_TOTAL" ], "description": "What the discount applies to (ALL_ITEMS / ITEMS_BY_COLLECTION / ORDER_TOTAL)." }, "scopeCollectionId": { "type": "string", "nullable": true, "format": "uuid", "description": "Target collection. Required when `scope` = ITEMS_BY_COLLECTION, `null` otherwise." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING) — same value semantics as coupons." }, "value": { "type": "number", "description": "Raw discount value: basis points for PERCENTAGE (1-10000), cents off for FIXED_AMOUNT, 0/ignored for FREE_SHIPPING." }, "minimumSubtotalInCents": { "type": "number", "description": "Subtotal floor in cents before the discount applies. 0 = none." }, "startsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Activation start. `null` = active immediately." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Expiry. `null` = runs until disabled." }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status (ACTIVE / DISABLED / EXPIRED)." }, "priority": { "type": "number", "description": "Tie-breaker when multiple auto-discounts could apply; higher wins. Default 0." }, "internalNotes": { "type": "string", "nullable": true, "description": "Merchant-only note; never shown to the customer." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "name", "scope", "scopeCollectionId", "type", "value", "minimumSubtotalInCents", "startsAt", "expiresAt", "status", "priority", "internalNotes", "createdAt", "updatedAt" ] }, "CreateAutoDiscountDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Merchant-facing label. Identifies the auto-discount in the admin list and audit rows. Never surfaced to the customer (storefront badge text comes from a separate field in slice 3B). Non-empty, up to 200 chars.", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "ALL_ITEMS", "ITEMS_BY_COLLECTION", "ORDER_TOTAL" ], "description": "Which cart contents the discount touches. ALL_ITEMS: every line. ITEMS_BY_COLLECTION: only lines in the named collection — scopeCollectionId is required. ORDER_TOTAL: the cart subtotal as a whole (differs from ALL_ITEMS for FIXED_AMOUNT discounts)." }, "scopeCollectionId": { "type": "string", "description": "Required when scope=ITEMS_BY_COLLECTION; must be null/omitted for ALL_ITEMS or ORDER_TOTAL. The collection must belong to the same organization — the service surfaces a structured 400 if not. A hard-deleted collection later flips this column to NULL via the FK SET NULL, which the apply path (slice 3B) treats as a no-op.", "nullable": true }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount discriminator (reuses the coupon enum). PERCENTAGE: value is basis points (1-10000). FIXED_AMOUNT: value is cents off subtotal (>=0). FREE_SHIPPING: value is ignored." }, "value": { "type": "number", "description": "PERCENTAGE: basis points (1-10000). FIXED_AMOUNT: cents off (>=0). FREE_SHIPPING: optional, defaults to 0 and is ignored. The service enforces per-type ranges with clearer error messages than the DTO can.", "minimum": 0 }, "minimumSubtotalInCents": { "type": "number", "description": "Floor on cart subtotal before the discount is applicable. 0 = no minimum. Defaults to 0.", "minimum": 0 }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp before which the auto-discount is not yet active. Null/omitted = active immediately.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp after which the auto-discount stops applying. Null/omitted = runs until manually disabled. Must be strictly after startsAt when both are provided.", "format": "date-time", "nullable": true }, "priority": { "type": "number", "description": "Tie-breaker when multiple auto-discounts could apply to the same cart. Higher wins. Any integer; defaults to 0. Slice 3B does the resolution; slice 3A merely stores the value." }, "internalNotes": { "type": "string", "description": "Merchant-only scratchpad. Never surfaced to the customer. Up to 4000 chars.", "maxLength": 4000 } }, "required": [ "name", "scope", "type" ] }, "UpdateAutoDiscountDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "ALL_ITEMS", "ITEMS_BY_COLLECTION", "ORDER_TOTAL" ] }, "scopeCollectionId": { "type": "string", "description": "Required when scope=ITEMS_BY_COLLECTION on the resulting row. Pass `null` to clear. The service re-validates the (scope, scopeCollectionId) pair against the merged state.", "nullable": true }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ] }, "value": { "type": "number", "minimum": 0 }, "minimumSubtotalInCents": { "type": "number", "minimum": 0 }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear. Must be > startsAt when both are set on the resulting row.", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status. PATCH cannot move an active or expired auto-discount to DISABLED; use DELETE /merchant/auto-discounts/:id with a reason for that high-risk action. EXPIRED is a label for past-window discounts the operator wants to keep in the list." }, "priority": { "type": "number", "description": "Tie-breaker priority. Any integer. Higher wins among ACTIVE auto-discounts that could otherwise apply to the same cart." }, "internalNotes": { "type": "string", "description": "Pass `null` to clear; pass a string up to 4000 chars to set.", "nullable": true, "maxLength": 4000 } } }, "BundleItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bundleId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "description": "The item this slot requires." }, "variantId": { "type": "string", "nullable": true, "format": "uuid", "description": "Optional variant scope for the slot. `null` = any variant." }, "minQuantity": { "type": "number", "description": "Required count of this item for the slot to be satisfied." } }, "required": [ "id", "bundleId", "itemId", "variantId", "minQuantity" ] }, "BundleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Merchant-facing bundle name." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type the bundle applies (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING)." }, "value": { "type": "number", "description": "Raw discount value: basis points for PERCENTAGE (1-10000), cents off for FIXED_AMOUNT, 0/ignored for FREE_SHIPPING." }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status (ACTIVE / DISABLED / EXPIRED)." }, "startsAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Activation start. `null` = active immediately." }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Expiry. `null` = runs until disabled." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "description": "The item slots that make up the bundle.", "type": "array", "items": { "$ref": "#/components/schemas/BundleItemResponseDto" } } }, "required": [ "id", "organizationId", "name", "type", "value", "status", "startsAt", "expiresAt", "createdAt", "updatedAt", "items" ] }, "CreateBundleItemDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Id of the catalog item that satisfies this slot. Canonical item ids are UUIDs, while the TEXT FK remains string-compatible for imported or historical identities, so validation uses `@IsString()` rather than `@IsUUID()`. Must belong to the active org — cross-tenant references are rejected by the service with a structured 400.", "minLength": 1 }, "variantId": { "type": "string", "description": "Optional id of a specific variant of `itemId`. TEXT FK — seeded rows use string ids like `variant_*`, so validation is `@IsString()` rather than `@IsUUID()`. When set, the cart must contain that exact variant to satisfy the slot. When null/omitted, any variant of the item counts. Must reference a variant of the supplied itemId (enforced by the service).", "minLength": 1, "nullable": true }, "minQuantity": { "type": "number", "description": "How many of this item the cart needs for the slot to be satisfied. Defaults to 1. Must be a positive integer (>= 1) — the service rejects 0 because a zero-quantity slot is meaningless.", "minimum": 1, "default": 1 } }, "required": [ "itemId" ] }, "CreateBundleDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Merchant-facing label. Identifies the bundle in the admin list and audit rows. Non-empty, up to 100 chars.", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount discriminator (reuses the coupon enum). PERCENTAGE: value is basis points (1-10000). FIXED_AMOUNT: value is cents off subtotal (>=0). FREE_SHIPPING: value is ignored." }, "value": { "type": "number", "description": "PERCENTAGE: basis points (1-10000). FIXED_AMOUNT: cents off (>=0). FREE_SHIPPING: optional, defaults to 0 and is ignored. The service enforces per-type ranges with clearer error messages than the DTO can.", "minimum": 0 }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp before which the bundle is not yet active. Null/omitted = active immediately.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp after which the bundle stops applying. Null/omitted = runs until manually disabled. Must be strictly after startsAt when both are provided.", "format": "date-time", "nullable": true }, "items": { "description": "Component items. A bundle requires at least 2 distinct items — a \"bundle\" of 1 isn't a bundle. Each row pins an item (and optionally a variant) plus the minQuantity required in the cart.", "minItems": 2, "type": "array", "items": { "$ref": "#/components/schemas/CreateBundleItemDto" } } }, "required": [ "name", "type", "items" ] }, "UpdateBundleDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ] }, "value": { "type": "number", "minimum": 0 }, "startsAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear.", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp; pass `null` to clear. Must be > startsAt when both are set on the resulting row.", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "EXPIRED" ], "description": "Lifecycle status (TEXT column on the DB side, TS union here). PATCH cannot move an active or expired bundle to DISABLED; use DELETE /merchant/bundles/:id with a reason for that high-risk action. EXPIRED is a label for past-window bundles the operator wants to keep in the list." }, "items": { "description": "When supplied, REPLACES the bundle's component items wholesale. Still must contain at least 2 entries — the service does not permit shrinking below the minimum-bundle threshold.", "minItems": 2, "type": "array", "items": { "$ref": "#/components/schemas/CreateBundleItemDto" } } } }, "CheckBundlesItemDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Catalog item id for the cart line.", "minLength": 1 }, "variantId": { "type": "string", "description": "Variant id when the line targets a specific variant of the item. Optional — lines without a variant default-select the item. The bundle matcher treats a slot with variantId=null as matching any variant of the item, and a slot with a specific variant as requiring that variant in the cart.", "minLength": 1 }, "quantity": { "type": "number", "minimum": 1, "description": "Number of units on this line. Lines with quantity <= 0 should be omitted from the request rather than included with a zero." }, "unitPriceInCents": { "type": "number", "minimum": 0, "description": "Per-unit price in cents at check-time. The matched-bundle discount math runs against `sum(quantity * unitPriceInCents)` of the lines that satisfied the bundle." } }, "required": [ "itemId", "quantity", "unitPriceInCents" ], "additionalProperties": false }, "CheckBundlesDto": { "type": "object", "properties": { "cartLines": { "minItems": 1, "maxItems": 200, "description": "Current cart contents. Bundle matching is purely composition-based, so the endpoint accepts only the structural fields (itemId, optional variantId, quantity, unit price). No subtotal is required because bundles do not have a minimum-spend gate.", "type": "array", "items": { "$ref": "#/components/schemas/CheckBundlesItemDto" } } }, "required": [ "cartLines" ], "additionalProperties": false }, "MatchedBundleDto": { "type": "object", "properties": { "id": { "type": "string", "description": "#3402 — the bundle's stable public identity, returned here for a bundle these cart lines satisfy. Resolve it anonymously with `GET /api/v1/public/bundles/{id}` for the full component slot list. A bundle belongs to many items and has no canonical parent item, so this id is its only public address. This endpoint RETURNS ids and does not accept one — it matches on `cartLines`.\n\nAn id returned here is NOT guaranteed to resolve, and the two gates differ deliberately. This match checks only the bundle's own lifecycle (tenant, `ACTIVE`, inside its window) and its slot ITEM IDS; it does not check whether those items are themselves published, because it returns no catalog detail and so leaks nothing by matching. The by-id read DOES return each slot's name, slug and price, so it drops the whole bundle when any slot references a draft or archived row. A stale cart containing an archived component therefore still matches here and 404s there. Treat that 404 as an ordinary outcome rather than an error.\n\nThis response is a PREVIEW computed from the `cartLines` you supplied, and it is not a promise about checkout. Checkout revalidates catalog availability and reprices server-side, so a match here can change or disappear. In particular, a line referencing a draft or archived item is REJECTED at repricing with a 400 before bundle resolution runs — so for the stale-cart case above checkout does not merely omit the discount, it refuses the line. Do not present a match here as a confirmed saving." }, "name": { "type": "string", "description": "Merchant-facing bundle name." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type the bundle applies (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING)." }, "value": { "type": "number", "description": "Raw discount value: basis points for PERCENTAGE (1-10000), cents off for FIXED_AMOUNT, ignored for FREE_SHIPPING." }, "discountInCents": { "type": "number", "description": "Estimated cents saved if the order-placement path honors the bundle. A preview — the order-create path re-runs the match against the server-priced cart." } }, "required": [ "id", "name", "type", "value", "discountInCents" ] }, "CheckBundlesResponseDto": { "type": "object", "properties": { "matchedBundles": { "description": "One entry per ACTIVE bundle the supplied cart satisfies; additively stacked. Empty array when nothing matches.\n\n#3648 — entries carry NO stock signal, and that silence is not an availability claim. This match is deliberately catalog-detail-free (slot item ids only), which is also why it can match a stale cart whose component is archived. The stock-eligibility verdict lives on the reads that already return catalog detail — `GET /api/v1/public/bundles/{id}` and `GET /api/v1/public/items/{slug}/bundles`, both of which publish `availability` per bundle and per slot. Use those before presenting a bundle as something to ADD; a match here describes a cart the shopper already holds, and checkout revalidates it either way.", "type": "array", "items": { "$ref": "#/components/schemas/MatchedBundleDto" } } }, "required": [ "matchedBundles" ] }, "ItemBundleSlotVariantDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Variant display name." }, "options": { "type": "object", "additionalProperties": true, "description": "Variant option map (e.g. `{ \"Size\": \"L\", \"Color\": \"Red\" }`)." }, "priceInCents": { "type": "number", "description": "Variant price in cents." } }, "required": [ "name", "options", "priceInCents" ] }, "ItemBundleSlotDto": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Catalog item id for this slot." }, "slug": { "type": "string", "description": "Slot item slug." }, "name": { "type": "string", "description": "Slot item name." }, "priceInCents": { "type": "number", "description": "Slot item base price in cents." }, "minQuantity": { "type": "number", "description": "Minimum quantity of this slot the bundle requires." }, "variantId": { "type": "string", "nullable": true, "description": "Variant id when the slot is variant-narrowed; null for an item-only slot (any variant of the item satisfies it)." }, "variant": { "nullable": true, "description": "Variant detail when the slot is variant-narrowed; null for an item-only slot.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ItemBundleSlotVariantDto" } ] }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK", "AVAILABLE", "CHECK_REQUIRED" ], "description": "#3648 — whether a shopper can obtain THIS SLOT'S `minQuantity` right now. Slot-scoped, not item-scoped: a slot needing 2 of an item with 1 unit left reads `OUT_OF_STOCK` even though the item's own product page is correctly purchasable, because the bundle is what cannot be completed. For an item-only slot (`variantId: null`) the units of every non-archived variant are summed, matching how the cart matcher counts them; for an item with no variants the item-level row is used instead. Stock a shopper of THIS slot cannot draw on is never counted, so a product whose every live variant is sold out cannot read as available: an archived variant keeps its inventory row internally, and once ANY variant exists the item's variant-less row is retired under DR-3694-01 = A. That retired row is never queried, counted, or allowed to veto a verdict. If every variant is archived, the slot has no eligible target and reads `CHECK_REQUIRED`; it never falls back to item-level stock. `AVAILABLE` is a SERVICE slot (no stock concept). PRESENTATION ELIGIBILITY, NOT A GUARANTEE. This is a snapshot taken while building this response so a surface can stop RECOMMENDING what checkout would refuse; stock moves between this read and the shopper's click, and the order path re-checks every line under a row lock. Never treat `IN_STOCK` as proof a purchase will succeed, and never use it to skip a checkout error path. Quantities, thresholds and reservations stay private here (as on the support-provider catalog summary this vocabulary mirrors) — `GET /api/v1/public/inventory/{itemId}` is the endpoint that publishes counts. `CHECK_REQUIRED` means availability could not be answered from stock rows at all (a RENTAL slot, whose capacity is booking-range governed; a composed product, whose own stock row is retired under ADR-038; an item whose variants are all archived, leaving no eligible target; or a governing stock target with no inventory row, for which the order path is deliberately LENIENT and reserves nothing) — it is NOT a synonym for out of stock, and it is never downgraded to an availability claim: `IN_STOCK` is only ever returned on the evidence of a stock row. That rule is symmetric, and PARTIAL evidence keeps it: `OUT_OF_STOCK` is published only when EVERY stock target governing the slot actually reported. Where a slot spans several targets (an item-only slot over multiple live variants), one target reporting zero while another has no row at all yields `CHECK_REQUIRED`, not `OUT_OF_STOCK` — the missing row is unbounded at checkout, so the shopper may well be able to complete the bundle through it. Evidence that is already sufficient still wins: rows covering `minQuantity` read `IN_STOCK` whatever a missing sibling target might have added. Stock that is AMBIGUOUS is likewise never aggregated: where one stock target holds more than one row, checkout reserves against a single one of them, so the rows are alternatives rather than a total and the slot reads `CHECK_REQUIRED` however large their sum. DR-3694-01 = A (catalog wins) makes variant existence decisive: an item-level `variantId: null` row governs only an item with NO variants at all. Once any variant exists — including an archived one — that row is retired and is never queried, counted, or allowed to veto a verdict. Live variants remain the governing stock targets. A covered shortfall across all of them therefore reads `OUT_OF_STOCK` regardless of stale or absent item-level data; if any governing live target has no row, the existing leniency keeps the result `CHECK_REQUIRED`. When every variant is archived there is no eligible target, so the result is also `CHECK_REQUIRED`, never a fallback to item-level stock." } }, "required": [ "itemId", "slug", "name", "priceInCents", "minQuantity", "variantId", "variant", "availability" ] }, "ItemBundleDto": { "type": "object", "properties": { "id": { "type": "string", "description": "#3402 — the bundle's stable public identity, and the ONLY public address a bundle has: a bundle belongs to many items, so it has no canonical parent item and cannot be addressed through any single item's slug. Resolve it anonymously with `GET /api/v1/public/bundles/{id}`, which returns this same shape. `POST /api/v1/public/cart/check-bundles` RETURNS ids but does not accept one — it takes `cartLines` and reports which bundles those lines satisfy, so sending an id there is a validation error. And an id is not permanently resolvable: archiving ANY component item removes the bundle from THIS read and from the by-id read, so treat 404 as a normal state rather than assuming a published id resolves forever. `check-bundles` is the deliberate exception — it carries no catalog detail, so it keeps matching a stale cart whose component was archived, and the id it returns can therefore already be unresolvable here." }, "name": { "type": "string", "description": "Merchant-facing bundle name." }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" ], "description": "Discount type the bundle applies (PERCENTAGE / FIXED_AMOUNT / FREE_SHIPPING)." }, "value": { "type": "number", "description": "Raw discount value: basis points for PERCENTAGE (1-10000), cents off for FIXED_AMOUNT, ignored for FREE_SHIPPING." }, "discountInCents": { "type": "number", "description": "Minimum qualifying saving in cents at current catalog prices (times minQuantity). Actual cart savings scale with quantity and come from POST /public/cart/check-bundles." }, "slots": { "description": "Full component slot list for the bundle.", "type": "array", "items": { "$ref": "#/components/schemas/ItemBundleSlotDto" } }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK", "AVAILABLE", "CHECK_REQUIRED" ], "description": "#3648 — the bundle rollup: it is exactly as available as its LEAST available slot, since every slot must be satisfiable for the saving to be reachable. Precedence, first match wins: any `OUT_OF_STOCK` slot → `OUT_OF_STOCK`; else any `CHECK_REQUIRED` → `CHECK_REQUIRED`; else any `IN_STOCK` → `IN_STOCK`; else `AVAILABLE` (every slot stockless). A known dead end deliberately outranks an unknown — one unobtainable component makes the whole recommendation unactionable. Intended use: suppress `OUT_OF_STOCK` bundles from upsell surfaces and de-prioritize (do not hide) `CHECK_REQUIRED` ones. Read `slots[].availability` to name the component that is holding the bundle back. PRESENTATION ELIGIBILITY, NOT A GUARANTEE. This is a snapshot taken while building this response so a surface can stop RECOMMENDING what checkout would refuse; stock moves between this read and the shopper's click, and the order path re-checks every line under a row lock. Never treat `IN_STOCK` as proof a purchase will succeed, and never use it to skip a checkout error path. Quantities, thresholds and reservations stay private here (as on the support-provider catalog summary this vocabulary mirrors) — `GET /api/v1/public/inventory/{itemId}` is the endpoint that publishes counts. `CHECK_REQUIRED` means availability could not be answered from stock rows at all (a RENTAL slot, whose capacity is booking-range governed; a composed product, whose own stock row is retired under ADR-038; an item whose variants are all archived, leaving no eligible target; or a governing stock target with no inventory row, for which the order path is deliberately LENIENT and reserves nothing) — it is NOT a synonym for out of stock, and it is never downgraded to an availability claim: `IN_STOCK` is only ever returned on the evidence of a stock row. That rule is symmetric, and PARTIAL evidence keeps it: `OUT_OF_STOCK` is published only when EVERY stock target governing the slot actually reported. Where a slot spans several targets (an item-only slot over multiple live variants), one target reporting zero while another has no row at all yields `CHECK_REQUIRED`, not `OUT_OF_STOCK` — the missing row is unbounded at checkout, so the shopper may well be able to complete the bundle through it. Evidence that is already sufficient still wins: rows covering `minQuantity` read `IN_STOCK` whatever a missing sibling target might have added. Stock that is AMBIGUOUS is likewise never aggregated: where one stock target holds more than one row, checkout reserves against a single one of them, so the rows are alternatives rather than a total and the slot reads `CHECK_REQUIRED` however large their sum. DR-3694-01 = A (catalog wins) makes variant existence decisive: an item-level `variantId: null` row governs only an item with NO variants at all. Once any variant exists — including an archived one — that row is retired and is never queried, counted, or allowed to veto a verdict. Live variants remain the governing stock targets. A covered shortfall across all of them therefore reads `OUT_OF_STOCK` regardless of stale or absent item-level data; if any governing live target has no row, the existing leniency keeps the result `CHECK_REQUIRED`. When every variant is archived there is no eligible target, so the result is also `CHECK_REQUIRED`, never a fallback to item-level stock." } }, "required": [ "id", "name", "type", "value", "discountInCents", "slots", "availability" ] }, "ItemBundlesResponseDto": { "type": "object", "properties": { "bundles": { "description": "ACTIVE bundles (lifecycle-window-gated, tenant-scoped) that contain the item. Empty array when none. Bundles referencing draft/archived catalog rows are omitted. Stock does NOT omit anything: a bundle a shopper cannot currently complete is still returned and labelled by its `availability` — `OUT_OF_STOCK` when a component is known to be short of what its slot needs, `CHECK_REQUIRED` when stock cannot answer — because suppressing versus annotating it is the consuming surface's decision and a silent omission would be indistinguishable from the bundle not existing.", "type": "array", "items": { "$ref": "#/components/schemas/ItemBundleDto" } } }, "required": [ "bundles" ] }, "PublicShippingRateDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Configured flat-rate id. Checkout inputs that accept a flat `shippingRateId` use this value." }, "name": { "type": "string", "description": "Customer-facing rate name (e.g. \"Standard\")." }, "priceInCents": { "type": "number", "description": "Rate price in minor units (cents)." }, "minimumSubtotalInCents": { "type": "number", "description": "Minimum order subtotal (cents) for this rate to apply. `0` when there is no floor. This read publishes the configured rate and floor; it does not evaluate a cart. A published rate therefore need not appear among the options resolved for a cart whose subtotal is below the floor." }, "sortOrder": { "type": "number", "description": "Display order — rates are listed ascending." }, "estimatedDelivery": { "type": "string", "description": "Free-text delivery estimate (e.g. \"3–5 business days\").", "nullable": true }, "transitMinDays": { "type": "number", "description": "#1103 — shortest calendar-day transit for this rate (null when unset). A BYO client combines this with the tenant delivery-estimate settings to render a structured ship-by / delivery-window date.", "nullable": true }, "transitMaxDays": { "type": "number", "description": "#1103 — longest calendar-day transit for this rate (null when unset).", "nullable": true } }, "required": [ "id", "name", "priceInCents", "minimumSubtotalInCents", "sortOrder", "estimatedDelivery", "transitMinDays", "transitMaxDays" ] }, "PublicShippingZoneDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Zone id." }, "name": { "type": "string", "description": "Merchant-facing zone name." }, "countries": { "description": "ISO 3166-1 alpha-2 country codes (uppercase) this zone matches. An EMPTY array matches NO destination, so this zone's flat-rate configuration and live-rate eligibility apply nowhere.", "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "number", "description": "Display order — zones are listed ascending." }, "liveRatesEnabled": { "type": "boolean", "description": "#3272 — ZONE-LEVEL ELIGIBILITY for live carrier rates: whether this zone is configured to permit carrier quoting. This is CONFIGURATION, NOT current availability. Read it with `rates` as four configuration states:\n\n- empty `rates` + `false`: no active flat rate; live eligibility paused.\n- empty `rates` + `true`: no active flat rate; live-rate eligible.\n- non-empty `rates` + `false`: active flat-rate configuration only.\n- non-empty `rates` + `true`: active flat-rate configuration and live-rate eligibility.\n\nBoth flat-rate configuration and live-rate eligibility apply only when the destination matches `countries`; an empty `countries` array matches nothing. `true` is NECESSARY but NOT SUFFICIENT for a carrier option: address, cart, tenant/platform, origin/carrier, and quote conditions that are not represented on this read still apply. For an ordinary checkout, resolve the current option set with `POST /api/v1/public/checkout/sessions/{token}/reprice` and read `availableShippingOptions`. Physical subscription checkout has no public equivalent for resolving its current shipping options." }, "rates": { "description": "This zone's active FLAT-rate configurations, ascending by `sortOrder` then name. Empty establishes ONLY that no active flat rate is published; read `liveRatesEnabled` to distinguish live-rate eligibility from a zone with neither configuration (#3272). A non-empty list does not mean every rate applies to the current cart, because each rate has its own `minimumSubtotalInCents` floor. This read does not resolve cart-specific options. For an ordinary checkout, use `POST /api/v1/public/checkout/sessions/{token}/reprice` and read `availableShippingOptions`; physical subscription checkout has no public equivalent for resolving its current shipping options.", "type": "array", "items": { "$ref": "#/components/schemas/PublicShippingRateDto" } } }, "required": [ "id", "name", "countries", "sortOrder", "liveRatesEnabled", "rates" ] }, "DeliveryPromiseRuleDto": { "type": "object", "properties": { "tierId": { "type": "string", "format": "uuid", "description": "Organization-global promise tier id enabled/configured in this zone." }, "enabled": { "type": "boolean", "description": "Whether this zone currently offers the tier. Disabled rules remain saved." }, "serviceCodes": { "minItems": 1, "maxItems": 50, "description": "Explicit ShipEngine service-code allowlist. Tier names or carrier marketing labels never infer eligibility.", "type": "array", "items": { "type": "string" } }, "maxTransitDays": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Maximum quoted transit days accepted for this promise in this zone." }, "pricingPolicy": { "type": "string", "enum": [ "carrier_cost" ], "description": "MVP supports raw `carrier_cost` only. Fixed/free/markup policies remain #1903." } }, "required": [ "tierId", "enabled", "serviceCodes", "maxTransitDays", "pricingPolicy" ] }, "ShippingRateResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "zoneId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Merchant-facing rate name shown at checkout." }, "priceInCents": { "type": "number", "description": "Flat per-shipment fee in cents. Non-negative." }, "minimumSubtotalInCents": { "type": "number", "description": "Minimum cart subtotal in cents to qualify for this rate. 0 = none." }, "estimatedDelivery": { "type": "string", "nullable": true, "description": "Optional delivery-estimate copy shown at checkout, e.g. \"Arrives in 3-5 business days.\" `null` when unset." }, "transitMinDays": { "type": "number", "nullable": true, "description": "#1103 — shortest calendar-day transit for the structured delivery estimate. `null` when unset." }, "transitMaxDays": { "type": "number", "nullable": true, "description": "#1103 — longest calendar-day transit. `null` when unset." }, "sortOrder": { "type": "number", "description": "Display order in checkout selectors." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-archive timestamp. `null` = active." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "zoneId", "name", "priceInCents", "minimumSubtotalInCents", "estimatedDelivery", "transitMinDays", "transitMaxDays", "sortOrder", "archivedAt", "createdAt", "updatedAt" ] }, "ShippingZoneResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Merchant-facing zone name." }, "countries": { "description": "ISO 3166-1 alpha-2 country codes, uppercase (e.g. [\"US\", \"CA\"]). Empty = matches no orders.", "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "number", "description": "Display order in admin lists / checkout." }, "liveRatesEnabled": { "type": "boolean", "description": "#1718 — offer live carrier rates for destinations this zone serves. Only has effect once the org connects a shipping provider in Settings → Shipping; off = flat rates only, provider key untouched." }, "deliveryPromiseRules": { "description": "#2000 — normalized zone-owned promise rules. Each rule references an organization-global tier id and carries explicit services/target/pricing.", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseRuleDto" } }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-archive timestamp. `null` = active." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "rates": { "description": "Rates in this zone, ordered by `sortOrder` then name.", "type": "array", "items": { "$ref": "#/components/schemas/ShippingRateResponseDto" } } }, "required": [ "id", "organizationId", "name", "countries", "sortOrder", "liveRatesEnabled", "deliveryPromiseRules", "archivedAt", "createdAt", "updatedAt", "rates" ] }, "UpsertShippingZoneDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "countries": { "description": "ISO-3166-1 alpha-2 country codes, uppercase (e.g. [\"US\", \"CA\"]). Empty array is permitted for a zone that is still being configured.", "maxItems": 300, "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "number", "minimum": 0, "description": "Display order — zones are listed ascending. Defaults to 0." }, "liveRatesEnabled": { "type": "boolean", "description": "#1718 — offer live carrier rates for destinations this zone serves. Defaults to true; only has effect once the org connects a shipping provider in Settings → Shipping (identity lives there, usage here). Turning it off pauses live quoting for the zone without touching the stored provider key." }, "deliveryPromiseRules": { "maxItems": 20, "description": "#2000 — zone-owned delivery-promise eligibility, target, and MVP pricing rules. Replaces the complete rule set when provided.", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseRuleDto" } } }, "required": [ "name", "countries" ] }, "UpdateShippingZoneDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "countries": { "description": "ISO-3166-1 alpha-2 country codes, uppercase. When supplied this replaces the current list — there is no append/merge mode.", "maxItems": 300, "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "number", "minimum": 0 }, "liveRatesEnabled": { "type": "boolean", "description": "#1718 — offer live carrier rates for destinations this zone serves. Only has effect once the org connects a shipping provider in Settings → Shipping." }, "deliveryPromiseRules": { "maxItems": 20, "description": "#2000 — complete replacement of this zone’s promise rules.", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseRuleDto" } }, "deliveryPromiseRulesExpectedRevision": { "type": "string", "format": "date-time", "description": "#2413 — required whenever `deliveryPromiseRules` is supplied. Echo the zone `updatedAt` value returned by the latest read; stale rule writes are rejected with HTTP 409." } } }, "UpsertShippingRateDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "priceInCents": { "type": "number", "minimum": 0, "maximum": 2147483647, "description": "Flat per-shipment fee in cents. Must be >= 0." }, "minimumSubtotalInCents": { "type": "number", "minimum": 0, "maximum": 2147483647, "description": "Minimum cart subtotal (in cents) for this rate to qualify. Defaults to 0 (no minimum). The storefront cost calc skips rates whose `minimumSubtotalInCents` exceeds the cart subtotal." }, "estimatedDelivery": { "type": "string", "maxLength": 200, "nullable": true, "description": "Optional checkout copy, e.g. \"Arrives in 3–5 business days.\" Stays on the rate so the merchant owns the per-rate messaging. Also the honest fallback shown when a structured delivery estimate cannot be computed (#1103)." }, "transitMinDays": { "type": "number", "minimum": 0, "maximum": 365, "nullable": true, "description": "#1103 — shortest CALENDAR-day transit for this rate. Combined with transitMaxDays and the tenant processing/cutoff settings to render a structured delivery estimate; omit (or null) to keep the free-text estimate only." }, "transitMaxDays": { "type": "number", "minimum": 0, "maximum": 365, "nullable": true, "description": "#1103 — longest CALENDAR-day transit for this rate. Must be >= transitMinDays (enforced server-side)." }, "sortOrder": { "type": "number", "minimum": 0, "description": "Display order — rates are listed ascending. Defaults to 0." } }, "required": [ "name", "priceInCents" ] }, "UpdateShippingRateDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "priceInCents": { "type": "number", "minimum": 0, "maximum": 2147483647 }, "minimumSubtotalInCents": { "type": "number", "minimum": 0, "maximum": 2147483647 }, "estimatedDelivery": { "type": "string", "maxLength": 200, "nullable": true }, "transitMinDays": { "type": "number", "minimum": 0, "maximum": 365, "nullable": true }, "transitMaxDays": { "type": "number", "minimum": 0, "maximum": 365, "nullable": true }, "sortOrder": { "type": "number", "minimum": 0 } } }, "ShippingBoxPresetType": { "type": "string", "enum": [ "CUSTOM", "CARRIER_FLAT_RATE" ] }, "ShippingBoxPresetResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable logical preset id shared by every revision." }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/ShippingBoxPresetType" } ] }, "insideLength": { "type": "number" }, "insideWidth": { "type": "number" }, "insideHeight": { "type": "number" }, "insideDimensionUnit": { "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "outsideLength": { "type": "number" }, "outsideWidth": { "type": "number" }, "outsideHeight": { "type": "number" }, "outsideDimensionUnit": { "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "tareWeight": { "type": "number" }, "tareWeightUnit": { "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "maxLoadedWeight": { "type": "number", "nullable": true }, "maxLoadedWeightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "providerPackageCode": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "preferenceOrder": { "type": "integer", "minimum": 0 }, "insideSameAsOutsideConfirmed": { "type": "boolean" }, "deactivatedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "revision", "name", "type", "insideLength", "insideWidth", "insideHeight", "insideDimensionUnit", "outsideLength", "outsideWidth", "outsideHeight", "outsideDimensionUnit", "tareWeight", "tareWeightUnit", "maxLoadedWeight", "maxLoadedWeightUnit", "providerPackageCode", "active", "isDefault", "preferenceOrder", "insideSameAsOutsideConfirmed", "deactivatedAt", "createdAt" ] }, "CreateShippingBoxPresetDto": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "example": "12 × 9 × 6 mailer" }, "type": { "description": "Authoring kind only. Carrier flat-rate behavior remains inactive until its dedicated provider slice.", "allOf": [ { "$ref": "#/components/schemas/ShippingBoxPresetType" } ] }, "insideLength": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside length: what contents can fit." }, "insideWidth": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside width: what contents can fit." }, "insideHeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside height: what contents can fit." }, "insideDimensionUnit": { "description": "Unit shared by the complete inside-dimension group.", "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "outsideLength": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel length sent to carrier rating." }, "outsideWidth": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel width sent to carrier rating." }, "outsideHeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel height sent to carrier rating." }, "outsideDimensionUnit": { "description": "Unit shared by the complete outside-dimension group.", "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "tareWeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Empty-carton packaging weight." }, "tareWeightUnit": { "description": "Unit for the empty-carton tare.", "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "maxLoadedWeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Optional maximum total loaded package weight. Send together with maxLoadedWeightUnit.", "nullable": true }, "maxLoadedWeightUnit": { "nullable": true, "description": "Unit for maxLoadedWeight. Both maximum-weight fields must be set or null.", "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "providerPackageCode": { "type": "string", "maxLength": 100, "nullable": true, "description": "Optional carrier package code. Saving it does not enable provider flat-rate behavior." }, "insideSameAsOutsideConfirmed": { "type": "boolean", "description": "Explicit merchant confirmation that inside dimensions are being approximated as exactly equal to outside dimensions." } }, "required": [ "name", "type", "insideLength", "insideWidth", "insideHeight", "insideDimensionUnit", "outsideLength", "outsideWidth", "outsideHeight", "outsideDimensionUnit", "tareWeight", "tareWeightUnit", "insideSameAsOutsideConfirmed" ] }, "ShippingBoxPresetOrderEntryDto": { "type": "object", "properties": { "presetId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "presetId", "expectedRevision" ] }, "ReorderShippingBoxPresetsDto": { "type": "object", "properties": { "presets": { "maxItems": 100, "description": "Every current preset exactly once, in the desired deterministic order.", "type": "array", "items": { "$ref": "#/components/schemas/ShippingBoxPresetOrderEntryDto" } } }, "required": [ "presets" ] }, "ReplaceShippingBoxPresetDto": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "example": "12 × 9 × 6 mailer" }, "type": { "description": "Authoring kind only. Carrier flat-rate behavior remains inactive until its dedicated provider slice.", "allOf": [ { "$ref": "#/components/schemas/ShippingBoxPresetType" } ] }, "insideLength": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside length: what contents can fit." }, "insideWidth": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside width: what contents can fit." }, "insideHeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Usable inside height: what contents can fit." }, "insideDimensionUnit": { "description": "Unit shared by the complete inside-dimension group.", "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "outsideLength": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel length sent to carrier rating." }, "outsideWidth": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel width sent to carrier rating." }, "outsideHeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Outside parcel height sent to carrier rating." }, "outsideDimensionUnit": { "description": "Unit shared by the complete outside-dimension group.", "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "tareWeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Empty-carton packaging weight." }, "tareWeightUnit": { "description": "Unit for the empty-carton tare.", "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "maxLoadedWeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000, "exclusiveMaximum": true, "description": "Optional maximum total loaded package weight. Send together with maxLoadedWeightUnit.", "nullable": true }, "maxLoadedWeightUnit": { "nullable": true, "description": "Unit for maxLoadedWeight. Both maximum-weight fields must be set or null.", "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "providerPackageCode": { "type": "string", "maxLength": 100, "nullable": true, "description": "Optional carrier package code. Saving it does not enable provider flat-rate behavior." }, "insideSameAsOutsideConfirmed": { "type": "boolean", "description": "Explicit merchant confirmation that inside dimensions are being approximated as exactly equal to outside dimensions." }, "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current revision observed by the editor. Stale writes fail with 409." } }, "required": [ "name", "type", "insideLength", "insideWidth", "insideHeight", "insideDimensionUnit", "outsideLength", "outsideWidth", "outsideHeight", "outsideDimensionUnit", "tareWeight", "tareWeightUnit", "insideSameAsOutsideConfirmed", "expectedRevision" ] }, "ShippingBoxPresetRevisionCommandDto": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current revision observed by the caller. Stale lifecycle/default writes fail with 409." } }, "required": [ "expectedRevision" ] }, "ShippingProviderCarrierDto": { "type": "object", "properties": { "carrierId": { "type": "string", "description": "Provider-assigned carrier id (`se-…`). Account-specific — required input on every rate call, never shared across tenants.", "example": "se-1234567" }, "carrierCode": { "type": "string", "description": "Provider carrier code, e.g. `usps` or `ups`.", "example": "usps" }, "friendlyName": { "type": "string", "description": "Carrier display name from the provider.", "example": "USPS" }, "nickname": { "type": "string", "nullable": true, "description": "The tenant's own nickname for the carrier account, or null." }, "requiresFundedAmount": { "type": "boolean", "nullable": true, "description": "Whether ShipEngine requires this carrier account to be pre-funded. Null when the provider did not return a trustworthy flag." }, "balanceInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true, "description": "Last refreshed ShipEngine scalar balance normalized to hundredths under its documented USD/GBP funding contract. List Carriers does not return the account currency. Null when the scalar is unavailable or invalid." } }, "required": [ "carrierId", "carrierCode", "friendlyName", "nickname", "requiresFundedAmount", "balanceInMinorUnits" ] }, "ShippingProviderStatusDto": { "type": "object", "properties": { "connected": { "type": "boolean", "description": "Whether a provider connection exists for this org." }, "provider": { "type": "string", "description": "Shipping provider discriminator. Always `shipengine` today.", "example": "shipengine" }, "sandbox": { "type": "boolean", "nullable": true, "description": "True when the stored key is a `TEST_`-prefixed sandbox key; null when no connection exists." }, "keyMask": { "type": "string", "nullable": true, "description": "Masked key fingerprint (e.g. `TEST_••••ab12`), or null when no connection exists. The full key is never returned.", "example": "TEST_••••ab12" }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the provider was first connected (ISO 8601), or null." }, "lastVerifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the stored key last passed a live provider check (ISO 8601), or null." }, "disabled": { "type": "boolean", "description": "True when the connection has been parked (soft kill switch) — live quoting skips disabled connections." }, "historicalLabelAccessVerified": { "type": "boolean", "description": "True when the current key was verified against an existing label in the same provider account. An enabled connection may access purchases from older key generations. False also covers a first connection; an unverified replacement leaves historical operations fenced." }, "carriers": { "description": "Cached snapshot of the tenant's connected carriers, refreshed at connect/test time. Empty when no connection exists.", "type": "array", "items": { "$ref": "#/components/schemas/ShippingProviderCarrierDto" } }, "carriersRefreshedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the carrier snapshot was last refreshed (ISO 8601), or null." }, "cipherConfigured": { "type": "boolean", "description": "Whether credential encryption is configured on this environment. When false, connect/test are unavailable (503) and the admin should show a configuration warning." } }, "required": [ "connected", "provider", "sandbox", "keyMask", "connectedAt", "lastVerifiedAt", "disabled", "historicalLabelAccessVerified", "carriers", "carriersRefreshedAt", "cipherConfigured" ] }, "ShippingProviderServiceDto": { "type": "object", "properties": { "serviceCode": { "type": "string", "description": "Provider service code, e.g. `usps_priority_mail`.", "example": "usps_priority_mail" }, "name": { "type": "string", "description": "Human-readable service name from the provider.", "example": "USPS Priority Mail" }, "carrierId": { "type": "string", "description": "Provider-assigned carrier id this service belongs to (`se-…`).", "example": "se-1234567" }, "carrierCode": { "type": "string", "description": "Provider carrier code, e.g. `usps`.", "example": "usps" }, "carrierFriendlyName": { "type": "string", "description": "Carrier display name from the provider.", "example": "USPS" }, "domestic": { "type": "boolean", "description": "Whether the service can carry domestic (same-country) shipments." }, "international": { "type": "boolean", "description": "Whether the service can carry international shipments." } }, "required": [ "serviceCode", "name", "carrierId", "carrierCode", "carrierFriendlyName", "domestic", "international" ] }, "ShippingProviderServicesDto": { "type": "object", "properties": { "services": { "description": "The tenant's connected carriers' rateable services, deduped by service code. Empty only when the live provider read succeeded but returned no catalog services.", "type": "array", "items": { "$ref": "#/components/schemas/ShippingProviderServiceDto" } }, "source": { "type": "string", "enum": [ "live", "snapshot" ], "description": "`live` when this request refreshed the provider successfully; `snapshot` when a provider failure was served from the stored carrier cache.", "example": "live" }, "refreshedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the returned catalog was last observed from the provider. Null is possible only for a legacy snapshot without refresh metadata.", "example": "2026-08-20T18:42:15.000Z" } }, "required": [ "services", "source", "refreshedAt" ] }, "ConnectShippingProviderDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "apiKey": { "type": "string", "minLength": 10, "maxLength": 200, "description": "The tenant's ShipEngine API key. Write-only: stored encrypted at rest and never returned by any read — status responses carry only a masked fingerprint. `TEST_`-prefixed keys connect in sandbox mode.", "example": "TEST_x2f9urMEQZ0…" } }, "required": [ "reason", "apiKey" ] }, "TestShippingProviderConnectionResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when the stored key passed a live carrier listing against the provider." }, "code": { "type": "string", "nullable": true, "description": "Coarse failure code on `ok: false` (e.g. `unauthorized`, `timeout`, `cipher_unavailable`), omitted/null on success." }, "message": { "type": "string", "nullable": true, "description": "Safe display message for the failure, omitted/null on success." }, "carriers": { "description": "The freshly fetched carrier list on success (also persisted to the connection snapshot).", "type": "array", "items": { "$ref": "#/components/schemas/ShippingProviderCarrierDto" } } }, "required": [ "ok" ] }, "BuyShippingLabelLineDto": { "type": "object", "properties": { "lineId": { "type": "string", "format": "uuid", "description": "Server-issued original-order commerce line id. The API verifies that it belongs to this tenant and order before allocating it." }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "Positive quantity from this order line to prepare.", "example": 1 } }, "required": [ "lineId", "quantity" ] }, "BuyShippingLabelPackageDto": { "type": "object", "properties": { "weight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Confirmed loaded package weight, expressed in `weightUnit`.", "example": 3.25 }, "weightUnit": { "description": "Unit for the confirmed loaded package weight.", "example": "LB", "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Confirmed outside parcel length. If any dimension is supplied, length, width, height, and `dimensionUnit` are all required.", "example": 12 }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Confirmed outside parcel width. Part of the all-or-none dimensions group.", "example": 9 }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Confirmed outside parcel height. Part of the all-or-none dimensions group.", "example": 6 }, "dimensionUnit": { "description": "Unit shared by all three outside dimensions. Required with any dimension.", "example": "IN", "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "providerPackageCode": { "type": "string", "maxLength": 100, "description": "Optional provider package code compatible with the selected carrier (for example `package`). It does not replace physical measurements.", "example": "package" }, "recommendationSignature": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$", "description": "Opaque server-authored package recommendation signature. Omit after editing any suggested package fact to proceed as a manual package." } }, "required": [ "weight", "weightUnit" ] }, "DeliveryPromiseRecommendationRequestDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "description": "Exact original-order line quantities being considered for this package. The API tenant-validates them but does not allocate or mutate them.", "type": "array", "items": { "$ref": "#/components/schemas/BuyShippingLabelLineDto" } }, "package": { "description": "Merchant-confirmed loaded package facts. The exact normalized package is used for the fresh reference and every candidate without being persisted.", "allOf": [ { "$ref": "#/components/schemas/BuyShippingLabelPackageDto" } ] } }, "required": [ "lines", "package" ] }, "DeliveryPromiseRecommendationPromiseDto": { "type": "object", "properties": { "tierId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "shipByDate": { "type": "string", "format": "date" }, "deliveryEndDate": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "settingsRevision": { "type": "string" }, "ruleRevision": { "type": "string" } }, "required": [ "tierId", "name", "shipByDate", "deliveryEndDate", "timezone", "settingsRevision", "ruleRevision" ] }, "DeliveryPromiseRecommendationAddressEvidenceDto": { "type": "object", "properties": { "countryCode": { "type": "string", "example": "US" }, "stateProvince": { "type": "string", "example": "ID" }, "postalCode": { "type": "string", "example": "83702" } }, "required": [ "countryCode", "stateProvince", "postalCode" ] }, "DeliveryPromiseRecommendationPackageEvidenceDto": { "type": "object", "properties": { "weightValue": { "type": "number", "example": 3.25 }, "weightUnit": { "type": "string", "enum": [ "pound", "ounce", "gram", "kilogram" ] }, "packageCode": { "type": "string", "example": "package" }, "length": { "type": "number", "nullable": true, "example": 12 }, "width": { "type": "number", "nullable": true, "example": 9 }, "height": { "type": "number", "nullable": true, "example": 6 }, "dimensionUnit": { "type": "string", "nullable": true, "enum": [ "inch", "centimeter" ], "example": "inch" } }, "required": [ "weightValue", "weightUnit", "packageCode", "length", "width", "height", "dimensionUnit" ] }, "DeliveryPromiseRecommendationCapabilityEvidenceDto": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "domestic", "international" ] }, "routeCatalogVerified": { "type": "boolean", "description": "True only when the fresh carrier catalog explicitly supports this route." }, "exactPackageRated": { "type": "boolean", "description": "True because the provider returned this rate for the exact normalized package." }, "customsRequired": { "type": "boolean", "description": "International/customs comparisons fail closed in this MVP, so every returned candidate has this set to false." }, "insuranceRequired": { "type": "boolean", "description": "Insurance-bearing frozen quotes fail closed until requirements are representable." }, "confirmationOrSignatureRequired": { "type": "boolean", "description": "Confirmation/signature-bearing frozen quotes fail closed until requirements are representable." } }, "required": [ "route", "routeCatalogVerified", "exactPackageRated", "customsRequired", "insuranceRequired", "confirmationOrSignatureRequired" ] }, "DeliveryPromiseRecommendationInputsDto": { "type": "object", "properties": { "shipDate": { "type": "string", "format": "date", "description": "Server-derived ship date sent identically for the reference and candidates." }, "currency": { "type": "string", "example": "usd" }, "route": { "type": "string", "enum": [ "domestic", "international" ] }, "origin": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationAddressEvidenceDto" }, "destination": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationAddressEvidenceDto" }, "package": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationPackageEvidenceDto" }, "serviceCodes": { "description": "Normalized service codes submitted together in the single fresh rate request.", "type": "array", "items": { "type": "string" } }, "requiredCapabilities": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationCapabilityEvidenceDto" } }, "required": [ "shipDate", "currency", "route", "origin", "destination", "package", "serviceCodes", "requiredCapabilities" ] }, "DeliveryPromiseRecommendationReferenceDto": { "type": "object", "properties": { "rateId": { "type": "string" }, "provider": { "type": "string", "enum": [ "shipengine" ] }, "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "carrierCostInMinorUnits": { "type": "number", "minimum": 1 }, "currency": { "type": "string" }, "deliveryDays": { "type": "number", "minimum": 0 }, "projectedDeliveryDate": { "type": "string", "format": "date" }, "quotedAt": { "type": "string", "format": "date-time" }, "capabilityEvidence": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationCapabilityEvidenceDto" } }, "required": [ "rateId", "provider", "carrierId", "carrierName", "serviceCode", "serviceName", "carrierCostInMinorUnits", "currency", "deliveryDays", "projectedDeliveryDate", "quotedAt", "capabilityEvidence" ] }, "DeliveryPromiseRecommendationCandidateDto": { "type": "object", "properties": { "rateId": { "type": "string" }, "provider": { "type": "string", "enum": [ "shipengine" ] }, "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "carrierCostInMinorUnits": { "type": "number", "minimum": 1 }, "currency": { "type": "string" }, "deliveryDays": { "type": "number", "minimum": 0 }, "projectedDeliveryDate": { "type": "string", "format": "date" }, "quotedAt": { "type": "string", "format": "date-time" }, "capabilityEvidence": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationCapabilityEvidenceDto" }, "classification": { "type": "string", "enum": [ "same_or_faster", "meets_promise" ] }, "savingsInMinorUnits": { "type": "number", "minimum": 50 } }, "required": [ "rateId", "provider", "carrierId", "carrierName", "serviceCode", "serviceName", "carrierCostInMinorUnits", "currency", "deliveryDays", "projectedDeliveryDate", "quotedAt", "capabilityEvidence", "classification", "savingsInMinorUnits" ] }, "DeliveryPromiseRecommendationResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "quoted", "unavailable" ] }, "unavailableReason": { "type": "string", "nullable": true, "enum": [ "not_promise_mode", "incomplete_promise_evidence", "promise_missed", "settings_changed", "zone_changed", "route_changed", "unsupported_capabilities", "provider_unavailable", "reference_unavailable" ] }, "minimumSavingsInMinorUnits": { "type": "number", "description": "Inclusive MVP savings floor. Only two-decimal currencies are supported.", "example": 50 }, "promise": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseRecommendationPromiseDto" } ] }, "inputs": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseRecommendationInputsDto" } ] }, "reference": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseRecommendationReferenceDto" } ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseRecommendationCandidateDto" } } }, "required": [ "status", "unavailableReason", "minimumSavingsInMinorUnits", "promise", "inputs", "reference", "candidates" ] }, "ShippingLabelRateRequirementsDto": { "type": "object", "properties": { "plannedShipDate": { "type": "string", "format": "date", "nullable": true, "description": "Planned carrier ship date. Omission or null leaves the date to the server/provider; a fresh quote and funded command must use the same explicit date when selected.", "example": "2026-09-15" }, "confirmation": { "type": "string", "enum": [ "none", "signature", "adult_signature" ], "description": "Requested delivery confirmation, applied to every compared rate and the funded label." }, "insuredValueInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Additional carrier insurance coverage in accepted order-currency minor units; zero requests none." } } }, "ShopShippingRatesDto": { "type": "object", "properties": { "shipmentPackageId": { "type": "string", "format": "uuid", "description": "Server-owned FAILED prepared package for a read-only recovery comparison; its lines and physical facts must match." }, "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/BuyShippingLabelLineDto" } }, "package": { "$ref": "#/components/schemas/BuyShippingLabelPackageDto" }, "requirements": { "$ref": "#/components/schemas/ShippingLabelRateRequirementsDto" }, "recipientPhone": { "type": "string", "maxLength": 50, "description": "Optional label-only recipient phone correction used for this comparison and the later exact quote. Does not change the accepted order address." } }, "required": [ "lines", "package" ] }, "ShippingLabelRateRequirementsResponseDto": { "type": "object", "properties": { "plannedShipDate": { "type": "string", "nullable": true, "format": "date", "description": "Carrier ship-date basis. Null means no date was selected for the exact quote, or Shop stopped before it could select a comparison date; a successful Shop comparison returns the server-selected date." }, "confirmation": { "type": "string", "enum": [ "none", "signature", "adult_signature" ] }, "insuredValueInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "description": "Additional carrier insurance coverage in accepted order-currency minor units; zero requests none." } }, "required": [ "plannedShipDate", "confirmation", "insuredValueInMinorUnits" ] }, "ShopShippingRateCostComponentsDto": { "type": "object", "properties": { "basePostageInMinorUnits": { "type": "integer", "minimum": 0, "description": "Provider-returned base shipping amount, before separately returned charges." }, "deliveryConfirmationFeeInMinorUnits": { "type": "integer", "nullable": true, "minimum": 0, "description": "Provider-returned delivery-confirmation charge, including a requested signature when separately itemized. Null means the provider did not return this component; it does not prove a zero fee or confirm the requested signature type." }, "insuranceFeeInMinorUnits": { "type": "integer", "nullable": true, "minimum": 0, "description": "Provider-returned insurance charge. Null means the provider did not separately itemize it, not that coverage was proven free." }, "otherFeeInMinorUnits": { "type": "integer", "nullable": true, "minimum": 0, "description": "Provider-returned aggregate other charge. Null means the provider did not separately itemize other charges." } }, "required": [ "basePostageInMinorUnits", "deliveryConfirmationFeeInMinorUnits", "insuranceFeeInMinorUnits", "otherFeeInMinorUnits" ] }, "ShopShippingRateDto": { "type": "object", "properties": { "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "merchantPostageInMinorUnits": { "type": "integer", "format": "int32", "minimum": 1 }, "costComponents": { "description": "The provider-returned base and separately itemized charges summed into merchantPostageInMinorUnits. A nullable component means it was not separately returned, not a proven zero charge.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingRateCostComponentsDto" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "estimatedDeliveryDate": { "type": "string", "nullable": true, "format": "date", "description": "Provider-authored estimated arrival date for the matching ship date; null means unknown." }, "guaranteedService": { "type": "boolean", "nullable": true, "description": "Provider guarantee flag, if known. An estimated date is never represented as a delivery guarantee." }, "originalService": { "type": "boolean", "description": "True for the immutable checkout carrier/service when captured. It does not rewrite customer guidance or charge." } }, "required": [ "carrierId", "carrierName", "serviceCode", "serviceName", "merchantPostageInMinorUnits", "costComponents", "currency", "estimatedDeliveryDate", "guaranteedService", "originalService" ] }, "ShopShippingCarrierCoverageDto": { "type": "object", "properties": { "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "returnedEligibleRate": { "type": "boolean", "description": "At least one eligible rate was returned for this carrier in this request." } }, "required": [ "carrierId", "carrierName", "returnedEligibleRate" ] }, "ShopShippingRatesResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "RATES", "NO_RATES", "UNAVAILABLE" ] }, "reason": { "type": "string", "nullable": true, "description": "Safe reason for no eligible rates or a non-funded provider failure; null when rates are returned." }, "requirements": { "$ref": "#/components/schemas/ShippingLabelRateRequirementsResponseDto" }, "rates": { "description": "Eligible services returned for this request. Empty means status/reason reports no eligible service or an unavailable comparison; it does not by itself prove that no carrier is connected. Partial results can omit services.", "type": "array", "items": { "$ref": "#/components/schemas/ShopShippingRateDto" } }, "carriers": { "description": "Connected-carrier coverage available to this request. Empty can mean promise evidence was unavailable or manual international shopping stopped before carrier access; it does not by itself prove the tenant has no connected carriers. Use status/reason and partial to interpret coverage.", "type": "array", "items": { "$ref": "#/components/schemas/ShopShippingCarrierCoverageDto" } }, "partial": { "type": "boolean", "description": "The provider reported partial errors, invalid rates, or unusable rows. Returned services are not asserted to cover every connected carrier." }, "quotedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "UI comparison freshness limit; selecting a rate always requires a separate exact quote." } }, "required": [ "status", "reason", "requirements", "rates", "carriers", "partial", "quotedAt", "expiresAt" ] }, "PackageRecommendationRequestDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "description": "Exact original-order line quantities the merchant intends to place in one package.", "type": "array", "items": { "$ref": "#/components/schemas/BuyShippingLabelLineDto" } } }, "required": [ "lines" ] }, "PackageRecommendationResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "RECOMMENDED", "NO_RECOMMENDATION" ], "description": "RECOMMENDED only when a bounded placement witness proves every selected unit fits." }, "signature": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Stable signature over the package decision and all measurement/preset evidence." }, "plan": { "type": "object", "additionalProperties": true, "description": "Server-owned signed plan, including the selected preset and placement witness, or an explicit no-recommendation reason." } }, "required": [ "status", "signature", "plan" ] }, "CancelPreparedShipmentDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" } }, "required": [ "reason" ] }, "ShippingLabelVoidOperationSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "purpose": { "type": "string", "enum": [ "PREPARED_SHIPMENT_CANCELLATION", "PARKED_LABEL_VOID", "POST_HANDOFF_POSTAGE_RETIREMENT" ], "description": "#4050 — what this void operation is FOR, and therefore what a confirmed void does besides retiring postage. PREPARED_SHIPMENT_CANCELLATION cancels the READY shipment; PARKED_LABEL_VOID cancels the PLANNED package; POST_HANDOFF_POSTAGE_RETIREMENT changes nothing but the postage. Read this field rather than inferring purpose from any other value." }, "status": { "type": "string", "enum": [ "REQUESTED", "PROCESSING", "RECONCILIATION_REQUIRED", "VOID_CONFIRMED_CANCEL_PENDING", "VOID_CONFIRMED_PARENT_ABORTED", "COMPLETED", "DENIED_OR_INELIGIBLE" ] }, "carrierRefundDisposition": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "SETTLED", "DENIED", "NOT_APPLICABLE" ] }, "providerMessage": { "type": "string", "nullable": true }, "requestedAt": { "format": "date-time", "type": "string" }, "reconciliationRequiredAt": { "type": "string", "format": "date-time", "nullable": true }, "automaticRetryExhaustedAt": { "type": "string", "format": "date-time", "nullable": true }, "voidConfirmedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "deniedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "purpose", "status", "carrierRefundDisposition", "providerMessage", "requestedAt", "reconciliationRequiredAt", "automaticRetryExhaustedAt", "voidConfirmedAt", "completedAt", "deniedAt", "updatedAt" ] }, "CommerceRecordRevisionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "integer", "format": "int32", "description": "Monotonic per-record revision counter (1-based). A revise op supersedes the current sent revision and clones its content into a new DRAFT at max+1; the customer-visible number is the highest non-superseded revision." }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SUPERSEDED", "ACCEPTED", "VOIDED", "EXPIRED" ], "description": "Revision lifecycle. Only a DRAFT revision is mutable; DRAFT→SENT freezes its content + pricing snapshots immutably, and a later revise flips the prior SENT/ACCEPTED revision to SUPERSEDED." }, "title": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "contentSnapshot": { "type": "object", "additionalProperties": true, "description": "Immutable content snapshot (lines, groups, customer/company block) frozen at send. The frozen record of what the customer was shown." }, "pricingSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Immutable priced-snapshot rationale (ADR-012): the per-line + document pricing breakdown captured at send, so the amounts never re-derive from live catalog/tax config. Null on DRAFT revisions not yet repriced." }, "paymentTermsSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen payment-terms snapshot (net-days / deposit schedule) resolved from the record's payment-term preset at send. Null when no terms apply." }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "shippingInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalInCents": { "type": "integer", "format": "int32" }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string", "nullable": true }, "customerVisibleAt": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "supersededAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "recordId", "revisionNumber", "status", "title", "notes", "contentSnapshot", "pricingSnapshot", "paymentTermsSnapshot", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents", "taxExempt", "taxExemptionReason", "customerVisibleAt", "sentAt", "acceptedAt", "supersededAt", "expiresAt", "createdAt", "updatedAt" ] }, "CommerceLineGroupDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid", "nullable": true }, "pricingRef": { "type": "string", "nullable": true, "description": "Stable reference into the revision pricing snapshot. Null on legacy/manual groups." }, "kind": { "type": "string", "enum": [ "BUNDLE", "PACKAGE", "KIT", "PROPOSAL_SECTION", "CUSTOM" ] }, "compositionItemId": { "type": "string", "format": "uuid", "nullable": true }, "compositionRevision": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "compositionSelectedQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "sortOrder": { "type": "integer", "format": "int32" }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "recordId", "revisionId", "pricingRef", "kind", "compositionItemId", "compositionRevision", "compositionSelectedQuantity", "title", "description", "sortOrder", "metadata", "createdAt", "updatedAt" ] }, "CommerceLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid", "nullable": true }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "pricingRef": { "type": "string", "nullable": true, "description": "Stable reference into the revision pricing snapshot. Null on legacy/manual lines." }, "compositionComponentId": { "type": "string", "format": "uuid", "nullable": true }, "compositionPosition": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "compositionDefinitionQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "compositionEffectiveQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "compositionDiscountBasisPoints": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "nullable": true }, "compositionIntrinsicSavingsInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "compositionPriceAuthorityKind": { "type": "string", "enum": [ "CATALOG", "BOOKING_SERVICE" ], "nullable": true, "description": "Frozen authority used to resolve this composed component price." }, "compositionBookingServiceId": { "type": "string", "format": "uuid", "nullable": true }, "compositionBookingPricingMode": { "type": "string", "enum": [ "FIXED_PRICE", "FLAT_TIME", "PRICING_STRUCTURE" ], "nullable": true }, "compositionBookingPricingBasis": { "type": "string", "enum": [ "FIXED_PRICE", "RESERVED_WINDOW" ], "nullable": true }, "compositionPricingIntervalMinutes": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "compositionPricingIntervalCount": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "compositionPricingUnits": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "appliedPricingPolicyId": { "type": "string", "format": "uuid", "nullable": true }, "appliedPricingPolicyRevisionId": { "type": "string", "format": "uuid", "nullable": true }, "appliedPricingPolicyRevisionNumber": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "appliedPricingPolicyBandId": { "type": "string", "maxLength": 128, "nullable": true }, "appliedPricingPolicyBandUpperBoundMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 527040, "nullable": true }, "appliedPricingPolicyFactorBasisPoints": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000, "nullable": true }, "appliedPricingPolicyElapsedMinutes": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "appliedPricingPolicyMinimumDurationMinutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 527040, "nullable": true }, "appliedPricingPolicyGraceMinutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1440, "nullable": true }, "appliedPricingPolicyEffectiveMinutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 527040, "nullable": true }, "appliedPricingPolicyDerivedUnitPriceInCents": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "category": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "FEE", "DEPOSIT", "ADJUSTMENT", "CUSTOM" ] }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "orderItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Reservation-owning legacy OrderItem for checkout-mirrored lines; null for manual orders and pre-activation aggregate-only history." }, "sku": { "type": "string", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int32" }, "unitPriceInCents": { "type": "integer", "format": "int32" }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalPriceInCents": { "type": "integer", "format": "int32" }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string", "nullable": true }, "servicePeriodStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "servicePeriodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "sortOrder": { "type": "integer", "format": "int32" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "recordId", "revisionId", "groupId", "pricingRef", "compositionComponentId", "compositionPosition", "compositionDefinitionQuantity", "compositionEffectiveQuantity", "compositionDiscountBasisPoints", "compositionIntrinsicSavingsInCents", "compositionPriceAuthorityKind", "compositionBookingServiceId", "compositionBookingPricingMode", "compositionBookingPricingBasis", "compositionPricingIntervalMinutes", "compositionPricingIntervalCount", "compositionPricingUnits", "appliedPricingPolicyId", "appliedPricingPolicyRevisionId", "appliedPricingPolicyRevisionNumber", "appliedPricingPolicyBandId", "appliedPricingPolicyBandUpperBoundMinutes", "appliedPricingPolicyFactorBasisPoints", "appliedPricingPolicyElapsedMinutes", "appliedPricingPolicyMinimumDurationMinutes", "appliedPricingPolicyGraceMinutes", "appliedPricingPolicyEffectiveMinutes", "appliedPricingPolicyDerivedUnitPriceInCents", "category", "itemId", "variantId", "orderItemId", "sku", "name", "description", "quantity", "unitPriceInCents", "subtotalInCents", "discountInCents", "taxInCents", "totalPriceInCents", "taxExempt", "taxExemptionReason", "servicePeriodStartsAt", "servicePeriodEndsAt", "tags", "metadata", "sortOrder", "createdAt", "updatedAt" ] }, "CommerceFulfillmentLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "fulfillmentId": { "type": "string", "format": "uuid" }, "lineId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "replacementReturnItemId": { "type": "string", "format": "uuid", "nullable": true }, "replacesFulfillmentLineId": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "fulfillmentId", "lineId", "quantity", "replacementReturnItemId", "replacesFulfillmentLineId", "metadata", "createdAt", "updatedAt" ] }, "CommerceShipmentLabelPurchaseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "labelKind": { "type": "string", "enum": [ "OUTBOUND", "RETURN" ] }, "packageOrdinal": { "type": "integer", "format": "int32", "minimum": 1 }, "version": { "type": "integer", "format": "int32", "minimum": 1 }, "fulfillmentId": { "type": "string", "format": "uuid", "nullable": true }, "shipmentPackageId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "PURCHASING", "PURCHASED", "FAILED", "RECONCILIATION_REQUIRED", "VOIDED" ] }, "provider": { "type": "string" }, "labelId": { "type": "string", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true }, "labelDownloadUrl": { "type": "string", "nullable": true }, "shipmentCostInCents": { "type": "integer", "format": "int32", "nullable": true }, "shipmentCostCurrency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3 }, "approvedCostInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "#3956 — the merchant-approved fresh quote this attempt was funded against, in minor units. Null on attempts recorded before approved-cost tracking existed." }, "approvedCostCurrency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "description": "Lowercase ISO currency of approvedCostInCents. Null exactly when approvedCostInCents is null (historical absence on attempts recorded before approved-cost tracking); it never signals incomplete provider evidence, which is carried by the reconciliation events." }, "costVarianceInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "Signed difference between the actual provider charge and the approved quote (actual − approved) in minor units. Null when either amount is missing or the currencies differ." }, "providerStatus": { "type": "string", "nullable": true }, "carrierCode": { "type": "string", "nullable": true }, "carrierId": { "type": "string", "nullable": true }, "carrierName": { "type": "string", "nullable": true }, "serviceCode": { "type": "string", "nullable": true }, "serviceDecisionClassification": { "type": "string", "enum": [ "ORIGINAL_SERVICE", "SAME_OR_FASTER", "MEETS_PROMISE", "OVERRIDE" ], "nullable": true }, "serviceDecisionReason": { "type": "string", "nullable": true }, "serviceDecisionActorUserId": { "type": "string", "format": "uuid", "nullable": true }, "serviceDecisionAt": { "type": "string", "format": "date-time", "nullable": true }, "testLabel": { "type": "boolean" }, "needsTracking": { "type": "boolean" }, "claimedAt": { "format": "date-time", "type": "string" }, "failureHttpStatus": { "type": "integer", "format": "int32", "nullable": true }, "failureErrorType": { "type": "string", "nullable": true }, "failureErrorCode": { "type": "string", "nullable": true }, "failureErrorSource": { "type": "string", "nullable": true }, "failureFieldName": { "type": "string", "nullable": true }, "failureRequestId": { "type": "string", "nullable": true }, "failureMessage": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "orderId", "labelKind", "packageOrdinal", "version", "fulfillmentId", "shipmentPackageId", "status", "provider", "labelId", "trackingNumber", "labelDownloadUrl", "shipmentCostInCents", "shipmentCostCurrency", "approvedCostInCents", "approvedCostCurrency", "costVarianceInCents", "providerStatus", "carrierCode", "carrierId", "carrierName", "serviceCode", "serviceDecisionClassification", "serviceDecisionReason", "serviceDecisionActorUserId", "serviceDecisionAt", "testLabel", "needsTracking", "claimedAt", "failureHttpStatus", "failureErrorType", "failureErrorCode", "failureErrorSource", "failureFieldName", "failureRequestId", "failureMessage", "createdAt", "updatedAt" ] }, "CommerceShippingLabelVoidOperationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "purpose": { "type": "string", "enum": [ "PREPARED_SHIPMENT_CANCELLATION", "PARKED_LABEL_VOID", "POST_HANDOFF_POSTAGE_RETIREMENT" ], "description": "#4050 — what this void operation is FOR, and therefore what a confirmed void does besides retiring postage. PREPARED_SHIPMENT_CANCELLATION cancels the READY shipment and releases its allocation; PARKED_LABEL_VOID cancels the PLANNED package; POST_HANDOFF_POSTAGE_RETIREMENT changes nothing but the postage on an already handed-off shipment. Branch on this field: purchaseStatusAtRequest cannot distinguish the first from the third." }, "status": { "type": "string", "enum": [ "REQUESTED", "PROCESSING", "RECONCILIATION_REQUIRED", "VOID_CONFIRMED_CANCEL_PENDING", "VOID_CONFIRMED_PARENT_ABORTED", "COMPLETED", "DENIED_OR_INELIGIBLE" ] }, "purchaseStatusAtRequest": { "type": "string", "enum": [ "PURCHASING", "PURCHASED", "FAILED", "RECONCILIATION_REQUIRED", "VOIDED" ], "description": "#3956 — the purchase state this operation snapshotted at request time: PURCHASED for a prepared-shipment cancellation, RECONCILIATION_REQUIRED for a parked cost-mismatch label voided directly. Immutable for the life of the operation." }, "carrierRefundDisposition": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "SETTLED", "DENIED", "NOT_APPLICABLE" ] }, "lastProviderMessage": { "type": "string", "nullable": true }, "requestedAt": { "format": "date-time", "type": "string" }, "reconciliationRequiredAt": { "type": "string", "format": "date-time", "nullable": true }, "automaticRetryExhaustedAt": { "type": "string", "format": "date-time", "nullable": true }, "voidConfirmedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "deniedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "purpose", "status", "purchaseStatusAtRequest", "carrierRefundDisposition", "lastProviderMessage", "requestedAt", "reconciliationRequiredAt", "automaticRetryExhaustedAt", "voidConfirmedAt", "completedAt", "deniedAt", "updatedAt" ] }, "CommerceExternalLabelRetirementAcknowledgementDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "fulfillmentId": { "type": "string", "format": "uuid" }, "shipmentPackageId": { "type": "string", "format": "uuid", "nullable": true }, "actorUserId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 500 }, "carrierResponsibilityAccepted": { "type": "boolean", "description": "Always true: the merchant accepted responsibility for any external carrier void and carrier-account refund." }, "evidenceSnapshot": { "type": "object", "additionalProperties": true, "description": "Immutable package-local snapshot of the tracking, label artifact, and cost evidence retained at acknowledgement time." }, "acknowledgedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "orderId", "recordId", "fulfillmentId", "shipmentPackageId", "actorUserId", "reason", "carrierResponsibilityAccepted", "evidenceSnapshot", "acknowledgedAt" ] }, "CommerceShipmentPackageContentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "packageId": { "type": "string", "format": "uuid" }, "lineId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "packageId", "lineId", "quantity", "createdAt" ] }, "CommerceShipmentPackageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "packageOrdinal": { "type": "integer", "format": "int32", "minimum": 1 }, "source": { "type": "string", "enum": [ "MANUAL_CUSTOM", "CHECKOUT_PLAN", "BOX_PRESET" ] }, "sourceSnapshot": { "type": "object", "additionalProperties": true }, "shipToSnapshot": { "type": "object", "additionalProperties": true }, "loadedWeight": { "type": "string", "description": "Loaded package weight serialized from Decimal as a base-10 JSON string." }, "loadedWeightUnit": { "type": "string", "enum": [ "OZ", "LB", "G", "KG" ] }, "outsideLength": { "type": "string", "nullable": true, "description": "Outside length serialized from Decimal as a base-10 JSON string." }, "outsideWidth": { "type": "string", "nullable": true, "description": "Outside width serialized from Decimal as a base-10 JSON string." }, "outsideHeight": { "type": "string", "nullable": true, "description": "Outside height serialized from Decimal as a base-10 JSON string." }, "outsideDimensionUnit": { "type": "string", "enum": [ "IN", "CM" ], "nullable": true }, "providerPackageCode": { "type": "string", "nullable": true }, "ratingProvider": { "type": "string" }, "ratingCarrierId": { "type": "string" }, "ratingServiceCode": { "type": "string" }, "ratingAmountInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "ratingCurrency": { "type": "string", "minLength": 3, "maxLength": 3 }, "ratingSnapshot": { "type": "object", "additionalProperties": true }, "ratedAt": { "format": "date-time", "type": "string" }, "confirmedByUserId": { "type": "string", "format": "uuid" }, "confirmedAt": { "format": "date-time", "type": "string" }, "supersedesPackageId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceShipmentPackageContentDto" } }, "labelPurchases": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceShipmentLabelPurchaseDto" } } }, "required": [ "id", "organizationId", "orderId", "recordId", "packageOrdinal", "source", "sourceSnapshot", "shipToSnapshot", "loadedWeight", "loadedWeightUnit", "outsideLength", "outsideWidth", "outsideHeight", "outsideDimensionUnit", "providerPackageCode", "ratingProvider", "ratingCarrierId", "ratingServiceCode", "ratingAmountInCents", "ratingCurrency", "ratingSnapshot", "ratedAt", "confirmedByUserId", "confirmedAt", "supersedesPackageId", "createdAt", "updatedAt", "contents", "labelPurchases" ] }, "CommerceFulfillmentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "goodsKind": { "type": "string", "enum": [ "ORIGINAL_ORDER", "REPLACEMENT_GOODS" ] }, "status": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED", "CANCELLED" ] }, "mode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ] }, "carrier": { "type": "string", "nullable": true }, "serviceLevel": { "type": "string", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true }, "trackingUrl": { "type": "string", "nullable": true }, "externalSource": { "type": "string", "nullable": true }, "externalId": { "type": "string", "nullable": true }, "shipStationOrderId": { "type": "string", "nullable": true }, "shipStationShipmentId": { "type": "string", "nullable": true }, "shipmentPackageId": { "type": "string", "format": "uuid", "nullable": true }, "readyAt": { "type": "string", "format": "date-time", "nullable": true }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "shipNotifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "#1770 — when the \"your order shipped\" customer email was first enqueued for this fulfillment (its first SHIPPED transition). Null until then; the idempotency anchor that stops repeated tracking saves from re-sending." }, "handoffNotificationDecision": { "type": "string", "enum": [ "SEND", "SUPPRESS" ], "nullable": true }, "handoffRecordedAt": { "type": "string", "format": "date-time", "nullable": true }, "handoffSource": { "type": "string", "enum": [ "MERCHANT", "TRUSTED_CARRIER_EVENT", "SYSTEM_CATCH_UP", "POS", "IMPORTED_SOURCE" ], "nullable": true }, "handoffActorId": { "type": "string", "format": "uuid", "nullable": true }, "deliveryRecordedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "#4049/#4054 - when the server recorded the delivery transition, from either a merchant assertion or verified carrier evidence. Distinct from `deliveredAt`, which is the asserted or carrier-observed receipt instant." }, "deliverySource": { "type": "string", "nullable": true, "description": "#4049 - how this delivery was established. Open-ended catalog: see x-extensible-enum for the known stable values and treat any unrecognized value as neither merchant- nor carrier-confirmed. MERCHANT_CONFIRMED is the merchant's own assertion and is never carrier confirmation. CARRIER_CONFIRMED means a verified carrier delivery event established receipt (#4054). Null beside a non-null `deliveredAt` means provenance was never established by the native delivery command (a historical tracking edit, POS in-person completion, or imported handoff evidence); that must not be rendered as carrier proof either.", "x-extensible-enum": [ "MERCHANT_CONFIRMED", "CARRIER_CONFIRMED" ] }, "deliveryActorId": { "type": "string", "format": "uuid", "nullable": true }, "deliveryReason": { "type": "string", "nullable": true, "description": "#4049 - the required merchant justification captured with the assertion. Merchant-internal; never projected to a customer surface." }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceFulfillmentLineDto" } }, "shippingLabelPurchases": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceShipmentLabelPurchaseDto" } }, "shippingLabelVoidOperations": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceShippingLabelVoidOperationDto" } }, "externalLabelRetirementAcknowledgement": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CommerceExternalLabelRetirementAcknowledgementDto" } ] }, "shipmentPackage": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CommerceShipmentPackageDto" } ] } }, "required": [ "id", "organizationId", "recordId", "goodsKind", "status", "mode", "carrier", "serviceLevel", "trackingNumber", "trackingUrl", "externalSource", "externalId", "shipStationOrderId", "shipStationShipmentId", "shipmentPackageId", "readyAt", "shippedAt", "deliveredAt", "shipNotifiedAt", "handoffNotificationDecision", "handoffRecordedAt", "handoffSource", "handoffActorId", "deliveryRecordedAt", "deliverySource", "deliveryActorId", "deliveryReason", "metadata", "createdAt", "updatedAt", "lines", "shippingLabelPurchases", "shippingLabelVoidOperations", "externalLabelRetirementAcknowledgement", "shipmentPackage" ] }, "CommerceContractPacketDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] }, "title": { "type": "string" }, "displayNumber": { "type": "string", "nullable": true, "description": "Human-facing contract number (e.g. C-1001), allocated at send. Null while DRAFT." }, "contentSnapshot": { "type": "object", "additionalProperties": true }, "provider": { "type": "string", "nullable": true, "description": "External e-signature provider, when the packet is fulfilled off-platform. Null for first-party (in-app) signing, the only mode shipped in M3.5." }, "externalId": { "type": "string", "nullable": true, "description": "Provider-side packet id when provider is set." }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "signedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "recordId", "revisionId", "status", "title", "displayNumber", "contentSnapshot", "provider", "externalId", "sentAt", "signedAt", "declinedAt", "expiresAt", "createdAt", "updatedAt" ] }, "CommerceRecordDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "source": { "type": "string", "enum": [ "ONLINE", "MANUAL", "POS", "WHOLESALE", "BOOKING", "SUBSCRIPTION", "RENEWAL" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ], "description": "Commercial lifecycle axis (DRAFT→SENT→ACCEPTED/DECLINED/EXPIRED→CONVERTED, plus terminal VOIDED/CANCELLED). Forward-only; drives which lifecycle actions are permitted. Independent of the payment/fulfillment/signature axes." }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "description": "Payment axis, derived from the payment/refund ledger. Full value space: NOT_REQUIRED, UNPAID, PARTIALLY_PAID, PAID, PARTIALLY_REFUNDED, REFUNDED, FAILED, CANCELLED. Moves independently of the commercial status." }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ], "description": "Shipment fulfillment axis. Committed orders with positive PRODUCT quantity start UNFULFILLED; orders without shippable PRODUCT quantity remain NOT_REQUIRED. Booking/service and subscription entitlement work stays on its operational projection." }, "outboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true, "description": "Canonical outbound physical handoff mode; null when not planned." }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true, "description": "Canonical inbound return handoff mode; null when not planned." }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Deprecated display-only compatibility summary derived from authoritative agreement requirements/satisfactions, with a legacy execution fallback. Full value space: NOT_REQUIRED, PENDING, SIGNED, DECLINED, EXPIRED, CANCELLED. Never use it to authorize or gate a command." }, "displayNumber": { "type": "string", "nullable": true, "description": "Human-facing document number (e.g. Q-1001, INV-1001, C-1001), allocated once at send/issue and stable for the life of the record. Null while DRAFT. Customers address account documents by this number." }, "displayNumberKind": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER", "CONTRACT" ], "nullable": true, "description": "Which numbering series allocated displayNumber (QUOTE/INVOICE/…)." }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "customerEmail": { "type": "string", "nullable": true }, "customerPhone": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "orderId": { "type": "string", "format": "uuid", "nullable": true }, "sourceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "The source quote this order was converted from (#1333)." }, "orderRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Authoritative shared-commerce order linked to this invoice, when present." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "paymentTermPresetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Payment-term preset applied to this record; its terms are frozen into paymentTermsSnapshot at send. Null when no terms apply." }, "paymentTermsSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen payment-terms snapshot (net-days / deposit schedule) captured at send from paymentTermPresetId. Null when no terms apply." }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string", "nullable": true }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "shippingInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalInCents": { "type": "integer", "format": "int32", "description": "Document total in minor units (cents). Commerce money amounts are 32-bit integer cents by design: document totals are capped at 2,147,483,647 cents (~$21.47M), and per-amount line inputs at ±1,000,000,000 cents ($10M). Pricing writes that would exceed these bounds are rejected with 400." }, "amountPaidInCents": { "type": "integer", "format": "int32", "description": "Gross recorded payments (minor units), derived from the payment ledger. Net paid = amountPaidInCents − refundedInCents." }, "refundedInCents": { "type": "integer", "format": "int32", "description": "Total refunded (minor units), derived from the payment ledger." }, "balanceDueInCents": { "type": "integer", "format": "int32", "description": "Outstanding balance (minor units): max(0, totalInCents − amountPaidInCents), i.e. based on GROSS payments. A refund does NOT re-open the balance (ADR-013); the refund dimension lives on refundedInCents + paymentStatus. Zero once gross payments cover the total." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "voidedAt": { "type": "string", "format": "date-time", "nullable": true }, "convertedAt": { "type": "string", "format": "date-time", "nullable": true }, "externalSource": { "type": "string", "nullable": true, "description": "System of record for an externally-originated document (e.g. a wholesale ERP). Together with externalId it forms the external identity; the list filter requires externalSource whenever externalId is supplied." }, "externalId": { "type": "string", "nullable": true, "description": "Opaque id of this document in the externalSource system. The triple (organization, externalSource, externalId) is unique — many externalIds may exist per source, each unique within its (organization, externalSource) pair — which enables idempotent external imports." }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceRecordRevisionDto" } }, "lineGroups": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceLineGroupDto" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceLineDto" } }, "fulfillments": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceFulfillmentDto" } }, "contractPackets": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceContractPacketDto" } } }, "required": [ "id", "organizationId", "type", "source", "commercialStatus", "paymentStatus", "fulfillmentStatus", "outboundFulfillmentMode", "outboundDueAt", "inboundFulfillmentMode", "inboundDueAt", "signatureStatus", "displayNumber", "displayNumberKind", "customerId", "customerName", "customerEmail", "customerPhone", "companyName", "orderId", "sourceRecordId", "orderRecordId", "currency", "paymentTermPresetId", "paymentTermsSnapshot", "taxExempt", "taxExemptionReason", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents", "amountPaidInCents", "refundedInCents", "balanceDueInCents", "expiresAt", "sentAt", "acceptedAt", "declinedAt", "cancelledAt", "voidedAt", "convertedAt", "externalSource", "externalId", "metadata", "createdAt", "updatedAt", "revisions", "lineGroups", "lines", "fulfillments", "contractPackets" ] }, "CancelPreparedShipmentResponseDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "CANCELLED", "CANCELLATION_PENDING", "CANCELLATION_RECONCILIATION_REQUIRED", "CANCELLATION_DENIED" ] }, "replayed": { "type": "boolean", "description": "True when this request returned an already-recorded target state or cancellation intent." }, "message": { "type": "string", "description": "Server-authored merchant guidance; never a raw provider response." }, "operation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShippingLabelVoidOperationSummaryDto" } ] }, "record": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } }, "required": [ "outcome", "replayed", "message", "operation", "record" ] }, "RetryPreparedShipmentCancellationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" } }, "required": [ "reason" ] }, "ShippingLabelReconciliationEventDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "purchaseId": { "type": "string", "format": "uuid" }, "shipmentPackageId": { "type": "string", "format": "uuid", "nullable": true, "description": "Null only for legacy attempts recorded before per-package label purchases existed; every current attempt is bound to one exact package." }, "fulfillmentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Null only for legacy attempts that predate prepared-shipment binding; every current attempt is bound to one exact fulfillment." }, "action": { "type": "string", "enum": [ "LOOKUP", "LEGACY_DISPOSITION" ], "description": "Original closed action catalog, kept stable for readers generated before #3956. LOOKUP is a safe provider read of the exact label (an acceptance at actual cost is projected here as LOOKUP because it is exactly that read plus adoption); LEGACY_DISPOSITION is attributable operator testimony for pre-package rows. The precise action is actionDetail." }, "actionDetail": { "type": "string", "description": "Precise reconciliation action from the open-ended catalog; see x-extensible-enum for the known stable values and tolerate an unknown value by rendering it by name. Equals action except where the precise value postdates the original closed catalog: ACCEPT_ACTUAL_COST (explicit provider-re-verified acceptance of a completed label at its actual cost) is published as action LOOKUP.", "example": "LOOKUP", "x-extensible-enum": [ "LOOKUP", "LEGACY_DISPOSITION", "ACCEPT_ACTUAL_COST" ] }, "result": { "type": "string", "enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED" ], "description": "Original closed outcome catalog, kept stable for readers generated before #3956. FOUND_ADOPTED_READY is the only outcome that moves a package to READY (an acceptance at actual cost is projected here as FOUND_ADOPTED_READY because the exact label was found and adopted); every other outcome leaves the attempt blocked, pending, or released for retry as documented on the message. The precise outcome is resultDetail." }, "resultDetail": { "type": "string", "description": "Precise reconciliation outcome from the open-ended catalog; see x-extensible-enum for the known stable values and tolerate an unknown value by rendering it by name. Equals result except where the precise value postdates the original closed catalog: COST_ACCEPTED_READY (the exact completed label was re-verified and adopted at its actual cost) is published as result FOUND_ADOPTED_READY.", "example": "EVIDENCE_MISMATCH", "x-extensible-enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED", "COST_ACCEPTED_READY" ] }, "actorUserId": { "type": "string", "format": "uuid" }, "reason": { "type": "string" }, "lookupIdentity": { "type": "string", "enum": [ "PROVIDER_LABEL_ID", "PROVIDER_EXTERNAL_SHIPMENT_ID", "NONE" ] }, "lookupIdentityValue": { "type": "string", "nullable": true, "description": "Exact bounded label id or server-minted external shipment reference used for the lookup; null for legacy dispositions." }, "providerHttpStatus": { "type": "number", "nullable": true }, "providerErrorType": { "type": "string", "nullable": true }, "providerErrorCode": { "type": "string", "nullable": true }, "providerErrorSource": { "type": "string", "nullable": true }, "providerFieldName": { "type": "string", "nullable": true }, "providerRequestId": { "type": "string", "nullable": true }, "providerMessage": { "type": "string", "nullable": true }, "originalFailureHttpStatus": { "type": "number", "nullable": true }, "originalFailureErrorType": { "type": "string", "nullable": true }, "originalFailureErrorCode": { "type": "string", "nullable": true }, "originalFailureErrorSource": { "type": "string", "nullable": true }, "originalFailureFieldName": { "type": "string", "nullable": true }, "originalFailureRequestId": { "type": "string", "nullable": true }, "originalFailureMessage": { "type": "string", "nullable": true }, "operatorEvidenceNote": { "type": "string", "nullable": true }, "evidenceLabelId": { "type": "string", "nullable": true }, "evidenceProviderStatus": { "type": "string", "nullable": true }, "evidenceIsReturnLabel": { "type": "boolean", "nullable": true }, "evidenceVoided": { "type": "boolean", "nullable": true }, "evidenceTrackingPresent": { "type": "boolean", "nullable": true }, "evidenceArtifactPresent": { "type": "boolean", "nullable": true }, "evidenceCostInCents": { "type": "number", "nullable": true }, "evidenceCostCurrency": { "type": "string", "nullable": true }, "evidenceCarrierCode": { "type": "string", "nullable": true }, "evidenceCarrierId": { "type": "string", "nullable": true }, "evidenceServiceCode": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "purchaseId", "shipmentPackageId", "fulfillmentId", "action", "actionDetail", "result", "resultDetail", "actorUserId", "reason", "lookupIdentity", "lookupIdentityValue", "providerHttpStatus", "providerErrorType", "providerErrorCode", "providerErrorSource", "providerFieldName", "providerRequestId", "providerMessage", "originalFailureHttpStatus", "originalFailureErrorType", "originalFailureErrorCode", "originalFailureErrorSource", "originalFailureFieldName", "originalFailureRequestId", "originalFailureMessage", "operatorEvidenceNote", "evidenceLabelId", "evidenceProviderStatus", "evidenceIsReturnLabel", "evidenceVoided", "evidenceTrackingPresent", "evidenceArtifactPresent", "evidenceCostInCents", "evidenceCostCurrency", "evidenceCarrierCode", "evidenceCarrierId", "evidenceServiceCode", "createdAt" ] }, "ShippingLabelReconciliationStatusDto": { "type": "object", "properties": { "purchaseId": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "AUTOMATIC_LOOKUP", "STALE_PURCHASE_RECOVERY", "LEGACY_DISPOSITION", "NONE" ] }, "automaticLookupAllowed": { "type": "boolean" }, "stalePurchaseRecoveryAllowed": { "type": "boolean", "description": "True only when an exact package-bound PURCHASING claim is stale enough for the explicit command to park it before safe reconciliation." }, "legacyDispositionAllowed": { "type": "boolean" }, "costAcceptanceAllowed": { "type": "boolean", "description": "#3956 — true only when the parked attempt is a known completed, printable outbound label on a planned package whose valid same-currency provider cost differs from the merchant-approved fresh quote. Acceptance re-verifies the label at the provider before adopting it." }, "parkedVoidAllowed": { "type": "boolean", "description": "#3956 — true only when the parked cost-mismatch label may be voided directly at the provider as the alternative to acceptance: exactly the acceptance eligibility (package-bound completed label whose valid same-currency cost differs from the approved quote, on a PLANNED fulfillment) and no void of this label requested yet. One void operation exists per label, so once a void has been requested this stays false for the life of the attempt; a denied void leaves acceptance available. A confirmed void cancels the planned package and releases its items." }, "parkedVoidRetryAllowed": { "type": "boolean", "description": "#3956 — true only when a parked-label void has exhausted automatic reconciliation and an Owner/Admin may retry one exact read-only carrier check." }, "voidOperationStatus": { "type": "string", "enum": [ "REQUESTED", "PROCESSING", "RECONCILIATION_REQUIRED", "VOID_CONFIRMED_CANCEL_PENDING", "VOID_CONFIRMED_PARENT_ABORTED", "COMPLETED", "DENIED_OR_INELIGIBLE" ], "nullable": true, "description": "Status of the void operation bound to this attempt. Null means no void of this label has ever been requested (the common case), never an unknown state." }, "fulfillmentId": { "type": "string", "format": "uuid", "nullable": true, "description": "The prepared fulfillment this attempt is bound to. Null only for legacy attempts that predate prepared-shipment binding; such attempts are never eligible for acceptance." }, "approvedCostInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "Merchant-approved fresh quote in minor units, from the purchase row or, for attempts claimed before approved-cost tracking, the package rating stapled to the same claim. Null only when neither exists (legacy attempt with no package rating); this is historical absence, not incomplete provider evidence." }, "approvedCostCurrency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "description": "Lowercase ISO currency of approvedCostInCents. Null exactly when approvedCostInCents is null." }, "actualCostInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "Actual provider charge in minor units as last recorded for this attempt. Null when the provider has not yet confirmed a label (attempt still ambiguous) or returned no valid amount; the two cases are distinguished by the event evidence, not by this field." }, "actualCostCurrency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "description": "Lowercase ISO currency of actualCostInCents. Null exactly when actualCostInCents is null, or when the provider returned an amount without a recognizable currency (that attempt is never acceptable)." }, "costVarianceInCents": { "type": "integer", "format": "int32", "nullable": true, "description": "Signed difference actual − approved in minor units. Null when either amount is absent or the currencies differ; consumers must not read null as \"no difference\"." }, "certainty": { "type": "string", "enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED" ], "description": "Latest recorded outcome for the current attempt in the original closed catalog (kept stable for readers generated before #3956), or null when no reconciliation event exists yet for this attempt. The precise value is certaintyDetail.", "nullable": true }, "certaintyDetail": { "type": "string", "description": "Precise latest outcome for the current attempt from the open-ended catalog (see x-extensible-enum; tolerate unknown values), or null exactly when certainty is null. Differs from certainty only where the precise value postdates the original closed catalog (COST_ACCEPTED_READY is published as certainty FOUND_ADOPTED_READY).", "example": "EVIDENCE_MISMATCH", "x-extensible-enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED", "COST_ACCEPTED_READY" ], "nullable": true }, "message": { "type": "string", "description": "Safe operator guidance derived by the server from current identity, credential generation, and immutable history." }, "nextLookupAt": { "type": "string", "format": "date-time", "nullable": true }, "lastEvent": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShippingLabelReconciliationEventDto" } ] } }, "required": [ "purchaseId", "mode", "automaticLookupAllowed", "stalePurchaseRecoveryAllowed", "legacyDispositionAllowed", "costAcceptanceAllowed", "parkedVoidAllowed", "parkedVoidRetryAllowed", "voidOperationStatus", "fulfillmentId", "approvedCostInCents", "approvedCostCurrency", "actualCostInCents", "actualCostCurrency", "costVarianceInCents", "certainty", "certaintyDetail", "message", "nextLookupAt", "lastEvent" ] }, "QuoteShippingLabelSelectionDto": { "type": "object", "properties": { "requirements": { "description": "Optional planned ship date, signature and carrier-insurance basis shared with comparison and purchase.", "allOf": [ { "$ref": "#/components/schemas/ShippingLabelRateRequirementsDto" } ] }, "shipmentPackageId": { "type": "string", "format": "uuid", "description": "Server-owned prepared-package id when refreshing a definitive FAILED attempt. Its locked lines/package facts must match this quote." }, "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/BuyShippingLabelLineDto" } }, "package": { "$ref": "#/components/schemas/BuyShippingLabelPackageDto" }, "carrierId": { "type": "string", "maxLength": 100, "description": "Exact connected ShipEngine carrier selected by the merchant.", "example": "se-123456" }, "serviceCode": { "type": "string", "maxLength": 100, "description": "Exact carrier service selected by the merchant.", "example": "usps_priority_mail" }, "recipientPhone": { "type": "string", "maxLength": 50, "description": "Optional label-only recipient phone correction, rated as part of the same exact contract that the funded command later confirms.", "example": "+1 208-555-1234" } }, "required": [ "lines", "package", "carrierId", "serviceCode" ] }, "ShippingLabelFundingPreflightDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SANDBOX", "NOT_REQUIRED", "SUFFICIENT", "INSUFFICIENT", "UNAVAILABLE" ] }, "unavailableReason": { "type": "string", "enum": [ "FUNDING_REQUIREMENT_UNAVAILABLE", "BALANCE_UNAVAILABLE", "BALANCE_CURRENCY_UNSUPPORTED" ], "nullable": true, "description": "Actionable reason for an `UNAVAILABLE` preflight; null for every other status." }, "requiresFundedAmount": { "type": "boolean", "nullable": true, "description": "ShipEngine carrier funding requirement, or null when it could not be proven." }, "balanceInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true, "description": "Current ShipEngine Balance scalar normalized to hundredths for comparison with the exact USD/GBP provider rate. List Carriers does not declare the balance currency. Null for sandbox or unavailable evidence." }, "requiredInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "usd" }, "canPurchase": { "type": "boolean", "description": "Whether the current preflight permits the separate funded label command." } }, "required": [ "status", "unavailableReason", "requiresFundedAmount", "balanceInMinorUnits", "requiredInMinorUnits", "currency", "canPurchase" ] }, "QuoteShippingLabelSelectionResponseDto": { "type": "object", "properties": { "requirements": { "$ref": "#/components/schemas/ShippingLabelRateRequirementsResponseDto" }, "selectionQuoteFingerprint": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Opaque fingerprint of the normalized server-authoritative decision evidence. The funded command must echo it and fails closed if any evidence changed." }, "classification": { "type": "string", "enum": [ "ORIGINAL_SERVICE", "SAME_OR_FASTER", "MEETS_PROMISE", "OVERRIDE" ] }, "serviceSelectionBasis": { "type": "string", "enum": [ "CAPTURED_CARRIER_SERVICE", "DELIVERY_PROMISE", "MANUAL_SHIPPING_METHOD", "NO_CAPTURED_CARRIER_SERVICE" ], "description": "The immutable customer-facing shipping basis against which the merchant is selecting actual postage. Manual/free and no-capture orders never imply carrier equivalence or a customer delivery promise." }, "recommended": { "type": "boolean", "description": "True only for a same-or-faster promise-preserving savings candidate." }, "requiresNonRecommendedConfirmation": { "type": "boolean", "description": "True when the Admin must collect a separate selection acknowledgement. Captured/promise substitutions acknowledge a non-recommended choice; manual/free and no-capture orders instead confirm the actual postage choice without making a recommendation, equivalence, or promise claim." }, "requiresOverrideReason": { "type": "boolean", "description": "True when the funded command must include a separate concise reason for either a non-recommended captured-service choice or the actual postage choice on a manual/free or no-capture order." }, "carrierId": { "type": "string" }, "carrierName": { "type": "string" }, "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "carrierCostInMinorUnits": { "type": "integer", "format": "int32", "minimum": 0 }, "fundingPreflight": { "$ref": "#/components/schemas/ShippingLabelFundingPreflightDto" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "usd" }, "deliveryDays": { "type": "number", "nullable": true, "minimum": 0 }, "estimatedDeliveryDate": { "type": "string", "nullable": true, "format": "date", "description": "Provider-authored estimated arrival date for the matching planned ship date; null means timing unknown." }, "guaranteedService": { "type": "boolean", "nullable": true, "description": "Provider rate guarantee flag; null means the provider did not supply one. This does not guarantee the customer delivery promise." }, "quotedAt": { "type": "string", "format": "date-time" }, "recommendation": { "nullable": true, "description": "Fresh original reference plus same-or-faster and meets-promise candidates. Null for exact-service checkout orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseRecommendationResponseDto" } ] } }, "required": [ "requirements", "selectionQuoteFingerprint", "classification", "serviceSelectionBasis", "recommended", "requiresNonRecommendedConfirmation", "requiresOverrideReason", "carrierId", "carrierName", "serviceCode", "serviceName", "carrierCostInMinorUnits", "fundingPreflight", "currency", "deliveryDays", "estimatedDeliveryDate", "guaranteedService", "quotedAt", "recommendation" ] }, "BuyShippingLabelDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "requirements": { "description": "Shipment requirements from the matching exact read-only quote; a mismatch fails before spend.", "allOf": [ { "$ref": "#/components/schemas/ShippingLabelRateRequirementsDto" } ] }, "shipmentPackageId": { "type": "string", "format": "uuid", "description": "Server-owned prepared-package id used to recover or retry an existing authoritative FAILED label attempt after a reload. It must belong to this tenant and order; immutable lines/package facts must match. Omit when creating a new prepared package." }, "lines": { "minItems": 1, "maxItems": 200, "description": "Exact original-order line quantities to allocate to this prepared package.", "type": "array", "items": { "$ref": "#/components/schemas/BuyShippingLabelLineDto" } }, "package": { "description": "Confirmed loaded package facts used identically for the fresh rate preflight and funded label request.", "allOf": [ { "$ref": "#/components/schemas/BuyShippingLabelPackageDto" } ] }, "serviceCode": { "type": "string", "maxLength": 100, "description": "Exact service code from the matching reviewed selection quote. Omit only to use the customer's captured original service; an exceptional cross-service choice must survive server classification, fresh preflight, fingerprint validation, and any required justification.", "example": "usps_priority_mail" }, "carrierId": { "type": "string", "maxLength": 100, "description": "Exact connected ShipEngine carrier id from the matching reviewed selection quote. Omit only with the customer's captured original carrier; it is never a free-form substitution at funded spend.", "example": "se-123456" }, "recipientPhone": { "type": "string", "maxLength": 50, "description": "Explicit recipient-phone correction for this label purchase only. Used when the selected carrier/service preflight requires a phone that was not captured (or rejects the captured value). Does not mutate the immutable order-time shipping snapshot and is not globally required.", "example": "+1 208-555-1234" }, "selectionQuoteFingerprint": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$", "description": "#2447 — opaque fingerprint returned by a matching reviewed exact selection quote. The server freshly recomputes all evidence and rejects stale or mismatched confirmation before provider spend." }, "overrideReason": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Separate concise justification required for a meets-promise or outside-recommendation service, or for the actual postage choice on a manual/free or no-capture order. It is not the high-risk spend reason.", "example": "Use the less expensive service; the customer promise is preserved." } }, "required": [ "reason", "lines", "package", "selectionQuoteFingerprint" ] }, "PurchasedShippingLabelDto": { "type": "object", "properties": { "labelId": { "type": "string", "description": "ShipEngine's label id (`se-…`) — the void/refund handle.", "example": "se-987654" }, "trackingNumber": { "type": "string", "nullable": true, "description": "Carrier tracking number, or null when the provider omitted it.", "example": "9400111899223197428490" }, "labelDownloadUrl": { "type": "string", "nullable": true, "description": "Direct URL to the printable PDF label, or null when absent.", "example": "https://api.shipengine.com/v1/downloads/10/…/label.pdf" }, "shipmentCostInCents": { "type": "number", "description": "Charged label cost in integer cents (shipping + insurance).", "example": 790 }, "shipmentCostCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Validated lowercase ISO-4217 currency for the charged cost.", "example": "usd" }, "carrierCode": { "type": "string", "description": "Carrier code the label was bought against (e.g. `usps`).", "example": "usps" }, "serviceCode": { "type": "string", "nullable": true, "description": "Service code the label was bought against.", "example": "usps_priority_mail" }, "testLabel": { "type": "boolean", "description": "True when a non-chargeable sandbox test label was produced (TEST_ key).", "example": false } }, "required": [ "labelId", "trackingNumber", "labelDownloadUrl", "shipmentCostInCents", "shipmentCostCurrency", "carrierCode", "serviceCode", "testLabel" ] }, "PreparedShippingLabelShipmentDto": { "type": "object", "properties": { "fulfillmentId": { "type": "string", "format": "uuid", "description": "Prepared CommerceFulfillment id for the selected line quantities." }, "shipmentPackageId": { "type": "string", "format": "uuid", "description": "Server-owned immutable order shipment package id bound to this label." }, "packageOrdinal": { "type": "number", "minimum": 1, "description": "Server-assigned order-scoped physical package ordinal.", "example": 1 }, "status": { "type": "string", "enum": [ "READY" ], "description": "Always READY: postage is prepared, but carrier handoff has not occurred.", "example": "READY" } }, "required": [ "fulfillmentId", "shipmentPackageId", "packageOrdinal", "status" ] }, "BuyShippingLabelResponseDto": { "type": "object", "properties": { "label": { "$ref": "#/components/schemas/PurchasedShippingLabelDto" }, "order": { "$ref": "#/components/schemas/MerchantOrderDto" }, "needsTracking": { "type": "boolean", "description": "#1809 — true when the provider returned NO tracking number: the label was purchased and recorded (voidable), but its prepared shipment remains READY. Add tracking before handoff when the carrier requires it. A labelId is never used as a tracking number.", "example": false }, "preparedShipment": { "$ref": "#/components/schemas/PreparedShippingLabelShipmentDto" } }, "required": [ "label", "order", "needsTracking", "preparedShipment" ] }, "ReconcileShippingLabelDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id. The API re-verifies tenant, order, logical label, package, and fulfillment ownership." } }, "required": [ "reason", "purchaseId" ] }, "ReconcileShippingLabelResponseDto": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED" ], "description": "Original closed outcome catalog, kept stable for readers generated before #3956. FOUND_ADOPTED_READY is the only outcome that moves a package to READY (an acceptance at actual cost is projected here as FOUND_ADOPTED_READY because the exact label was found and adopted); every other outcome leaves the attempt blocked, pending, or released for retry as documented on the message. The precise outcome is resultDetail." }, "resultDetail": { "type": "string", "description": "Precise reconciliation outcome from the open-ended catalog; see x-extensible-enum for the known stable values and tolerate an unknown value by rendering it by name. Equals result except where the precise value postdates the original closed catalog: COST_ACCEPTED_READY (the exact completed label was re-verified and adopted at its actual cost) is published as result FOUND_ADOPTED_READY.", "example": "EVIDENCE_MISMATCH", "x-extensible-enum": [ "FOUND_ADOPTED_READY", "NOT_FOUND_PENDING", "NOT_FOUND_BLOCKED", "NOT_FOUND_RELEASED", "LOOKUP_FAILED", "EVIDENCE_MISMATCH", "CONNECTION_GENERATION_MISMATCH", "NO_PROVIDER_REFERENCE", "LEGACY_LABEL_FOUND_RECORDED", "LEGACY_NO_LABEL_RECORDED", "LEGACY_UNRESOLVED", "COST_ACCEPTED_READY" ] }, "message": { "type": "string", "description": "Operator-facing next state. It never includes provider secrets or raw response data." }, "retryAllowed": { "type": "boolean", "description": "True only after the conservative repeated-404 policy released this exact package claim to FAILED." }, "nextLookupAt": { "type": "string", "format": "date-time", "nullable": true }, "event": { "$ref": "#/components/schemas/ShippingLabelReconciliationEventDto" } }, "required": [ "result", "resultDetail", "message", "retryAllowed", "nextLookupAt", "event" ] }, "AcceptShippingLabelActualCostDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id of the parked completed label. The API re-verifies tenant, order, logical label, package, fulfillment, and provider identity before adopting it at the actual cost." } }, "required": [ "reason", "purchaseId" ] }, "RetirePostHandoffPostageDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id of the exact outbound postage to retire. The API re-verifies tenant, order, fulfillment, package, provider connection generation and exact label identity under lock before recording any intent, and rejects the request if this is no longer the current postage on that shipment." } }, "required": [ "reason", "purchaseId" ] }, "RetirePostHandoffPostageResponseDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "POSTAGE_RETIRED", "RETIREMENT_PENDING", "RETIREMENT_UNRESOLVED", "RETIREMENT_DENIED" ], "description": "POSTAGE_RETIRED: the carrier confirmed the void and the exact label is retired; the shipment stays shipped and nothing else changed. RETIREMENT_PENDING: the request is durably recorded and the exact carrier void is queued or in progress. RETIREMENT_UNRESOLVED: the carrier outcome is not yet known and exact-label checks are reconciling it; the label is not assumed retired or usable. RETIREMENT_DENIED: the carrier refused the void, so the postage remains live and usable. No outcome implies a carrier-account credit, a customer refund, or anything about whether the goods were delivered." }, "replayed": { "type": "boolean", "description": "True when this request returned an already-recorded retirement for the same idempotency key or the same exact label." }, "message": { "type": "string", "description": "Server-authored merchant guidance; never a raw provider response." }, "operation": { "$ref": "#/components/schemas/ShippingLabelVoidOperationSummaryDto" }, "record": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } }, "required": [ "outcome", "replayed", "message", "operation", "record" ] }, "RetryPostHandoffPostageRetirementCheckDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id whose postage retirement is awaiting recovery." } }, "required": [ "reason", "purchaseId" ] }, "VoidParkedShippingLabelDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id of the parked completed label. The API re-verifies tenant, order, package, fulfillment, provider generation and exact label identity before recording the void intent." } }, "required": [ "reason", "purchaseId" ] }, "VoidParkedShippingLabelResponseDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "LABEL_VOIDED", "VOID_PENDING", "VOID_RECONCILIATION_REQUIRED", "VOID_DENIED" ], "description": "LABEL_VOIDED: the carrier confirmed the void, the purchase is VOIDED and the planned package is CANCELLED with its allocation released for a fresh preparation. VOID_PENDING: the intent is recorded and the exact provider void is queued or in progress. VOID_RECONCILIATION_REQUIRED: the provider result is ambiguous and exact-label lookups are reconciling it. VOID_DENIED: the carrier refused; the label stays parked and can still be accepted at its actual cost." }, "replayed": { "type": "boolean", "description": "True when this request returned an already-recorded void intent for the same idempotency key or the same parked label." }, "message": { "type": "string", "description": "Server-authored merchant guidance; never a raw provider response." }, "operation": { "$ref": "#/components/schemas/ShippingLabelVoidOperationSummaryDto" }, "record": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } }, "required": [ "outcome", "replayed", "message", "operation", "record" ] }, "RetryParkedShippingLabelVoidCheckDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid", "description": "Server-issued label-purchase id whose parked-label void is awaiting recovery." } }, "required": [ "reason", "purchaseId" ] }, "RecordLegacyShippingLabelDispositionDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "purchaseId": { "type": "string", "format": "uuid" }, "disposition": { "type": "string", "enum": [ "LABEL_FOUND", "NO_LABEL_CONFIRMED", "UNRESOLVED" ] }, "evidence": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Non-secret evidence note, such as the provider label id or support case. Never include an API key, raw response, or customer data." } }, "required": [ "reason", "purchaseId", "disposition", "evidence" ] }, "WarehouseOutputAddressDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "company": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "addressLine1": { "type": "string", "nullable": true }, "addressLine2": { "type": "string", "nullable": true }, "cityLocality": { "type": "string", "nullable": true }, "stateProvince": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true } }, "required": [ "name", "company", "phone", "addressLine1", "addressLine2", "cityLocality", "stateProvince", "postalCode", "countryCode" ] }, "WarehouseOutputLineDto": { "type": "object", "properties": { "lineId": { "type": "string", "format": "uuid" }, "sku": { "type": "string", "nullable": true }, "name": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 } }, "required": [ "lineId", "sku", "name", "quantity" ] }, "WarehouseOutputLabelDto": { "type": "object", "properties": { "purchaseId": { "type": "string", "format": "uuid" }, "labelId": { "type": "string" }, "version": { "type": "integer", "format": "int32", "minimum": 1 }, "testLabel": { "type": "boolean" } }, "required": [ "purchaseId", "labelId", "version", "testLabel" ] }, "WarehouseOutputRowDto": { "type": "object", "properties": { "fulfillmentId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid", "nullable": true }, "displayNumber": { "type": "string", "nullable": true }, "orderNumber": { "type": "string", "nullable": true }, "organizationName": { "type": "string" }, "customerName": { "type": "string", "nullable": true }, "customerEmail": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "goodsKind": { "type": "string", "enum": [ "ORIGINAL_ORDER", "REPLACEMENT_GOODS" ] }, "status": { "type": "string", "enum": [ "PLANNED", "READY", "SHIPPED", "DELIVERED" ] }, "readyAt": { "type": "string", "format": "date-time", "nullable": true }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "packageOrdinal": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true }, "carrier": { "type": "string", "nullable": true }, "serviceLevel": { "type": "string", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true }, "shipTo": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/WarehouseOutputAddressDto" } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseOutputLineDto" } }, "labelEligibility": { "type": "string", "enum": [ "ELIGIBLE", "NO_CURRENT_PURCHASED_OUTBOUND_LABEL", "LABEL_VOID_IN_PROGRESS", "LABEL_ARTIFACT_UNAVAILABLE" ] }, "label": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/WarehouseOutputLabelDto" } ] } }, "required": [ "fulfillmentId", "recordId", "orderId", "displayNumber", "orderNumber", "organizationName", "customerName", "customerEmail", "companyName", "goodsKind", "status", "readyAt", "shippedAt", "deliveredAt", "createdAt", "packageOrdinal", "carrier", "serviceLevel", "trackingNumber", "shipTo", "lines", "labelEligibility", "label" ] }, "WarehouseOutputListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseOutputRowDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "WarehouseOutputSelectionDto": { "type": "object", "properties": { "fulfillmentIds": { "minItems": 1, "maxItems": 50, "uniqueItems": true, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "fulfillmentIds" ] }, "PublicSubscriptionPlanVisibility": { "type": "string", "enum": [ "PUBLIC_STOREFRONT", "API_BYO_ONLY" ], "description": "Where the plan is offered. API_BYO_ONLY plans are never returned by the list endpoint and require a known-slug detail lookup." }, "SubscriptionPlanType": { "type": "string", "enum": [ "PRODUCT", "MEMBERSHIP", "SERVICE_ACCESS" ] }, "SubscriptionTrialMode": { "type": "string", "enum": [ "NONE", "CARD_UPFRONT", "NO_CARD" ] }, "SubscriptionTrialEndBehavior": { "type": "string", "enum": [ "CANCEL", "CREATE_INVOICE", "PAUSE" ], "description": "NO_CARD trial behavior when no payment method exists at trial end; null for other trial modes." }, "PublicSubscriptionSellMode": { "type": "string", "enum": [ "SUBSCRIPTION", "ONE_TIME_AND_SUBSCRIPTION" ], "description": "The catalog target's effective purchase mode after applying a variant override to the parent item's default. Public plans are returned only when this permits subscriptions." }, "PublicSubscriptionCatalogTargetDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "itemSlug": { "type": "string", "description": "Public catalog slug for the attached item." }, "itemName": { "type": "string", "description": "Customer-facing item name." }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "variantName": { "type": "string", "nullable": true }, "variantSku": { "type": "string", "nullable": true }, "effectiveSellMode": { "description": "The catalog target's effective purchase mode after applying a variant override to the parent item's default. Public plans are returned only when this permits subscriptions.", "allOf": [ { "$ref": "#/components/schemas/PublicSubscriptionSellMode" } ] } }, "required": [ "itemId", "itemSlug", "itemName", "variantId", "variantName", "variantSku", "effectiveSellMode" ] }, "SubscriptionPriceInterval": { "type": "string", "enum": [ "DAY", "WEEK", "MONTH", "YEAR" ] }, "PublicSubscriptionPriceUsageType": { "type": "string", "enum": [ "LICENSED" ], "description": "Licensed recurring usage. Metered subscription checkout is not part of the public contract." }, "PublicSubscriptionPriceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." }, "unitAmountInCents": { "type": "integer", "minimum": 0, "description": "Recurring unit amount in the currency minor unit." }, "interval": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceInterval" } ] }, "intervalCount": { "type": "integer", "minimum": 1 }, "usageType": { "description": "Licensed recurring usage. Metered subscription checkout is not part of the public contract.", "allOf": [ { "$ref": "#/components/schemas/PublicSubscriptionPriceUsageType" } ] }, "isDefault": { "type": "boolean", "description": "True when this is the merchant-selected default price." } }, "required": [ "id", "currency", "unitAmountInCents", "interval", "intervalCount", "usageType", "isDefault" ] }, "PublicSubscriptionPlanDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped public plan slug." }, "name": { "type": "string", "description": "Customer-facing plan name." }, "description": { "type": "string", "nullable": true }, "channelVisibility": { "description": "Where the plan is offered. API_BYO_ONLY plans are never returned by the list endpoint and require a known-slug detail lookup.", "allOf": [ { "$ref": "#/components/schemas/PublicSubscriptionPlanVisibility" } ] }, "planType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanType" } ] }, "trialMode": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialMode" } ] }, "trialDays": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1 }, "trialEndBehavior": { "nullable": true, "description": "NO_CARD trial behavior when no payment method exists at trial end; null for other trial modes.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } ] }, "requiresShipping": { "type": "boolean", "description": "Whether fulfillment requires a shipping destination." }, "catalogTarget": { "nullable": true, "description": "Attached public catalog item/variant for a product-backed plan; null for membership or service-access plans without a catalog target.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicSubscriptionCatalogTargetDto" } ] }, "prices": { "maxItems": 100, "description": "Eligible recurring prices in this page. A continuation request can return an empty final page when prices change between requests.", "type": "array", "items": { "$ref": "#/components/schemas/PublicSubscriptionPriceDto" } }, "nextPriceCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next recurring-price page. Fetch the same plan by slug with `priceCursor`; null when this page is complete." } }, "required": [ "id", "slug", "name", "description", "channelVisibility", "planType", "trialMode", "trialDays", "trialEndBehavior", "requiresShipping", "catalogTarget", "prices", "nextPriceCursor" ] }, "PublicSubscriptionPlanListDto": { "type": "object", "properties": { "data": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PublicSubscriptionPlanDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next plan page; null when there are no more plans." } }, "required": [ "data", "nextCursor" ] }, "SubscriptionPlanStatus": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] }, "SubscriptionPlanVisibility": { "type": "string", "enum": [ "PUBLIC_STOREFRONT", "API_BYO_ONLY", "MERCHANT_CREATED_ONLY" ] }, "SubscriptionAudience": { "type": "string", "enum": [ "CUSTOMER", "BUSINESS_ACCOUNT" ] }, "SubscriptionPlanResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanStatus" } ] }, "channelVisibility": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanVisibility" } ] }, "planType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanType" } ] }, "audience": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionAudience" } ] }, "trialMode": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialMode" } ] }, "trialDays": { "type": "number", "nullable": true }, "trialEndBehavior": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } ] }, "requiresShipping": { "type": "boolean" }, "requiresEntitlementProjection": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "itemId", "variantId", "slug", "name", "description", "status", "channelVisibility", "planType", "audience", "trialMode", "trialDays", "trialEndBehavior", "requiresShipping", "requiresEntitlementProjection", "metadata", "archivedAt", "createdAt", "updatedAt" ] }, "SubscriptionPriceUsageType": { "type": "string", "enum": [ "LICENSED", "METERED" ] }, "SubscriptionPriceStatus": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "SubscriptionPriceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "stripeAccountId": { "type": "string", "nullable": true }, "stripeProductId": { "type": "string", "nullable": true }, "stripePriceId": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "unitAmountInCents": { "type": "number" }, "interval": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceInterval" } ] }, "intervalCount": { "type": "number" }, "usageType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceUsageType" } ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceStatus" } ] }, "isDefault": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "planId", "stripeAccountId", "stripeProductId", "stripePriceId", "currency", "unitAmountInCents", "interval", "intervalCount", "usageType", "status", "isDefault", "metadata", "createdAt", "updatedAt" ] }, "SubscriptionEntitlementType": { "type": "string", "enum": [ "ACCESS", "DISCOUNT", "ALLOWANCE", "SERVICE_CREDIT", "LIMIT_OVERRIDE" ] }, "SubscriptionEntitlementResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "entitlementType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEntitlementType" } ] }, "value": { "type": "object", "additionalProperties": true, "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "planId", "key", "entitlementType", "value", "metadata", "createdAt", "updatedAt" ] }, "SubscriptionPlanDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "variantId": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanStatus" } ] }, "channelVisibility": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanVisibility" } ] }, "planType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanType" } ] }, "audience": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionAudience" } ] }, "trialMode": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialMode" } ] }, "trialDays": { "type": "number", "nullable": true }, "trialEndBehavior": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } ] }, "requiresShipping": { "type": "boolean" }, "requiresEntitlementProjection": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPriceResponseDto" } }, "entitlementRules": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionEntitlementResponseDto" } } }, "required": [ "id", "organizationId", "itemId", "variantId", "slug", "name", "description", "status", "channelVisibility", "planType", "audience", "trialMode", "trialDays", "trialEndBehavior", "requiresShipping", "requiresEntitlementProjection", "metadata", "archivedAt", "createdAt", "updatedAt", "prices", "entitlementRules" ] }, "CreateSubscriptionPlanDto": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 200, "description": "URL-safe unique key within the org. Lower-case letters, digits, and dashes." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "planType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanType" } ] }, "channelVisibility": { "description": "Offering channel; defaults to MERCHANT_CREATED_ONLY. Orthogonal to lifecycle status. Storefront/BYO filtering that consumes it is #629.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanVisibility" } ] }, "audience": { "description": "Defaults to CUSTOMER.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionAudience" } ] }, "trialMode": { "description": "Defaults to NONE.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialMode" } ] }, "trialDays": { "type": "number", "minimum": 1, "maximum": 3650, "nullable": true, "description": "Trial length in days; required when trialMode !== NONE." }, "trialEndBehavior": { "nullable": true, "description": "For NO_CARD trials, what happens if the trial ends without a saved payment method (ADR-024 Decision 6).", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } ] }, "requiresShipping": { "type": "boolean", "description": "Defaults to false." }, "requiresEntitlementProjection": { "type": "boolean", "description": "Defaults to false." }, "itemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional catalog item this plan replenishes. Must belong to the same org; validated at the service layer." }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional catalog variant override (same-org, under `itemId`)." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "slug", "name", "planType" ] }, "UpdateSubscriptionPlanDto": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 200, "description": "URL-safe unique key within the org. Lower-case letters, digits, and dashes." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "planType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanType" } ] }, "channelVisibility": { "description": "Offering channel; defaults to MERCHANT_CREATED_ONLY. Orthogonal to lifecycle status. Storefront/BYO filtering that consumes it is #629.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlanVisibility" } ] }, "audience": { "description": "Defaults to CUSTOMER.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionAudience" } ] }, "trialMode": { "description": "Defaults to NONE.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialMode" } ] }, "trialDays": { "type": "number", "minimum": 1, "maximum": 3650, "nullable": true, "description": "Trial length in days; required when trialMode !== NONE." }, "trialEndBehavior": { "nullable": true, "description": "For NO_CARD trials, what happens if the trial ends without a saved payment method (ADR-024 Decision 6).", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialEndBehavior" } ] }, "requiresShipping": { "type": "boolean", "description": "Defaults to false." }, "requiresEntitlementProjection": { "type": "boolean", "description": "Defaults to false." }, "itemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional catalog item this plan replenishes. Must belong to the same org; validated at the service layer." }, "variantId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional catalog variant override (same-org, under `itemId`)." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } }, "CreateSubscriptionPriceDto": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 currency code (lower-case), e.g. `usd`." }, "unitAmountInCents": { "type": "number", "minimum": 0, "description": "Recurring amount per interval, in the currency minor unit." }, "interval": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceInterval" } ] }, "intervalCount": { "type": "number", "minimum": 1, "maximum": 52, "description": "Intervals between charges (default 1)." }, "usageType": { "description": "Defaults to LICENSED.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionPriceUsageType" } ] }, "isDefault": { "type": "boolean", "description": "Mark as the plan's default price. Setting true demotes the plan's previous default (one default per plan, enforced at the service layer)." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "currency", "unitAmountInCents", "interval" ] }, "UpdateSubscriptionPriceDto": { "type": "object", "properties": { "isDefault": { "type": "boolean", "description": "Promote this price to the plan's default (demotes the previous default). Cannot be set on an archived price." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } }, "CreateSubscriptionEntitlementDto": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Stable machine key unique within the plan (e.g. `priority-support`)." }, "entitlementType": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEntitlementType" } ] }, "value": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Type-specific payload (e.g. `{ \"percentOff\": 1000 }` for DISCOUNT). Shape is validated by the consuming projection (#631), not here." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "key", "entitlementType" ] }, "UpdateSubscriptionEntitlementDto": { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": true, "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } }, "DashboardSummaryDto": { "type": "object", "properties": { "totalItems": { "type": "number", "example": 42, "description": "Count of non-archived items (any status) for the active org — the \"Total Items\" metric." }, "activeBookings": { "type": "number", "example": 7, "description": "Count of bookings in CONFIRMED or ACTIVE status — the \"Active Bookings\" metric." }, "orderCount": { "type": "number", "example": 128, "description": "Count of all orders for the active org." }, "completedRevenueInCents": { "type": "number", "example": 1049900, "description": "Sum of `totalInCents` across COMPLETED orders (minor units) — the \"Revenue\" metric." } }, "required": [ "totalItems", "activeBookings", "orderCount", "completedRevenueInCents" ] }, "PublicPageSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug (e.g. `about`, `faq`)." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Full page body (Markdown/HTML per the storefront renderer)." }, "excerpt": { "type": "string", "nullable": true, "description": "Optional short summary for listings/SEO. `null` when unset." }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The public read only ever returns `PUBLISHED` rows." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp. Always `null` on the public read (archived pages are filtered out)." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "slug", "title", "content", "excerpt", "status", "archivedAt", "createdAt", "updatedAt" ] }, "MerchantPageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Tenant-scoped unique URL slug (e.g. `about`, `faq`)." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Full page body (Markdown/HTML per the storefront renderer)." }, "excerpt": { "type": "string", "nullable": true, "description": "Optional short summary for listings/SEO. `null` when unset." }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "ARCHIVED" ], "description": "Lifecycle status. The merchant surface returns DRAFT, PUBLISHED, and ARCHIVED rows (unlike the published-only public read)." }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft-delete timestamp. Non-null on archived pages (the merchant read surfaces them); `null` for live pages." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "slug", "title", "content", "excerpt", "status", "archivedAt", "createdAt", "updatedAt" ] }, "CreatePageDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "content": { "type": "string", "maxLength": 1000000, "description": "Page body. Stored as TEXT in Postgres so there is no schema-level length cap; the 1 MB DTO limit is a runtime safety guard." }, "excerpt": { "type": "string", "maxLength": 500, "nullable": true } }, "required": [ "title", "slug", "status", "content" ] }, "UpdatePageDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "content": { "type": "string", "maxLength": 1000000, "description": "Page body. Stored as TEXT in Postgres so there is no schema-level length cap; the 1 MB DTO limit is a runtime safety guard." }, "excerpt": { "type": "string", "maxLength": 500, "nullable": true } } }, "StorefrontDestinationOriginsDto": { "type": "object", "properties": { "returnToStoreUrl": { "type": "string", "nullable": true }, "postCheckoutRedirectUrl": { "type": "string", "nullable": true }, "checkoutRetryUrl": { "type": "string", "nullable": true }, "checkoutCancelUrl": { "type": "string", "nullable": true }, "customerActionBaseUrl": { "type": "string", "nullable": true }, "postActionRedirectUrl": { "type": "string", "nullable": true }, "newsletterUnsubscribeRedirectUrl": { "type": "string", "nullable": true }, "newsletterInactiveRedirectUrl": { "type": "string", "nullable": true } }, "required": [ "returnToStoreUrl", "postCheckoutRedirectUrl", "checkoutRetryUrl", "checkoutCancelUrl", "customerActionBaseUrl", "postActionRedirectUrl", "newsletterUnsubscribeRedirectUrl", "newsletterInactiveRedirectUrl" ] }, "StorefrontOrderProcessingDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "description", "structured" ], "description": "The tenant's configured delivery-estimate mode. `structured` means the tenant has ENABLED structured delivery estimation, which is what drives the `shipByDate` / delivery window on a checkout session. It does NOT guarantee that either timing field below is non-null: a merchant may enable structured estimates and configure no cutoff, and both fields are suppressed when `timezone` is `null`. Read each field for its own state rather than inferring it from this one. `description` means they are NOT configured — read it as \"no processing policy is published\", never as zero processing days or no cutoff. In `description` mode the only timing the platform publishes is the per-rate free-text `estimatedDelivery` on `GET /api/v1/public/shipping/zones`, and a policy surface must not state a processing time from this object." }, "timezone": { "type": "string", "nullable": true, "example": "America/Denver", "description": "Timezone the cutoff and the processing business days are evaluated in. Almost always an IANA name (`America/Denver`), but the gate is what `Intl.DateTimeFormat` accepts as a `timeZone`, which is a SUPERSET of the IANA database — a tenant storing a fixed ISO offset such as `+05:00` or `-03:00` has that published verbatim. Treat this as \"a string you can pass to `Intl`\", not as \"a zone name you can look up in the IANA database\". Published alongside the cutoff deliberately: a bare `HH:mm` with no zone is not actionable for a consumer rendering a policy page. `null` means the stored zone is not one this read will publish, for one of THREE distinct reasons — they are not interchangeable, and which one applies changes what checkout is doing: (1) the platform cannot resolve it at all (blank, or not a zone), so checkout computes no dates either; (2) it is PROCESS-RELATIVE (`local`, `system`) — accepted by the date engine, but it means \"whatever machine evaluates it\", so it would resolve to YOUR runtime zone rather than the merchant's; (3) it is a deterministic offset written in a spelling `Intl` rejects (`UTC+5`), which is interpretable and identical for every caller — this read simply does not publish that spelling, and you should NOT read it as ambiguous the way `local` is. In cases 2 and 3 checkout still computes dates, so do not read `null` as \"checkout shows no dates\". Cases 2 and 3 also require a row written outside the platform API, which validates this column with the same predicate this read uses. Either way nothing publishable is available, so when this is `null`, `processingDays` and `cutoffTime` are BOTH `null` too. The invariant runs ONE WAY only: a cutoff is never published without a zone, but a zone IS published without a cutoff whenever the merchant configured none. `timezone` set alongside `cutoffTime: null` is a normal, valid response — do not reject or re-interpret it." }, "processingDays": { "type": "integer", "nullable": true, "minimum": 0, "example": 2, "description": "Effective business days (Mon–Fri) of processing before an order ships, as the platform applies it — not the raw stored value. `null` in two cases, both of which mean \"no processing policy is published\" rather than zero: `mode` is `description`, or `timezone` is `null` (see below). That is what distinguishes \"not configured\" from a configured `0`. A published `0` means dispatch on the SAME BUSINESS DAY, not literally the same day: business days are Mon–Fri, so a weekend order ships the next weekday even at `0`. It normally arrives WITH a `cutoffTime`, because a structured estimate configured with no cutoff is floored to 1 business day rather than promising same-business-day dispatch at any hour. `0` together with `cutoffTime: null` IS reachable, for a tenant whose stored cutoff is in a form the platform cannot apply, and it means what it says: same-business-day dispatch, no cutoff. Do not treat that pair as impossible. No holiday calendar is applied, so a configured holiday is not skipped." }, "cutoffTime": { "type": "string", "nullable": true, "example": "16:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Effective local order cutoff in canonical 24-hour `HH:mm`, evaluated in `timezone`, which is non-null whenever this is. An order placed at or after it starts processing the next calendar day. `null` covers four cases: `mode` is `description`; the merchant configured no cutoff; the stored value is in a form the platform cannot apply and therefore ignores; or `timezone` is `null`, so no cutoff could be expressed without the zone a consumer needs to render it. The first three mean orders are not shifted to the next day by a cutoff. The fourth is announced by `timezone` being `null` as well, which also nulls `processingDays` — read `timezone` first." } }, "required": [ "mode", "timezone", "processingDays", "cutoffTime" ] }, "StorefrontSiteConfigDto": { "type": "object", "properties": { "organizationSlug": { "type": "string", "description": "Organization slug resolved from the x-organization-slug tenant context." }, "checkoutMode": { "type": "string", "enum": [ "hosted_litecheckout", "byo", "hybrid" ], "description": "Tenant checkout posture from checkoutSettings. `hosted_litecheckout` uses hosted litecheckout, `byo` uses the tenant frontend, and `hybrid` keeps both routes available." }, "phoneRequired": { "type": "boolean", "default": false, "description": "Whether ordinary cart checkout bind requires a non-blank `customer.phone`. Subscription and booking checkout are excluded. The response always includes this effective boolean after applying the legacy storage rule: Absent means not configured, which means not required. When true, a consumer should render phone as required; the API also enforces the requirement at bind, so a client that ignores the flag receives a field-keyed validation error instead of silently dropping it." }, "supportEmail": { "type": "string", "nullable": true, "format": "email", "maxLength": 254, "description": "Customer-facing support email resolved from the active Business Profile with the legacy checkout-settings fallback. Null when the merchant has not configured a valid value of at most 254 characters or explicitly cleared it." }, "supportPhone": { "type": "string", "nullable": true, "maxLength": 50, "description": "Customer-facing support phone resolved from the active Business Profile with the legacy checkout-settings fallback. Null when the merchant has not configured a valid value of at most 50 characters or explicitly cleared it." }, "termsUrl": { "type": "string", "nullable": true, "maxLength": 10500, "description": "Customer-facing Terms of Service URL resolved from checkout settings through the public http(s)-only URL guard. Null when unset or invalid." }, "privacyUrl": { "type": "string", "nullable": true, "maxLength": 10500, "description": "Customer-facing Privacy Policy URL resolved from checkout settings through the public http(s)-only URL guard. Null when unset or invalid." }, "returnPolicyUrl": { "type": "string", "nullable": true, "maxLength": 10500, "description": "Customer-facing Returns Policy URL resolved from checkout settings through the public http(s)-only URL guard. Null when unset or invalid." }, "storefrontOrigin": { "type": "string", "nullable": true, "example": "https://shop.example.com", "description": "The tenant’s canonical storefront origin (`https://`, no trailing slash or path), derived env-aware from the ADR-003 org record: a production deployment (`VERCEL_ENV=production`) resolves the production custom domain; every other environment — preview/staging deployments, and equally local development or CI where `VERCEL_ENV` is unset — resolves the staging domain, so only production can ever advertise the production origin. Storefronts use this as the `SITE_URL` source for canonicals / JSON-LD / sitemaps; a local env var should be an explicit override only. `null` when no origin is configured for the serving environment (including the dormant SUBDOMAIN hosting mode) — render no canonical rather than a broken one." }, "trustedStorefrontOrigin": { "type": "string", "nullable": true, "description": "The env-aware storefront origin only when its custom domain is VERIFIED or operator-ATTESTED. Null for an absent, malformed, unverified, pending, or failed domain." }, "checkoutRecoveryUrls": { "allOf": [ { "type": "object", "required": [ "returnToStoreUrl", "checkoutRetryUrl", "checkoutCancelUrl" ], "properties": { "returnToStoreUrl": { "type": "string", "nullable": true, "description": "Full effective return-to-store destination after environment and redirect-trust resolution. `null` means no configured candidate, canonical storefront origin, or operator fallback resolved to a safe destination; a consumer MUST NOT redirect when it is null." }, "checkoutRetryUrl": { "type": "string", "nullable": true, "description": "Full effective checkout-retry destination. A safe return-to-store setting may supply the configured fallback before the canonical storefront or operator fallback is considered. `null` means none of those branches produced a safe destination; a consumer MUST NOT redirect when it is null." }, "checkoutCancelUrl": { "type": "string", "nullable": true, "description": "Full effective checkout-cancel destination. Safe retry and return settings may supply configured fallbacks before the canonical storefront or operator fallback is considered. `null` means none of those branches produced a safe destination; a consumer MUST NOT redirect when it is null." } } } ], "description": "Full effective checkout retry, cancel, and return destinations after environment and redirect-trust resolution. Paths and queries are preserved; raw checkout settings are never returned." }, "destinationOrigins": { "description": "Origins of the effective API-resolved checkout, customer-action, and newsletter destinations. Null means the API emits no destination for that branch. Raw checkout settings are never returned.", "allOf": [ { "$ref": "#/components/schemas/StorefrontDestinationOriginsDto" } ] }, "orderProcessing": { "description": "#3275 — the tenant-wide order-processing timing a shipping-policy surface needs: effective processing business days, the effective local order cutoff, and the timezone both are evaluated in. Always present. Read each field for its own state: `mode` says whether structured estimation is ENABLED, not whether either timing value is non-null. These are the same inputs that produce `shipByDate` on a checkout session, so a policy page wired to this object tracks what checkout promises — with one exception worth knowing: for a tenant whose stored zone is process-relative (`local`, `system`) or a deterministic offset in a spelling `Intl` rejects (`UTC+5`), this object publishes nothing while checkout still computes dates, so the page under-reports rather than contradicting. Neither is reachable through the platform write API. Per-rate transit windows and the free-text per-rate estimate stay on `GET /api/v1/public/shipping/zones`, since they are per-rate rather than tenant-wide.", "allOf": [ { "$ref": "#/components/schemas/StorefrontOrderProcessingDto" } ] } }, "required": [ "organizationSlug", "checkoutMode", "phoneRequired", "supportEmail", "supportPhone", "termsUrl", "privacyUrl", "returnPolicyUrl", "storefrontOrigin", "trustedStorefrontOrigin", "checkoutRecoveryUrls", "destinationOrigins", "orderProcessing" ] }, "OrganizationAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "description": "Street address line 1.", "maxLength": 300, "example": "1120 S Rackham Way" }, "line2": { "type": "string", "description": "Street address line 2 (suite, unit, floor).", "maxLength": 300, "example": "Suite 300" }, "city": { "type": "string", "description": "City / locality.", "maxLength": 200, "example": "Meridian" }, "state": { "type": "string", "description": "State / province / region.", "maxLength": 200, "example": "ID" }, "zip": { "type": "string", "description": "Postal / ZIP code.", "maxLength": 32, "example": "83642" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. `US`). Must be an ASSIGNED code; user-assigned ranges such as `ZZ` are rejected.", "minLength": 2, "maxLength": 2, "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "example": "US" } }, "required": [ "line1", "city", "state", "zip", "country" ] }, "DomainVerificationEnvironment": { "type": "string", "enum": [ "PRODUCTION", "STAGING" ] }, "DomainVerificationStatus": { "type": "string", "enum": [ "UNVERIFIED", "PENDING", "VERIFIED", "ATTESTED", "FAILED" ] }, "DomainVerificationMethod": { "type": "string", "enum": [ "DNS_TXT", "DNS_CNAME" ] }, "DomainVerificationChallengeDto": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationEnvironment" } ] }, "host": { "type": "string", "description": "Bare host (no scheme) this challenge proves." }, "method": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationMethod" } ] }, "recordName": { "type": "string", "description": "DNS record name the tenant must create.", "example": "_litecommerce-challenge.shop.acme.com" }, "recordValue": { "type": "string", "description": "Exact TXT value the tenant must publish.", "example": "litecommerce-domain-verification=3f8a…" }, "status": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationStatus" } ] }, "attempts": { "type": "number", "description": "Number of verify attempts made so far." }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastError": { "type": "string", "nullable": true, "description": "Why the last check did not pass (DNS miss, expiry, …)." }, "verifiedAt": { "type": "string", "nullable": true, "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "environment", "host", "method", "recordName", "recordValue", "status", "attempts", "lastCheckedAt", "lastError", "verifiedAt", "expiresAt", "createdAt" ] }, "DomainEnvVerificationStatusDto": { "type": "object", "properties": { "environment": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationEnvironment" } ] }, "host": { "type": "string", "nullable": true, "description": "The configured custom-domain host for this env, if any." }, "status": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationStatus" } ] }, "trusted": { "type": "boolean", "description": "Whether this host is currently auto-trustable (VERIFIED or ATTESTED)." }, "verifiedAt": { "type": "string", "nullable": true, "format": "date-time" }, "activeChallenge": { "nullable": true, "description": "The active (pending) challenge for this env, if one exists.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DomainVerificationChallengeDto" } ] } }, "required": [ "environment", "host", "status", "trusted", "verifiedAt", "activeChallenge" ] }, "DomainVerificationStatusDto": { "type": "object", "properties": { "production": { "$ref": "#/components/schemas/DomainEnvVerificationStatusDto" }, "staging": { "$ref": "#/components/schemas/DomainEnvVerificationStatusDto" } }, "required": [ "production", "staging" ] }, "DomainVerificationResultDto": { "type": "object", "properties": { "environment": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationEnvironment" } ] }, "host": { "type": "string" }, "verified": { "type": "boolean", "description": "True only when ownership was just proven." }, "status": { "allOf": [ { "$ref": "#/components/schemas/DomainVerificationStatus" } ] }, "message": { "type": "string", "nullable": true }, "challenge": { "$ref": "#/components/schemas/DomainVerificationChallengeDto" } }, "required": [ "environment", "host", "verified", "status", "message", "challenge" ] }, "ApiKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Operator-facing label for the key." }, "publicKey": { "type": "string", "description": "Non-secret public identifier (`lck_…`). Safe to display." }, "scopes": { "description": "Granted scope strings.", "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last use, or `null` if never used." }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Revocation time, or `null` if active." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry time, or `null` if the key never expires (no default TTL). A past `expiresAt` authenticates identically to a revoked key." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "publicKey", "scopes", "lastUsedAt", "revokedAt", "expiresAt", "createdAt", "updatedAt" ] }, "CreateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable label for the operator. Shown in admin.", "minLength": 1, "maxLength": 100 }, "scopes": { "description": "Scope strings from the supported vocabulary (e.g. `storefront:read`). Lowercase ASCII with optional colon-separated namespacing. Unknown scopes are rejected at mint (400). `import:*` write scopes are operator-granted only and rejected from this self-serve surface (403).", "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] }, "ApiKeyWithSecretDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Operator-facing label for the key." }, "publicKey": { "type": "string", "description": "Non-secret public identifier (`lck_…`). Safe to display." }, "scopes": { "description": "Granted scope strings.", "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last use, or `null` if never used." }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Revocation time, or `null` if active." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry time, or `null` if the key never expires (no default TTL). A past `expiresAt` authenticates identically to a revoked key." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Plaintext API secret (`lck_…`). Returned ONCE on creation only — store it now; it is never retrievable again." } }, "required": [ "id", "organizationId", "name", "publicKey", "scopes", "lastUsedAt", "revokedAt", "expiresAt", "createdAt", "updatedAt", "secret" ] }, "MerchantAuditLogDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "actorUserId": { "type": "string", "format": "uuid", "nullable": true, "description": "Actor user id, or `null` for system actions." }, "action": { "type": "string", "example": "order.status_changed", "description": "Dotted action key." }, "targetType": { "type": "string", "example": "order" }, "targetId": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Action metadata (free-form JSON)." }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "actorUserId", "action", "targetType", "targetId", "metadata", "createdAt" ] }, "MerchantAuditLogPageDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantAuditLogDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page, or `null` at the end." } }, "required": [ "data", "nextCursor" ] }, "DeliveryEstimateSettingsDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "description", "structured" ], "description": "#1103 — `description` (default) keeps the free-text per-rate estimate; `structured` opts into computed ship-by / delivery-window dates from the rate transit window + the processing/cutoff settings below." }, "displayStyle": { "type": "string", "enum": [ "ship_by", "delivery_window", "both" ], "description": "How a structured estimate renders: `ship_by`, `delivery_window` (default), or `both`." }, "processingDays": { "type": "integer", "minimum": 0, "maximum": 60, "description": "Business days (Mon–Fri) of processing before an order ships. Default 0." }, "cutoffTime": { "type": "string", "nullable": true, "description": "Local order cutoff `HH:mm` (24h, tenant timezone). Orders at/after it start processing the next day. Null/omitted = no cutoff." } } }, "CheckoutLogoAssetDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storagePath": { "type": "string" }, "url": { "type": "string", "description": "Environment-matched public platform-media URL. A different immutable URL is minted for every replacement." }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/avif" ] }, "bytes": { "type": "integer", "maximum": 5242880 }, "width": { "type": "integer", "minimum": 1, "maximum": 4096 }, "height": { "type": "integer", "minimum": 1, "maximum": 4096 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "storagePath", "url", "mimeType", "bytes", "width", "height", "createdAt" ] }, "CheckoutSettingsResponseDto": { "type": "object", "properties": { "checkoutMode": { "type": "string", "enum": [ "hosted_litecheckout", "byo", "hybrid" ], "description": "Tenant checkout posture. `hosted_litecheckout` uses the first-party hosted surface, `byo` expects the tenant frontend to consume the public APIs, and `hybrid` allows either route." }, "phoneRequired": { "type": "boolean", "default": false, "description": "When true, ordinary cart checkout requires a non-blank customer phone at bind and hosted litecheckout renders the phone field as required. Subscription and booking checkout are excluded. Absent means not configured, which means not required." }, "ga4MeasurementId": { "type": "string", "nullable": true, "maxLength": 15, "pattern": "^G-[A-Z0-9]{4,12}$", "description": "#4023 (DR-2265-02) — Google Analytics 4 web-stream measurement ID for hosted litecheckout: `G-` plus 4–12 letters/digits, trimmed and uppercased on write. Stored per environment, so a Preview value never reaches production hosts. Anyone with settings permission may store, change, or clear it, but it is projected on the public organization snapshot only while a disclosure attestation is recorded (`ga4DisclosureAttestedAt`), so an un-attested ID stays dark. Absent means unchanged; `null` clears the ID and its attestation, which is the kill switch: no tag renders. Changing an attested ID to a different value also clears the attestation, so the new ID stays dark until an Owner or Admin attests again." }, "logoUrl": { "type": "string", "maxLength": 500, "nullable": true, "deprecated": true, "description": "Read-compatible legacy field. New values, replacements, and removal must use `/merchant/uploads/checkout-logo`; arbitrary external URLs are not renderable under hosted checkout CSP." }, "brandColor": { "type": "string", "maxLength": 64, "nullable": true }, "accentColor": { "type": "string", "maxLength": 7, "nullable": true, "description": "#1062 — hosted-checkout accent color as a hex string (`#rgb` or `#rrggbb`, normalized to lowercase `#rrggbb`). Drives the hosted surface `--color-accent` + Stripe Elements appearance. Blank/null falls back to the platform brand-purple default." }, "supportEmail": { "type": "string", "maxLength": 254, "nullable": true }, "supportPhone": { "type": "string", "maxLength": 50, "nullable": true }, "checkoutHeadline": { "type": "string", "maxLength": 120, "nullable": true }, "checkoutSubcopy": { "type": "string", "maxLength": 500, "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "When true, hosted checkout shows a default-unchecked marketing opt-in checkbox; a ticked box subscribes the shopper to the tenant newsletter (double opt-in) on confirmation, separate from transactional email." }, "marketingOptInCopy": { "type": "string", "maxLength": 300, "nullable": true }, "returnToStoreUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional explicit return-to-store destination for hosted checkout and order-status CTAs. Honored only when trusted by the #1127 destination gate; otherwise the API falls back to the tenant storefront origin / neutral fallback." }, "postCheckoutRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional explicit completion redirect after the server-read checkout session is CONFIRMED. Honored only when trusted by the #1127 destination gate; otherwise falls back to returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "checkoutRetryUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional destination for retry/start-over checkout CTAs after a checkout cannot continue. Honored only when trusted by the #1127 destination gate; otherwise falls back to returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "checkoutCancelUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional destination for canceled/expired checkout CTAs. Honored only when trusted by the #1127 destination gate; otherwise falls back to checkoutRetryUrl, returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "customerActionBaseUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1117 — BYO customer-action base ORIGIN. For a tenant that hosts its OWN customer transaction/account surfaces instead of hosted litecheckout, this is the origin (scheme + host) that customer-action links are built onto in place of `.litecheckout.io`: magic-link sign-in (`/account/sign-in`), order status (`/order//status`), and the forward-looking my-account / payment-retry / returns / saved-card pages in the BYO action-path set. NOTE: the full BYO path map is not yet published — do not assume it matches the hosted litecheckout paths, which differ on several surfaces. Confirm the exact paths with support before implementing beyond the two named above. ORIGIN-ONLY: only the scheme + host are used and the platform appends the standard action path, so configure your customer-action root (a path is ignored). Honored ONLY when its host is the tenant's VERIFIED custom domain (#1126), the hosted litecheckout origin, or an operator-approved host (the #1127 destination-trust gate); otherwise links fall back to the hosted default — never a tokenized link to an unverified host. Distinct from `returnToStoreUrl` / `postCheckoutRedirectUrl` (#1116), which are post-checkout redirect DESTINATIONS, not a customer-action origin." }, "postActionRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Shared destination a customer lands on after a successful newsletter confirm/unsubscribe token action (#566/#1115). Honored only when it passes the trusted redirect-destination gate (verified custom domain, hosted litecheckout origin, or operator-approved host). Blank/untrusted falls back to the ADR-003 storefront origin, then the neutral fallback page." }, "newsletterUnsubscribeRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional trusted override (#566/#1115) for where a customer lands after a successful newsletter UNSUBSCRIBE, distinct from confirm. Falls back to postActionRedirectUrl, then the ADR-003 storefront origin, then the neutral fallback page." }, "newsletterInactiveRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional trusted destination (#566/#1115) for a confirm link clicked AFTER the customer already unsubscribed (\"link no longer active\"). Resolved on its own chain — never a success page or storefront-origin fallback — so it can never imply the customer is subscribed. Blank/untrusted keeps the neutral API-hosted page or operator neutral fallback." }, "termsUrl": { "type": "string", "maxLength": 500, "nullable": true }, "privacyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "returnPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "shippingPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "subscriptionPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "taxMode": { "type": "string", "enum": [ "stripe_tax", "manual_no_tax" ], "description": "`stripe_tax` means litecommerce should use the configured Stripe Tax provider when available. `manual_no_tax` is an explicit tenant fallback where checkout/receipts must disclose that litecommerce did not calculate tax." }, "manualTaxResponsibilityAccepted": { "type": "boolean", "description": "Required to be true when `taxMode=manual_no_tax`; records that the merchant accepted responsibility for tax handling." }, "deliveryEstimate": { "description": "#1103 — tenant delivery-estimate behavior (mode + display style + processing/cutoff). Combined with each rate transit window to render structured ship-by / delivery-window dates at checkout.", "allOf": [ { "$ref": "#/components/schemas/DeliveryEstimateSettingsDto" } ] }, "logoAsset": { "description": "Server-owned upload-backed checkout logo metadata. Absent when no logo is configured, only a legacy external `logoUrl` remains, or the stored metadata is malformed, belongs to another tenant, or was copied from a different Preview/Production environment.", "allOf": [ { "$ref": "#/components/schemas/CheckoutLogoAssetDto" } ] }, "ga4DisclosureAttestedAt": { "type": "string", "nullable": true, "format": "date-time", "readOnly": true, "description": "#4023 (DR-2265-04) — server-stamped ISO timestamp of the Owner/Admin disclosure attestation that activates `ga4MeasurementId` on public surfaces. Absent or `null` means no attestation is recorded, so no measurement ID is projected publicly even when one is stored. Read-only: PATCH rejects it; send `ga4DisclosureAttested: true` instead." }, "ga4DisclosureAttestedByUserId": { "type": "string", "nullable": true, "readOnly": true, "description": "#4023 (DR-2265-04) — user id of the tenant Owner or Admin who recorded the disclosure attestation; `null` or absent when none is recorded. Read-only: stamped by the service together with `ga4DisclosureAttestedAt` and cleared with it." } } }, "ShipFromOriginDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Contact / facility name printed on the shipping label.", "minLength": 1, "maxLength": 120 }, "phone": { "type": "string", "description": "Origin contact phone. Carriers require one on the ship-from address.", "minLength": 1, "maxLength": 40 }, "line1": { "type": "string", "description": "Street address line 1.", "minLength": 1, "maxLength": 200 }, "line2": { "type": "string", "nullable": true, "description": "Street address line 2 (suite, unit). Null/omitted = none.", "maxLength": 200 }, "city": { "type": "string", "description": "City / town.", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "description": "State / province / region — ISO 3166-2 subdivision code when possible (e.g. `ID`).", "minLength": 1, "maxLength": 120 }, "postalCode": { "type": "string", "description": "ZIP / postal code.", "minLength": 1, "maxLength": 20 }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. `US`).", "minLength": 2, "maxLength": 2, "example": "US" } }, "required": [ "name", "phone", "line1", "city", "state", "postalCode", "country" ] }, "LiveRatePresentationDto": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "all", "cheapest_n", "cheapest_and_fastest" ], "description": "How quoted services are picked: `all` (default) offers every quoted service up to `maxOptions`; `cheapest_n` is the same math under the name the admin UI shows (\"cheapest N\" of the cheapest-first list); `cheapest_and_fastest` offers at most two options — the cheapest service plus the fastest (fewest transit days), collapsing to just the cheapest when they coincide or no transit data exists." }, "serviceFilterMode": { "type": "string", "enum": [ "exclude", "include" ], "description": "#1781 — which service list governs curation. `exclude` (default) is a blocklist: offer every quoted service EXCEPT `excludedServiceCodes` (fail-open). `include` is an allowlist: offer ONLY the services in `includedServiceCodes` (fail-closed) — an EMPTY allowlist offers no live services at all (flat rates only). Absent/`exclude` preserves the pre-#1781 behavior exactly." }, "maxOptions": { "type": "integer", "minimum": 1, "maximum": 8, "description": "Most live options checkout may offer (integer 1..8). Default 8 — the pre-#1767 hard cap." }, "excludedServiceCodes": { "maxItems": 50, "description": "ShipEngine service codes (e.g. `usps_media_mail`) checkout must never offer, matched case-insensitively. At most 50 entries, each a non-blank string of at most 100 characters; persisted trimmed and lowercased.", "type": "array", "items": { "type": "string" } }, "includedServiceCodes": { "maxItems": 50, "description": "#1781 — ShipEngine service codes checkout may offer EXCLUSIVELY when `serviceFilterMode` is `include` (matched case-insensitively). Same shape/validation as `excludedServiceCodes`: at most 50 entries, each a non-blank string of at most 100 characters; persisted trimmed and lowercased. An empty list in `include` mode offers no live services (fail-closed). Ignored while `serviceFilterMode` is `exclude`.", "type": "array", "items": { "type": "string" } } } }, "DeliveryPromiseTierResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-owned stable tier id." }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "nullable": true, "maxLength": 240 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "id", "name", "description", "sortOrder" ] }, "DeliveryPromisePresentationResponseDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ] }, "tiers": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseTierResponseDto" } }, "retiredTierIds": { "description": "Server-maintained stable-id tombstones. Retired ids cannot be reused.", "type": "array", "items": { "type": "string" } }, "revision": { "type": "string", "nullable": true, "format": "date-time", "description": "#2413 — catalog concurrency revision to echo as `expectedRevision` on save." } }, "required": [ "mode", "tiers", "retiredTierIds", "revision" ] }, "ShippingSettingsResponseDto": { "type": "object", "properties": { "shipFromOrigin": { "nullable": true, "description": "#1564 — the origin address live rate quotes ship from. All fields but `line2` are required when the object is present; set to `null` to clear the configured origin.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShipFromOriginDto" } ] }, "liveRatePresentation": { "nullable": true, "description": "#1767 — merchant policy for how live carrier quotes are presented at checkout (strategy, option cap, and #1781 service-filter mode with its exclude/include service lists). Persisted normalized; set to `null` to reset to the defaults (`all`, 8, `exclude` mode, no service lists).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LiveRatePresentationDto" } ] }, "deliveryPromisePresentation": { "description": "#2000/#2413 — normalized presentation mode, server-owned global tier catalog, retirement tombstones, and optimistic-concurrency revision.", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromisePresentationResponseDto" } ] } } }, "OrganizationSettingsResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization id this settings row belongs to." }, "timezone": { "type": "string", "description": "Active organization IANA timezone used by tenant-local settings such as delivery cutoff.", "example": "America/Boise" }, "businessProfile": { "type": "object", "additionalProperties": true }, "checkoutSettings": { "$ref": "#/components/schemas/CheckoutSettingsResponseDto" }, "apiSettings": { "type": "object", "additionalProperties": true }, "notifications": { "type": "object", "additionalProperties": true }, "shippingSettings": { "$ref": "#/components/schemas/ShippingSettingsResponseDto" }, "reserveDuringCheckout": { "type": "boolean" }, "checkoutReservationMinutes": { "type": "number", "nullable": true }, "subscriptionPastDueGraceHours": { "type": "number", "nullable": true, "description": "#631 — PAST_DUE entitlement grace window in hours; null = no grace." }, "subscriptionPauseBehavior": { "type": "string", "enum": [ "PAUSE_IMMEDIATELY", "CONTINUE_UNTIL_PERIOD_END", "FREEZE_ALLOWANCES" ], "nullable": true, "description": "#631 — PAUSED entitlement behavior; null = not chosen (projection fail-closes to PAUSE_IMMEDIATELY)." }, "subscriptionAllowanceRollover": { "type": "string", "enum": [ "NONE", "CARRY_UNUSED" ], "nullable": true, "description": "#631 — ALLOWANCE/SERVICE_CREDIT rollover policy; null = not chosen (balance-type plans cannot publish until set)." }, "subscriptionRecoveryTerminalAction": { "type": "string", "enum": [ "UNPAID", "CANCEL", "SUSPEND", "MANUAL_RECOVERY" ], "nullable": true, "description": "#2411 — exhausted-recovery terminal action; null is stored as unconfigured and the terminal-policy selector fail-closes to UNPAID." }, "subscriptionTerminalEntitlementBehavior": { "type": "string", "enum": [ "LAPSE_IMMEDIATELY", "FREEZE_BALANCES" ], "nullable": true, "description": "#2411 / DR-2411-09 — terminal entitlement behavior; null means the tenant has not selected lapse or frozen balances." }, "subscriptionTerminalSelfServeRecovery": { "type": "boolean", "default": false, "description": "#2411 / DR-2411-10 — whether an eligible terminal cycle permits customer self-service recovery." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "organizationId", "timezone", "businessProfile", "checkoutSettings", "apiSettings", "notifications", "shippingSettings", "reserveDuringCheckout", "checkoutReservationMinutes", "subscriptionPastDueGraceHours", "subscriptionPauseBehavior", "subscriptionAllowanceRollover", "subscriptionRecoveryTerminalAction", "subscriptionTerminalEntitlementBehavior", "subscriptionTerminalSelfServeRecovery", "createdAt", "updatedAt" ] }, "CheckoutSettingsDto": { "type": "object", "properties": { "checkoutMode": { "type": "string", "enum": [ "hosted_litecheckout", "byo", "hybrid" ], "description": "Tenant checkout posture. `hosted_litecheckout` uses the first-party hosted surface, `byo` expects the tenant frontend to consume the public APIs, and `hybrid` allows either route." }, "phoneRequired": { "type": "boolean", "default": false, "description": "When true, ordinary cart checkout requires a non-blank customer phone at bind and hosted litecheckout renders the phone field as required. Subscription and booking checkout are excluded. Absent means not configured, which means not required." }, "ga4MeasurementId": { "type": "string", "nullable": true, "maxLength": 15, "pattern": "^G-[A-Z0-9]{4,12}$", "description": "#4023 (DR-2265-02) — Google Analytics 4 web-stream measurement ID for hosted litecheckout: `G-` plus 4–12 letters/digits, trimmed and uppercased on write. Stored per environment, so a Preview value never reaches production hosts. Anyone with settings permission may store, change, or clear it, but it is projected on the public organization snapshot only while a disclosure attestation is recorded (`ga4DisclosureAttestedAt`), so an un-attested ID stays dark. Absent means unchanged; `null` clears the ID and its attestation, which is the kill switch: no tag renders. Changing an attested ID to a different value also clears the attestation, so the new ID stays dark until an Owner or Admin attests again." }, "ga4DisclosureAttested": { "type": "boolean", "writeOnly": true, "description": "#4023 (DR-2265-04) — write intent, never stored and never returned. A literal JSON `true` from a tenant Owner or Admin records that the merchant's published privacy policy discloses Google Analytics use on hosted checkout, stamping `ga4DisclosureAttestedAt`; that activates `ga4MeasurementId` on public surfaces. `true` requires a measurement ID in the same request or already stored (400 otherwise) and a tenant Owner or Admin (403 otherwise, decided before the ID is examined). `false` or omitted never revokes a recorded attestation: clear or change the ID instead. Strings such as `\"true\"` and an explicit `null` are rejected." }, "logoUrl": { "type": "string", "maxLength": 500, "nullable": true, "deprecated": true, "description": "Read-compatible legacy field. New values, replacements, and removal must use `/merchant/uploads/checkout-logo`; arbitrary external URLs are not renderable under hosted checkout CSP." }, "brandColor": { "type": "string", "maxLength": 64, "nullable": true }, "accentColor": { "type": "string", "maxLength": 7, "nullable": true, "description": "#1062 — hosted-checkout accent color as a hex string (`#rgb` or `#rrggbb`, normalized to lowercase `#rrggbb`). Drives the hosted surface `--color-accent` + Stripe Elements appearance. Blank/null falls back to the platform brand-purple default." }, "supportEmail": { "type": "string", "maxLength": 254, "nullable": true }, "supportPhone": { "type": "string", "maxLength": 50, "nullable": true }, "checkoutHeadline": { "type": "string", "maxLength": 120, "nullable": true }, "checkoutSubcopy": { "type": "string", "maxLength": 500, "nullable": true }, "marketingOptInEnabled": { "type": "boolean", "description": "When true, hosted checkout shows a default-unchecked marketing opt-in checkbox; a ticked box subscribes the shopper to the tenant newsletter (double opt-in) on confirmation, separate from transactional email." }, "marketingOptInCopy": { "type": "string", "maxLength": 300, "nullable": true }, "returnToStoreUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional explicit return-to-store destination for hosted checkout and order-status CTAs. Honored only when trusted by the #1127 destination gate; otherwise the API falls back to the tenant storefront origin / neutral fallback." }, "postCheckoutRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional explicit completion redirect after the server-read checkout session is CONFIRMED. Honored only when trusted by the #1127 destination gate; otherwise falls back to returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "checkoutRetryUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional destination for retry/start-over checkout CTAs after a checkout cannot continue. Honored only when trusted by the #1127 destination gate; otherwise falls back to returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "checkoutCancelUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1116 — optional destination for canceled/expired checkout CTAs. Honored only when trusted by the #1127 destination gate; otherwise falls back to checkoutRetryUrl, returnToStoreUrl, then the tenant storefront origin / neutral fallback." }, "customerActionBaseUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "#1117 — BYO customer-action base ORIGIN. For a tenant that hosts its OWN customer transaction/account surfaces instead of hosted litecheckout, this is the origin (scheme + host) that customer-action links are built onto in place of `.litecheckout.io`: magic-link sign-in (`/account/sign-in`), order status (`/order//status`), and the forward-looking my-account / payment-retry / returns / saved-card pages in the BYO action-path set. NOTE: the full BYO path map is not yet published — do not assume it matches the hosted litecheckout paths, which differ on several surfaces. Confirm the exact paths with support before implementing beyond the two named above. ORIGIN-ONLY: only the scheme + host are used and the platform appends the standard action path, so configure your customer-action root (a path is ignored). Honored ONLY when its host is the tenant's VERIFIED custom domain (#1126), the hosted litecheckout origin, or an operator-approved host (the #1127 destination-trust gate); otherwise links fall back to the hosted default — never a tokenized link to an unverified host. Distinct from `returnToStoreUrl` / `postCheckoutRedirectUrl` (#1116), which are post-checkout redirect DESTINATIONS, not a customer-action origin." }, "postActionRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Shared destination a customer lands on after a successful newsletter confirm/unsubscribe token action (#566/#1115). Honored only when it passes the trusted redirect-destination gate (verified custom domain, hosted litecheckout origin, or operator-approved host). Blank/untrusted falls back to the ADR-003 storefront origin, then the neutral fallback page." }, "newsletterUnsubscribeRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional trusted override (#566/#1115) for where a customer lands after a successful newsletter UNSUBSCRIBE, distinct from confirm. Falls back to postActionRedirectUrl, then the ADR-003 storefront origin, then the neutral fallback page." }, "newsletterInactiveRedirectUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional trusted destination (#566/#1115) for a confirm link clicked AFTER the customer already unsubscribed (\"link no longer active\"). Resolved on its own chain — never a success page or storefront-origin fallback — so it can never imply the customer is subscribed. Blank/untrusted keeps the neutral API-hosted page or operator neutral fallback." }, "termsUrl": { "type": "string", "maxLength": 500, "nullable": true }, "privacyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "returnPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "shippingPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "subscriptionPolicyUrl": { "type": "string", "maxLength": 500, "nullable": true }, "taxMode": { "type": "string", "enum": [ "stripe_tax", "manual_no_tax" ], "description": "`stripe_tax` means litecommerce should use the configured Stripe Tax provider when available. `manual_no_tax` is an explicit tenant fallback where checkout/receipts must disclose that litecommerce did not calculate tax." }, "manualTaxResponsibilityAccepted": { "type": "boolean", "description": "Required to be true when `taxMode=manual_no_tax`; records that the merchant accepted responsibility for tax handling." }, "deliveryEstimate": { "description": "#1103 — tenant delivery-estimate behavior (mode + display style + processing/cutoff). Combined with each rate transit window to render structured ship-by / delivery-window dates at checkout.", "allOf": [ { "$ref": "#/components/schemas/DeliveryEstimateSettingsDto" } ] } } }, "DeliveryPromiseTierDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "#2000 — durable promise-tier id. Omit this field when creating a tier; the server allocates the id. Existing tiers must echo their returned id, which cannot be changed or reused after retirement." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Customer-facing promise label, such as `Standard` or `Express`." }, "description": { "type": "string", "nullable": true, "maxLength": 240, "description": "Optional customer-facing explanation. Null removes the description." }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Customer display order, ascending." } }, "required": [ "name", "sortOrder" ] }, "DeliveryPromisePresentationDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "exact_services", "delivery_promises" ], "description": "`exact_services` is the backward-compatible default. `delivery_promises` opts checkout into enforceable generic promise tiers." }, "tiers": { "maxItems": 20, "description": "Organization-global customer promise tiers. Zone rules decide where each tier is enabled and which provider services may anchor it.", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryPromiseTierDto" } }, "expectedRevision": { "type": "string", "nullable": true, "format": "date-time", "description": "#2413 — optimistic concurrency fence for this promise catalog only. Echo the `revision` returned by GET, or null when the catalog has never been saved. A stale value is rejected with HTTP 409." } }, "required": [ "mode", "tiers", "expectedRevision" ] }, "ShippingSettingsDto": { "type": "object", "properties": { "shipFromOrigin": { "nullable": true, "description": "#1564 — the origin address live rate quotes ship from. All fields but `line2` are required when the object is present; set to `null` to clear the configured origin.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShipFromOriginDto" } ] }, "liveRatePresentation": { "nullable": true, "description": "#1767 — merchant policy for how live carrier quotes are presented at checkout (strategy, option cap, and #1781 service-filter mode with its exclude/include service lists). Persisted normalized; set to `null` to reset to the defaults (`all`, 8, `exclude` mode, no service lists).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LiveRatePresentationDto" } ] }, "deliveryPromisePresentation": { "description": "#2000 / ADR-023 — checkout presentation mode plus the global promise tier catalog. The API stamps revision/tombstone evidence internally; zone eligibility stays on each shipping zone. Null is not a reset because it cannot carry the required optimistic-concurrency revision; reset with `exact_services`, the current `expectedRevision`, and an empty tier list.", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromisePresentationDto" } ] } } }, "UpdateSettingsDto": { "type": "object", "properties": { "businessProfile": { "type": "object", "additionalProperties": true, "description": "Business profile keys (company name, support email/phone, legal address, etc.). Shallow-merged into the existing column value: unmentioned keys are preserved, mentioned keys overwrite, and explicit `null` clears the value." }, "checkoutSettings": { "description": "Checkout configuration. Shallow-merged into the existing column value: unmentioned keys are preserved, mentioned keys overwrite, and explicit `null` clears nullable values.", "allOf": [ { "$ref": "#/components/schemas/CheckoutSettingsDto" } ] }, "reserveDuringCheckout": { "type": "boolean", "description": "Mode-B inventory reservation seam from #605. false = reserve at confirmation, true = reserve during checkout." }, "checkoutReservationMinutes": { "type": "integer", "format": "int32", "nullable": true, "minimum": 5, "maximum": 1440, "description": "Optional Mode-B hold duration in minutes. Null uses the checkout default; ignored when reserveDuringCheckout is false." }, "subscriptionPastDueGraceHours": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "maximum": 8760, "description": "#631 (M5-8) — PAST_DUE entitlement grace window in hours. Explicit null UNSETS the knob: past-due grants then lapse immediately (fail-closed; Batch-5 item 11 forbids an implicit default)." }, "subscriptionPauseBehavior": { "type": "string", "enum": [ "PAUSE_IMMEDIATELY", "CONTINUE_UNTIL_PERIOD_END", "FREEZE_ALLOWANCES" ], "nullable": true, "description": "#631 (M5-8) — what PAUSED does to entitlements. Explicit null UNSETS the choice; the projection then fail-closes to PAUSE_IMMEDIATELY." }, "subscriptionAllowanceRollover": { "type": "string", "enum": [ "NONE", "CARRY_UNUSED" ], "nullable": true, "description": "#631 (M5-8) — REQUIRED rollover policy for ALLOWANCE / SERVICE_CREDIT entitlements (no implicit default). Explicit null unsets it, but is rejected while ACTIVE plans carry balance-type rules — the publish-gate invariant, applied at the settings edge." }, "subscriptionRecoveryTerminalAction": { "type": "string", "enum": [ "UNPAID", "CANCEL", "SUSPEND", "MANUAL_RECOVERY" ], "nullable": true, "description": "#2411 (M5-9 Slice C) — organization-level action selected after subscription payment recovery is exhausted. Explicit null unsets the choice; the terminal-policy selector then fail-closes to UNPAID." }, "subscriptionTerminalEntitlementBehavior": { "type": "string", "enum": [ "LAPSE_IMMEDIATELY", "FREEZE_BALANCES" ], "nullable": true, "description": "#2411 / DR-2411-09 — entitlement treatment at terminal recovery. Explicit null unsets the tenant choice; FREEZE_BALANCES preserves value for later revival without allowing unpaid use." }, "subscriptionTerminalSelfServeRecovery": { "type": "boolean", "default": false, "description": "#2411 / DR-2411-10 — allow customer self-service recovery from an eligible terminal cycle. Defaults false; merchant recovery is governed by its separate policy/workbench path." }, "apiSettings": { "type": "object", "additionalProperties": true, "description": "API surface preferences (rate-limit policy, webhook defaults, CORS allow-list, etc.). Shallow-merge semantics." }, "notifications": { "type": "object", "additionalProperties": true, "description": "Notification preferences (email/SMS opt-ins, digest cadence, incident routing, etc.). Shallow-merge semantics." }, "shippingSettings": { "description": "#1564 — shipping configuration (ship-from origin). Shallow-merged into the existing column value: unmentioned keys are preserved, mentioned keys overwrite, and explicit `null` clears nullable values.", "allOf": [ { "$ref": "#/components/schemas/ShippingSettingsDto" } ] } } }, "TaxReadinessDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "tenant_setup_required", "platform_unavailable", "read_unavailable" ], "description": "Fresh connected-account readiness for the authenticated tenant. Ready means the connected provider is loaded, payment account is verified and Stripe Tax settings are active; it does not certify registrations, nexus, product classification, filing, or the tax amount of a future checkout. read_unavailable means the check failed, never that setup is complete. Independent of the stored tax-mode selection." }, "mode": { "type": "string", "enum": [ "live", "test", "unknown" ], "description": "API Stripe mode. test includes test mode and isolated sandboxes and does not prove live readiness. unknown means mode could not be established; no credential or account identifier is exposed." }, "checkedAt": { "type": "string", "format": "date-time", "description": "UTC time this readiness check completed. Advisory only; checkout rechecks before committing." } }, "required": [ "status", "mode", "checkedAt" ] }, "PlanLimitsDto": { "type": "object", "properties": { "items": { "type": "number", "nullable": true, "description": "Max catalog items; `null` = unlimited." }, "apiCallsPerDay": { "type": "number", "nullable": true, "description": "Max public API calls per UTC day; `null` = unlimited." }, "storageBytes": { "type": "number", "nullable": true, "description": "Max total image storage bytes; `null` = unlimited." }, "staffSeats": { "type": "number", "nullable": true, "description": "Max active staff memberships; `null` = unlimited." }, "storefronts": { "type": "number", "nullable": true, "description": "Max storefronts; `null` = unlimited." } }, "required": [ "items", "apiCallsPerDay", "storageBytes", "staffSeats", "storefronts" ] }, "LimitsUsageDto": { "type": "object", "properties": { "items": { "type": "number", "example": 12, "description": "Current non-archived item count." }, "apiCallsToday": { "type": "number", "example": 340, "description": "Public API calls so far today (UTC)." }, "storageBytes": { "type": "number", "example": 1048576, "description": "Total image storage bytes in use." }, "staffSeats": { "type": "number", "example": 3, "description": "Current active staff membership count." } }, "required": [ "items", "apiCallsToday", "storageBytes", "staffSeats" ] }, "MerchantLimitsDto": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ], "example": "FREE_TRIAL" }, "limits": { "$ref": "#/components/schemas/PlanLimitsDto" }, "usage": { "$ref": "#/components/schemas/LimitsUsageDto" } }, "required": [ "plan", "limits", "usage" ] }, "SignUploadUrlDto": { "type": "object", "properties": { "ownerType": { "type": "string", "enum": [ "item", "collection" ], "description": "Polymorphic owner type. The service looks up the row by `ownerId` in the matching table and enforces tenant ownership before minting the signed URL." }, "ownerId": { "type": "string", "description": "Owner row id (Item or Collection). Must belong to the caller org. Canonical Item ids are UUIDs, while Collection and legacy import identities remain text-compatible Prisma `String` values; the service therefore accepts a bounded non-empty string and does the tenant + existence check." }, "filename": { "type": "string", "description": "Original client filename. Only the extension is honored; the server mints a fresh uuid for the storage path so two clients uploading `cover.jpg` never collide.", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/avif" ], "description": "Allow-list-restricted MIME type. The Supabase Storage bucket enforces the same list on its end; a payload that slipped past this DTO would fail at upload time." }, "bytes": { "type": "number", "description": "File size in bytes. Capped server-side against MAX_IMAGE_BYTES (env-tunable, default 15 MB). Reject early so the merchant doesn't upload a 200 MB blob just to be told no.", "minimum": 1 } }, "required": [ "ownerType", "ownerId", "filename", "mimeType", "bytes" ] }, "SignedUploadResultDto": { "type": "object", "properties": { "imageId": { "type": "string", "format": "uuid", "description": "Pre-allocated image id to reference after upload." }, "uploadUrl": { "type": "string", "description": "Time-limited signed Supabase upload URL (expires per `expiresAt`)." }, "token": { "type": "string", "description": "Single-use token; pass with `storagePath` to `uploadToSignedUrl`." }, "bucket": { "type": "string", "description": "Supabase storage bucket name." }, "publicUrl": { "type": "string", "description": "Eventual public URL once the upload completes." }, "storagePath": { "type": "string", "description": "Bucket-relative object path." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Signed-URL expiry (ISO, ~2h from mint)." } }, "required": [ "imageId", "uploadUrl", "token", "bucket", "publicUrl", "storagePath", "expiresAt" ] }, "SignCheckoutLogoUploadDto": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Original client filename. The basename and extension are not trusted for the storage path; the server derives the extension from the allow-listed MIME type and mints a fresh UUID." }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/avif" ], "description": "Static raster MIME type accepted for checkout logos. SVG and animated/multi-page content are not supported." }, "bytes": { "type": "integer", "minimum": 1, "maximum": 5242880, "description": "Client-reported file size in bytes, capped at 5 MiB." } }, "required": [ "filename", "mimeType", "bytes" ] }, "ConfirmCheckoutLogoUploadDto": { "type": "object", "properties": { "imageId": { "type": "string", "format": "uuid", "description": "Id minted by the signed-upload endpoint." }, "storagePath": { "type": "string", "maxLength": 500, "description": "Bucket-relative path minted by the signed-upload endpoint. The API requires the matching durable tenant-owned mint intent before attach." } }, "required": [ "imageId", "storagePath" ] }, "CheckoutLogoRemovalResultDto": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True when an upload-backed asset or retained legacy URL was cleared; false when the tenant already had neither." } }, "required": [ "removed" ] }, "EmailSuppressionStatusDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "UNAVAILABLE", "NEEDS_ATTENTION", "NO_OPEN_INCIDENT" ], "description": "UNAVAILABLE means suppression observation is disabled, unbound, or unreadable. NO_OPEN_INCIDENT means no observed open local-suppression incident for this organization; neither state establishes delivery, inbox placement, or provider-wide permission." }, "banner": { "type": "string", "nullable": true, "description": "Redacted support banner when an observed local suppression incident remains open. Null when there is no observed open incident or observation is unavailable; inspect state to distinguish these cases. Contains no recipient or provider identity." } }, "required": [ "state", "banner" ] }, "IntercomMerchantCapabilityStatusDto": { "type": "object", "properties": { "capability": { "type": "string", "description": "Provider-neutral capability name allowed on the connection.", "example": "customer_context_read" }, "authorityState": { "type": "string", "enum": [ "UNBOUND", "ACTIVE", "DISABLED" ] }, "resourceState": { "type": "string", "enum": [ "UNCONFIGURED", "PROVISIONING", "DRAFT", "PUBLISHING", "LIVE", "DRIFTED", "CLEANUP_REQUIRED" ] }, "attentionRequired": { "type": "boolean", "description": "Whether this capability requires operator attention before it can be used." }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "nextVerificationAt": { "type": "string", "format": "date-time", "nullable": true }, "attentionRequiredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "capability", "authorityState", "resourceState", "attentionRequired", "verifiedAt", "nextVerificationAt", "attentionRequiredAt" ] }, "IntercomMerchantCleanupStatusDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "ACTION_REQUIRED", "COMPLETE" ] }, "pendingCredentialRevocations": { "type": "integer", "minimum": 0 }, "pendingProviderActions": { "type": "integer", "minimum": 0 }, "actionRequiredItems": { "type": "integer", "minimum": 0 }, "lastConfirmedAt": { "type": "string", "format": "date-time", "nullable": true }, "actionRequiredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "state", "pendingCredentialRevocations", "pendingProviderActions", "actionRequiredItems", "lastConfirmedAt", "actionRequiredAt" ] }, "IntercomMerchantActionStatusDto": { "type": "object", "properties": { "available": { "type": "boolean" }, "blockedReason": { "type": "string", "enum": [ "ALREADY_CONNECTED", "ALREADY_DISCONNECTED", "CONNECT_IN_PROGRESS", "CONFIGURATION_UNAVAILABLE", "CREDENTIAL_RETIREMENT_PENDING", "NOT_CONNECTED", "OPERATOR_ACTION_REQUIRED", "ORGANIZATION_SUSPENDED", "RECONNECT_REQUIRED" ], "nullable": true } }, "required": [ "available", "blockedReason" ] }, "IntercomMerchantLifecycleActionsDto": { "type": "object", "properties": { "connect": { "description": "Initial-connect action. Execute an available action with POST /merchant/support-provider-connections/intercom/connect.", "allOf": [ { "$ref": "#/components/schemas/IntercomMerchantActionStatusDto" } ] }, "reconnect": { "description": "Same-owner reconnect action after cleanup completes. Execute an available action with the same POST /merchant/support-provider-connections/intercom/connect route.", "allOf": [ { "$ref": "#/components/schemas/IntercomMerchantActionStatusDto" } ] }, "disconnect": { "$ref": "#/components/schemas/IntercomMerchantActionStatusDto" }, "reasonRequired": { "type": "boolean", "description": "Connect, reconnect, and disconnect all require a human reason." } }, "required": [ "connect", "reconnect", "disconnect", "reasonRequired" ] }, "IntercomMerchantLifecycleStatusDto": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "intercom" ] }, "surfaceAvailable": { "type": "boolean", "description": "Whether this tenant may render the merchant Intercom lifecycle surface. False is a routine eligibility answer, not a service failure." }, "lifecycleState": { "type": "string", "enum": [ "NOT_CONNECTED", "CONNECTING", "ACTIVE", "DISCONNECTING", "ACTION_REQUIRED", "DISCONNECTED" ] }, "connectionMode": { "type": "string", "enum": [ "PUBLIC_OAUTH", "OPERATOR_MANAGED_PILOT" ], "nullable": true }, "region": { "type": "string", "enum": [ "US", "EU", "AU" ], "nullable": true }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true }, "reconnectedAt": { "type": "string", "format": "date-time", "nullable": true }, "disconnectedAt": { "type": "string", "format": "date-time", "nullable": true }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/IntercomMerchantCapabilityStatusDto" } }, "cleanup": { "$ref": "#/components/schemas/IntercomMerchantCleanupStatusDto" }, "actions": { "$ref": "#/components/schemas/IntercomMerchantLifecycleActionsDto" } }, "required": [ "provider", "surfaceAvailable", "lifecycleState", "connectionMode", "region", "connectedAt", "reconnectedAt", "disconnectedAt", "capabilities", "cleanup", "actions" ] }, "StartIntercomConnectionDto": { "type": "object", "properties": { "region": { "type": "string", "enum": [ "US", "EU", "AU" ], "description": "Proposed Intercom data region. The server maps this enum to a fixed OAuth host and persists it only after GET /me attests the same region." }, "reason": { "type": "string", "minLength": 12, "maxLength": 500, "description": "Reason for this high-risk provider connection change; retained in the typed lifecycle audit.", "example": "Connect the EKGIS staging support workspace" } }, "required": [ "region", "reason" ] }, "StartIntercomConnectionResponseDto": { "type": "object", "properties": { "authorizeUrl": { "type": "string", "description": "Fixed-region Intercom OAuth authorization URL containing a signed, single-use state." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Expiry of the one-time OAuth state." } }, "required": [ "authorizeUrl", "expiresAt" ] }, "DisconnectIntercomConnectionDto": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "description": "Caller-generated idempotency key for the disconnect transition." }, "reason": { "type": "string", "minLength": 12, "maxLength": 500, "description": "Reason for the high-risk disconnect; retained only in typed lifecycle audit evidence.", "example": "Disconnect before replacing the staging workspace" } }, "required": [ "requestId", "reason" ] }, "SendingDomainDnsRecordDto": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "SPF", "DKIM" ], "description": "What the record authenticates. Only records needed to authenticate **sending** are returned. Note that one of them may legitimately be an MX record: the SPF entry is published as MX in some regions, and it is required. What is never returned is the inbound `Receiving` MX record — publishing that would redirect the domain’s incoming mail to the email provider — nor tracking records, which this integration disables." }, "type": { "type": "string", "description": "DNS record type, e.g. `TXT`, `CNAME`, `MX`." }, "name": { "type": "string", "description": "Record name/host to create in the DNS zone." }, "value": { "type": "string", "description": "Record value." }, "ttl": { "type": "string", "description": "Suggested TTL, as reported by the provider." }, "priority": { "type": "number", "nullable": true, "description": "MX priority when the record type needs one, otherwise null." }, "status": { "type": "string", "description": "The provider's per-record verification state, passed through verbatim so the merchant can see which single record is still missing." } }, "required": [ "purpose", "type", "name", "value", "ttl", "priority", "status" ] }, "EmailSendingDomainDto": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether this organization has a sending domain configured at all. When false there is no provider-bound local domain row; pending intent and lifecycle fields may still describe an unresolved configure operation. Mail continues to use the platform default sender." }, "domain": { "type": "string", "nullable": true }, "fromEmail": { "type": "string", "nullable": true, "description": "The sender address this domain would use (`fromLocalPart@domain`). A candidate, not a guarantee that admission succeeds or that an existing delivery uses it — see `activeSender` for the current sender-policy selection for new tenant-authored production deliveries." }, "pendingDomain": { "type": "string", "nullable": true, "description": "Normalized domain from an unresolved CONFIGURE intent when no provider-bound local domain exists yet." }, "pendingFromEmail": { "type": "string", "nullable": true, "description": "Candidate sender address for an unresolved CONFIGURE intent. It is never an active sender." }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "TEMPORARY_FAILURE", "VERIFIED", "PARTIALLY_VERIFIED", "FAILED", "PARTIALLY_FAILED" ], "nullable": true }, "verifiedForSending": { "type": "boolean", "description": "Whether the domain has a stable, completed provider-bound lifecycle operation whose status is VERIFIED. Legacy, pending, removing, failed, resolved, and attention states are ineligible even when a stale provider snapshot says VERIFIED. This reports eligibility; the closed-default sender-resolution switch separately controls whether sender policy selects this candidate or the platform sender for new tenant-authored deliveries." }, "dnsRecords": { "description": "DNS records the merchant must publish for this domain.", "type": "array", "items": { "$ref": "#/components/schemas/SendingDomainDnsRecordDto" } }, "lastCheckedAt": { "type": "string", "nullable": true, "description": "When verification was last ATTEMPTED, whatever the outcome. Distinct from `verifiedAt`." }, "verifiedAt": { "type": "string", "nullable": true }, "activeSender": { "type": "string", "description": "The address sender-selection policy chooses for a new tenant-authored production delivery after its independent delivery-admission checks succeed. This field does not assert canonical-key-pin or delivery-store health. Platform-authored notices always retain the platform sender. Always present: it is `fromEmail` only when sender resolution is enabled and the complete provider-bound VERIFIED predicate passes; otherwise it is the configured platform sender after surrounding-whitespace normalization. Automatic retries keep the sender already stored on their durable attempt, so an older in-flight delivery may intentionally retain a different address." }, "lifecycleState": { "type": "string", "enum": [ "UNCONFIGURED", "CONFIGURING", "LEGACY_PROVENANCE_MISSING", "PENDING_DNS", "VERIFYING", "VERIFIED", "REMOVING", "NEEDS_ATTENTION", "FAILED", "RESOLVED_NON_SENDABLE" ], "description": "Provider-neutral durable lifecycle. Legacy, pending, removing, failed, resolved, and attention states are never sender-eligible even when a stale provider snapshot says VERIFIED." }, "operationKind": { "type": "string", "enum": [ "CONFIGURE", "REFRESH", "REMOVE" ], "nullable": true }, "operationState": { "type": "string", "enum": [ "QUEUED", "PROCESSING", "RETRY_SCHEDULED", "NEEDS_ATTENTION", "FAILED", "RESOLVED", "COMPLETED" ], "nullable": true }, "attentionCode": { "type": "string", "enum": [ "CREATE_OUTCOME_UNKNOWN", "UNBOUND_PROVIDER_OBJECT", "PROVIDER_UNAVAILABLE", "PROVIDER_RATE_LIMITED", "PROVIDER_REJECTED", "PROVIDER_CONFIGURATION_INVALID", "PROVIDER_DISPATCH_DEADLINE_EXPIRED", "PROVIDER_ACCOUNT_SCOPE_MISMATCH", "LEGACY_PROVENANCE_MISSING", "PROVIDER_RESPONSE_INVALID", "VERIFICATION_TIMEOUT", "RETRY_BUDGET_EXHAUSTED", "KNOWN_ID_ROLLBACK_FAILED", "KNOWN_ID_ROLLED_BACK", "LOCAL_PROJECTION_CONFLICT", "LOCAL_PROJECTION_UNAVAILABLE", "PROVIDER_ABSENCE_CONFIRMED" ], "nullable": true, "description": "Fixed, secret-free reconciliation reason for failed/attention/resolved states. Raw provider errors are never returned." }, "retryAt": { "type": "string", "nullable": true }, "reconciliationRequired": { "type": "boolean", "description": "True when a legacy or attended reconciliation state requires operator action before this domain can ever become sender-eligible." } }, "required": [ "configured", "domain", "fromEmail", "pendingDomain", "pendingFromEmail", "status", "verifiedForSending", "dnsRecords", "lastCheckedAt", "verifiedAt", "activeSender", "lifecycleState", "operationKind", "operationState", "attentionCode", "retryAt", "reconciliationRequired" ] }, "ConfigureEmailSendingDomainDto": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "example": "mail.acme-supply.com", "description": "Bare domain to send from — no scheme, port, path, or address. Stored lowercased. A domain already claimed by another tenant, the platform sending domain (or a subdomain of it), and consumer mailbox providers are all rejected." }, "fromLocalPart": { "type": "string", "maxLength": 64, "default": "noreply", "example": "orders", "description": "Local part of the sender address. The domain half is always the verified domain above and cannot be set independently. Defaults to `noreply`." } }, "required": [ "domain" ] }, "MerchantNoticeDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "GENERAL", "INCIDENT", "DEPRECATION", "BILLING" ] }, "publishedAt": { "format": "date-time", "type": "string" }, "readAt": { "type": "string", "format": "date-time", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "title", "body", "kind", "publishedAt", "readAt", "dismissedAt" ] }, "MarkMerchantNoticesReadDto": { "type": "object", "properties": { "noticeIds": { "minItems": 1, "maxItems": 1000, "uniqueItems": true, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "noticeIds" ] }, "OrganizationNoticeStateDto": { "type": "object", "properties": { "noticeId": { "type": "string", "format": "uuid" }, "readAt": { "type": "string", "format": "date-time", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "noticeId", "readAt", "dismissedAt" ] }, "SubmitContactMessageDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Submitter's display name. Untrusted free text.", "example": "Jamie Rivera", "maxLength": 200 }, "email": { "type": "string", "description": "Reply address. Normalised lowercase before insert. Validated as an email but never verified — treated as a reply target only.", "example": "jamie@example.com", "maxLength": 320 }, "subject": { "type": "string", "description": "Optional subject line.", "example": "Question about bulk orders", "maxLength": 200 }, "message": { "type": "string", "description": "Message body.", "example": "Do you ship to Canada?", "maxLength": 5000 } }, "required": [ "name", "email", "message" ] }, "ContactSubmitResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always `true`. Constant regardless of what happened server-side.", "example": true } }, "required": [ "ok" ] }, "MerchantContactMessageSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Submitter's display name (untrusted text)." }, "email": { "type": "string", "format": "email", "description": "Reply address as submitted. Validated as an email but never verified — a reply target, not proof of identity." }, "subject": { "type": "string", "nullable": true, "description": "Subject line, or `null` when the form did not collect one." }, "status": { "type": "string", "enum": [ "UNREAD", "READ", "ARCHIVED" ], "example": "UNREAD" }, "readAt": { "type": "string", "format": "date-time", "nullable": true, "description": "First time the message was marked read. Retained if it is later marked unread again." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "When it was submitted." }, "preview": { "type": "string", "description": "First 200 characters of the body, whitespace-collapsed to one line and ellipsised when truncated. Fetch the detail route for the full message." } }, "required": [ "id", "name", "email", "subject", "status", "readAt", "archivedAt", "createdAt", "preview" ] }, "MerchantContactMessagePageDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantContactMessageSummaryDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page, or `null` at the end." } }, "required": [ "data", "nextCursor" ] }, "MerchantContactMessageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Submitter's display name (untrusted text)." }, "email": { "type": "string", "format": "email", "description": "Reply address as submitted. Validated as an email but never verified — a reply target, not proof of identity." }, "subject": { "type": "string", "nullable": true, "description": "Subject line, or `null` when the form did not collect one." }, "status": { "type": "string", "enum": [ "UNREAD", "READ", "ARCHIVED" ], "example": "UNREAD" }, "readAt": { "type": "string", "format": "date-time", "nullable": true, "description": "First time the message was marked read. Retained if it is later marked unread again." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "When it was submitted." }, "message": { "type": "string", "description": "Full message body (untrusted text)." } }, "required": [ "id", "name", "email", "subject", "status", "readAt", "archivedAt", "createdAt", "message" ] }, "UpdateContactMessageStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "UNREAD", "READ", "ARCHIVED" ], "description": "New triage state. `UNREAD` restores the row to the unread filter without erasing `readAt` — that records that it was once seen.", "example": "READ" } }, "required": [ "status" ] }, "CreateReturnItemDto": { "type": "object", "properties": { "orderItemId": { "type": "string", "description": "Order item id this line is returning units from.", "minLength": 1 }, "quantity": { "type": "integer", "description": "How many units to return. Must be > 0 and <= the original order line's quantity minus what's already been requested on prior non-cancelled returns.", "minimum": 1 } }, "required": [ "orderItemId", "quantity" ], "additionalProperties": false }, "CreateReturnDto": { "type": "object", "properties": { "customerEmail": { "type": "string", "description": "Customer email. Must match the order's customerEmail (case-folded, trimmed) — slice 1A auth is shared-secret style.", "maxLength": 320 }, "customerName": { "type": "string", "description": "Optional display name for the requester.", "maxLength": 200 }, "reason": { "type": "string", "description": "Free-text reason for the return.", "maxLength": 4000 }, "items": { "description": "Lines being returned. 1-50 entries; cumulative quantity across non-cancelled returns may not exceed the original order line.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/CreateReturnItemDto" } } }, "required": [ "customerEmail", "items" ], "additionalProperties": false }, "PublicReturnItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return line id." }, "orderItemId": { "type": "string", "description": "Order line this return line claims." }, "quantity": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "PENDING", "RESELLABLE", "DAMAGED", "WRITE_OFF" ], "example": "PENDING" } }, "required": [ "id", "orderItemId", "quantity", "condition" ] }, "PublicReturnResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return id." }, "orderId": { "type": "string", "description": "Legacy raw Order id retained only for measured compatibility.", "deprecated": true }, "orderReference": { "type": "string", "nullable": true, "description": "Customer-safe stable reference for the parent order. Possession does not authorize return access. `null` only for a legacy Order awaiting the measured reference backfill.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "refundAmountInCents": { "type": "number", "description": "Refund to the customer for this return, in cents. 0 until the merchant sets an amount.", "example": 0 }, "refundState": { "type": "string", "enum": [ "NOT_APPLICABLE", "PROCESSING", "ISSUED", "REIMBURSEMENT_PENDING", "RECONCILIATION_REQUIRED", "REIMBURSEMENT_RECORDED", "RESOLVED" ] }, "amountOwedInCents": { "type": "integer", "minimum": 0, "nullable": true, "description": "Amount still owed after a provider reversed an earlier successful refund; null when no such correction exists." }, "refundCurrency": { "type": "string", "nullable": true, "example": "usd", "description": "Lowercase ISO 4217 code that BOTH `refundAmountInCents` and `amountOwedInCents` are denominated in (#4007). Read from immutable history — the refund exception when one exists, else the persisted currency of the exact successful payment attempt that created the parent order — never from the organization's current currency setting, which can change after checkout. `null` means the historical denomination is genuinely unrecoverable for this return; it is NOT a licence to substitute a default. A client that receives `null` must not render these amounts under any assumed currency." }, "requestedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReturnItemResponseDto" } } }, "required": [ "id", "orderId", "orderReference", "status", "reason", "refundAmountInCents", "refundState", "amountOwedInCents", "refundCurrency", "requestedAt", "updatedAt", "items" ] }, "CancelReturnDto": { "type": "object", "properties": { "customerEmail": { "type": "string", "description": "Customer email. Must match the order's customerEmail (case-folded, trimmed) — the same shared-secret check used to file the return.", "maxLength": 320 } }, "required": [ "customerEmail" ], "additionalProperties": false }, "MerchantReturnLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "returnId": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid", "description": "The order line this return claims." }, "quantity": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "PENDING", "RESELLABLE", "DAMAGED", "WRITE_OFF" ], "example": "PENDING" }, "lineRefundInCents": { "type": "number", "example": 0, "description": "Refund attributed to this line, in minor units." }, "refundTaxComponentKey": { "type": "string", "nullable": true, "description": "Frozen original Stripe Tax component key used for refund reversal, or `null` when the component was excluded." }, "refundTaxProviderExcluded": { "type": "boolean", "description": "Whether the frozen component was deliberately excluded from the original Stripe Tax calculation." }, "refundComponentTaxInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Original frozen component tax, in minor units." }, "intakeNotes": { "type": "string", "nullable": true, "description": "Merchant intake notes, or `null`." }, "restockDisposition": { "type": "string", "enum": [ "PENDING", "RESTOCKED", "NOT_ELIGIBLE", "NOT_APPLICABLE" ], "description": "Terminal retail-restock outcome. NOT_APPLICABLE means a booking/rental line returned through the booking capacity workflow and did not mutate Inventory." }, "restockedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When this line was restocked, or `null`." }, "restockedInventoryId": { "type": "string", "format": "uuid", "nullable": true, "description": "Inventory row this line restocked to, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "returnId", "orderItemId", "quantity", "condition", "lineRefundInCents", "refundTaxComponentKey", "refundTaxProviderExcluded", "refundComponentTaxInCents", "intakeNotes", "restockDisposition", "restockedAt", "restockedInventoryId", "createdAt", "updatedAt" ] }, "MerchantReturnOrderRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string", "example": "ACME-2026-042" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string", "description": "Buyer name on the order." } }, "required": [ "id", "orderNumber", "customerEmail", "customerName" ] }, "MerchantReturnRefundExceptionSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "OPEN", "CLAIMED", "FINANCIALLY_REMEDIATED", "CLOSED" ] }, "amountInCents": { "type": "integer", "minimum": 1 }, "reimbursedInCents": { "type": "integer", "minimum": 0 }, "amountOwedInCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "example": "usd" }, "providerReconciliationRequiredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "status", "amountInCents", "reimbursedInCents", "amountOwedInCents", "currency", "providerReconciliationRequiredAt" ] }, "MerchantReturnListItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string", "nullable": true, "description": "Buyer name, or `null`." }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "internalNotes": { "type": "string", "nullable": true, "description": "Merchant-internal notes, or `null`." }, "refundAmountInCents": { "type": "number", "example": 0, "description": "Refund to the customer, in minor units." }, "restockingFeeInCents": { "type": "number", "example": 0 }, "stripeRefundId": { "type": "string", "nullable": true, "description": "Stripe refund id, or `null`." }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true }, "refundFailedAt": { "type": "string", "format": "date-time", "nullable": true }, "refundError": { "type": "string", "nullable": true, "description": "Last refund failure message, or `null`." }, "requestedAt": { "format": "date-time", "type": "string" }, "reviewedAt": { "type": "string", "format": "date-time", "nullable": true }, "reviewedById": { "type": "string", "format": "uuid", "nullable": true, "description": "Reviewer user id, or `null`." }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnLineDto" } }, "order": { "$ref": "#/components/schemas/MerchantReturnOrderRefDto" }, "refundException": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantReturnRefundExceptionSummaryDto" } ] } }, "required": [ "id", "organizationId", "orderId", "customerEmail", "customerName", "status", "reason", "internalNotes", "refundAmountInCents", "restockingFeeInCents", "stripeRefundId", "refundedAt", "refundFailedAt", "refundError", "requestedAt", "reviewedAt", "reviewedById", "receivedAt", "completedAt", "createdAt", "updatedAt", "items", "order", "refundException" ] }, "MerchantReturnEvidenceLineDto": { "type": "object", "properties": { "sourceLineId": { "type": "string", "description": "Immutable source-platform line identity." }, "orderItemId": { "type": "string", "format": "uuid" }, "itemName": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "sourceLineId", "orderItemId", "itemName", "quantity" ] }, "MerchantReturnEvidencePackageDto": { "type": "object", "properties": { "sourceShipmentId": { "type": "string" }, "sourcePackageId": { "type": "string" }, "terminalStatus": { "type": "string", "enum": [ "SHIPPED", "DELIVERED" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnEvidenceLineDto" } } }, "required": [ "sourceShipmentId", "sourcePackageId", "terminalStatus", "handedOffAt", "deliveredAt", "lines" ] }, "MerchantReturnEvidenceReconciliationDto": { "type": "object", "properties": { "reconciledAt": { "format": "date-time", "type": "string" }, "evidenceFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "reconciledAt", "evidenceFingerprint" ] }, "MerchantReturnEvidenceDto": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string" }, "sourceSystem": { "type": "string", "nullable": true }, "sourceOrderId": { "type": "string", "nullable": true }, "posture": { "type": "string", "enum": [ "REBUILDABLE", "RECONCILIATION_REQUIRED", "INSUFFICIENT" ] }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "ALREADY_CANONICAL", "COMMERCE_RECORD_MISSING", "COMMERCE_RECORD_AMBIGUOUS", "ORDER_ITEM_LINK_MISSING", "ORDER_ITEM_LINK_AMBIGUOUS", "LEDGER_MIXED_OR_INVALID", "TERMINAL_AGGREGATE_MISSING", "EVIDENCE_MISSING", "EVIDENCE_MALFORMED", "EVIDENCE_VERSION_UNSUPPORTED", "SOURCE_IDENTITY_MISMATCH", "TERMINAL_STATUS_MISMATCH", "TERMINAL_TIMESTAMP_MISMATCH", "SOURCE_LINE_UNKNOWN", "SOURCE_QUANTITY_EXCEEDS_ORDER", "SOURCE_QUANTITY_OVERLAPS_LEDGER", "RETURN_ACTIVITY_PRESENT", "ORDER_CANCELLATION_ACTIVE" ] } }, "canReconcile": { "type": "boolean", "description": "True only when exact machine evidence can be normalized by an Owner/Admin." }, "evidenceFingerprint": { "type": "string", "nullable": true, "pattern": "^[0-9a-f]{64}$", "description": "Present only for a currently reconcilable exact evidence snapshot." }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnEvidencePackageDto" } }, "latestReconciliation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantReturnEvidenceReconciliationDto" } ] } }, "required": [ "orderId", "orderNumber", "sourceSystem", "sourceOrderId", "posture", "reasons", "canReconcile", "evidenceFingerprint", "packages", "latestReconciliation" ] }, "ReconcileMerchantReturnEvidenceDto": { "type": "object", "properties": { "confirmation": { "type": "string", "example": "RECONCILE_IMPORTED_HANDOFF_EVIDENCE", "enum": [ "RECONCILE_IMPORTED_HANDOFF_EVIDENCE" ] }, "evidenceFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Exact fingerprint returned by the latest evidence classification." } }, "required": [ "confirmation", "evidenceFingerprint" ] }, "MerchantReturnLineOrderItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Trail Tent 2P" }, "quantity": { "type": "number", "example": 2 }, "unitPriceInCents": { "type": "number", "example": 14900 }, "totalPriceInCents": { "type": "number", "example": 29800 } }, "required": [ "id", "name", "quantity", "unitPriceInCents", "totalPriceInCents" ] }, "MerchantReturnDetailLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "returnId": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid", "description": "The order line this return claims." }, "quantity": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "PENDING", "RESELLABLE", "DAMAGED", "WRITE_OFF" ], "example": "PENDING" }, "lineRefundInCents": { "type": "number", "example": 0, "description": "Refund attributed to this line, in minor units." }, "refundTaxComponentKey": { "type": "string", "nullable": true, "description": "Frozen original Stripe Tax component key used for refund reversal, or `null` when the component was excluded." }, "refundTaxProviderExcluded": { "type": "boolean", "description": "Whether the frozen component was deliberately excluded from the original Stripe Tax calculation." }, "refundComponentTaxInCents": { "type": "integer", "format": "int32", "minimum": 0, "description": "Original frozen component tax, in minor units." }, "intakeNotes": { "type": "string", "nullable": true, "description": "Merchant intake notes, or `null`." }, "restockDisposition": { "type": "string", "enum": [ "PENDING", "RESTOCKED", "NOT_ELIGIBLE", "NOT_APPLICABLE" ], "description": "Terminal retail-restock outcome. NOT_APPLICABLE means a booking/rental line returned through the booking capacity workflow and did not mutate Inventory." }, "restockedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When this line was restocked, or `null`." }, "restockedInventoryId": { "type": "string", "format": "uuid", "nullable": true, "description": "Inventory row this line restocked to, or `null`." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "orderItem": { "$ref": "#/components/schemas/MerchantReturnLineOrderItemDto" } }, "required": [ "id", "returnId", "orderItemId", "quantity", "condition", "lineRefundInCents", "refundTaxComponentKey", "refundTaxProviderExcluded", "refundComponentTaxInCents", "intakeNotes", "restockDisposition", "restockedAt", "restockedInventoryId", "createdAt", "updatedAt", "orderItem" ] }, "MerchantReturnOrderContextDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string", "example": "ACME-2026-042" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string", "description": "Buyer name on the order." }, "subtotalInCents": { "type": "number", "example": 29800 }, "discountInCents": { "type": "number", "example": 0 }, "taxInCents": { "type": "number", "example": 1788 }, "totalInCents": { "type": "number", "example": 31588 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "example": "UNFULFILLED" } }, "required": [ "id", "orderNumber", "customerEmail", "customerName", "subtotalInCents", "discountInCents", "taxInCents", "totalInCents", "status", "fulfillmentStatus" ] }, "MerchantReturnRefundWorkflowDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "NOT_APPLICABLE", "READY", "PROCESSING", "NEEDS_ATTENTION", "SUCCEEDED", "REFUND_REVERSED_NEEDS_REIMBURSEMENT", "REFUND_REVERSAL_RECONCILIATION_REQUIRED", "RESOLUTION_PENDING", "RESOLVED" ] }, "latestGeneration": { "type": "integer", "minimum": 1, "nullable": true }, "retryAvailable": { "type": "boolean", "description": "True when the Return remains RECEIVED and its latest generation is durably rejected with no-money proof and an acknowledged processing event, so a generation-backed retry command is structurally available. This is not authorization: mutable Return/order, capacity, generation-chain, audit, and ownership facts are revalidated atomically when the command runs." }, "problemCode": { "type": "string", "enum": [ "PROCESSING_UNAVAILABLE", "PROVIDER_REJECTED", "RECONCILIATION_REQUIRED", "STATE_INCONSISTENT" ], "nullable": true, "description": "Stable merchant-safe reason when state is NEEDS_ATTENTION; null otherwise." }, "amountOwedInCents": { "type": "integer", "minimum": 0, "nullable": true, "description": "Current alternative-reimbursement obligation in minor units, or null when no post-success refund exception exists." } }, "required": [ "state", "latestGeneration", "retryAvailable", "problemCode", "amountOwedInCents" ] }, "ReturnRefundRemediationMethod": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "OTHER" ] }, "MerchantReturnRefundRemediationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "method": { "allOf": [ { "$ref": "#/components/schemas/ReturnRefundRemediationMethod" } ] }, "amountInCents": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "example": "usd" }, "occurredAt": { "format": "date-time", "type": "string" }, "reference": { "type": "string", "nullable": true }, "actorUserId": { "type": "string", "format": "uuid" }, "createdAt": { "format": "date-time", "type": "string" }, "ledgerStatus": { "type": "string", "enum": [ "COMPLETED", "FAILED", "VOIDED" ], "nullable": true }, "taxReversalStatus": { "type": "string", "nullable": true }, "taxReversalAdmissionStatus": { "type": "string", "nullable": true } }, "required": [ "id", "method", "amountInCents", "currency", "occurredAt", "reference", "actorUserId", "createdAt", "ledgerStatus", "taxReversalStatus", "taxReversalAdmissionStatus" ] }, "MerchantReturnRefundNotificationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "CORRECTION", "RESOLUTION", "COMBINED" ] }, "status": { "type": "string", "enum": [ "BLOCKED", "READY", "PROVIDER_IN_FLIGHT", "PROVIDER_ACCEPTED", "DEFINITIVELY_NOT_ACCEPTED", "SUPERSEDED" ] }, "admittedAt": { "type": "string", "format": "date-time", "nullable": true }, "terminalAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "status", "admittedAt", "terminalAt", "createdAt" ] }, "MerchantReturnRefundTaxCorrectionDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUPPRESSION_PENDING", "SUPPRESSED", "NO_CALL", "AWAITING_ORIGINAL_OUTCOME", "COMPENSATION_READY", "COMPENSATION_IN_FLIGHT", "COMPENSATED", "RECONCILIATION_REQUIRED" ] }, "noCallDisposition": { "type": "string", "nullable": true }, "providerHandoffStartedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "noCallDisposition", "providerHandoffStartedAt", "completedAt" ] }, "ReturnRefundClosureBlocker": { "type": "string", "enum": [ "PROVIDER_RECONCILIATION_REQUIRED", "REIMBURSEMENT_OUTSTANDING", "REIMBURSEMENT_LEDGER_RECONCILIATION_REQUIRED", "CUSTOMER_NOTICE_PENDING", "CUSTOMER_NOTICE_RECONCILIATION_REQUIRED", "TAX_ADJUSTMENT_PENDING", "TAX_ADJUSTMENT_RECONCILIATION_REQUIRED" ], "description": "Why this exception has not closed, derived from its own rows by the same predicate the closer enforces. Empty for a FINANCIALLY_REMEDIATED case exactly when it may close now; empty once CLOSED except PROVIDER_RECONCILIATION_REQUIRED when a later contradictory provider observation was recorded after closure. Stable order; clients own the merchant copy." }, "MerchantReturnRefundExceptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "OPEN", "CLAIMED", "FINANCIALLY_REMEDIATED", "CLOSED" ] }, "providerStatus": { "type": "string", "example": "failed" }, "latestProviderStatus": { "type": "string", "example": "failed" }, "providerReconciliationRequiredAt": { "type": "string", "format": "date-time", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "amountInCents": { "type": "integer", "minimum": 1 }, "reimbursedInCents": { "type": "integer", "minimum": 0 }, "amountOwedInCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "example": "usd" }, "claimedByUserId": { "type": "string", "format": "uuid", "nullable": true }, "claimedAt": { "type": "string", "format": "date-time", "nullable": true }, "financiallyRemediatedAt": { "type": "string", "format": "date-time", "nullable": true }, "closedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "remediations": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnRefundRemediationDto" } }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnRefundNotificationDto" } }, "taxCorrection": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantReturnRefundTaxCorrectionDto" } ] }, "closureBlockers": { "type": "array", "description": "Why this exception has not closed, derived from its own rows by the same predicate the closer enforces. Empty for a FINANCIALLY_REMEDIATED case exactly when it may close now; empty once CLOSED except PROVIDER_RECONCILIATION_REQUIRED when a later contradictory provider observation was recorded after closure. Stable order; clients own the merchant copy.", "items": { "$ref": "#/components/schemas/ReturnRefundClosureBlocker" } } }, "required": [ "id", "status", "providerStatus", "latestProviderStatus", "providerReconciliationRequiredAt", "failureReason", "amountInCents", "reimbursedInCents", "amountOwedInCents", "currency", "claimedByUserId", "claimedAt", "financiallyRemediatedAt", "closedAt", "createdAt", "remediations", "notifications", "taxCorrection", "closureBlockers" ] }, "MerchantReturnDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string", "nullable": true, "description": "Buyer name, or `null`." }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "internalNotes": { "type": "string", "nullable": true, "description": "Merchant-internal notes, or `null`." }, "refundAmountInCents": { "type": "number", "example": 0, "description": "Refund to the customer, in minor units." }, "restockingFeeInCents": { "type": "number", "example": 0 }, "stripeRefundId": { "type": "string", "nullable": true, "description": "Stripe refund id, or `null`." }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true }, "refundFailedAt": { "type": "string", "format": "date-time", "nullable": true }, "refundError": { "type": "string", "nullable": true, "description": "Last refund failure message, or `null`." }, "requestedAt": { "format": "date-time", "type": "string" }, "reviewedAt": { "type": "string", "format": "date-time", "nullable": true }, "reviewedById": { "type": "string", "format": "uuid", "nullable": true, "description": "Reviewer user id, or `null`." }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantReturnDetailLineDto" } }, "order": { "$ref": "#/components/schemas/MerchantReturnOrderContextDto" }, "refundWorkflow": { "$ref": "#/components/schemas/MerchantReturnRefundWorkflowDto" }, "refundException": { "nullable": true, "description": "Operator-visible post-success refund exception and its independent money, notification, and tax obligations.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantReturnRefundExceptionDto" } ] }, "refundableCapInCents": { "type": "number", "example": 29800, "description": "Server-computed refundable ceiling, clamped to the order balance after sibling returns. Prefills/bounds the refund-amount input." } }, "required": [ "id", "organizationId", "orderId", "customerEmail", "customerName", "status", "reason", "internalNotes", "refundAmountInCents", "restockingFeeInCents", "stripeRefundId", "refundedAt", "refundFailedAt", "refundError", "requestedAt", "reviewedAt", "reviewedById", "receivedAt", "completedAt", "createdAt", "updatedAt", "items", "order", "refundWorkflow", "refundException", "refundableCapInCents" ] }, "ReturnIntakeItemDto": { "type": "object", "properties": { "returnItemId": { "type": "string", "description": "Return-item id whose intake outcome is being recorded." }, "condition": { "type": "string", "enum": [ "RESELLABLE", "DAMAGED", "WRITE_OFF" ], "description": "Terminal inspection outcome. PENDING is intentionally excluded: receipt cannot complete until every line has an operator-recorded outcome." }, "notes": { "type": "string", "nullable": true, "maxLength": 4000, "description": "Merchant intake notes. Pass null or an empty/whitespace-only value to clear the notes; the field must be present so omission cannot silently erase an existing note." } }, "required": [ "returnItemId", "condition", "notes" ] }, "UpdateReturnStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "description": "Target return status. State machine: REQUESTED → {APPROVED, REJECTED, CANCELLED}, APPROVED → {IN_TRANSIT, CANCELLED}, IN_TRANSIT → {RECEIVED, CANCELLED}, RECEIVED → COMPLETED. COMPLETED, REJECTED, CANCELLED are terminal." }, "items": { "minItems": 1, "maxItems": 50, "description": "Optional intake outcomes applied atomically with an IN_TRANSIT → RECEIVED transition. Rejected for every other target status. Existing durable outcomes may be omitted; every line must be non-PENDING after the supplied updates are applied.", "type": "array", "items": { "$ref": "#/components/schemas/ReturnIntakeItemDto" } }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required for RECEIVED. Captured with condition and restock audit evidence." } }, "required": [ "status" ] }, "UpdateReturnIntakeDto": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "One or more return-item outcomes. Item ids must be unique and belong to the return.", "type": "array", "items": { "$ref": "#/components/schemas/ReturnIntakeItemDto" } }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Operator reason captured in audit metadata for the condition decision." } }, "required": [ "items", "reason" ] }, "ReturnRefundItemCapDto": { "type": "object", "properties": { "returnItemId": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Frozen order-item name, for operator display." }, "componentKey": { "type": "string", "description": "Frozen Sales component backing this item. Echoed in capacity errors." }, "quantity": { "type": "integer", "format": "int32", "description": "Quantity being returned on this item." }, "orderItemQuantity": { "type": "integer", "format": "int32", "description": "Quantity originally ordered, used to prorate the cap." }, "grossAmountInCents": { "type": "integer", "format": "int32", "description": "Total gross cents of the frozen Sales line." }, "allocatedInCents": { "type": "integer", "format": "int32", "description": "Gross cents already consumed by active refund allocations and sibling returns against the same order item." }, "capInCents": { "type": "integer", "format": "int32", "description": "Maximum cents allocatable to this item: the quantity-prorated line total, capped by what remains after prior allocations. An `allocations[]` entry above this is rejected with RETURN_REFUND_COMPONENT_CAPACITY_EXCEEDED." } }, "required": [ "returnItemId", "orderItemId", "name", "componentKey", "quantity", "orderItemQuantity", "grossAmountInCents", "allocatedInCents", "capInCents" ] }, "ReturnRefundAllocationPreparationDto": { "type": "object", "properties": { "items": { "description": "Return items that can receive refund cents, including any whose cap is currently 0 so the operator can see where capacity went.", "type": "array", "items": { "$ref": "#/components/schemas/ReturnRefundItemCapDto" } }, "pendingReturnItemIds": { "description": "Return items whose frozen Sales line has not reconciled yet. They cannot be allocated against; allocating to one is rejected with RETURN_REFUND_COMPONENT_LINE_PENDING. Retry after order reconciliation.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "items", "pendingReturnItemIds" ] }, "ReturnRefundItemAllocationDto": { "type": "object", "properties": { "returnItemId": { "type": "string", "format": "uuid", "description": "ReturnItem receiving this exact gross refund amount." }, "amountInCents": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000000, "description": "Gross cents returned against this item, including its attributed tax." } }, "required": [ "returnItemId", "amountInCents" ] }, "UpdateReturnRefundAmountDto": { "type": "object", "properties": { "refundAmountInCents": { "type": "integer", "description": "Refund amount in cents. Non-negative integer; validated server-side to be <= the return's refundable cap (returned line totals + attributed order tax). This endpoint only records the amount — 0 means no cash refund will be issued when the return is later marked COMPLETED.", "format": "int32", "minimum": 0, "example": 2599 }, "allocations": { "minItems": 0, "maxItems": 50, "description": "Operator-specified per-item allocation. Required and non-empty when refundAmountInCents is positive; amounts must sum exactly. Use [] when the refund amount is 0.", "type": "array", "items": { "$ref": "#/components/schemas/ReturnRefundItemAllocationDto" } } }, "required": [ "refundAmountInCents", "allocations" ] }, "RecordReturnRefundRemediationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the action — required for high-risk actions that mandate one (#651); recorded on the audit/activity timeline.", "maxLength": 500 }, "amountInCents": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Amount already reimbursed to the customer, in minor units." }, "method": { "description": "Observed non-card reimbursement method. This command records completed money movement; it never initiates it.", "allOf": [ { "$ref": "#/components/schemas/ReturnRefundRemediationMethod" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$", "example": "usd" }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the alternative reimbursement actually occurred. Future timestamps are rejected." }, "reference": { "type": "string", "maxLength": 200 } }, "required": [ "amountInCents", "method", "currency", "occurredAt" ] }, "UpdateReturnNotesDto": { "type": "object", "properties": { "notes": { "type": "string", "description": "Merchant-only internal notes. Pass `null` to clear; pass a string up to 4000 chars to set.", "nullable": true, "maxLength": 4000 } }, "required": [ "notes" ] }, "CreateContractSignatureDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT" ], "description": "CUSTOMER signs via the customer token surface; MERCHANT is the first-party countersignature (#1380). INTERNAL is not signable yet." }, "signerName": { "type": "string", "maxLength": 200 }, "signerEmail": { "type": "string", "description": "Signatory email (used for delivery in #598)." } }, "required": [ "role" ] }, "CreateContractPacketDto": { "type": "object", "properties": { "recordId": { "type": "string", "description": "The commerce record (quote/invoice/order) this packet is for." }, "revisionId": { "type": "string", "description": "Pin the packet to a specific revision of the record." }, "title": { "type": "string", "maxLength": 200 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional signing deadline." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/CreateContractSignatureDto" } } }, "required": [ "recordId", "title", "signatures" ] }, "MerchantContractSignatureDto": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT", "INTERNAL" ] }, "status": { "type": "string", "enum": [ "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "signerName": { "type": "string", "nullable": true }, "signerEmail": { "type": "string", "nullable": true }, "signedAt": { "type": "string", "nullable": true, "format": "date-time" }, "declinedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "role", "status", "signerName", "signerEmail", "signedAt", "declinedAt" ] }, "MerchantContractPacketDto": { "type": "object", "properties": { "id": { "type": "string" }, "recordId": { "type": "string" }, "revisionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] }, "title": { "type": "string" }, "displayNumber": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "sentAt": { "type": "string", "nullable": true, "format": "date-time" }, "signedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "format": "date-time", "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantContractSignatureDto" } } }, "required": [ "id", "recordId", "revisionId", "status", "title", "displayNumber", "expiresAt", "sentAt", "signedAt", "createdAt", "signatures" ] }, "ContractPacketListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantContractPacketDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "SendContractPacketDto": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } }, "ContractActionLinkDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Raw customer action token — returned ONCE at send." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "token", "expiresAt" ] }, "SendContractResultDto": { "type": "object", "properties": { "packet": { "$ref": "#/components/schemas/MerchantContractPacketDto" }, "customerAction": { "$ref": "#/components/schemas/ContractActionLinkDto" } }, "required": [ "packet", "customerAction" ] }, "CommercePaymentTermPresetDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Operator-facing preset label (e.g. \"Net 30\")." }, "kind": { "type": "string", "enum": [ "DUE_ON_RECEIPT", "DUE_ON_FULFILLMENT", "NET_TERMS", "FIXED_DATE", "MANUAL" ], "description": "Term style: DUE_ON_RECEIPT, DUE_ON_FULFILLMENT, NET_TERMS (see netDays), FIXED_DATE, or MANUAL (free-text termsText)." }, "netDays": { "type": "integer", "format": "int32", "nullable": true, "description": "Net days for NET_TERMS presets (e.g. 30 for \"Net 30\"). Null otherwise." }, "description": { "type": "string", "nullable": true }, "termsText": { "type": "string", "nullable": true, "description": "Free-text terms shown on the document (required for MANUAL presets)." }, "isDefault": { "type": "boolean", "description": "The org's default preset for new documents." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Set when the preset is archived; archived presets are omitted from this list." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "name", "kind", "netDays", "description", "termsText", "isDefault", "archivedAt", "createdAt", "updatedAt" ] }, "CommercePaymentTermPresetListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommercePaymentTermPresetDto" } } }, "required": [ "data" ] }, "CommerceRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "source": { "type": "string", "enum": [ "ONLINE", "MANUAL", "POS", "WHOLESALE", "BOOKING", "SUBSCRIPTION", "RENEWAL" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ], "description": "Commercial lifecycle axis (DRAFT→SENT→ACCEPTED/DECLINED/EXPIRED→CONVERTED, plus terminal VOIDED/CANCELLED). Forward-only; drives which lifecycle actions are permitted. Independent of the payment/fulfillment/signature axes." }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "description": "Payment axis, derived from the payment/refund ledger. Full value space: NOT_REQUIRED, UNPAID, PARTIALLY_PAID, PAID, PARTIALLY_REFUNDED, REFUNDED, FAILED, CANCELLED. Moves independently of the commercial status." }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ], "description": "Shipment fulfillment axis. Committed orders with positive PRODUCT quantity start UNFULFILLED; orders without shippable PRODUCT quantity remain NOT_REQUIRED. Booking/service and subscription entitlement work stays on its operational projection." }, "outboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true, "description": "Canonical outbound physical handoff mode; null when not planned." }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true, "description": "Canonical inbound return handoff mode; null when not planned." }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Deprecated display-only compatibility summary derived from authoritative agreement requirements/satisfactions, with a legacy execution fallback. Full value space: NOT_REQUIRED, PENDING, SIGNED, DECLINED, EXPIRED, CANCELLED. Never use it to authorize or gate a command." }, "displayNumber": { "type": "string", "nullable": true, "description": "Human-facing document number (e.g. Q-1001, INV-1001, C-1001), allocated once at send/issue and stable for the life of the record. Null while DRAFT. Customers address account documents by this number." }, "displayNumberKind": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER", "CONTRACT" ], "nullable": true, "description": "Which numbering series allocated displayNumber (QUOTE/INVOICE/…)." }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "customerEmail": { "type": "string", "nullable": true }, "customerPhone": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "orderId": { "type": "string", "format": "uuid", "nullable": true }, "sourceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "The source quote this order was converted from (#1333)." }, "orderRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Authoritative shared-commerce order linked to this invoice, when present." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "paymentTermPresetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Payment-term preset applied to this record; its terms are frozen into paymentTermsSnapshot at send. Null when no terms apply." }, "paymentTermsSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen payment-terms snapshot (net-days / deposit schedule) captured at send from paymentTermPresetId. Null when no terms apply." }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string", "nullable": true }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "shippingInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalInCents": { "type": "integer", "format": "int32", "description": "Document total in minor units (cents). Commerce money amounts are 32-bit integer cents by design: document totals are capped at 2,147,483,647 cents (~$21.47M), and per-amount line inputs at ±1,000,000,000 cents ($10M). Pricing writes that would exceed these bounds are rejected with 400." }, "amountPaidInCents": { "type": "integer", "format": "int32", "description": "Gross recorded payments (minor units), derived from the payment ledger. Net paid = amountPaidInCents − refundedInCents." }, "refundedInCents": { "type": "integer", "format": "int32", "description": "Total refunded (minor units), derived from the payment ledger." }, "balanceDueInCents": { "type": "integer", "format": "int32", "description": "Outstanding balance (minor units): max(0, totalInCents − amountPaidInCents), i.e. based on GROSS payments. A refund does NOT re-open the balance (ADR-013); the refund dimension lives on refundedInCents + paymentStatus. Zero once gross payments cover the total." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "voidedAt": { "type": "string", "format": "date-time", "nullable": true }, "convertedAt": { "type": "string", "format": "date-time", "nullable": true }, "externalSource": { "type": "string", "nullable": true, "description": "System of record for an externally-originated document (e.g. a wholesale ERP). Together with externalId it forms the external identity; the list filter requires externalSource whenever externalId is supplied." }, "externalId": { "type": "string", "nullable": true, "description": "Opaque id of this document in the externalSource system. The triple (organization, externalSource, externalId) is unique — many externalIds may exist per source, each unique within its (organization, externalSource) pair — which enables idempotent external imports." }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "type", "source", "commercialStatus", "paymentStatus", "fulfillmentStatus", "outboundFulfillmentMode", "outboundDueAt", "inboundFulfillmentMode", "inboundDueAt", "signatureStatus", "displayNumber", "displayNumberKind", "customerId", "customerName", "customerEmail", "customerPhone", "companyName", "orderId", "sourceRecordId", "orderRecordId", "currency", "paymentTermPresetId", "paymentTermsSnapshot", "taxExempt", "taxExemptionReason", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents", "amountPaidInCents", "refundedInCents", "balanceDueInCents", "expiresAt", "sentAt", "acceptedAt", "declinedAt", "cancelledAt", "voidedAt", "convertedAt", "externalSource", "externalId", "metadata", "createdAt", "updatedAt" ] }, "CommerceRecordListItemDto": { "type": "object", "properties": { "primaryStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED", "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED" ], "description": "Primary lifecycle shown by the Sales list. A tenant-owned linked ORDER projects its Order processing status; quotes, invoices, and unlinked orders fall back to commercialStatus." }, "primaryStatusKind": { "type": "string", "enum": [ "COMMERCIAL", "ORDER_PROCESSING" ], "description": "Lifecycle that supplied primaryStatus. Clients must use this discriminator because values such as CANCELLED exist on both lifecycles." } }, "required": [ "primaryStatus", "primaryStatusKind" ] }, "CommerceRecordListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CommerceRecordDto" }, { "$ref": "#/components/schemas/CommerceRecordListItemDto" } ] } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page (the last record id), or null on the last page." } }, "required": [ "data", "nextCursor" ] }, "CommercePaymentLedgerRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "INVOICE", "ORDER" ] }, "displayNumber": { "type": "string", "nullable": true }, "customerId": { "type": "string", "nullable": true, "format": "uuid" }, "customerName": { "type": "string", "nullable": true }, "customerEmail": { "type": "string", "nullable": true, "format": "email" }, "companyName": { "type": "string", "nullable": true } }, "required": [ "id", "type", "displayNumber", "customerId", "customerName", "customerEmail", "companyName" ] }, "CommercePaymentLedgerEntryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "PAYMENT", "REFUND", "REFUND_REVERSAL" ] }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "VOIDED" ] }, "method": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "CARD", "OTHER" ] }, "amountInCents": { "type": "integer", "format": "int32", "description": "Signed by intent via `direction`; always a positive magnitude." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "actorType": { "type": "string", "description": "Who recorded it: USER | SYSTEM." }, "actorId": { "type": "string", "nullable": true, "description": "Actor id — a user id for USER, or a system identifier for SYSTEM." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the payment/refund actually occurred (business date)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the ledger row was written." }, "record": { "$ref": "#/components/schemas/CommercePaymentLedgerRecordDto" } }, "required": [ "id", "direction", "status", "method", "amountInCents", "currency", "actorType", "actorId", "occurredAt", "createdAt", "record" ] }, "CommercePaymentLedgerListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommercePaymentLedgerEntryDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque `(occurredAt,id)` cursor for the next business-date-ordered page, or null on the last page." } }, "required": [ "data", "nextCursor" ] }, "CommerceCustomerOptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "normalizedEmail": { "type": "string", "description": "Normalized (folded) email — the picker label / secondary match." }, "phone": { "type": "string", "nullable": true } }, "required": [ "id", "name", "normalizedEmail", "phone" ] }, "CommerceCustomerOptionListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceCustomerOptionDto" } } }, "required": [ "data" ] }, "MerchantCommerceRecordReadDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "source": { "type": "string", "enum": [ "ONLINE", "MANUAL", "POS", "WHOLESALE", "BOOKING", "SUBSCRIPTION", "RENEWAL" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ], "description": "Commercial lifecycle axis (DRAFT→SENT→ACCEPTED/DECLINED/EXPIRED→CONVERTED, plus terminal VOIDED/CANCELLED). Forward-only; drives which lifecycle actions are permitted. Independent of the payment/fulfillment/signature axes." }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "description": "Payment axis, derived from the payment/refund ledger. Full value space: NOT_REQUIRED, UNPAID, PARTIALLY_PAID, PAID, PARTIALLY_REFUNDED, REFUNDED, FAILED, CANCELLED. Moves independently of the commercial status." }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ], "description": "Shipment fulfillment axis. Committed orders with positive PRODUCT quantity start UNFULFILLED; orders without shippable PRODUCT quantity remain NOT_REQUIRED. Booking/service and subscription entitlement work stays on its operational projection." }, "outboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "nullable": true, "description": "Canonical outbound physical handoff mode; null when not planned." }, "outboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "inboundFulfillmentMode": { "type": "string", "enum": [ "SHIPMENT", "RETRIEVAL", "CUSTOMER_RETURN" ], "nullable": true, "description": "Canonical inbound return handoff mode; null when not planned." }, "inboundDueAt": { "type": "string", "format": "date-time", "nullable": true }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Deprecated display-only compatibility summary derived from authoritative agreement requirements/satisfactions, with a legacy execution fallback. Full value space: NOT_REQUIRED, PENDING, SIGNED, DECLINED, EXPIRED, CANCELLED. Never use it to authorize or gate a command." }, "displayNumber": { "type": "string", "nullable": true, "description": "Human-facing document number (e.g. Q-1001, INV-1001, C-1001), allocated once at send/issue and stable for the life of the record. Null while DRAFT. Customers address account documents by this number." }, "displayNumberKind": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER", "CONTRACT" ], "nullable": true, "description": "Which numbering series allocated displayNumber (QUOTE/INVOICE/…)." }, "customerId": { "type": "string", "format": "uuid", "nullable": true }, "customerName": { "type": "string", "nullable": true }, "customerEmail": { "type": "string", "nullable": true }, "customerPhone": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "orderId": { "type": "string", "format": "uuid", "nullable": true }, "sourceRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "The source quote this order was converted from (#1333)." }, "orderRecordId": { "type": "string", "format": "uuid", "nullable": true, "description": "Authoritative shared-commerce order linked to this invoice, when present." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "paymentTermPresetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Payment-term preset applied to this record; its terms are frozen into paymentTermsSnapshot at send. Null when no terms apply." }, "paymentTermsSnapshot": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Frozen payment-terms snapshot (net-days / deposit schedule) captured at send from paymentTermPresetId. Null when no terms apply." }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string", "nullable": true }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "shippingInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalInCents": { "type": "integer", "format": "int32", "description": "Document total in minor units (cents). Commerce money amounts are 32-bit integer cents by design: document totals are capped at 2,147,483,647 cents (~$21.47M), and per-amount line inputs at ±1,000,000,000 cents ($10M). Pricing writes that would exceed these bounds are rejected with 400." }, "amountPaidInCents": { "type": "integer", "format": "int32", "description": "Gross recorded payments (minor units), derived from the payment ledger. Net paid = amountPaidInCents − refundedInCents." }, "refundedInCents": { "type": "integer", "format": "int32", "description": "Total refunded (minor units), derived from the payment ledger." }, "balanceDueInCents": { "type": "integer", "format": "int32", "description": "Outstanding balance (minor units): max(0, totalInCents − amountPaidInCents), i.e. based on GROSS payments. A refund does NOT re-open the balance (ADR-013); the refund dimension lives on refundedInCents + paymentStatus. Zero once gross payments cover the total." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "voidedAt": { "type": "string", "format": "date-time", "nullable": true }, "convertedAt": { "type": "string", "format": "date-time", "nullable": true }, "externalSource": { "type": "string", "nullable": true, "description": "System of record for an externally-originated document (e.g. a wholesale ERP). Together with externalId it forms the external identity; the list filter requires externalSource whenever externalId is supplied." }, "externalId": { "type": "string", "nullable": true, "description": "Opaque id of this document in the externalSource system. The triple (organization, externalSource, externalId) is unique — many externalIds may exist per source, each unique within its (organization, externalSource) pair — which enables idempotent external imports." }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceRecordRevisionDto" } }, "lineGroups": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceLineGroupDto" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceLineDto" } }, "fulfillments": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceFulfillmentDto" } }, "contractPackets": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceContractPacketDto" } }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Booking operations record linked through the booking-side commerceRecordId foreign key, or null." } }, "required": [ "id", "organizationId", "type", "source", "commercialStatus", "paymentStatus", "fulfillmentStatus", "outboundFulfillmentMode", "outboundDueAt", "inboundFulfillmentMode", "inboundDueAt", "signatureStatus", "displayNumber", "displayNumberKind", "customerId", "customerName", "customerEmail", "customerPhone", "companyName", "orderId", "sourceRecordId", "orderRecordId", "currency", "paymentTermPresetId", "paymentTermsSnapshot", "taxExempt", "taxExemptionReason", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents", "amountPaidInCents", "refundedInCents", "balanceDueInCents", "expiresAt", "sentAt", "acceptedAt", "declinedAt", "cancelledAt", "voidedAt", "convertedAt", "externalSource", "externalId", "metadata", "createdAt", "updatedAt", "revisions", "lineGroups", "lines", "fulfillments", "contractPackets", "bookingId" ] }, "CommerceSignatureDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "packetId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT", "INTERNAL" ] }, "status": { "type": "string", "enum": [ "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "signerName": { "type": "string", "nullable": true }, "signerEmail": { "type": "string", "nullable": true }, "signedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "packetId", "role", "status", "signerName", "signerEmail", "signedAt", "declinedAt", "metadata", "createdAt", "updatedAt" ] }, "CommerceContractPacketDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] }, "title": { "type": "string" }, "displayNumber": { "type": "string", "nullable": true, "description": "Human-facing contract number (e.g. C-1001), allocated at send. Null while DRAFT." }, "contentSnapshot": { "type": "object", "additionalProperties": true }, "provider": { "type": "string", "nullable": true, "description": "External e-signature provider, when the packet is fulfilled off-platform. Null for first-party (in-app) signing, the only mode shipped in M3.5." }, "externalId": { "type": "string", "nullable": true, "description": "Provider-side packet id when provider is set." }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "signedAt": { "type": "string", "format": "date-time", "nullable": true }, "declinedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceSignatureDto" } } }, "required": [ "id", "organizationId", "recordId", "revisionId", "status", "title", "displayNumber", "contentSnapshot", "provider", "externalId", "sentAt", "signedAt", "declinedAt", "expiresAt", "createdAt", "updatedAt", "signatures" ] }, "CommercePaymentTransactionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "PAYMENT", "REFUND", "REFUND_REVERSAL" ] }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "VOIDED" ] }, "method": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "CARD", "OTHER" ] }, "amountInCents": { "type": "integer", "format": "int32", "description": "Signed by intent via `direction`; always a positive magnitude." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "reference": { "type": "string", "nullable": true, "description": "Merchant-supplied reference (cheque no., transfer id, …)." }, "actorType": { "type": "string", "description": "Who recorded it: USER | SYSTEM." }, "actorId": { "type": "string", "nullable": true, "description": "Actor id — a user id for USER, or a system identifier (e.g. \"stripe-webhook\") for SYSTEM." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the payment/refund actually occurred (business date)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the ledger row was written." } }, "required": [ "id", "direction", "status", "method", "amountInCents", "currency", "reference", "actorType", "actorId", "occurredAt", "createdAt" ] }, "CommercePaymentTransactionListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommercePaymentTransactionDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page (last entry id), or null on the last page." } }, "required": [ "data", "nextCursor" ] }, "CommerceActivityEventDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid", "nullable": true, "description": "The revision the event anchors to, when revision-scoped." }, "eventType": { "type": "string", "description": "Dotted event type, e.g. `commerce.record.sent`." }, "actorType": { "type": "string", "nullable": true, "description": "USER (merchant staff) | TOKEN (customer action link) | SYSTEM (webhook/sweep)." }, "actorId": { "type": "string", "nullable": true, "description": "User id for USER, token id for TOKEN, or a system identifier (e.g. \"expiry-sweep\") for SYSTEM." }, "customerVisible": { "type": "boolean" }, "moneyMoving": { "type": "boolean" }, "statusChanging": { "type": "boolean" }, "permissionSensitive": { "type": "boolean", "description": "True when the event records the exercise of a permission-gated (high-risk) capability (#651)." }, "fromStatus": { "type": "string", "nullable": true }, "toStatus": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true, "description": "Reason captured by the high-risk gate, when one was given." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Allow-listed event detail (ids/numbers/enums/timestamps); audit-only values are excluded." }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "revisionId", "eventType", "actorType", "actorId", "customerVisible", "moneyMoving", "statusChanging", "permissionSensitive", "fromStatus", "toStatus", "reason", "metadata", "createdAt" ] }, "CommerceActivityEventListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommerceActivityEventDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page (last event id), or null on the last page." } }, "required": [ "data", "nextCursor" ] }, "CreateCommerceRecordDto": { "type": "object", "properties": { "source": { "type": "string", "description": "Origin of the record. Defaults to MANUAL for staff-created docs.", "enum": [ "ONLINE", "MANUAL", "POS", "WHOLESALE", "BOOKING", "SUBSCRIPTION", "RENEWAL" ] }, "customerId": { "type": "string", "description": "Linked customer id." }, "customerName": { "type": "string", "description": "Customer display name captured on the document." }, "customerEmail": { "type": "string", "description": "Customer email." }, "customerPhone": { "type": "string", "description": "Customer phone." }, "companyName": { "type": "string", "description": "Company / account name for B2B documents." }, "currency": { "type": "string", "description": "ISO 4217 currency, lower-case (e.g. `usd`). Defaults to `usd`." }, "paymentTermPresetId": { "type": "string", "description": "Reusable payment-term preset id to snapshot on send." }, "taxExempt": { "type": "boolean", "description": "Document-level tax exemption." }, "taxExemptionReason": { "type": "string", "description": "Reason for the tax exemption (audited)." }, "expiresAt": { "type": "string", "description": "Quote/document expiry (ISO-8601). Required before sending a quote.", "format": "date-time" }, "externalSource": { "type": "string", "description": "External source system (for import dedupe with externalId)." }, "externalId": { "type": "string", "description": "External id, unique per (org, externalSource)." }, "metadata": { "type": "object", "description": "Free-form metadata object stored on the record." } } }, "UpdateCommerceRecordDto": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Linked customer id." }, "customerName": { "type": "string", "description": "Customer display name." }, "customerEmail": { "type": "string", "description": "Customer email." }, "customerPhone": { "type": "string", "description": "Customer phone." }, "companyName": { "type": "string", "description": "Company / account name." }, "currency": { "type": "string", "description": "ISO 4217 currency, lower-case." }, "paymentTermPresetId": { "type": "string", "description": "Reusable payment-term preset id. Pass null to clear.", "nullable": true }, "taxExempt": { "type": "boolean", "description": "Document-level tax exemption." }, "taxExemptionReason": { "type": "string", "description": "Reason for the tax exemption (audited)." }, "expiresAt": { "type": "string", "description": "Quote/document expiry (ISO-8601). Pass null to clear.", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "description": "Free-form metadata object stored on the record." } } }, "AcknowledgeExternalLabelRetirementDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "carrierResponsibilityAccepted": { "type": "boolean", "enum": [ true ], "description": "Must be true. Confirms the merchant owns any required external carrier void and carrier-account refund; this is not provider proof." } }, "required": [ "reason", "carrierResponsibilityAccepted" ] }, "AcknowledgeExternalLabelRetirementResponseDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "CANCELLED" ] }, "replayed": { "type": "boolean", "description": "True when the exact acknowledgement already completed and this request only reloaded it." }, "message": { "type": "string", "description": "Server-authored merchant guidance. It never claims provider confirmation or carrier credit." }, "acknowledgement": { "$ref": "#/components/schemas/CommerceExternalLabelRetirementAcknowledgementDto" }, "record": { "$ref": "#/components/schemas/CommerceRecordDetailDto" } }, "required": [ "outcome", "replayed", "message", "acknowledgement", "record" ] }, "HandoffCommerceFulfillmentDto": { "type": "object", "properties": { "notify": { "type": "boolean", "description": "Required customer-communication decision. True durably enqueues one shipment notification; false durably records suppression." }, "trackingNumber": { "type": "string", "maxLength": 120, "description": "Optional tracking number for a READY shipment that does not already have one. An existing tracking number cannot be replaced at handoff." } }, "required": [ "notify" ] }, "DeliverCommerceFulfillmentDto": { "type": "object", "properties": { "deliveredAt": { "type": "string", "format": "date-time", "description": "The instant the merchant asserts the recipient received this shipment. Must be a valid ISO 8601 date-time, on or after the recorded handoff, and not in the future. Distinct from the server-recorded time of the assertion itself.", "example": "2026-09-12T18:30:00.000Z" }, "reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Required merchant-facing justification for asserting delivery without carrier confirmation. Stored as durable internal evidence and never exposed on a customer projection.", "example": "Recipient confirmed receipt by phone; carrier scan never posted." } }, "required": [ "deliveredAt", "reason" ] }, "CreateCommerceFulfillmentLineDto": { "type": "object", "properties": { "lineId": { "type": "string", "format": "uuid", "description": "Fulfillment-eligible CommerceLine id from the same ORDER CommerceRecord. Only positive PRODUCT lines are shipment-eligible; SERVICE, CUSTOM, FEE, DEPOSIT, and ADJUSTMENT lines are not. A REPLACEMENT_GOODS request may repeat a lineId when each entry names a different exact original allocation." }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000000, "description": "Positive quantity fulfilled in this shipment. ORIGINAL_ORDER quantity is capped by the ordered line; REPLACEMENT_GOODS quantity is capped by its linked ReturnItem and original handed-off allocation. Multiple replacement entries can share a lineId while retaining distinct source links." }, "replacementReturnItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Required for REPLACEMENT_GOODS: the ReturnItem authorizing this replacement quantity." }, "replacesFulfillmentLineId": { "type": "string", "format": "uuid", "nullable": true, "description": "Required for REPLACEMENT_GOODS: the exact original SHIPPED/DELIVERED fulfillment-line allocation being replaced." } }, "required": [ "lineId", "quantity" ] }, "CreateCommerceFulfillmentDto": { "type": "object", "properties": { "goodsKind": { "type": "string", "enum": [ "ORIGINAL_ORDER", "REPLACEMENT_GOODS" ], "default": "ORIGINAL_ORDER", "description": "Original-order goods own the canonical order rollup. Replacement goods require explicit per-line return/original-allocation links and project separately." }, "lines": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/CreateCommerceFulfillmentLineDto" } }, "notify": { "type": "boolean", "description": "Required customer-communication decision for this direct carrier handoff. True durably enqueues one shipment notification; false durably records suppression. DELIVERY and CUSTOMER_PICKUP require false." }, "mode": { "type": "string", "enum": [ "SHIPMENT", "DELIVERY", "CUSTOMER_PICKUP" ], "default": "SHIPMENT", "description": "Canonical outbound handoff mode. Defaults to SHIPMENT for backward compatibility; DELIVERY and CUSTOMER_PICKUP do not enqueue a shipment email." }, "carrier": { "type": "string", "maxLength": 80, "nullable": true, "description": "Optional carrier label for this fulfillment." }, "serviceLevel": { "type": "string", "maxLength": 80, "nullable": true, "description": "Optional carrier service level." }, "trackingNumber": { "type": "string", "maxLength": 120, "nullable": true, "description": "Optional carrier tracking number." }, "trackingUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional http(s) carrier tracking URL." }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Shipment time; defaults to the current server time." } }, "required": [ "lines", "notify" ] }, "SelectComposedProductDto": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Tenant-owned composed parent Item id from the merchant package picker." }, "expectedRevision": { "type": "number", "format": "int32", "minimum": 1, "maximum": 2147483647, "description": "Exact composition revision shown by the package picker. A stale revision fails before any group or line is written." }, "selectedQuantity": { "type": "number", "format": "int32", "minimum": 1, "maximum": 2147483647, "default": 1 }, "servicePeriodStartsAt": { "type": "string", "format": "date-time", "description": "Operational window start for tracked RENTAL/SERVICE components. Must be supplied with servicePeriodEndsAt." }, "servicePeriodEndsAt": { "type": "string", "format": "date-time", "description": "Operational window end for tracked RENTAL/SERVICE components. Must be later than servicePeriodStartsAt." } }, "required": [ "itemId", "expectedRevision", "selectedQuantity" ] }, "CreateCommerceLineDto": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "FEE", "DEPOSIT", "ADJUSTMENT", "CUSTOM" ] }, "name": { "type": "string", "description": "Line name / label." }, "quantity": { "type": "integer", "description": "Quantity (default 1).", "format": "int32", "minimum": 0, "maximum": 1000000 }, "unitPriceInCents": { "type": "integer", "description": "Unit price in cents. >= 0 for all categories except ADJUSTMENT (credit) lines, which may be negative.", "format": "int32", "minimum": -1000000000, "maximum": 1000000000 }, "groupId": { "type": "string", "description": "Line group id (must belong to this record)." }, "itemId": { "type": "string", "description": "Catalog item id (snapshot reference)." }, "variantId": { "type": "string", "description": "Catalog variant id (snapshot reference)." }, "sku": { "type": "string", "description": "SKU snapshot." }, "description": { "type": "string", "description": "Line description." }, "taxExempt": { "type": "boolean", "description": "Line-level tax exemption." }, "taxExemptionReason": { "type": "string", "description": "Reason for the line tax exemption." }, "servicePeriodStartsAt": { "type": "string", "description": "Service period start (ISO-8601).", "format": "date-time" }, "servicePeriodEndsAt": { "type": "string", "description": "Service period end (ISO-8601).", "format": "date-time" }, "depositPurpose": { "type": "string", "description": "Structured deposit purpose for DEPOSIT lines." }, "tags": { "description": "Free-form tags.", "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "integer", "description": "Sort order within the record/group.", "format": "int32" }, "metadata": { "type": "object", "description": "Free-form metadata object." } }, "required": [ "category", "name" ] }, "UpdateCommerceLineDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Line name / label." }, "quantity": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000000 }, "unitPriceInCents": { "type": "integer", "format": "int32", "minimum": -1000000000, "maximum": 1000000000, "description": "Unit price in cents. Negative is only accepted when the line is an ADJUSTMENT (credit); enforced by the service." }, "groupId": { "type": "string", "description": "Move the line to a group (must belong to this record), or `null` to ungroup it. Omit to leave the current group unchanged.", "nullable": true }, "sku": { "type": "string" }, "description": { "type": "string" }, "taxExempt": { "type": "boolean" }, "taxExemptionReason": { "type": "string" }, "servicePeriodStartsAt": { "type": "string", "format": "date-time" }, "servicePeriodEndsAt": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "sortOrder": { "type": "integer", "format": "int32" }, "metadata": { "type": "object" } } }, "CreateCommerceLineGroupDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BUNDLE", "PACKAGE", "KIT", "PROPOSAL_SECTION", "CUSTOM" ] }, "title": { "type": "string", "description": "Group title / section heading." }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "format": "int32" }, "metadata": { "type": "object" } }, "required": [ "kind", "title" ] }, "UpdateCommerceLineGroupDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BUNDLE", "PACKAGE", "KIT", "PROPOSAL_SECTION", "CUSTOM" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "format": "int32" }, "metadata": { "type": "object" } } }, "SetLinePriceOverrideDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the override action — required by the high-risk gate (#651); recorded in the pricing snapshot and on the activity timeline.", "maxLength": 500 }, "unitPriceInCents": { "type": "integer", "description": "Overridden unit price in cents. >= 0 for all categories except ADJUSTMENT (credit) lines, which may be negative.", "format": "int32", "minimum": -1000000000, "maximum": 1000000000 } }, "required": [ "unitPriceInCents" ] }, "CommerceOverrideActionDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the override action — required by the high-risk gate (#651); recorded in the pricing snapshot and on the activity timeline.", "maxLength": 500 } } }, "SetDiscountOverrideDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the override action — required by the high-risk gate (#651); recorded in the pricing snapshot and on the activity timeline.", "maxLength": 500 }, "amountInCents": { "type": "integer", "description": "Fixed discount in cents (> 0). Mutually exclusive with percentDecimal.", "format": "int32", "minimum": 1, "maximum": 1000000000 }, "percentDecimal": { "type": "string", "description": "Discount rate as a decimal string (\"0.10\" = 10%), 0 < rate <= 1, up to 4 decimal places. Mutually exclusive with amountInCents.", "example": "0.10" }, "label": { "type": "string", "description": "Human-facing label rendered in the pricing explanation (defaults to \"Manual discount\").", "maxLength": 255 } } }, "SetTaxOverrideDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the override action — required by the high-risk gate (#651); recorded in the pricing snapshot and on the activity timeline.", "maxLength": 500 }, "taxExempt": { "type": "boolean", "description": "Overridden document-level tax exemption." }, "taxExemptionReason": { "type": "string", "description": "Exemption reason surfaced on the document (defaults to the override reason).", "maxLength": 500 } }, "required": [ "taxExempt" ] }, "SendCommerceRecordDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for sending — required for high-risk send actions that mandate one (#651); recorded on the audit/activity timeline.", "maxLength": 500 } } }, "CustomerActionLinkDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Raw customer action token — returned ONCE at send. Deliver it to the customer; they read/act via /api/v1/customer/commerce/{quotes,invoices}/:tokenOrId." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the action link expires (document expiry + grace)." } }, "required": [ "token", "expiresAt" ] }, "SendCommerceResultDto": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/CommerceRecordDetailDto" }, "customerAction": { "$ref": "#/components/schemas/CustomerActionLinkDto" } }, "required": [ "record", "customerAction" ] }, "CommerceActionDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the action — required for high-risk actions that mandate one (#651); recorded on the audit/activity timeline.", "maxLength": 500 } } }, "CreateCommerceTerminalRequestDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for collecting a card-present Terminal payment; required by the high-risk gate and recorded for audit.", "maxLength": 500 }, "source": { "type": "string", "description": "Short source label for audit metadata.", "maxLength": 120 } }, "required": [ "reason" ] }, "CommerceTerminalConnectionTokenDto": { "type": "object", "properties": { "secret": { "type": "string", "description": "Short-lived Stripe Terminal connection token secret for the browser SDK." }, "stripeAccountId": { "type": "string", "description": "Tenant connected Stripe account the Terminal token is scoped to." } }, "required": [ "secret", "stripeAccountId" ] }, "CommerceTerminalPaymentIntentDto": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "PaymentIntent client secret for Stripe Terminal collect/process calls." }, "paymentIntentId": { "type": "string", "description": "Stripe PaymentIntent id created on the tenant connected account." }, "paymentAttemptId": { "type": "string", "description": "Internal PaymentAttempt id used by webhook reconciliation." }, "stripeAccountId": { "type": "string", "description": "Tenant connected Stripe account the PaymentIntent lives on." }, "amountInCents": { "type": "integer", "format": "int32", "description": "Server-authoritative balance due being collected, in cents." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." } }, "required": [ "clientSecret", "paymentIntentId", "paymentAttemptId", "stripeAccountId", "amountInCents", "currency" ] }, "CommerceManualPaymentMethod": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "OTHER" ], "description": "Manual/offline settlement method (cash, check, bank transfer, store credit, other). CARD is reserved for online Stripe capture and is rejected on this manual route." }, "RecordCommercePaymentDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the action — required for high-risk actions that mandate one (#651); recorded on the audit/activity timeline.", "maxLength": 500 }, "amountInCents": { "type": "integer", "description": "Amount of the payment/refund in cents (> 0).", "format": "int32", "minimum": 1, "maximum": 1000000000 }, "method": { "description": "Manual/offline settlement method (cash, check, bank transfer, store credit, other). CARD is reserved for online Stripe capture and is rejected on this manual route.", "allOf": [ { "$ref": "#/components/schemas/CommerceManualPaymentMethod" } ] }, "currency": { "type": "string", "description": "ISO 4217 currency. Defaults to the document currency; a mismatch is rejected.", "minLength": 3, "maxLength": 3 }, "reference": { "type": "string", "description": "Operator's external reference — check number, transfer id, etc.", "maxLength": 200 }, "occurredAt": { "type": "string", "description": "When the money actually moved (ISO 8601). Defaults to now.", "format": "date-time" } }, "required": [ "amountInCents", "method" ] }, "IssueCommerceStripeRefundDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the action — required for high-risk actions that mandate one (#651); recorded on the audit/activity timeline.", "maxLength": 500 }, "paymentTransactionId": { "type": "string", "format": "uuid", "description": "The COMPLETED online card PAYMENT ledger row whose original PaymentIntent this refund issues against." }, "amountInCents": { "type": "integer", "description": "Amount to refund in cents (> 0). Partial or full, capped at both the targeted payment's amount and the record's net paid.", "format": "int32", "minimum": 1, "maximum": 1000000000 }, "allocations": { "minItems": 1, "maxItems": 100, "description": "Operator-specified component allocation. Gross component amounts must sum exactly to amountInCents and cannot exceed each component's remaining refundable balance.", "type": "array", "items": { "$ref": "#/components/schemas/RefundComponentAllocationDto" } } }, "required": [ "paymentTransactionId", "amountInCents", "allocations" ] }, "RefundableComponentDto": { "type": "object", "properties": { "componentKind": { "type": "string", "enum": [ "LINE", "SHIPPING" ], "description": "LINE is one frozen Sales line; SHIPPING is the frozen shipping component." }, "componentKey": { "type": "string", "description": "Stable key identifying this component on the frozen revision. Echoed in capacity errors from the issue endpoint." }, "lineId": { "type": "string", "format": "uuid", "nullable": true, "description": "Frozen Sales line id for LINE components; null for SHIPPING. Send this back as `allocations[].lineId` when allocating to a LINE." }, "orderItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Originating order item, when this component maps to one. Informational: return allocations against the same order item also consume capacity." }, "grossAmountInCents": { "type": "integer", "format": "int32", "description": "Total gross cents this component was billed for." }, "allocatedInCents": { "type": "integer", "format": "int32", "description": "Gross cents already consumed by active refund allocations and by returns against the same order item." }, "remainingInCents": { "type": "integer", "format": "int32", "description": "Gross cents still allocatable. An `allocations[]` entry above this is rejected with REFUND_COMPONENT_CAPACITY_EXCEEDED." } }, "required": [ "componentKind", "componentKey", "lineId", "orderItemId", "grossAmountInCents", "allocatedInCents", "remainingInCents" ] }, "RefundAllocationPreparationDto": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "description": "ISO currency of every amount in this payload." }, "components": { "description": "Every refundable component on the frozen revision, including those with zero remaining cents so the operator can see why capacity is gone.", "type": "array", "items": { "$ref": "#/components/schemas/RefundableComponentDto" } } }, "required": [ "recordId", "currency", "components" ] }, "CommerceCaptureCaseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Enrolled case reference; for a SIGNED_CAPTURE_AMOUNT_UNKNOWN diagnostic this is a conflict-evidence id that the capture-acceptance route does not accept. canRequestAcceptance distinguishes eligibility, subject to the route’s further checks." }, "status": { "type": "string", "enum": [ "OPEN", "POSTED", "FULLY_RETURNED" ], "description": "Separate capture disposition; does not replace ledger-derived payment status." }, "reasonCode": { "type": "string", "description": "Structured current refusal or capture classification." }, "conflict": { "type": "boolean", "description": "Unresolved contradictory evidence; blocks financial disposition." }, "expectedAmountInCents": { "type": "integer", "nullable": true, "description": "Immutable expected minor units; null when the original expected amount was invalid." }, "expectedCurrency": { "type": "string", "nullable": true, "description": "Frozen expected currency, also used for recorded ledger amounts. Null when the original currency was invalid or a predecessor diagnostic did not retain it; never inferred from the current record or signed currency." }, "capturedAmountInCents": { "type": "integer", "nullable": true, "description": "Verified full signed captured minor units; null for a missing-facts investigation diagnostic. Never the stored expected amount." }, "currency": { "type": "string", "nullable": true, "description": "Signed currency; null when the ordinary successful delivery omitted it. Null prevents case acceptance." }, "recordedAmountInCents": { "type": "integer", "description": "Amount recorded for this capture; zero while unposted, irrespective of Stripe success." }, "returnedAmountInCents": { "type": "integer", "description": "Distinct verified successful refund evidence total; conflict may invalidate its use for disposition." }, "recordedRefundAmountInCents": { "type": "integer", "description": "Distinct completed ledger refunds verified against this capture’s retained refund facts; separate from the provider-returned total." }, "refundRecoveryStatus": { "type": "string", "enum": [ "NOT_APPLICABLE", "PENDING", "REFUSED", "COMPLETE" ], "description": "Ordinary refund accounting recovery for a posted exact capture. PENDING means retained owner work is unfinished; REFUSED means its existing durable reconciliation refusal remains. COMPLETE is scoped to known retained observations, not future provider settlement. NOT_APPLICABLE means the capture is unposted or its money facts are unknown." }, "occurredAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Signed occurrence time; null if absent on the ordinary successful path." }, "acceptedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Staff acceptance time; null if no staff acceptance committed." }, "acceptanceReason": { "type": "string", "nullable": true, "description": "Staff’s recorded reason; null if no staff acceptance committed." }, "canRequestAcceptance": { "type": "boolean", "description": "Necessary evidence conditions only. Actor permission, high-risk reason, current identity, currency, document status and ledger cap are rechecked on acceptance." } }, "required": [ "id", "status", "reasonCode", "conflict", "expectedAmountInCents", "expectedCurrency", "capturedAmountInCents", "currency", "recordedAmountInCents", "returnedAmountInCents", "recordedRefundAmountInCents", "refundRecoveryStatus", "occurredAt", "acceptedAt", "acceptanceReason", "canRequestAcceptance" ] }, "CommerceCaptureCaseListDto": { "type": "object", "properties": { "collectionHeld": { "type": "boolean", "description": "Full-history capture collection hold at read time, independent of pagination. True blocks new Terminal collection; manual recording eligibility is unchanged. False is a status snapshot, not collection authorization: the server rechecks under the record lock before admitting Terminal collection." }, "data": { "description": "Up to 100 enrolled capture cases and unresolved missing-amount diagnostics, combined by immutable creation time, id and source descending. Follow nextCursor for older pages. Empty means no matching prospective item remains on this page; it does not prove historical accounting or provider settlement is complete.", "type": "array", "items": { "$ref": "#/components/schemas/CommerceCaptureCaseDto" } }, "hasMore": { "type": "boolean", "description": "True when a further page existed at selection time. Pagination does not authorize collection or replace the server’s full-history capture hold." }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque continuation for the same organization and record; null when there is no further page. Newer inserts do not shift continuation; newly enrolled captures can replace earlier diagnostics, so refresh the newest page for current evidence. This is not a frozen historical snapshot." } }, "required": [ "collectionHeld", "data", "hasMore", "nextCursor" ] }, "AcceptCommerceCaptureDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Required staff reason for recording this exact immutable capture; no money or provider identity may be supplied.", "maxLength": 500 } }, "required": [ "reason" ] }, "CustomerCommerceDocumentType": { "type": "string", "enum": [ "QUOTE", "INVOICE" ] }, "CustomerCommerceLineDto": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "FEE", "DEPOSIT", "ADJUSTMENT", "CUSTOM" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "number" }, "includedQuantity": { "type": "number", "description": "Frozen operational quantity included. For package components this is compositionEffectiveQuantity; otherwise it equals quantity." }, "unitPriceInCents": { "type": "number", "description": "Unit price in minor units (cents)." }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "intrinsicSavingsInCents": { "type": "number", "description": "Intrinsic COMPOSED_PRODUCT savings included in discountInCents." }, "promotionDiscountInCents": { "type": "number", "description": "Coupon, automatic, bundle, or entitlement savings excluding intrinsic package savings." }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" }, "servicePeriodStartsAt": { "type": "string", "nullable": true, "format": "date-time" }, "servicePeriodEndsAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "category", "name", "description", "quantity", "includedQuantity", "unitPriceInCents", "subtotalInCents", "discountInCents", "intrinsicSavingsInCents", "promotionDiscountInCents", "taxInCents", "totalInCents", "servicePeriodStartsAt", "servicePeriodEndsAt" ] }, "CustomerCommerceLineGroupDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BUNDLE", "PACKAGE", "KIT", "PROPOSAL_SECTION", "CUSTOM" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "selectedQuantity": { "type": "integer", "format": "int32", "minimum": 1, "nullable": true, "description": "Frozen top-level package quantity; null for an ordinary proposal section." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCommerceLineDto" } } }, "required": [ "kind", "title", "description", "selectedQuantity", "lines" ] }, "CustomerCommerceDocumentDto": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CustomerCommerceDocumentType" } ] }, "displayNumber": { "type": "string", "nullable": true, "description": "Customer-visible document number, allocated at send." }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "fulfillmentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never an action authority or payment gate." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "customerName": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "revisionNumber": { "type": "number", "description": "The revision number this token addresses (immutable once sent)." }, "title": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Business expiry of the document (quotes). May be in the past." }, "sentAt": { "type": "string", "nullable": true, "format": "date-time" }, "acceptedAt": { "type": "string", "nullable": true, "format": "date-time" }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "shippingInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" }, "amountPaidInCents": { "type": "number" }, "balanceDueInCents": { "type": "number" }, "lineGroups": { "description": "Grouped line items (e.g. proposal sections), in display order.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerCommerceLineGroupDto" } }, "lines": { "description": "Ungrouped line items, in display order.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerCommerceLineDto" } } }, "required": [ "type", "displayNumber", "commercialStatus", "paymentStatus", "fulfillmentStatus", "signatureStatus", "currency", "customerName", "companyName", "revisionNumber", "title", "expiresAt", "sentAt", "acceptedAt", "subtotalInCents", "discountInCents", "shippingInCents", "taxInCents", "totalInCents", "amountPaidInCents", "balanceDueInCents", "lineGroups", "lines" ] }, "CustomerInvoicePaymentDto": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "The PaymentIntent client secret for the Stripe Payment Element." }, "publishableKey": { "type": "string", "description": "The Stripe publishable key for this environment." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "The tenant's connected Stripe account the PaymentIntent lives on. The client must initialize Stripe.js with `{ stripeAccount }` so the Payment Element confirms against it (mirrors the checkout PaymentSessionDto). null on the platform account (test/sandbox)." }, "amountInCents": { "type": "integer", "format": "int32", "description": "Amount being charged (the outstanding balance), in cents." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." } }, "required": [ "clientSecret", "publishableKey", "stripeAccountId", "amountInCents", "currency" ] }, "DeclineCommerceDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for declining — recorded on the audit timeline.", "maxLength": 1000 } } }, "CustomerContractStatus": { "type": "string", "enum": [ "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] }, "CustomerContractSignatureDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT", "INTERNAL" ] }, "status": { "type": "string", "enum": [ "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "signerName": { "type": "string", "nullable": true, "description": "Display name of the signatory." }, "signedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "role", "status", "signerName", "signedAt" ] }, "CustomerContractPacketDto": { "type": "object", "properties": { "displayNumber": { "type": "string", "nullable": true, "description": "Customer-visible contract number." }, "status": { "allOf": [ { "$ref": "#/components/schemas/CustomerContractStatus" } ] }, "title": { "type": "string" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "sentAt": { "type": "string", "nullable": true, "format": "date-time" }, "signedAt": { "type": "string", "nullable": true, "format": "date-time" }, "declinedAt": { "type": "string", "nullable": true, "format": "date-time" }, "signatures": { "description": "Signature requests on the packet, in creation order.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerContractSignatureDto" } } }, "required": [ "displayNumber", "status", "title", "expiresAt", "sentAt", "signedAt", "declinedAt", "signatures" ] }, "SignContractDto": { "type": "object", "properties": { "signerName": { "type": "string", "description": "Optional typed signer name recorded on the signature.", "maxLength": 200 } } }, "CustomerCommerceSummaryDto": { "type": "object", "properties": { "displayNumber": { "type": "string", "description": "Public document number (e.g. Q-1042) — the row handle." }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never an action authority or payment gate." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "totalInCents": { "type": "integer", "format": "int32", "description": "Total of the latest customer-visible revision, in minor units." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Business expiry, when set (quotes)." }, "sentAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the latest visible revision was sent." }, "stale": { "type": "boolean", "description": "True while the merchant is revising: the shown revision has been superseded and an updated document will follow." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "displayNumber", "type", "commercialStatus", "paymentStatus", "signatureStatus", "currency", "totalInCents", "expiresAt", "sentAt", "stale", "createdAt" ] }, "CustomerCommerceListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCommerceSummaryDto" } }, "page": { "type": "integer", "format": "int32", "description": "1-based page number." }, "pageSize": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "required": [ "data", "page", "pageSize", "total" ] }, "CustomerAccountCommerceLineDto": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "FEE", "DEPOSIT", "ADJUSTMENT", "CUSTOM" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int32" }, "includedQuantity": { "type": "integer", "format": "int32", "description": "Frozen operational quantity; compositionEffectiveQuantity for package components." }, "unitPriceInCents": { "type": "integer", "format": "int32" }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "intrinsicSavingsInCents": { "type": "integer", "format": "int32" }, "promotionDiscountInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "totalPriceInCents": { "type": "integer", "format": "int32" } }, "required": [ "category", "name", "description", "quantity", "includedQuantity", "unitPriceInCents", "subtotalInCents", "discountInCents", "intrinsicSavingsInCents", "promotionDiscountInCents", "taxInCents", "totalPriceInCents" ] }, "CustomerAccountCommerceLineGroupDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BUNDLE", "PACKAGE", "KIT", "PROPOSAL_SECTION", "CUSTOM" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "selectedQuantity": { "type": "integer", "format": "int32", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountCommerceLineDto" } } }, "required": [ "kind", "title", "description", "selectedQuantity", "lines" ] }, "CustomerCommerceDetailDto": { "type": "object", "properties": { "displayNumber": { "type": "string", "description": "Public document number (e.g. Q-1042) — the row handle." }, "type": { "type": "string", "enum": [ "QUOTE", "INVOICE" ] }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never an action authority or payment gate." }, "currency": { "type": "string", "description": "ISO-4217 currency code (lowercase)." }, "totalInCents": { "type": "integer", "format": "int32", "description": "Total of the latest customer-visible revision, in minor units." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Business expiry, when set (quotes)." }, "sentAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the latest visible revision was sent." }, "stale": { "type": "boolean", "description": "True while the merchant is revising: the shown revision has been superseded and an updated document will follow." }, "createdAt": { "type": "string", "format": "date-time" }, "subtotalInCents": { "type": "integer", "format": "int32" }, "discountInCents": { "type": "integer", "format": "int32" }, "taxInCents": { "type": "integer", "format": "int32" }, "lines": { "description": "Lines of the latest customer-visible revision.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountCommerceLineDto" } }, "lineGroups": { "description": "Frozen grouped lines, including package headers and all component quantities and money.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountCommerceLineGroupDto" } } }, "required": [ "displayNumber", "type", "commercialStatus", "paymentStatus", "signatureStatus", "currency", "totalInCents", "expiresAt", "sentAt", "stale", "createdAt", "subtotalInCents", "discountInCents", "taxInCents", "lines", "lineGroups" ] }, "RegisterPosSessionDto": { "type": "object", "properties": { "installationId": { "type": "string", "format": "uuid", "description": "Random per-installation identifier. The API stores only its SHA-256 hash." }, "appVersion": { "type": "string", "example": "1.0.0" }, "appBuild": { "type": "string", "example": "42" } }, "required": [ "installationId", "appVersion", "appBuild" ] }, "PosSessionMembershipDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "organizationSlug": { "type": "string" }, "organizationName": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "staff" ] }, "permissionGroups": { "type": "array", "items": { "type": "string" } }, "permissionPresetId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "organizationId", "organizationSlug", "organizationName", "role", "permissionGroups", "permissionPresetId" ] }, "PosSessionResponseDto": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "selectedOrganizationId": { "type": "string", "format": "uuid", "nullable": true }, "selectedOrganizationSlug": { "type": "string", "nullable": true }, "requiresOrganizationSelection": { "type": "boolean" }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/PosSessionMembershipDto" } } }, "required": [ "sessionId", "selectedOrganizationId", "selectedOrganizationSlug", "requiresOrganizationSelection", "memberships" ] }, "SelectPosOrganizationDto": { "type": "object", "properties": { "organizationSlug": { "type": "string", "example": "acme-outfitters" } }, "required": [ "organizationSlug" ] }, "PosSessionRevocationDto": { "type": "object", "properties": { "revoked": { "type": "boolean", "example": true } }, "required": [ "revoked" ] }, "PosCustomerIdentityDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "description": "API displayName is name ?? \"Guest\": only null selects the fallback; empty and whitespace-only names pass through unchanged. For presentation, preserve this value for a nonblank canonical name. Otherwise, REGISTERED rows display \"Unnamed customer\"; GUEST rows keep a nonblank API display value or use \"Unnamed customer\" if it is blank. Use name to identify the fallback so a stored name of \"Guest\" is preserved. This value is not identity or verification proof." }, "name": { "type": "string", "nullable": true, "description": "Canonical Customer name. Null when no canonical name is recorded; displayName then contains the literal Guest fallback. Empty and whitespace-only strings are returned unchanged." }, "normalizedEmail": { "type": "string", "description": "Normalized email and tenant-scoped Customer identity key." }, "phone": { "type": "string", "nullable": true, "description": "Canonical Customer phone number. Null when no canonical phone is recorded. Empty and whitespace-only strings are returned unchanged." }, "accountStatus": { "type": "string", "enum": [ "GUEST", "REGISTERED" ], "description": "Derived from email verification. GUEST means unverified and REGISTERED means verified; neither status guarantees that canonical name or phone is populated." }, "emailVerifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Time the canonical email was verified. Null when accountStatus is GUEST and the email is unverified." }, "isArchived": { "type": "boolean", "description": "Archived Customers are hidden from the default list but remain addressable by exact id." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "displayName", "name", "normalizedEmail", "phone", "accountStatus", "emailVerifiedAt", "isArchived", "createdAt" ] }, "PosCustomerListDto": { "type": "object", "properties": { "data": { "description": "Matching active, non-tombstoned Customer identities for the selected POS-session organization. An empty array means no identities matched the search on this page; with nextCursor null, the result is exhausted.", "type": "array", "items": { "$ref": "#/components/schemas/PosCustomerIdentityDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page. Null means there is no later page and the current result is complete." } }, "required": [ "data", "nextCursor" ] }, "PosCatalogAvailabilityDto": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether this exact item/variant selection is currently sellable." }, "tracked": { "type": "boolean", "description": "Whether inventory is explicitly tracked. Untracked SALE items follow existing order semantics and are treated as unbounded." }, "availableQuantity": { "type": "number", "nullable": true, "description": "Current reservation-aware quantity, or null when inventory is untracked." } }, "required": [ "available", "tracked", "availableQuantity" ] }, "PosCatalogVariantDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string" }, "priceInCents": { "type": "number", "description": "Current server preview price. Sale creation re-resolves and freezes the authoritative price." }, "availability": { "$ref": "#/components/schemas/PosCatalogAvailabilityDto" } }, "required": [ "id", "name", "sku", "priceInCents", "availability" ] }, "PosCatalogItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "shortDescription": { "type": "string" }, "priceInCents": { "type": "number", "description": "Current server preview price. Sale creation re-resolves and freezes the authoritative price." }, "imageUrl": { "type": "string", "nullable": true }, "availability": { "$ref": "#/components/schemas/PosCatalogAvailabilityDto" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PosCatalogVariantDto" } } }, "required": [ "id", "name", "shortDescription", "priceInCents", "imageUrl", "availability", "variants" ] }, "PosCatalogPageDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Tenant currency, normalized to lower-case ISO." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PosCatalogItemDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "currency", "items", "nextCursor" ] }, "PosPreflightResponseDto": { "type": "object", "properties": { "ready": { "type": "boolean", "enum": [ true ] }, "currency": { "type": "string", "description": "Tenant currency, normalized to lower-case ISO." }, "terminalLocationId": { "type": "string", "description": "Server-selected Stripe Terminal Location id." }, "terminalLocationLabel": { "type": "string", "description": "Display label of the selected Terminal Location." }, "cardPaymentsCapability": { "type": "string", "enum": [ "active" ] } }, "required": [ "ready", "currency", "terminalLocationId", "terminalLocationLabel", "cardPaymentsCapability" ] }, "PosSaleLineDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 1, "maximum": 999 } }, "required": [ "itemId", "quantity" ] }, "PosSaleCustomerDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "WALK_IN", "EXISTING_CUSTOMER", "CONTACT" ], "default": "WALK_IN" }, "customerId": { "type": "string", "format": "uuid", "description": "Required only for EXISTING_CUSTOMER mode." }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 80 }, "companyName": { "type": "string", "maxLength": 200 } }, "required": [ "mode" ] }, "CreatePosSaleDto": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PosSaleLineDto" } }, "customer": { "description": "Omit for an explicit WALK_IN sale. Other modes require their matching tenant customer or supplied contact data.", "allOf": [ { "$ref": "#/components/schemas/PosSaleCustomerDto" } ] } }, "required": [ "lines" ] }, "PosSaleFrozenLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "FEE", "DEPOSIT", "ADJUSTMENT", "CUSTOM" ], "description": "Frozen line category. PRODUCT is a sold good; FEE carries non-goods amounts such as the #2537 card-present tip." }, "itemId": { "type": "string", "nullable": true, "format": "uuid" }, "variantId": { "type": "string", "nullable": true, "format": "uuid" }, "sku": { "type": "string", "nullable": true }, "name": { "type": "string" }, "quantity": { "type": "number" }, "unitPriceInCents": { "type": "number" }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" }, "taxExempt": { "type": "boolean", "description": "True when this line is excluded from tax under ADR-012 line-level exemption." } }, "required": [ "id", "category", "itemId", "variantId", "sku", "name", "quantity", "unitPriceInCents", "subtotalInCents", "discountInCents", "taxInCents", "totalInCents", "taxExempt" ] }, "PosSaleResponseDto": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string" }, "invoiceStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ], "description": "Authoritative payment status of the linked issued invoice, including PARTIALLY_REFUNDED / REFUNDED after an Admin refund (ADR-021 #2531 amendment section 8)." }, "customerMode": { "type": "string", "enum": [ "WALK_IN", "EXISTING_CUSTOMER", "CONTACT" ], "description": "Immutable creation provenance (ADR-021 section 6). It records what was true when the sale was created and is never rewritten. It is NOT an answer to \"does this sale have a customer?\" — read customerId for that." }, "customerId": { "type": "string", "nullable": true, "format": "uuid", "description": "Current tenant-scoped customer association on the authoritative order, or null when the sale has none. Separate from customerMode by ADR-021 #2531 amendment section 5: a WALK_IN sale that later gains a customer keeps customerMode=WALK_IN and reports the attachment here." }, "currency": { "type": "string" }, "subtotalInCents": { "type": "number" }, "discountInCents": { "type": "number" }, "taxInCents": { "type": "number" }, "totalInCents": { "type": "number" }, "amountPaidInCents": { "type": "number", "description": "Gross completed payments recorded against the linked invoice (ADR-013 derived rollup). Refunds are reported separately in refundedInCents." }, "refundedInCents": { "type": "number", "description": "Completed refunds recorded against the linked invoice. Admin (#1630/#1634) is the only first-release refund mechanism; POS reflects it and never initiates it." }, "balanceDueInCents": { "type": "number", "description": "Remaining collectible balance from the authoritative invoice rollup, never a POS-local tally." }, "payable": { "type": "boolean", "description": "True only while the linked issued invoice has a positive collectible balance." }, "tender": { "type": "string", "enum": [ "CASH", "CHECK", "BANK_TRANSFER", "STORE_CREDIT", "CARD", "OTHER" ], "nullable": true, "description": "Tender of the settled payment, derived from completed payment transactions on the linked invoice. Null when nothing has settled yet, and null when more than one tender settled the invoice (split tender is D2 #2538 and is not representable here)." }, "lines": { "description": "Frozen lines of the authoritative order, in commit order.", "type": "array", "items": { "$ref": "#/components/schemas/PosSaleFrozenLineDto" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the authoritative order was committed." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the authoritative order last changed." }, "invoiceIssuedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the linked invoice was issued (ADR-021 section 5 freezes it at creation)." }, "settledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Occurrence time of the most recent completed payment on the linked invoice, or null when nothing has settled." }, "pricingSnapshotVersion": { "type": "string" }, "pricingSnapshotHash": { "type": "string", "description": "SHA-256 of the immutable ADR-012 snapshot." } }, "required": [ "orderId", "orderNumber", "orderStatus", "invoiceId", "invoiceNumber", "invoiceStatus", "paymentStatus", "customerMode", "customerId", "currency", "subtotalInCents", "discountInCents", "taxInCents", "totalInCents", "amountPaidInCents", "refundedInCents", "balanceDueInCents", "payable", "tender", "lines", "createdAt", "updatedAt", "invoiceIssuedAt", "settledAt", "pricingSnapshotVersion", "pricingSnapshotHash" ] }, "PosSaleListDto": { "type": "object", "properties": { "sales": { "description": "Order-anchored POS sales, newest first. Each entry preserves its order and invoice as distinct records (ADR-021 section 10).", "type": "array", "items": { "$ref": "#/components/schemas/PosSaleResponseDto" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "sales", "nextCursor" ] }, "PosTerminalConnectionTokenDto": { "type": "object", "properties": { "secret": { "type": "string", "description": "Short-lived Stripe Terminal connection token secret for the native SDK." }, "stripeAccountId": { "type": "string", "description": "Tenant connected Stripe account the token is scoped to." }, "terminalLocationId": { "type": "string", "description": "Server-selected Stripe Terminal Location for Tap to Pay reader connection." }, "terminalLocationLabel": { "type": "string", "description": "Display label for the selected Terminal Location." }, "orderId": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" } }, "required": [ "secret", "stripeAccountId", "terminalLocationId", "terminalLocationLabel", "orderId", "invoiceId" ] }, "PosTerminalPaymentIntentDto": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "PaymentIntent client secret for Stripe Terminal collect and process calls." }, "paymentIntentId": { "type": "string", "description": "Stripe PaymentIntent created on the tenant connected account." }, "paymentAttemptId": { "type": "string", "description": "Internal PaymentAttempt used by webhook reconciliation." }, "stripeAccountId": { "type": "string", "description": "Tenant connected Stripe account the PaymentIntent lives on." }, "amountInCents": { "type": "integer", "format": "int32", "description": "Server-authoritative invoice balance being collected, in cents." }, "currency": { "type": "string", "description": "ISO-4217 currency code in lowercase." }, "terminalLocationId": { "type": "string", "description": "Server-selected Stripe Terminal Location for Tap to Pay reader connection." }, "terminalLocationLabel": { "type": "string", "description": "Display label for the selected Terminal Location." }, "orderId": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" } }, "required": [ "clientSecret", "paymentIntentId", "paymentAttemptId", "stripeAccountId", "amountInCents", "currency", "terminalLocationId", "terminalLocationLabel", "orderId", "invoiceId" ] }, "BoundedDomainCountDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "`available` — computed and visible. `restricted` — the caller lacks the owning-domain read; says NOTHING about whether data exists. `unavailable` — this build does not implement the feature. Charter §8: restricted or omitted information must not render as \"no history\"." }, "count": { "type": "number", "nullable": true, "description": "The count, ONLY when `status` is `available`; otherwise `null` — never `0`. A hidden count is not zero." }, "atLeast": { "type": "boolean", "description": "True when the bounded count hit its cap, meaning \"at least `count`\" rather than exactly. Charter §3 asks for bounded counts; an unbounded COUNT(*) over a large tenant is what that rules out." } }, "required": [ "status", "count", "atLeast" ] }, "CustomerCommerceTypeCountsDto": { "type": "object", "properties": { "quote": { "description": "Non-draft QUOTE records in the aggregate commerce population.", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] }, "invoice": { "description": "Non-draft INVOICE records, including subscription-raised invoices.", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] }, "order": { "description": "Non-draft ORDER records, including subscription-raised orders. This is not limited to accepted orders; use acceptedOrderHistory for acceptance presence.", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] } }, "required": [ "quote", "invoice", "order" ] }, "CustomerDomainCountsDto": { "type": "object", "properties": { "commerce": { "description": "Canonical commerce records (quotes, invoices, orders).", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] }, "commerceByType": { "description": "Composition of the same tenant-qualified, customer-linked non-draft commerce population as commerce. Subscription-raised records remain in their record kind. Each kind independently probes up to 101 records: 0–100 is exact; more than 100 returns count 100 with atLeast true. The aggregate retains its own independent cap, so capped values need not sum to it. Each kind preserves typed availability: restricted or unavailable counts are null, never zero; available zero means no matching records of that kind.", "allOf": [ { "$ref": "#/components/schemas/CustomerCommerceTypeCountsDto" } ] }, "booking": { "description": "Booking-domain records across BOTH tenant-qualified sources — bookings and booking groups — matching what the activity aggregate and the domain-presence facet consider authoritative. Counting only `bookings` let a group-only customer read `count: 0` in the same response that reported booking-derived activity.", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] }, "subscription": { "$ref": "#/components/schemas/BoundedDomainCountDto" }, "operationalTag": { "description": "Operational tags (charter §7). Always `unavailable` in this slice — the tag model does not exist and §7 is gated on the surviving E21 policy. Reported as an omitted feature rather than an empty set, so a consumer cannot read \"not built\" as \"this customer has no tags\".", "allOf": [ { "$ref": "#/components/schemas/BoundedDomainCountDto" } ] } }, "required": [ "commerce", "commerceByType", "booking", "subscription", "operationalTag" ] }, "CustomerAcceptedOrderHistoryDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "`available` — accepted-order presence was checked through this exact tenant Customer link. `restricted` — the caller lacks the commerce-domain read, so `hasAcceptedOrders` is `null` and says NOTHING about whether orders exist. `unavailable` — the response could not establish the state. Only `available` plus `false` authorizes the Admin copy “No accepted orders yet.”" }, "hasAcceptedOrders": { "type": "boolean", "nullable": true, "description": "`true` when at least one ORDER linked through this exact tenant Customer has authoritative acceptance history; `false` only when the authorized bounded existence check found none; otherwise `null`. This is not a payment result: `false` must never render as payment failed or payment not completed, and it does not alter spend, LTV, AOV, conversion, purchaser, verified-account, or marketing meaning." } }, "required": [ "status", "hasAcceptedOrders" ] }, "CustomerDirectoryEntryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "description": "API `displayName` is `name ?? \"Guest\"`: only `null` selects the fallback; empty and whitespace-only names pass through unchanged (`DR-3032-24-A`). For presentation, preserve the API value for a nonblank canonical name, regardless of account status. Otherwise, `REGISTERED` rows display `Unnamed customer`; `GUEST` rows keep a nonblank API display value or use `Unnamed customer` if it is blank. Use `name` to identify the fallback; a stored name of `Guest` is preserved. This display value is not identity or verification proof." }, "name": { "type": "string", "nullable": true, "description": "The canonical `Customer.name`, or `null` when no canonical name is stored. Empty and whitespace-only strings are returned unchanged. An unverified Customer may have a canonical name, including a value retained from historical data. E26 charter §4 permits authorized merchant stewardship; that write surface is not yet implemented. Account status does not imply absence. Unverified checkout input never populates this field; order-derived names remain on immutable snapshots and appear as identity variants on the detail surface." }, "normalizedEmail": { "type": "string", "description": "Normalized (case-folded) email — the tenant identity key." }, "phone": { "type": "string", "nullable": true, "description": "Canonical phone, or `null` when no canonical phone is stored. Empty and whitespace-only strings are returned unchanged. An unverified Customer may have a canonical phone, including a value retained from historical data. E26 charter §4 permits authorized merchant stewardship; that write surface is not yet implemented. Account status does not imply absence. Unverified checkout input never populates this field; order-derived phones remain identity variants on detail." }, "accountStatus": { "type": "string", "enum": [ "GUEST", "REGISTERED" ], "description": "`DR-3032-20-A` account-status facet. Derived from verification: under `DR-3032-22-A` registering stamps the same row verified in place. `GUEST` means unverified, not that canonical name/phone are absent; `REGISTERED` does not guarantee those fields are populated." }, "emailVerifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the customer proved control of this email, or `null` if never. An Order association is NOT verification (charter §1) — a customer can have many orders and a null value here." }, "isArchived": { "type": "boolean", "description": "Archive posture. Archived customers are hidden from the default list yet remain addressable by id. Archive does not change authentication, purchase eligibility, retention, or data rights (charter §6)." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "lastAuthoritativeActivityAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last AUTHORITATIVE relationship activity, or `null` when there is none to report. Authority is charter §8: a tenant-qualified link only. `null` means \"no authoritative activity is linked to this customer\" — it does NOT mean the person never transacted. Orders accepted before #3233 carry no customer link and are not backfilled (`DR-3032-21-A`), so a long-standing customer can legitimately read `null` here." }, "lastAuthoritativeActivityStatus": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "Whether the activity above was computed from EVERY authoritative source. `restricted` means at least one owning domain was withheld from this caller, so a `null` above does NOT mean inactive and a non-null value is a LOWER BOUND — read the two fields together, never the timestamp alone. Charter §8: restricted information must not render as \"no history\". The same reason every count carries a status." }, "domainCounts": { "$ref": "#/components/schemas/CustomerDomainCountsDto" }, "acceptedOrderHistory": { "description": "ADR-047 zero-order directory truth, kept separate from generalized commerce counts and every payment or customer-value metric.", "allOf": [ { "$ref": "#/components/schemas/CustomerAcceptedOrderHistoryDto" } ] } }, "required": [ "id", "displayName", "name", "normalizedEmail", "phone", "accountStatus", "emailVerifiedAt", "isArchived", "archivedAt", "createdAt", "lastAuthoritativeActivityAt", "lastAuthoritativeActivityStatus", "domainCounts", "acceptedOrderHistory" ] }, "CustomerDirectoryListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDirectoryEntryDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor — pass back as `?cursor=` for the next page. `null` when there are no more customers. Bound to the sort it was issued for." }, "capabilities": { "type": "array", "description": "The capabilities this caller holds on this surface, so a client can distinguish \"restricted\" from \"absent\" without probing endpoints and reading the failures — which is itself the permission side channel charter §8 forbids.", "items": { "type": "string", "enum": [ "customer.directory.read", "customer.detail.read", "customer.domain.commerce.read", "customer.domain.booking.read", "customer.domain.subscription.read", "customer.tag.read" ] } }, "sort": { "type": "string", "enum": [ "CREATED", "NAME", "LAST_ACTIVITY" ], "description": "The sort actually applied, echoed so a client never guesses." } }, "required": [ "data", "nextCursor", "capabilities", "sort" ] }, "CustomerPaymentReconciliationTotalDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Lowercase ISO currency code. Each currency is reported separately; consumers must never add unlike currencies into one customer total." }, "grossPaidInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Gross collected cents: the sum of COMPLETED PAYMENT rows in the litecommerce commerce payment ledger for tenant-qualified records linked to this Customer. This is not order value, net sales, LTV, or a Stripe Dashboard Customer Insights value." }, "refundedInCents": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "description": "Effective returned cents: COMPLETED REFUND rows minus their completed append-only REFUND_REVERSAL corrections for the same linked record set." } }, "required": [ "currency", "grossPaidInCents", "refundedInCents" ] }, "CustomerPaymentReconciliationDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "`available` — the linked litecommerce payment ledger was aggregated for this caller. `restricted` — the caller lacks the commerce-domain read, so `totals` is empty and says NOTHING about whether payment history exists. `unavailable` is reserved for a build that cannot provide this boundary." }, "source": { "type": "string", "enum": [ "LITECOMMERCE_PAYMENT_LEDGER" ], "description": "The authoritative source for these merchant operational totals. The value means completed rows in the litecommerce commerce payment ledger, reached only through tenant-qualified `CommerceRecord.customerId` links; record rollups, email equality, and provider dashboard analytics are not summed independently." }, "coverage": { "type": "string", "enum": [ "LINKED_COMMERCE_RECORDS" ], "description": "The identity boundary for the aggregate. Only commerce records carrying this exact tenant-scoped `Customer.id` contribute; matching email text does not. Older records intentionally left unlinked by the no-backfill decision are therefore outside coverage." }, "providerCustomerInsightsPosture": { "type": "string", "enum": [ "NOT_AUTHORITATIVE" ], "description": "Stripe Customer Insights is a provider-derived Dashboard summary, not the reconciliation authority for this flow. In particular, a Customer attached after PaymentIntent success can show a Dashboard `Spent` value that does not equal the one successful charge. Compare money against `totals`, never against that insight." }, "totals": { "description": "Complete per-currency aggregation over completed ledger movements linked to this Customer. When `status` is `available`, empty means no such linked ledger movement exists. It does not prove the person never paid: pre-#3233 orders are intentionally not backfilled and email equality is never relationship authority. When `status` is not `available`, empty has no data meaning.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerPaymentReconciliationTotalDto" } } }, "required": [ "status", "source", "coverage", "providerCustomerInsightsPosture", "totals" ] }, "CustomerIdentityVariantDto": { "type": "object", "properties": { "sourceReference": { "type": "string", "description": "The record this identity was captured on. Reference only — the detail surface does not reproduce owning-domain ledgers or mutations (§8)." }, "capturedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true, "description": "Single-line rendering of a captured address on the source record, or `null` when neither address slot produced a renderable value. `null` can mean the snapshot was absent or empty, or that legacy data was present in an unrecognised shape; it does not prove the record carried no address. A rendering, not a parseable address object: this surface exists so an operator can recognise a variant, not so a client can re-address anything from it." }, "addressUsages": { "type": "array", "maxItems": 2, "uniqueItems": true, "description": "How this rendered address was used on this source record. Distinct shipping and billing values each carry one usage; one equal rendered value carries both. Every variant keeps its source record's exact usages; usages from different records are never merged into a fabricated combined variant. The same rendered address can therefore appear in multiple record-local variants when each adds role coverage, so consumers must not deduplicate by address alone. Empty exactly when `address` is `null`. A usage is omitted when that snapshot slot was absent or empty, or could not be rendered from a legacy shape; omission does not prove the source record lacked that address. This does not preserve whether an equal billing address was copied or entered independently.", "items": { "type": "string", "enum": [ "SHIPPING", "BILLING" ] } } }, "required": [ "sourceReference", "capturedAt", "name", "phone", "address", "addressUsages" ] }, "CustomerDirectoryDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "description": "API `displayName` is `name ?? \"Guest\"`: only `null` selects the fallback; empty and whitespace-only names pass through unchanged (`DR-3032-24-A`). For presentation, preserve the API value for a nonblank canonical name, regardless of account status. Otherwise, `REGISTERED` rows display `Unnamed customer`; `GUEST` rows keep a nonblank API display value or use `Unnamed customer` if it is blank. Use `name` to identify the fallback; a stored name of `Guest` is preserved. This display value is not identity or verification proof." }, "name": { "type": "string", "nullable": true, "description": "The canonical `Customer.name`, or `null` when no canonical name is stored. Empty and whitespace-only strings are returned unchanged. An unverified Customer may have a canonical name, including a value retained from historical data. E26 charter §4 permits authorized merchant stewardship; that write surface is not yet implemented. Account status does not imply absence. Unverified checkout input never populates this field; order-derived names remain on immutable snapshots and appear as identity variants on the detail surface." }, "normalizedEmail": { "type": "string", "description": "Normalized (case-folded) email — the tenant identity key." }, "phone": { "type": "string", "nullable": true, "description": "Canonical phone, or `null` when no canonical phone is stored. Empty and whitespace-only strings are returned unchanged. An unverified Customer may have a canonical phone, including a value retained from historical data. E26 charter §4 permits authorized merchant stewardship; that write surface is not yet implemented. Account status does not imply absence. Unverified checkout input never populates this field; order-derived phones remain identity variants on detail." }, "accountStatus": { "type": "string", "enum": [ "GUEST", "REGISTERED" ], "description": "`DR-3032-20-A` account-status facet. Derived from verification: under `DR-3032-22-A` registering stamps the same row verified in place. `GUEST` means unverified, not that canonical name/phone are absent; `REGISTERED` does not guarantee those fields are populated." }, "emailVerifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the customer proved control of this email, or `null` if never. An Order association is NOT verification (charter §1) — a customer can have many orders and a null value here." }, "isArchived": { "type": "boolean", "description": "Archive posture. Archived customers are hidden from the default list yet remain addressable by id. Archive does not change authentication, purchase eligibility, retention, or data rights (charter §6)." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "lastAuthoritativeActivityAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last AUTHORITATIVE relationship activity, or `null` when there is none to report. Authority is charter §8: a tenant-qualified link only. `null` means \"no authoritative activity is linked to this customer\" — it does NOT mean the person never transacted. Orders accepted before #3233 carry no customer link and are not backfilled (`DR-3032-21-A`), so a long-standing customer can legitimately read `null` here." }, "lastAuthoritativeActivityStatus": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "Whether the activity above was computed from EVERY authoritative source. `restricted` means at least one owning domain was withheld from this caller, so a `null` above does NOT mean inactive and a non-null value is a LOWER BOUND — read the two fields together, never the timestamp alone. Charter §8: restricted information must not render as \"no history\". The same reason every count carries a status." }, "domainCounts": { "$ref": "#/components/schemas/CustomerDomainCountsDto" }, "acceptedOrderHistory": { "description": "ADR-047 zero-order directory truth, kept separate from generalized commerce counts and every payment or customer-value metric.", "allOf": [ { "$ref": "#/components/schemas/CustomerAcceptedOrderHistoryDto" } ] }, "paymentReconciliation": { "description": "#3519 merchant payment truth for this Customer, explicitly separated from provider Customer Insights and grouped by currency.", "allOf": [ { "$ref": "#/components/schemas/CustomerPaymentReconciliationDto" } ] }, "identityVariants": { "description": "Every distinct order-derived identity for this customer, newest first (`DR-3032-24-A`). Legitimately EMPTY for a customer whose orders all predate #3233, because no backfill links them (`DR-3032-21-A`) — empty here means \"no linked snapshot carries an identity\", not \"this person never ordered\".", "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentityVariantDto" } }, "identityVariantsStatus": { "type": "string", "enum": [ "available", "restricted", "unavailable" ], "description": "Whether `identityVariants` was computed for this caller. When not `available` the array is empty AND this field says why — the two are read together, never the array alone." }, "identityVariantsCompleteness": { "type": "string", "enum": [ "complete", "truncated", "indeterminate" ], "description": "Whether `identityVariants` is the WHOLE set. `identityVariantsStatus` reports whether the set could be computed at all; this reports whether what was computed is everything. Both are needed — without this a capped set would report `available` and read as exhaustive, the partial-answer-indistinguishable-from-complete failure charter §8 forbids. `complete` — the source was exhausted. `truncated` — more variants were built than are returned, so more definitely exist. `indeterminate` — the bounded scan ended first, so whether more exist was never established. `indeterminate` is deliberately NOT merged into `truncated`: asserting that more exist without having looked is the same overclaim in the other direction." } }, "required": [ "id", "displayName", "name", "normalizedEmail", "phone", "accountStatus", "emailVerifiedAt", "isArchived", "archivedAt", "createdAt", "lastAuthoritativeActivityAt", "lastAuthoritativeActivityStatus", "domainCounts", "acceptedOrderHistory", "paymentReconciliation", "identityVariants", "identityVariantsStatus", "identityVariantsCompleteness" ] }, "SubmitReviewDto": { "type": "object", "properties": { "rating": { "type": "number", "description": "Star rating, 1–5 inclusive.", "minimum": 1, "maximum": 5, "example": 5 }, "title": { "type": "string", "description": "Optional short review headline.", "nullable": true, "maxLength": 120 }, "body": { "type": "string", "description": "Optional free-form review body.", "nullable": true, "maxLength": 4000 }, "authorName": { "type": "string", "description": "Display name shown on the storefront next to the review.", "example": "Jordan P.", "maxLength": 80 }, "authorEmail": { "type": "string", "description": "Author email. Normalised lowercase before insert. Used for dedupe and the verified-purchase match ONLY — never returned to public callers.", "example": "customer@example.com", "maxLength": 320 } }, "required": [ "rating", "authorName", "authorEmail" ], "additionalProperties": false }, "SubmitReviewResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always `true` on a 201 — the review was accepted for moderation.", "example": true } }, "required": [ "ok" ] }, "PublicProductReviewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rating": { "type": "number", "description": "Star rating, 1–5.", "minimum": 1, "maximum": 5, "example": 5 }, "title": { "type": "string", "nullable": true, "description": "Optional review headline. `null` when the author left none." }, "body": { "type": "string", "nullable": true, "description": "Optional review body. `null` when the author left none." }, "authorName": { "type": "string", "description": "Author display name only — never the author email.", "example": "Jordan P." }, "verifiedPurchase": { "type": "boolean", "description": "True when the review email matched a paid order for this item. A badge only — it never gated submission.", "example": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "rating", "title", "body", "authorName", "verifiedPurchase", "createdAt" ] }, "PublicItemReviewsResponseDto": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProductReviewDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; pass it back as `?cursor=`. `null` when there are no more reviews." }, "ratingAverage": { "type": "number", "nullable": true, "description": "Mean rating across PUBLISHED reviews. `null` when there are none (distinguishes \"unrated\" from a literal 0).", "example": 4.6 }, "ratingCount": { "type": "number", "description": "Number of PUBLISHED reviews for the item.", "example": 23 } }, "required": [ "reviews", "nextCursor", "ratingAverage", "ratingCount" ] }, "MerchantReviewItemRefDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "MerchantReviewModerationItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "rating": { "type": "number", "minimum": 1, "maximum": 5, "description": "1–5 star rating." }, "title": { "type": "string", "nullable": true, "description": "Optional review headline; `null` for a bare star rating." }, "body": { "type": "string", "nullable": true, "description": "Optional review prose; `null` for a bare star rating." }, "authorName": { "type": "string", "description": "Public display name shown next to the review." }, "authorEmail": { "type": "string", "description": "Reviewer email. PRIVATE — exposed on the merchant moderation surface (moderators need it to judge a review) but never on the public read." }, "status": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED" ], "description": "Moderation status: PENDING / PUBLISHED / REJECTED." }, "visibility": { "type": "string", "enum": [ "VISIBLE", "HIDDEN" ], "description": "Storefront visibility of a PUBLISHED review: VISIBLE / HIDDEN (hide/show toggle this without changing `status`)." }, "verifiedPurchase": { "type": "boolean", "description": "True when the author email matched a paid/fulfilled order for this item at submit time. A badge only." }, "moderatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Moderation decision timestamp; `null` while PENDING." }, "moderatedByUserId": { "type": "string", "format": "uuid", "nullable": true, "description": "Id of the moderating user; `null` while PENDING." }, "createdAt": { "format": "date-time", "type": "string" }, "item": { "$ref": "#/components/schemas/MerchantReviewItemRefDto" } }, "required": [ "id", "organizationId", "itemId", "rating", "title", "body", "authorName", "authorEmail", "status", "visibility", "verifiedPurchase", "moderatedAt", "moderatedByUserId", "createdAt", "item" ] }, "MerchantProductReviewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "rating": { "type": "number", "minimum": 1, "maximum": 5, "description": "1–5 star rating." }, "title": { "type": "string", "nullable": true, "description": "Optional review headline; `null` for a bare star rating." }, "body": { "type": "string", "nullable": true, "description": "Optional review prose; `null` for a bare star rating." }, "authorName": { "type": "string", "description": "Public display name shown next to the review." }, "authorEmail": { "type": "string", "description": "Reviewer email. PRIVATE — exposed on the merchant moderation surface (moderators need it to judge a review) but never on the public read." }, "status": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED" ], "description": "Moderation status: PENDING / PUBLISHED / REJECTED." }, "visibility": { "type": "string", "enum": [ "VISIBLE", "HIDDEN" ], "description": "Storefront visibility of a PUBLISHED review: VISIBLE / HIDDEN (hide/show toggle this without changing `status`)." }, "verifiedPurchase": { "type": "boolean", "description": "True when the author email matched a paid/fulfilled order for this item at submit time. A badge only." }, "moderatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Moderation decision timestamp; `null` while PENDING." }, "moderatedByUserId": { "type": "string", "format": "uuid", "nullable": true, "description": "Id of the moderating user; `null` while PENDING." }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "itemId", "rating", "title", "body", "authorName", "authorEmail", "status", "visibility", "verifiedPurchase", "moderatedAt", "moderatedByUserId", "createdAt" ] }, "CustomerOrderItemDto": { "type": "object", "properties": { "orderItemId": { "type": "string", "description": "Order-item handle used when starting a return. Scoped to this order/customer surface." }, "name": { "type": "string", "example": "Trail Tent 2P" }, "productName": { "type": "string", "nullable": true, "example": "Deodorant", "description": "#3972 (UAT F08) — the PRODUCT half of `name`, or `null` when the frozen line name was not segmented. `name` remains the authoritative frozen purchase identity and is unchanged; this field and `variantName` are an additive, lossless view of it — they are non-null TOGETHER or not at all, and when present `productName + \" — \" + variantName` reconstructs `name` exactly. So a non-null value here is always a real product half, never a whole combined name. `null` means render `name` as a single line: a line whose `name` was NOT written by a shared-pricing writer (the legacy public quote route stores a caller-supplied label, which proves nothing about product/variant structure), an item-level line with no variant, a product OR variant renamed or deleted since purchase, or a catalog name that itself contains the \" — \" separator. The server never splits on a hyphen and never parses the stored value: it requires a proven pricing origin, then segments only when BOTH current catalog names are separator-free AND rebuild the stored string exactly, which makes the decomposition unique and therefore the historical one. No frozen product/variant halves are persisted, so any line outside that provable shape reports null rather than a guessed boundary." }, "variantName": { "type": "string", "nullable": true, "example": "Unscented", "description": "#3972 (UAT F08) — the VARIANT half of `name`, exactly as the catalog stores it (never trimmed, so the two halves rejoin losslessly). `null` whenever `productName` is `null`; the two are always resolved together." }, "imageUrl": { "type": "string", "nullable": true, "example": "https://cdn.example.com/items/trail-tent.jpg", "description": "Catalog thumbnail URL snapshotted on the order line at confirmation (#982). `null` when the item had no image — render a placeholder." }, "quantity": { "type": "number", "example": 2 }, "unitPriceInCents": { "type": "number", "description": "Per-unit price in minor units (cents).", "example": 12999 }, "totalPriceInCents": { "type": "number", "description": "Line total in minor units (cents).", "example": 25998 }, "isPackageComponent": { "type": "boolean" }, "returnEligibleQuantity": { "type": "integer", "minimum": 0, "nullable": true, "description": "Units of this line that could still be claimed on a new return when this page was read (#3973 F17): handed-off quantity minus the quantity already claimed by active returns. `0` means the line is exhausted or was never handed off; `null` means eligibility could not be established from the fulfillment ledger and this value must not be used to gate anything. A snapshot, never an authorization: the create endpoint re-evaluates the same rule under a row lock and remains the only authority, so a concurrent or stale client is still rejected." } }, "required": [ "orderItemId", "name", "productName", "variantName", "imageUrl", "quantity", "unitPriceInCents", "totalPriceInCents", "isPackageComponent", "returnEligibleQuantity" ] }, "CustomerOrderTimeContactDto": { "type": "object", "properties": { "recipientName": { "type": "string", "nullable": true, "description": "Delivery recipient captured when the order was placed. The current Order contract freezes the same checkout name for recipient and contact roles; it is never read from the current profile or saved addresses. `null` when a legacy order has no non-blank captured name.", "example": "Alice Buyer" }, "contactName": { "type": "string", "nullable": true, "description": "Checkout contact name captured when the order was placed. `null` when a legacy order has no non-blank captured name. Never replaced by the current customer profile or saved-address recipient.", "example": "Alice Buyer" }, "contactEmail": { "type": "string", "format": "email", "nullable": true, "description": "Contact email captured when the order was placed. `null` when a legacy order has no non-blank captured email. Never replaced by the current customer profile email.", "example": "alice@example.com" }, "phone": { "type": "string", "nullable": true, "description": "Delivery/contact phone captured when the order was placed. `null` when no phone was recorded. Never derived from the current customer profile or saved addresses.", "example": "+1 555 010 1234" } }, "required": [ "recipientName", "contactName", "contactEmail", "phone" ] }, "CustomerOrderByReferenceDto": { "type": "object", "properties": { "orderNumber": { "type": "string", "description": "Human-readable public order number. Authenticated order-number routes remain supported alongside the stable order reference.", "example": "LC-100423" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "description": "Order lifecycle status.", "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "description": "Fulfillment status.", "example": "UNFULFILLED" }, "subtotalInCents": { "type": "number", "description": "Subtotal in minor units (cents).", "example": 25998 }, "discountInCents": { "type": "number", "description": "Discount applied in minor units (cents).", "example": 0 }, "taxInCents": { "type": "number", "description": "Tax in minor units (cents).", "example": 1560 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "number", "description": "Grand total in minor units (cents).", "example": 27558 }, "createdAt": { "type": "string", "description": "When the order was placed (ISO 8601).", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderItemDto" } }, "paymentDisplay": { "nullable": true, "description": "Immutable display-safe facts from the exact successful card Charge. `null` for free orders, paid orders predating snapshot capture, or while a paid order's exact provider display evidence is temporarily unavailable and bounded repair remains pending. It does not mean the order is unpaid. Available only on authenticated detail reads.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderPaymentDisplayDto" } ] }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "shippingInCents": { "type": "number", "description": "Shipping charged on the order in minor units (#854) — `0` when none applied. Already included in `totalInCents`; surfaced so the detail view can itemize the shipping line.", "example": 0 }, "shippingMethod": { "nullable": true, "description": "The immutable exact selection or delivery promise captured on `Order.shippingMethod` at confirmation (#1769/#2415). For orders confirmed before that snapshot was introduced, the original frozen checkout selection is returned when the Order snapshot is absent. `null` when the authoritative source has no valid recorded snapshot; original-quote and actual-shipment facts are never substituted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderShippingMethodDto" } ] }, "shipments": { "description": "#1562 — customer-safe handed-off and delivered shipment history. PLANNED and READY preparation is excluded; tracking fields may be null when the carrier supplied no tracking. Carries no raw order or fulfillment ids.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "orderTimeContact": { "description": "Immutable order-time recipient/contact facts. The object is always present; nullable members preserve missing legacy values honestly. Available only after authenticated tenant/customer ownership checks.", "allOf": [ { "$ref": "#/components/schemas/CustomerOrderTimeContactDto" } ] }, "shipmentDeliveryComplete": { "type": "boolean", "description": "True only when at least one non-cancelled fulfillment exists and every non-cancelled fulfillment is DELIVERED. This server-derived flag includes PLANNED and READY fulfillments intentionally omitted from `shipments`; an empty or all-delivered visible array alone cannot establish completion." }, "shippingAddress": { "description": "Shipping address captured at checkout (JSON snapshot), or null.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "description": "Billing address captured at checkout (JSON snapshot), or null.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "orderReference": { "type": "string", "nullable": false, "description": "The exact active Order reference resolved for this owned-order read.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" } }, "required": [ "orderNumber", "status", "fulfillmentStatus", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "totalInCents", "createdAt", "items", "paymentDisplay", "packages", "shippingInCents", "shippingMethod", "shipments", "orderTimeContact", "shipmentDeliveryComplete", "shippingAddress", "billingAddress", "orderReference" ] }, "CustomerReturnItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return-item id." }, "orderItemId": { "type": "string", "description": "Order-item handle this return line came from." }, "name": { "type": "string", "example": "Trail Tent 2P" }, "quantity": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "PENDING", "RESELLABLE", "DAMAGED", "WRITE_OFF" ], "example": "PENDING" } }, "required": [ "id", "orderItemId", "name", "quantity", "condition" ] }, "CustomerReturnByReferenceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return id." }, "orderNumber": { "type": "string", "example": "LC-100423" }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "refundAmountInCents": { "type": "integer", "minimum": 0, "description": "Refund to the customer for this return, in cents. 0 until the merchant sets an amount.", "example": 0 }, "refundState": { "type": "string", "enum": [ "NOT_APPLICABLE", "PROCESSING", "ISSUED", "REIMBURSEMENT_PENDING", "RECONCILIATION_REQUIRED", "REIMBURSEMENT_RECORDED", "RESOLVED" ], "description": "Customer-safe money state of the refund (#3964). Same derivation as the public return surface: ISSUED means the original-method refund completed; REIMBURSEMENT_PENDING means it was later reversed and the merchant still owes an alternative reimbursement; REIMBURSEMENT_RECORDED and RESOLVED mean that reimbursement is recorded." }, "amountOwedInCents": { "type": "integer", "minimum": 0, "nullable": true, "description": "Amount still owed after a provider reversed an earlier successful refund; null when no such correction exists." }, "refundCurrency": { "type": "string", "nullable": true, "example": "usd", "description": "Lowercase ISO 4217 code the refund amounts are denominated in, taken from the persisted refund records (the refund exception, else the order's payment) rather than the organization's current setting (#3964). Null when the order has no recorded payment currency. #4007 tightened that null: it means the historical denomination is unrecoverable, NOT that the client may substitute the currency it is already displaying. A client receiving null must present the refund without denominating it. Derived by the same shared precedence as the email-gated public return surface, so the two cannot disagree." }, "requestedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnItemResponseDto" } }, "orderReference": { "type": "string", "nullable": false, "description": "The exact active reference used to address this return's parent Order.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" } }, "required": [ "id", "orderNumber", "status", "reason", "refundAmountInCents", "refundState", "amountOwedInCents", "refundCurrency", "requestedAt", "updatedAt", "items", "orderReference" ] }, "CustomerReturnListByReferenceResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnByReferenceResponseDto" } } }, "required": [ "data" ] }, "CreateReturnByReferenceDto": { "type": "object", "properties": { "customerName": { "type": "string", "description": "Optional display name for the requester.", "maxLength": 200 }, "reason": { "type": "string", "description": "Free-text reason for the return.", "maxLength": 4000 }, "items": { "description": "Lines being returned. 1-50 entries; cumulative quantity across non-cancelled returns may not exceed the original order line.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/CreateReturnItemDto" } } }, "required": [ "items" ], "additionalProperties": false }, "OrderReferenceReturnDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return id." }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "refundAmountInCents": { "type": "number", "description": "Refund to the customer for this return, in cents. 0 until the merchant sets an amount.", "example": 0 }, "refundState": { "type": "string", "enum": [ "NOT_APPLICABLE", "PROCESSING", "ISSUED", "REIMBURSEMENT_PENDING", "RECONCILIATION_REQUIRED", "REIMBURSEMENT_RECORDED", "RESOLVED" ] }, "amountOwedInCents": { "type": "integer", "minimum": 0, "nullable": true, "description": "Amount still owed after a provider reversed an earlier successful refund; null when no such correction exists." }, "refundCurrency": { "type": "string", "nullable": true, "example": "usd", "description": "Lowercase ISO 4217 code that BOTH `refundAmountInCents` and `amountOwedInCents` are denominated in (#4007). Read from immutable history — the refund exception when one exists, else the persisted currency of the exact successful payment attempt that created the parent order — never from the organization's current currency setting, which can change after checkout. `null` means the historical denomination is genuinely unrecoverable for this return; it is NOT a licence to substitute a default. A client that receives `null` must not render these amounts under any assumed currency." }, "requestedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicReturnItemResponseDto" } }, "orderReference": { "type": "string", "nullable": false, "description": "The exact active reference used to address this return's parent Order.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" } }, "required": [ "id", "status", "reason", "refundAmountInCents", "refundState", "amountOwedInCents", "refundCurrency", "requestedAt", "updatedAt", "items", "orderReference" ] }, "CustomerReturnLineRequestDto": { "type": "object", "properties": { "orderItemId": { "type": "string", "description": "Order-item handle from the customer order detail response." }, "quantity": { "type": "number", "minimum": 1, "description": "Quantity to return." } }, "required": [ "orderItemId", "quantity" ] }, "IssueReturnActionDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional free-text return reason.", "maxLength": 4000 }, "items": { "description": "Lines to return. Duplicate orderItemId entries are aggregated before validation.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnLineRequestDto" } } }, "required": [ "items" ] }, "CustomerReturnLinePreviewDto": { "type": "object", "properties": { "orderItemId": { "type": "string", "description": "Order-item handle from the customer order detail response." }, "name": { "type": "string", "example": "Trail Tent 2P" }, "quantity": { "type": "number", "example": 1 } }, "required": [ "orderItemId", "name", "quantity" ] }, "CustomerActionOrderByReferenceDto": { "type": "object", "properties": { "orderNumber": { "type": "string", "example": "LC-100423" }, "createdAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "orderReference": { "type": "string", "nullable": false, "description": "The exact active reference used to address this Order.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" } }, "required": [ "orderNumber", "createdAt", "orderReference" ] }, "CustomerReturnActionByReferencePreviewDto": { "type": "object", "properties": { "action": { "type": "string", "example": "order.return" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnLinePreviewDto" } }, "order": { "$ref": "#/components/schemas/CustomerActionOrderByReferenceDto" } }, "required": [ "action", "reason", "items", "order" ] }, "IssueReturnActionByReferenceResponseDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Raw customer action token. Returned once; use it at /customer/actions/:token.", "example": "a1234567890abcdefghijklmnop" }, "expiresAt": { "type": "string", "example": "2026-06-12T14:36:18.000Z" }, "preview": { "$ref": "#/components/schemas/CustomerReturnActionByReferencePreviewDto" } }, "required": [ "token", "expiresAt", "preview" ] }, "CustomerProfileResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The authenticated customer id." }, "email": { "type": "string", "description": "Normalized (lower-cased) email — the identity key. Read-only.", "example": "alice@example.com" }, "name": { "type": "string", "description": "Display name.", "nullable": true, "example": "Alice Buyer" }, "phone": { "type": "string", "description": "Contact phone.", "nullable": true, "example": "+1 555 010 1234" }, "emailVerifiedAt": { "type": "string", "description": "When the email was verified, or null if not yet verified (ISO 8601).", "format": "date-time", "nullable": true, "example": "2026-06-05T14:36:18.000Z" } }, "required": [ "id", "email", "name", "phone", "emailVerifiedAt" ] }, "UpdateProfileDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer display name. Pass null to clear.", "nullable": true, "maxLength": 200, "example": "Alice Buyer" }, "phone": { "type": "string", "description": "Customer contact phone (free-text). Pass null to clear.", "nullable": true, "maxLength": 32, "example": "+1 555 010 1234" } } }, "CustomerAddressResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Address id — the customer-safe handle for this entry." }, "label": { "type": "string", "nullable": true, "example": "Home" }, "recipientName": { "type": "string", "example": "Alice Buyer" }, "line1": { "type": "string", "example": "123 Main St" }, "line2": { "type": "string", "nullable": true, "example": "Apt 4B" }, "city": { "type": "string", "example": "Boise" }, "region": { "type": "string", "nullable": true, "example": "ID" }, "postalCode": { "type": "string", "example": "83702" }, "country": { "type": "string", "example": "US" }, "phone": { "type": "string", "nullable": true, "example": "+1 555 010 1234" }, "isDefaultShipping": { "type": "boolean", "example": false }, "isDefaultBilling": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "description": "ISO 8601.", "example": "2026-06-05T14:36:18.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601.", "example": "2026-06-05T14:36:18.000Z" } }, "required": [ "id", "label", "recipientName", "line1", "line2", "city", "region", "postalCode", "country", "phone", "isDefaultShipping", "isDefaultBilling", "createdAt", "updatedAt" ] }, "CreateAddressDto": { "type": "object", "properties": { "label": { "type": "string", "description": "Optional short label, e.g. \"Home\" or \"Office\".", "maxLength": 100, "example": "Home" }, "recipientName": { "type": "string", "description": "Name of the person this address ships to.", "maxLength": 200, "example": "Alice Buyer" }, "line1": { "type": "string", "description": "Street address line 1.", "maxLength": 300, "example": "123 Main St" }, "line2": { "type": "string", "description": "Street address line 2 (apt, suite, unit).", "maxLength": 300, "example": "Apt 4B" }, "city": { "type": "string", "description": "City / locality.", "maxLength": 200, "example": "Boise" }, "region": { "type": "string", "description": "State / province / region.", "maxLength": 200, "example": "ID" }, "postalCode": { "type": "string", "description": "Postal / ZIP code.", "maxLength": 32, "example": "83702" }, "country": { "type": "string", "description": "Country (ISO code or name).", "maxLength": 100, "example": "US" }, "phone": { "type": "string", "description": "Contact phone for this address (free-text).", "maxLength": 32, "example": "+1 555 010 1234" }, "isDefaultShipping": { "type": "boolean", "description": "Mark this as the default shipping address. Setting true clears the customer's prior default-shipping address.", "default": false }, "isDefaultBilling": { "type": "boolean", "description": "Mark this as the default billing address. Setting true clears the customer's prior default-billing address.", "default": false } }, "required": [ "recipientName", "line1", "city", "postalCode", "country" ] }, "UpdateAddressDto": { "type": "object", "properties": { "label": { "type": "string", "description": "Optional short label, e.g. \"Home\" or \"Office\". Pass null to clear.", "maxLength": 100, "example": "Home", "nullable": true }, "recipientName": { "type": "string", "description": "Name of the person this address ships to.", "maxLength": 200, "example": "Alice Buyer" }, "line1": { "type": "string", "description": "Street address line 1.", "maxLength": 300, "example": "123 Main St" }, "line2": { "type": "string", "description": "Street address line 2 (apt, suite, unit). Pass null to clear.", "maxLength": 300, "example": "Apt 4B", "nullable": true }, "city": { "type": "string", "description": "City / locality.", "maxLength": 200, "example": "Boise" }, "region": { "type": "string", "description": "State / province / region. Pass null to clear.", "maxLength": 200, "example": "ID", "nullable": true }, "postalCode": { "type": "string", "description": "Postal / ZIP code.", "maxLength": 32, "example": "83702" }, "country": { "type": "string", "description": "Country (ISO code or name).", "maxLength": 100, "example": "US" }, "phone": { "type": "string", "description": "Contact phone for this address (free-text). Pass null to clear.", "maxLength": 32, "example": "+1 555 010 1234", "nullable": true }, "isDefaultShipping": { "type": "boolean", "description": "Mark this as the default shipping address. Setting true clears the customer's prior default-shipping address.", "default": false }, "isDefaultBilling": { "type": "boolean", "description": "Mark this as the default billing address. Setting true clears the customer's prior default-billing address.", "default": false } } }, "CustomerOrderSummaryDto": { "type": "object", "properties": { "orderReference": { "type": "string", "nullable": true, "description": "Customer-safe stable order reference. This is an address, not an authorization credential. `null` only for a legacy Order awaiting the measured reference backfill.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" }, "orderNumber": { "type": "string", "description": "Human-readable public order number. Authenticated order-number routes remain supported alongside the stable order reference.", "example": "LC-100423" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "description": "Order lifecycle status.", "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "description": "Fulfillment status.", "example": "UNFULFILLED" }, "subtotalInCents": { "type": "number", "description": "Subtotal in minor units (cents).", "example": 25998 }, "discountInCents": { "type": "number", "description": "Discount applied in minor units (cents).", "example": 0 }, "taxInCents": { "type": "number", "description": "Tax in minor units (cents).", "example": 1560 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "number", "description": "Grand total in minor units (cents).", "example": 27558 }, "createdAt": { "type": "string", "description": "When the order was placed (ISO 8601).", "example": "2026-06-05T14:36:18.000Z" } }, "required": [ "orderReference", "orderNumber", "status", "fulfillmentStatus", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "totalInCents", "createdAt" ] }, "CustomerOrderListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderSummaryDto" } }, "page": { "type": "number", "description": "1-based page returned.", "example": 1 }, "pageSize": { "type": "number", "description": "Page size used.", "example": 20 }, "total": { "type": "number", "description": "Total orders for this customer.", "example": 3 } }, "required": [ "data", "page", "pageSize", "total" ] }, "CustomerOrderDetailDto": { "type": "object", "properties": { "orderReference": { "type": "string", "nullable": true, "description": "Customer-safe stable order reference. This is an address, not an authorization credential. `null` only for a legacy Order awaiting the measured reference backfill.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" }, "orderNumber": { "type": "string", "description": "Human-readable public order number. Authenticated order-number routes remain supported alongside the stable order reference.", "example": "LC-100423" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED" ], "description": "Order lifecycle status.", "example": "CONFIRMED" }, "fulfillmentStatus": { "type": "string", "enum": [ "UNFULFILLED", "PARTIALLY_FULFILLED", "FULFILLED" ], "description": "Fulfillment status.", "example": "UNFULFILLED" }, "subtotalInCents": { "type": "number", "description": "Subtotal in minor units (cents).", "example": 25998 }, "discountInCents": { "type": "number", "description": "Discount applied in minor units (cents).", "example": 0 }, "taxInCents": { "type": "number", "description": "Tax in minor units (cents).", "example": 1560 }, "taxDisclosure": { "nullable": true, "description": "Customer-safe disclosure when litecommerce did not calculate tax for this order (manual/no-tax mode). Null for provider-calculated tax and legacy/merchant-created orders.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CheckoutTaxDisclosureDto" } ] }, "totalInCents": { "type": "number", "description": "Grand total in minor units (cents).", "example": 27558 }, "createdAt": { "type": "string", "description": "When the order was placed (ISO 8601).", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderItemDto" } }, "paymentDisplay": { "nullable": true, "description": "Immutable display-safe facts from the exact successful card Charge. `null` for free orders, paid orders predating snapshot capture, or while a paid order's exact provider display evidence is temporarily unavailable and bounded repair remains pending. It does not mean the order is unpaid. Available only on authenticated detail reads.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderPaymentDisplayDto" } ] }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPackageGroupDto" } }, "shippingInCents": { "type": "number", "description": "Shipping charged on the order in minor units (#854) — `0` when none applied. Already included in `totalInCents`; surfaced so the detail view can itemize the shipping line.", "example": 0 }, "shippingMethod": { "nullable": true, "description": "The immutable exact selection or delivery promise captured on `Order.shippingMethod` at confirmation (#1769/#2415). For orders confirmed before that snapshot was introduced, the original frozen checkout selection is returned when the Order snapshot is absent. `null` when the authoritative source has no valid recorded snapshot; original-quote and actual-shipment facts are never substituted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderShippingMethodDto" } ] }, "shipments": { "description": "#1562 — customer-safe handed-off and delivered shipment history. PLANNED and READY preparation is excluded; tracking fields may be null when the carrier supplied no tracking. Carries no raw order or fulfillment ids.", "type": "array", "items": { "$ref": "#/components/schemas/OrderShipmentDto" } }, "orderTimeContact": { "description": "Immutable order-time recipient/contact facts. The object is always present; nullable members preserve missing legacy values honestly. Available only after authenticated tenant/customer ownership checks.", "allOf": [ { "$ref": "#/components/schemas/CustomerOrderTimeContactDto" } ] }, "shipmentDeliveryComplete": { "type": "boolean", "description": "True only when at least one non-cancelled fulfillment exists and every non-cancelled fulfillment is DELIVERED. This server-derived flag includes PLANNED and READY fulfillments intentionally omitted from `shipments`; an empty or all-delivered visible array alone cannot establish completion." }, "shippingAddress": { "description": "Shipping address captured at checkout (JSON snapshot), or null.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] }, "billingAddress": { "description": "Billing address captured at checkout (JSON snapshot), or null.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressSnapshotDto" } ] } }, "required": [ "orderReference", "orderNumber", "status", "fulfillmentStatus", "subtotalInCents", "discountInCents", "taxInCents", "taxDisclosure", "totalInCents", "createdAt", "items", "paymentDisplay", "packages", "shippingInCents", "shippingMethod", "shipments", "orderTimeContact", "shipmentDeliveryComplete", "shippingAddress", "billingAddress" ] }, "CustomerReturnResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Return id." }, "orderReference": { "type": "string", "nullable": true, "description": "Customer-safe stable reference for the parent order. Possession does not authorize return access. `null` only for a legacy Order awaiting the measured reference backfill.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" }, "orderNumber": { "type": "string", "example": "LC-100423" }, "status": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "IN_TRANSIT", "RECEIVED", "COMPLETED", "REJECTED", "CANCELLED" ], "example": "REQUESTED" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "refundAmountInCents": { "type": "integer", "minimum": 0, "description": "Refund to the customer for this return, in cents. 0 until the merchant sets an amount.", "example": 0 }, "refundState": { "type": "string", "enum": [ "NOT_APPLICABLE", "PROCESSING", "ISSUED", "REIMBURSEMENT_PENDING", "RECONCILIATION_REQUIRED", "REIMBURSEMENT_RECORDED", "RESOLVED" ], "description": "Customer-safe money state of the refund (#3964). Same derivation as the public return surface: ISSUED means the original-method refund completed; REIMBURSEMENT_PENDING means it was later reversed and the merchant still owes an alternative reimbursement; REIMBURSEMENT_RECORDED and RESOLVED mean that reimbursement is recorded." }, "amountOwedInCents": { "type": "integer", "minimum": 0, "nullable": true, "description": "Amount still owed after a provider reversed an earlier successful refund; null when no such correction exists." }, "refundCurrency": { "type": "string", "nullable": true, "example": "usd", "description": "Lowercase ISO 4217 code the refund amounts are denominated in, taken from the persisted refund records (the refund exception, else the order's payment) rather than the organization's current setting (#3964). Null when the order has no recorded payment currency. #4007 tightened that null: it means the historical denomination is unrecoverable, NOT that the client may substitute the currency it is already displaying. A client receiving null must present the refund without denominating it. Derived by the same shared precedence as the email-gated public return surface, so the two cannot disagree." }, "requestedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnItemResponseDto" } } }, "required": [ "id", "orderReference", "orderNumber", "status", "reason", "refundAmountInCents", "refundState", "amountOwedInCents", "refundCurrency", "requestedAt", "updatedAt", "items" ] }, "CustomerReturnListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnResponseDto" } } }, "required": [ "data" ] }, "CustomerActionOrderDto": { "type": "object", "properties": { "orderReference": { "type": "string", "nullable": true, "description": "Customer-safe stable order reference. Possession does not authorize this action. `null` only when a legacy action targets an Order still awaiting the measured reference backfill.", "example": "or1_0123456789abcdef0123456789abcdef", "pattern": "^or1_[0-9a-f]{32}$" }, "orderNumber": { "type": "string", "example": "LC-100423" }, "createdAt": { "type": "string", "example": "2026-06-05T14:36:18.000Z" } }, "required": [ "orderReference", "orderNumber", "createdAt" ] }, "CustomerReturnActionPreviewDto": { "type": "object", "properties": { "action": { "type": "string", "example": "order.return" }, "order": { "$ref": "#/components/schemas/CustomerActionOrderDto" }, "reason": { "type": "string", "nullable": true, "example": "Wrong size" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReturnLinePreviewDto" } } }, "required": [ "action", "order", "reason", "items" ] }, "IssueReturnActionResponseDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Raw customer action token. Returned once; use it at /customer/actions/:token.", "example": "a1234567890abcdefghijklmnop" }, "expiresAt": { "type": "string", "example": "2026-06-12T14:36:18.000Z" }, "preview": { "$ref": "#/components/schemas/CustomerReturnActionPreviewDto" } }, "required": [ "token", "expiresAt", "preview" ] }, "CustomerActionConsumeResponseDto": { "type": "object", "properties": { "action": { "type": "string", "example": "order.return" }, "status": { "type": "string", "example": "CONSUMED" }, "returnRequest": { "$ref": "#/components/schemas/CustomerReturnResponseDto" } }, "required": [ "action", "status", "returnRequest" ] }, "PaymentAccountRequirementsDto": { "type": "object", "properties": { "currentlyDue": { "description": "Stripe requirement keys currently due on the connected account. Keys only; no submitted values or documents are returned.", "type": "array", "items": { "type": "string" } }, "pastDue": { "description": "Stripe requirement keys that are past due on the connected account. Keys only; no submitted values or documents are returned.", "type": "array", "items": { "type": "string" } }, "pendingVerification": { "description": "Stripe requirement keys pending Stripe verification. Keys only; no submitted values or documents are returned.", "type": "array", "items": { "type": "string" } }, "disabledReason": { "type": "string", "nullable": true, "description": "Stripe disabled reason for the connected account, when Stripe reports one." } }, "required": [ "currentlyDue", "pastDue", "pendingVerification", "disabledReason" ] }, "StripeConnectedAccountSummaryDto": { "type": "object", "properties": { "displayName": { "type": "string", "nullable": true, "description": "Safe display/business name from the connected Stripe account, when Stripe reports one. Never includes legal/person objects." }, "email": { "type": "string", "nullable": true, "description": "Safe connected-account email from Stripe, when available to the account owner/admin status surface." }, "chargesEnabled": { "type": "boolean", "description": "Raw Stripe `charges_enabled` readiness flag for the connected account." }, "detailsSubmitted": { "type": "boolean", "description": "Raw Stripe `details_submitted` readiness flag for the connected account." }, "requirements": { "$ref": "#/components/schemas/PaymentAccountRequirementsDto" } }, "required": [ "displayName", "email", "chargesEnabled", "detailsSubmitted", "requirements" ] }, "PaymentAccountStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NONE", "CONNECTED", "VERIFIED", "RESTRICTED" ], "description": "Capability gate. Live charges require VERIFIED; everything else fails closed at the charge boundary. CONNECTED = mid-onboarding, RESTRICTED = Stripe has disabled charges, NONE = no account linked." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Masked connected Stripe account id (e.g. `acct_••••1234`), or null when no account is linked. Never the full id." }, "provider": { "type": "string", "description": "Payment-account provider. Always `stripe` today." }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the account was first connected (ISO 8601), or null." }, "stripeAccount": { "nullable": true, "description": "Safe connected-account identity and requirement summary from Stripe, or null when no account is linked or the live Stripe lookup is unavailable.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/StripeConnectedAccountSummaryDto" } ] } }, "required": [ "status", "stripeAccountId", "provider", "connectedAt", "stripeAccount" ] }, "StartConnectResponseDto": { "type": "object", "properties": { "authorizeUrl": { "type": "string", "description": "Stripe Connect OAuth authorize URL to redirect the merchant to. Carries the single-use CSRF `state` bound to this organization.", "example": "https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_…&scope=read_write&redirect_uri=…&state=…" } }, "required": [ "authorizeUrl" ] }, "TerminalLocationAddressSnapshotDto": { "type": "object", "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } }, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, "TerminalLocationSnapshotDto": { "type": "object", "properties": { "terminalLocationId": { "type": "string", "example": "tml_FBakXQG8bQk4Mm" }, "displayName": { "type": "string", "example": "Front counter" }, "address": { "$ref": "#/components/schemas/TerminalLocationAddressSnapshotDto" } }, "required": [ "terminalLocationId", "displayName", "address" ] }, "VerifiedDefaultTerminalLocationDto": { "type": "object", "properties": { "terminalLocationId": { "type": "string", "example": "tml_FBakXQG8bQk4Mm" }, "displayName": { "type": "string", "example": "Front counter" }, "address": { "$ref": "#/components/schemas/TerminalLocationAddressSnapshotDto" }, "verifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "terminalLocationId", "displayName", "address", "verifiedAt" ] }, "TerminalLocationAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 300, "example": "1120 S Rackham Way" }, "line2": { "type": "string", "maxLength": 300, "example": "Suite 300" }, "city": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Meridian" }, "state": { "type": "string", "minLength": 1, "maxLength": 200, "example": "ID" }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 32, "example": "83642" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US", "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "city", "state", "postalCode", "country" ] }, "TerminalLocationSetupResponseDto": { "type": "object", "properties": { "cardPaymentsCapability": { "type": "string", "enum": [ "active" ], "description": "The connected account card_payments capability. This endpoint fails closed unless it is active." }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/TerminalLocationSnapshotDto" } }, "defaultLocation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/VerifiedDefaultTerminalLocationDto" } ] }, "suggestedAddress": { "nullable": true, "description": "Complete organization address offered only as an editable prefill. Creating a Location always requires an explicit request body.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TerminalLocationAddressDto" } ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "cardPaymentsCapability", "locations", "defaultLocation", "suggestedAddress", "hasMore", "nextCursor" ] }, "TapToPayAppleAccountLinkResponseDto": { "type": "object", "properties": { "redirectUrl": { "type": "string", "format": "uri", "description": "Short-lived Stripe-generated HTTPS onboarding URL for accepting or relinking the active tenant's Tap to Pay on iPhone Apple Account. The URL must not be persisted or logged." } }, "required": [ "redirectUrl" ] }, "CreateTerminalLocationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 1000, "example": "Front counter", "description": "Merchant-facing name for this physical POS location." }, "address": { "$ref": "#/components/schemas/TerminalLocationAddressDto" } }, "required": [ "reason", "displayName", "address" ] }, "SetDefaultTerminalLocationResponseDto": { "type": "object", "properties": { "defaultLocation": { "$ref": "#/components/schemas/VerifiedDefaultTerminalLocationDto" } }, "required": [ "defaultLocation" ] }, "AdoptTerminalLocationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Human-readable explanation for performing this high-risk action. Captured in audit metadata for traceability.", "minLength": 1, "maxLength": 500, "example": "Promotion was entered in error before launch" }, "terminalLocationId": { "type": "string", "minLength": 1, "maxLength": 255, "example": "tml_FBakXQG8bQk4Mm", "description": "Existing Stripe Terminal Location to verify and make the default." } }, "required": [ "reason", "terminalLocationId" ] }, "DisconnectPaymentAccountResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NONE", "CONNECTED", "VERIFIED", "RESTRICTED" ], "description": "Capability gate. Live charges require VERIFIED; everything else fails closed at the charge boundary. CONNECTED = mid-onboarding, RESTRICTED = Stripe has disabled charges, NONE = no account linked." }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Masked connected Stripe account id (e.g. `acct_••••1234`), or null when no account is linked. Never the full id." }, "provider": { "type": "string", "description": "Payment-account provider. Always `stripe` today." }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the account was first connected (ISO 8601), or null." }, "stripeAccount": { "nullable": true, "description": "Safe connected-account identity and requirement summary from Stripe, or null when no account is linked or the live Stripe lookup is unavailable.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/StripeConnectedAccountSummaryDto" } ] }, "deauthorization": { "type": "string", "enum": [ "deauthorized", "skipped_unconfigured", "failed" ], "description": "Best-effort Stripe OAuth deauthorization outcome. `deauthorized` = the platform↔account link was also severed in Stripe; `skipped_unconfigured` = Stripe Connect is not configured in this environment so no Stripe call was made; `failed` = the Stripe call errored. In every case the local disconnect has already succeeded and charges fail closed." } }, "required": [ "status", "stripeAccountId", "provider", "connectedAt", "stripeAccount", "deauthorization" ] }, "StorefrontContextOrganizationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable tenant organization id." }, "slug": { "type": "string", "description": "URL-safe tenant slug." }, "name": { "type": "string", "description": "Tenant display name." }, "status": { "type": "string", "description": "Lifecycle status of the tenant org.", "example": "ACTIVE" }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. `USD`." }, "timezone": { "type": "string", "description": "IANA timezone, e.g. `America/Denver`." } }, "required": [ "id", "slug", "name", "status", "currency", "timezone" ] }, "StorefrontContextApiKeyDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The authenticated key id (non-secret)." }, "name": { "type": "string", "description": "Operator-assigned key label." }, "scopes": { "description": "Scopes granted to this key.", "example": [ "storefront:read" ], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "scopes" ] }, "StorefrontContextResponseDto": { "type": "object", "properties": { "organization": { "$ref": "#/components/schemas/StorefrontContextOrganizationDto" }, "apiKey": { "$ref": "#/components/schemas/StorefrontContextApiKeyDto" } }, "required": [ "organization", "apiKey" ] }, "ImportCatalogRowDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "type": { "allOf": [ { "$ref": "#/components/schemas/ItemType" } ] }, "sellMode": { "description": "How this item may be purchased (default `ONE_TIME`). Authoring contract only — sell-mode enforcement and storefront/BYO filtering ship with subscription checkout (#629). A variant may override this per-variant.", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "Send `null` to clear an existing value; omit to leave it alone." }, "description": { "type": "string", "maxLength": 10000 }, "shortDescription": { "type": "string", "maxLength": 500 }, "tags": { "type": "array", "items": { "type": "string" } }, "brand": { "type": "string", "maxLength": 200, "nullable": true }, "vendor": { "type": "string", "maxLength": 200, "nullable": true }, "productFamily": { "type": "string", "maxLength": 200, "nullable": true }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "description": "Packed-item orientation. Omit to keep the saved-face default; ANY_SIDE_RIGHT_ANGLE permits every distinct 90-degree face rotation of reviewed dimensions.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary key/value attributes." }, "channelPublishStatus": { "type": "object", "additionalProperties": true, "description": "Per-channel publish status, e.g. `{ \"storefront\": \"published\" }`." }, "target": { "type": "string", "enum": [ "product" ], "description": "Row discriminator — a product upsert row. Optional: an omitted `target` is a product row (the shipped first-vertical shape)." }, "externalId": { "type": "string", "description": "The source platform's own primary key for this row (e.g. `gid://shopify/Product/123` or a SKU), stored verbatim. Combined with the batch `sourceSystem` it is the idempotency key: the same pair resolves to the same litecommerce item on re-import.", "minLength": 1, "maxLength": 512 }, "sortOrder": { "type": "number", "minimum": 0, "description": "Status/sort mapping — the product's display position within the tenant catalog. Omitted: appends to the end on insert, preserves the stored order on update." } }, "required": [ "name", "slug", "type", "status", "priceInCents", "externalId" ] }, "ImportCatalogCollectionRowDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "description": { "type": "string", "maxLength": 10000 }, "image": { "type": "object", "additionalProperties": true, "description": "Image metadata as an open JSON object. Shape will be tightened by Epic 6 (Catalog Media). Send `null` to clear.", "nullable": true }, "sortOrder": { "type": "number", "minimum": 0, "description": "Display order — collections are listed ascending. Defaults to 0." }, "target": { "type": "string", "enum": [ "collection" ], "description": "Row discriminator — a collection upsert row." }, "externalId": { "type": "string", "description": "The source platform's own primary key for this collection (e.g. `gid://shopify/Collection/123`), stored verbatim. With the batch `sourceSystem` it is the idempotency key: the same pair resolves to the same litecommerce collection on re-import.", "minLength": 1, "maxLength": 512 } }, "required": [ "name", "slug", "status", "target", "externalId" ] }, "ImportCatalogVariantRowDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "description": "Inventory-side identifier. Unique within the parent item. Allowed: alphanumerics, `-`, `_`, `.`", "minLength": 1, "maxLength": 100 }, "priceInCents": { "type": "number", "minimum": 0 }, "compareAtPriceInCents": { "type": "number", "minimum": 0, "nullable": true, "description": "Send `null` to clear an existing value; omit to leave it alone." }, "sellMode": { "nullable": true, "description": "Per-variant override of the item's `sellMode`. Send `null` (or omit) to inherit the parent item default. Authoring contract only — enforcement is subscription checkout (#629).", "allOf": [ { "$ref": "#/components/schemas/SellMode" } ] }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Variant-distinguishing attributes (e.g. `{ \"size\": \"M\", \"color\": \"Red\" }`). Keys and values must both be strings." }, "metafields": { "type": "object", "additionalProperties": true, "description": "Arbitrary merchant-side attributes." }, "weight": { "type": "number", "nullable": true, "description": "Physical weight, expressed in `weightUnit`. Positive; must be sent together with `weightUnit`. Overrides the parent item weight." }, "weightUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WeightUnit" } ] }, "length": { "type": "number", "nullable": true, "description": "Longest side, expressed in `dimensionUnit`. Positive." }, "width": { "type": "number", "nullable": true, "description": "Width, expressed in `dimensionUnit`. Positive." }, "height": { "type": "number", "nullable": true, "description": "Height, expressed in `dimensionUnit`. Positive." }, "dimensionUnit": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionUnit" } ] }, "orientationPolicy": { "nullable": true, "description": "Variant orientation override. Null or omitted inherits the item; otherwise choose saved-face only or every distinct 90-degree face rotation.", "allOf": [ { "$ref": "#/components/schemas/OrientationPolicy" } ] }, "target": { "type": "string", "enum": [ "variant" ], "description": "Row discriminator — a product-variant upsert row." }, "externalId": { "type": "string", "description": "The source platform's own primary key for this variant (e.g. `gid://shopify/ProductVariant/456`), stored verbatim. With the batch `sourceSystem` it is the idempotency key. Write-once: a variant can never be re-pointed to a different parent product via import.", "minLength": 1, "maxLength": 512 }, "productExternalId": { "type": "string", "description": "The PARENT PRODUCT's external id in the same sourceSystem (e.g. `gid://shopify/Product/123`). Must resolve to an already-imported product in this tenant — earlier rows in the same batch count.", "minLength": 1, "maxLength": 512 }, "sortOrder": { "type": "number", "minimum": 0, "description": "Status/sort mapping — the variant's display position within its parent product. Omitted: appends to the end on insert, preserves the stored order on update." } }, "required": [ "name", "sku", "priceInCents", "target", "externalId", "productExternalId" ] }, "ImportCatalogMembershipRowDto": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "membership" ], "description": "Row discriminator — an item↔collection assignment row." }, "externalId": { "type": "string", "description": "The source platform's own id for the assignment (e.g. a Shopify `Collect` gid) — job-row lineage only, NOT the idempotency key (the resolved collection+item pair is). Omitted: synthesized as `::`.", "minLength": 1, "maxLength": 512 }, "collectionExternalId": { "type": "string", "description": "The COLLECTION's external id in the same sourceSystem. Must resolve to an already-imported collection in this tenant.", "minLength": 1, "maxLength": 512 }, "itemExternalId": { "type": "string", "description": "The ITEM's external id in the same sourceSystem. Must resolve to an already-imported product in this tenant.", "minLength": 1, "maxLength": 512 }, "sortOrder": { "type": "number", "minimum": 0, "description": "Status/sort mapping — the item's display position within the collection. Omitted: appends after the collection tail on insert, preserves the stored position on update." } }, "required": [ "target", "collectionExternalId", "itemExternalId" ] }, "ImportCatalogCompositionComponentDto": { "type": "object", "properties": { "productExternalId": { "type": "string", "description": "The component product's external id in this batch sourceSystem.", "minLength": 1, "maxLength": 512 }, "variantExternalId": { "type": "string", "description": "An exact component variant's external id in this batch sourceSystem.", "minLength": 1, "maxLength": 512, "nullable": true }, "quantity": { "type": "number", "format": "int32", "minimum": 1, "maximum": 2147483647 }, "discountBasisPoints": { "type": "number", "minimum": 0, "maximum": 10000 }, "capacityMode": { "type": "string", "enum": [ "TRACKED", "UNTRACKED" ] }, "untrackedReason": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 500 } }, "required": [ "productExternalId", "quantity", "discountBasisPoints", "capacityMode" ] }, "ImportCatalogCompositionRowDto": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "composition" ] }, "externalId": { "type": "string", "description": "Source identity for this composition row's import ledger entry. It is not a litecommerce composition key.", "minLength": 1, "maxLength": 512 }, "productExternalId": { "type": "string", "description": "The composed parent product's external id in this batch sourceSystem.", "minLength": 1, "maxLength": 512 }, "kind": { "type": "string", "enum": [ "PACKAGE", "KIT" ] }, "expectedRevision": { "type": "number", "minimum": 0, "maximum": 2147483646, "description": "0 creates the definition; an update supplies its exact current revision. Exact replay of an identical imported definition is idempotent." }, "components": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/ImportCatalogCompositionComponentDto" } } }, "required": [ "target", "externalId", "productExternalId", "kind", "expectedRevision", "components" ] }, "ImportCatalogBatchDto": { "type": "object", "properties": { "sourceSystem": { "type": "string", "description": "The origin platform, lowercased and free-form (e.g. `shopify`, `woocommerce`, `custom`). Source-agnostic — Shopify is the reference use case, never the only one. Stamped on every imported row as lineage.", "minLength": 1, "maxLength": 64, "example": "shopify" }, "dryRun": { "type": "boolean", "description": "Validate-only. When true, every row is parsed/mapped/validated and reported per-row, but NOTHING is written — no item insert/update, no side-effect. Use it to diff a mapping until clean, then flip to false.", "default": false }, "idempotencyKey": { "type": "string", "description": "Optional request-level idempotency key for the JOB SUBMISSION (dedupes a network-retried submit into one job). Orthogonal to the per-row external-ID idempotency, which already makes re-imports safe.", "maxLength": 200 }, "rows": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ImportCatalogRowDto" }, { "$ref": "#/components/schemas/ImportCatalogCollectionRowDto" }, { "$ref": "#/components/schemas/ImportCatalogVariantRowDto" }, { "$ref": "#/components/schemas/ImportCatalogMembershipRowDto" }, { "$ref": "#/components/schemas/ImportCatalogCompositionRowDto" } ] }, "description": "The catalog rows to upsert. 1..200 rows run synchronously (terminal job + per-row results in the response); 201..5000 rows are accepted as an async job (202 + `QUEUED`; poll `GET /import/jobs/:id`). A larger batch is rejected with `IMPORT_BATCH_TOO_LARGE` and must be split. Each row is one of the five target shapes, discriminated by `target` (omitted = `product`)." } }, "required": [ "sourceSystem", "rows" ] }, "ImportFamily": { "type": "string", "enum": [ "CATALOG", "INVENTORY", "CONTENT", "PRICING", "CUSTOMERS" ] }, "ImportJobStatus": { "type": "string", "enum": [ "QUEUED", "RUNNING", "SUCCEEDED", "PARTIALLY_SUCCEEDED", "FAILED", "CANCELLED" ] }, "ImportJobRowStatus": { "type": "string", "enum": [ "QUEUED", "RUNNING", "SUCCEEDED", "FAILED", "SKIPPED" ] }, "ImportJobRowResultDto": { "type": "object", "properties": { "id": { "type": "string" }, "rowIndex": { "type": "number", "description": "Position of this row in the submitted batch (0-based)." }, "sourceSystem": { "type": "string", "description": "The origin platform this row came from." }, "externalId": { "type": "string", "description": "The source platform's own id for this row." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ImportJobRowStatus" } ] }, "targetType": { "type": "string", "nullable": true, "description": "The litecommerce entity type this row upserted into (e.g. `item`). Null until a successful write, and always null on a dryRun." }, "targetId": { "type": "string", "nullable": true, "description": "The id of the upserted litecommerce entity. Null until success / for a dryRun." }, "wouldApply": { "type": "string", "nullable": true, "description": "On a dryRun, whether this row WOULD insert or update its target. Product/collection/variant rows match the external-ID triple; membership and composition rows use their documented resolved domain identity. Null on a real run.", "enum": [ "insert", "update" ] }, "errorCode": { "type": "string", "nullable": true, "description": "Typed per-row error code (null when the row succeeded)." }, "errorMessage": { "type": "string", "nullable": true }, "errorDetails": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "id", "rowIndex", "sourceSystem", "externalId", "status" ] }, "ImportJobResultDto": { "type": "object", "properties": { "id": { "type": "string" }, "family": { "allOf": [ { "$ref": "#/components/schemas/ImportFamily" } ] }, "sourceSystem": { "type": "string" }, "status": { "allOf": [ { "$ref": "#/components/schemas/ImportJobStatus" } ] }, "dryRun": { "type": "boolean", "description": "True when this was a validate-only job." }, "totalRows": { "type": "number" }, "succeededRows": { "type": "number" }, "failedRows": { "type": "number" }, "skippedRows": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobRowResultDto" } } }, "required": [ "id", "family", "sourceSystem", "status", "dryRun", "totalRows", "succeededRows", "failedRows", "skippedRows", "createdAt", "rows" ] }, "ImportContentPageRowDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "URL-safe identifier; tenant-scoped unique. Lowercase letters, digits, and hyphens only.", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT" ], "description": "Lifecycle status. `ARCHIVED` is reserved for the archive endpoint and is intentionally not accepted here." }, "content": { "type": "string", "maxLength": 1000000, "description": "Page body. Stored as TEXT in Postgres so there is no schema-level length cap; the 1 MB DTO limit is a runtime safety guard." }, "excerpt": { "type": "string", "maxLength": 500, "nullable": true, "description": "Send `null` to clear an existing excerpt; omit to leave it alone." }, "target": { "type": "string", "enum": [ "page" ], "description": "Row discriminator — a page upsert row. Optional: an omitted `target` is a page row (the only content target today)." }, "externalId": { "type": "string", "description": "The source platform's own primary key for this row (e.g. `gid://shopify/Page/123` or a CMS slug), stored verbatim. Combined with the batch `sourceSystem` it is the idempotency key: the same pair resolves to the same litecommerce page on re-import.", "minLength": 1, "maxLength": 512 } }, "required": [ "title", "slug", "status", "content", "externalId" ] }, "ImportContentBatchDto": { "type": "object", "properties": { "sourceSystem": { "type": "string", "description": "The origin platform, lowercased and free-form (e.g. `shopify`, `woocommerce`, `custom`). Source-agnostic. Stamped on every imported row as lineage.", "minLength": 1, "maxLength": 64, "example": "shopify" }, "dryRun": { "type": "boolean", "description": "Validate-only. When true, every row is parsed/mapped/validated and reported per-row, but NOTHING is written — no page insert/update, no side-effect. Use it to diff a mapping until clean, then flip to false.", "default": false }, "idempotencyKey": { "type": "string", "description": "Optional request-level idempotency key for the JOB SUBMISSION (dedupes a network-retried submit into one job). Orthogonal to the per-row external-ID idempotency, which already makes re-imports safe.", "maxLength": 200 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ImportContentPageRowDto" }, "description": "The content rows to upsert. 1..200 rows run synchronously (terminal job + per-row results in the response); 201..5000 rows are accepted as an async job (202 + `QUEUED`; poll `GET /import/jobs/:id`). A larger batch is rejected with `IMPORT_BATCH_TOO_LARGE` and must be split. **Size, not row count, is usually the binding limit here:** the whole request body is capped at 2 MB, enforced by the JSON parser BEFORE this batch is validated, so an oversized submission returns a plain `413` rather than the typed row-cap error. Because a page body may be up to 1 MB, the reachable row count scales with page size — roughly 1,000 rows of 2 KB pages, ~200 rows of 10 KB pages, and only a couple of very large ones. Chunk submissions by BYTES and keep each under ~2 MB; per-row external-ID idempotency makes the split boundaries harmless." } }, "required": [ "sourceSystem", "rows" ] }, "BookingServiceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] }, "deliveryPosture": { "type": "string", "enum": [ "PICKUP_ONLY", "OPTIONAL", "REQUIRED" ] }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "durationMinutes": { "type": "number", "nullable": true }, "durationOptionsMinutes": { "type": "array", "items": { "type": "number" } }, "fixedSlotTemplate": { "type": "object", "nullable": true, "description": "FIXED_SLOT launch shape: { slots: [{ label, startMinuteOfDay, durationMinutes }] }." }, "timePickerIncrementMinutes": { "type": "number" }, "defaultStartMinuteOfDay": { "type": "number", "nullable": true }, "defaultEndMinuteOfDay": { "type": "number", "nullable": true }, "bufferBeforeMinutes": { "type": "number" }, "bufferAfterMinutes": { "type": "number" }, "minPartySize": { "type": "number", "nullable": true }, "maxPartySize": { "type": "number", "nullable": true }, "capacity": { "type": "number" }, "timezone": { "type": "string", "nullable": true }, "pricingMode": { "type": "string", "enum": [ "FLAT_TIME", "FIXED_PRICE", "PRICING_STRUCTURE" ] }, "basePriceInCents": { "type": "number" }, "pricingIntervalMinutes": { "type": "number", "nullable": true }, "pricingPolicyId": { "type": "string", "nullable": true }, "pricingBasis": { "type": "string", "enum": [ "RESERVED_WINDOW", "CHARGED_DURATION", "FIXED_PRICE" ] }, "paymentMode": { "type": "string", "enum": [ "PAY_LATER", "DEPOSIT_PERCENT", "FULL_PAYMENT" ] }, "paymentDepositPercent": { "type": "number", "nullable": true }, "paymentDepositAmountInCents": { "type": "number", "nullable": true }, "securityDepositMode": { "type": "string", "enum": [ "NONE", "FIXED_AMOUNT", "PERCENTAGE_OF_ORDER", "PERCENTAGE_OF_RESOURCE_VALUES" ] }, "securityDepositAmountInCents": { "type": "number", "nullable": true }, "securityDepositPercent": { "type": "number", "nullable": true }, "approvalMode": { "type": "string", "enum": [ "AUTO_CONFIRM", "MANUAL_APPROVAL" ] }, "leadTimeMinutes": { "type": "number" }, "maxAdvanceDays": { "type": "number", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "itemId", "slug", "name", "description", "status", "bookingType", "deliveryPosture", "periodMode", "durationMinutes", "durationOptionsMinutes", "fixedSlotTemplate", "timePickerIncrementMinutes", "defaultStartMinuteOfDay", "defaultEndMinuteOfDay", "bufferBeforeMinutes", "bufferAfterMinutes", "minPartySize", "maxPartySize", "capacity", "timezone", "pricingMode", "basePriceInCents", "pricingIntervalMinutes", "pricingPolicyId", "pricingBasis", "paymentMode", "paymentDepositPercent", "paymentDepositAmountInCents", "securityDepositMode", "securityDepositAmountInCents", "securityDepositPercent", "approvalMode", "leadTimeMinutes", "maxAdvanceDays", "metadata", "archivedAt", "createdAt", "updatedAt" ] }, "BookingServiceListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingServiceResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "BookingFixedSlotDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100, "example": "Morning" }, "startMinuteOfDay": { "type": "number", "minimum": 0, "maximum": 1439, "example": 540 }, "durationMinutes": { "type": "number", "minimum": 1, "maximum": 1440, "example": 180 } }, "required": [ "label", "startMinuteOfDay", "durationMinutes" ] }, "BookingFixedSlotTemplateDto": { "type": "object", "properties": { "slots": { "type": "array", "items": { "$ref": "#/components/schemas/BookingFixedSlotDto" } } }, "required": [ "slots" ] }, "CreateBookingServiceDto": { "type": "object", "properties": { "itemId": { "type": "object", "format": "uuid", "nullable": true }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "nullable": true, "maxLength": 10000 }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "default": "DRAFT" }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] }, "deliveryPosture": { "type": "string", "enum": [ "PICKUP_ONLY", "OPTIONAL", "REQUIRED" ], "default": "PICKUP_ONLY", "description": "Whether this service is pickup-only, optionally deliverable, or requires delivery." }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "durationMinutes": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "durationOptionsMinutes": { "maxItems": 50, "type": "array", "items": { "type": "number" } }, "fixedSlotTemplate": { "nullable": true, "description": "Stable launch shape for FIXED_SLOT: { slots: [{ label, startMinuteOfDay, durationMinutes }] }.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingFixedSlotTemplateDto" } ] }, "timePickerIncrementMinutes": { "type": "number", "minimum": 1, "maximum": 1440, "default": 30 }, "defaultStartMinuteOfDay": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1439 }, "defaultEndMinuteOfDay": { "type": "number", "nullable": true, "minimum": 1, "maximum": 1440 }, "bufferBeforeMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "bufferAfterMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "minPartySize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "maxPartySize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "capacity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "pricingMode": { "type": "string", "enum": [ "FLAT_TIME", "FIXED_PRICE", "PRICING_STRUCTURE" ], "default": "FLAT_TIME" }, "basePriceInCents": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "pricingIntervalMinutes": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647, "default": 60, "description": "Minutes represented by one base-price unit for FLAT_TIME pricing. Distinct from the time-picker increment; null for FIXED_PRICE." }, "pricingBasis": { "type": "string", "enum": [ "RESERVED_WINDOW", "CHARGED_DURATION", "FIXED_PRICE" ], "default": "RESERVED_WINDOW" }, "paymentMode": { "type": "string", "enum": [ "PAY_LATER", "DEPOSIT_PERCENT", "FULL_PAYMENT" ], "default": "FULL_PAYMENT" }, "paymentDepositPercent": { "type": "number", "nullable": true, "minimum": 1, "maximum": 100 }, "securityDepositMode": { "type": "string", "enum": [ "NONE", "FIXED_AMOUNT", "PERCENTAGE_OF_ORDER", "PERCENTAGE_OF_RESOURCE_VALUES" ], "default": "NONE" }, "securityDepositAmountInCents": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "securityDepositPercent": { "type": "number", "nullable": true, "minimum": 1, "maximum": 100 }, "approvalMode": { "type": "string", "enum": [ "AUTO_CONFIRM", "MANUAL_APPROVAL" ], "default": "AUTO_CONFIRM" }, "leadTimeMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "maxAdvanceDays": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "metadata": { "type": "object", "nullable": true } }, "required": [ "slug", "name", "bookingType", "periodMode" ] }, "UpdateBookingServiceDto": { "type": "object", "properties": { "itemId": { "type": "object", "format": "uuid", "nullable": true }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "nullable": true, "maxLength": 10000 }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "default": "DRAFT" }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ] }, "deliveryPosture": { "type": "string", "enum": [ "PICKUP_ONLY", "OPTIONAL", "REQUIRED" ], "default": "PICKUP_ONLY", "description": "Whether this service is pickup-only, optionally deliverable, or requires delivery." }, "periodMode": { "type": "string", "enum": [ "EXACT_RANGE", "FIXED_DURATION", "FIXED_SLOT" ] }, "durationMinutes": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "durationOptionsMinutes": { "maxItems": 50, "type": "array", "items": { "type": "number" } }, "fixedSlotTemplate": { "nullable": true, "description": "Stable launch shape for FIXED_SLOT: { slots: [{ label, startMinuteOfDay, durationMinutes }] }.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingFixedSlotTemplateDto" } ] }, "timePickerIncrementMinutes": { "type": "number", "minimum": 1, "maximum": 1440, "default": 30 }, "defaultStartMinuteOfDay": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1439 }, "defaultEndMinuteOfDay": { "type": "number", "nullable": true, "minimum": 1, "maximum": 1440 }, "bufferBeforeMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "bufferAfterMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "minPartySize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "maxPartySize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "capacity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "pricingMode": { "type": "string", "enum": [ "FLAT_TIME", "FIXED_PRICE", "PRICING_STRUCTURE" ], "default": "FLAT_TIME" }, "basePriceInCents": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "pricingIntervalMinutes": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647, "default": 60, "description": "Minutes represented by one base-price unit for FLAT_TIME pricing. Distinct from the time-picker increment; null for FIXED_PRICE." }, "pricingBasis": { "type": "string", "enum": [ "RESERVED_WINDOW", "CHARGED_DURATION", "FIXED_PRICE" ], "default": "RESERVED_WINDOW" }, "paymentMode": { "type": "string", "enum": [ "PAY_LATER", "DEPOSIT_PERCENT", "FULL_PAYMENT" ], "default": "FULL_PAYMENT" }, "paymentDepositPercent": { "type": "number", "nullable": true, "minimum": 1, "maximum": 100 }, "securityDepositMode": { "type": "string", "enum": [ "NONE", "FIXED_AMOUNT", "PERCENTAGE_OF_ORDER", "PERCENTAGE_OF_RESOURCE_VALUES" ], "default": "NONE" }, "securityDepositAmountInCents": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "securityDepositPercent": { "type": "number", "nullable": true, "minimum": 1, "maximum": 100 }, "approvalMode": { "type": "string", "enum": [ "AUTO_CONFIRM", "MANUAL_APPROVAL" ], "default": "AUTO_CONFIRM" }, "leadTimeMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "maxAdvanceDays": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647 }, "metadata": { "type": "object", "nullable": true } } }, "BookingResourceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "capacity": { "type": "number" }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ] }, "timezone": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "name", "slug", "resourceType", "capacity", "allocationMode", "timezone", "status", "userId", "metadata", "archivedAt", "createdAt", "updatedAt" ] }, "BookingResourceListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingResourceDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "capacity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ], "default": "POOLED_QUANTITY" }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "required": [ "name", "slug", "resourceType" ] }, "UpdateBookingResourceDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ] }, "capacity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "allocationMode": { "type": "string", "enum": [ "POOLED_QUANTITY", "EXACT_UNIT" ], "default": "POOLED_QUANTITY" }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "nullable": true } } }, "BookingResourceUnitResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "barcode": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "MAINTENANCE", "LOST", "RETIRED" ] }, "metadata": { "type": "object", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "resourceId", "identifier", "sku", "barcode", "status", "metadata", "archivedAt", "createdAt", "updatedAt" ] }, "BookingResourceUnitListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceUnitResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingResourceUnitDto": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "nullable": true, "maxLength": 200 }, "barcode": { "type": "string", "nullable": true, "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "MAINTENANCE", "LOST", "RETIRED" ], "default": "ACTIVE" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "identifier" ] }, "UpdateBookingResourceUnitDto": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "maxLength": 200 }, "sku": { "type": "string", "nullable": true, "maxLength": 200 }, "barcode": { "type": "string", "nullable": true, "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "MAINTENANCE", "LOST", "RETIRED" ], "default": "ACTIVE" }, "metadata": { "type": "object", "nullable": true } } }, "BookingResourceRequirementResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ], "nullable": true }, "quantity": { "type": "number" }, "required": { "type": "boolean" }, "selectionStrategy": { "type": "string", "enum": [ "ANY_AVAILABLE", "SPECIFIC_RESOURCE", "CUSTOMER_SELECTS", "MERCHANT_ASSIGN" ] }, "sortOrder": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "serviceId", "resourceId", "resourceType", "quantity", "required", "selectionStrategy", "sortOrder", "createdAt", "updatedAt" ] }, "BookingResourceRequirementListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceRequirementResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingResourceRequirementDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ], "nullable": true }, "quantity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "required": { "type": "boolean", "default": true }, "selectionStrategy": { "type": "string", "enum": [ "ANY_AVAILABLE", "SPECIFIC_RESOURCE", "CUSTOMER_SELECTS", "MERCHANT_ASSIGN" ], "default": "ANY_AVAILABLE" }, "sortOrder": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 } }, "required": [ "serviceId" ] }, "UpdateBookingResourceRequirementDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceType": { "type": "string", "enum": [ "STAFF", "EQUIPMENT", "ROOM", "LOCATION", "VEHICLE", "POOL" ], "nullable": true }, "quantity": { "type": "number", "minimum": 1, "maximum": 2147483647, "default": 1 }, "required": { "type": "boolean", "default": true }, "selectionStrategy": { "type": "string", "enum": [ "ANY_AVAILABLE", "SPECIFIC_RESOURCE", "CUSTOMER_SELECTS", "MERCHANT_ASSIGN" ], "default": "ANY_AVAILABLE" }, "sortOrder": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 } } }, "BookingAvailabilityRuleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "targetType": { "type": "string", "enum": [ "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "weekday": { "type": "number" }, "startMinuteOfDay": { "type": "number" }, "endMinuteOfDay": { "type": "number" }, "timezone": { "type": "string", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "format": "date-time", "nullable": true }, "capacityOverride": { "type": "number", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "targetType", "serviceId", "resourceId", "weekday", "startMinuteOfDay", "endMinuteOfDay", "timezone", "effectiveFrom", "effectiveTo", "capacityOverride", "createdAt", "updatedAt" ] }, "BookingAvailabilityRuleListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAvailabilityRuleResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingAvailabilityRuleDto": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "weekday": { "type": "number", "minimum": 0, "maximum": 6 }, "startMinuteOfDay": { "type": "number", "minimum": 0, "maximum": 1439 }, "endMinuteOfDay": { "type": "number", "minimum": 1, "maximum": 1440 }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "effectiveFrom": { "type": "string", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "format": "date-time", "nullable": true }, "capacityOverride": { "type": "number", "nullable": true, "minimum": 0, "maximum": 2147483647 } }, "required": [ "targetType", "weekday", "startMinuteOfDay", "endMinuteOfDay" ] }, "UpdateBookingAvailabilityRuleDto": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "weekday": { "type": "number", "minimum": 0, "maximum": 6 }, "startMinuteOfDay": { "type": "number", "minimum": 0, "maximum": 1439 }, "endMinuteOfDay": { "type": "number", "minimum": 1, "maximum": 1440 }, "timezone": { "type": "string", "nullable": true, "maxLength": 100 }, "effectiveFrom": { "type": "string", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "format": "date-time", "nullable": true }, "capacityOverride": { "type": "number", "nullable": true, "minimum": 0, "maximum": 2147483647 } } }, "BookingBlackoutResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "targetType": { "type": "string", "enum": [ "ORGANIZATION", "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "reason": { "type": "string", "nullable": true }, "recurrenceRule": { "type": "string", "nullable": true }, "recurrenceTimezone": { "type": "string", "nullable": true }, "recurrenceEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "createdByUserId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "targetType", "serviceId", "resourceId", "startsAt", "endsAt", "reason", "recurrenceRule", "recurrenceTimezone", "recurrenceEndsAt", "createdByUserId", "createdAt" ] }, "BookingBlackoutListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingBlackoutResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingBlackoutDto": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "ORGANIZATION", "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "nullable": true, "maxLength": 500 }, "recurrenceRule": { "type": "string", "nullable": true, "maxLength": 1000 }, "recurrenceTimezone": { "type": "string", "nullable": true, "maxLength": 100 }, "recurrenceEndsAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "targetType", "startsAt", "endsAt" ] }, "UpdateBookingBlackoutDto": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "ORGANIZATION", "SERVICE", "RESOURCE" ] }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "nullable": true, "maxLength": 500 }, "recurrenceRule": { "type": "string", "nullable": true, "maxLength": 1000 }, "recurrenceTimezone": { "type": "string", "nullable": true, "maxLength": 100 }, "recurrenceEndsAt": { "type": "string", "format": "date-time", "nullable": true } } }, "BookingPolicyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "cancelMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ] }, "cancelCutoffMinutes": { "type": "number" }, "rescheduleMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ] }, "rescheduleCutoffMinutes": { "type": "number" }, "refundMode": { "type": "string", "enum": [ "FULL", "PARTIAL", "NONE", "MANUAL" ] }, "refundPercent": { "type": "number", "nullable": true }, "requiresApproval": { "type": "boolean", "description": "Change-policy approval flag; independent of the service initial-confirmation approvalMode." }, "manualDatePolicyOverrideMode": { "type": "string", "enum": [ "DISALLOW", "REQUIRE_PERMISSION" ] }, "manualCapacityConflictMode": { "type": "string", "enum": [ "STRICT_BLOCK", "CONTROLLED_SHORTAGE_ALLOWED" ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "serviceId", "name", "cancelMode", "cancelCutoffMinutes", "rescheduleMode", "rescheduleCutoffMinutes", "refundMode", "refundPercent", "requiresApproval", "manualDatePolicyOverrideMode", "manualCapacityConflictMode", "createdAt", "updatedAt" ] }, "BookingPolicyListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingPolicyResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingPolicyDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cancelMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ], "default": "REQUEST_ONLY" }, "cancelCutoffMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "rescheduleMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ], "default": "REQUEST_ONLY" }, "rescheduleCutoffMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "refundMode": { "type": "string", "enum": [ "FULL", "PARTIAL", "NONE", "MANUAL" ], "default": "MANUAL" }, "refundPercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "requiresApproval": { "type": "boolean", "default": false, "description": "Whether cancellation/reschedule policy actions require merchant approval. Independent of BookingService.approvalMode, which controls initial booking confirmation." }, "manualDatePolicyOverrideMode": { "type": "string", "enum": [ "DISALLOW", "REQUIRE_PERMISSION" ], "default": "REQUIRE_PERMISSION" }, "manualCapacityConflictMode": { "type": "string", "enum": [ "STRICT_BLOCK", "CONTROLLED_SHORTAGE_ALLOWED" ], "default": "STRICT_BLOCK" } }, "required": [ "name" ] }, "UpdateBookingPolicyDto": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cancelMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ], "default": "REQUEST_ONLY" }, "cancelCutoffMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "rescheduleMode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ], "default": "REQUEST_ONLY" }, "rescheduleCutoffMinutes": { "type": "number", "minimum": 0, "maximum": 2147483647, "default": 0 }, "refundMode": { "type": "string", "enum": [ "FULL", "PARTIAL", "NONE", "MANUAL" ], "default": "MANUAL" }, "refundPercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "requiresApproval": { "type": "boolean", "default": false, "description": "Whether cancellation/reschedule policy actions require merchant approval. Independent of BookingService.approvalMode, which controls initial booking confirmation." }, "manualDatePolicyOverrideMode": { "type": "string", "enum": [ "DISALLOW", "REQUIRE_PERMISSION" ], "default": "REQUIRE_PERMISSION" }, "manualCapacityConflictMode": { "type": "string", "enum": [ "STRICT_BLOCK", "CONTROLLED_SHORTAGE_ALLOWED" ], "default": "STRICT_BLOCK" } } }, "BookingPricingPolicyRevisionSummaryDto": { "type": "object", "properties": { "publishedRevisionNumber": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647, "description": "Revision number of the currently published revision; null when none is published." }, "latestDraftRevisionNumber": { "type": "number", "nullable": true, "minimum": 1, "maximum": 2147483647, "description": "Highest-numbered DRAFT revision; null when the policy carries no draft." }, "hasNewerDraft": { "type": "boolean", "description": "True when a DRAFT revision is newer than the published one (or exists while nothing is published) — the unpublished-changes signal." } }, "required": [ "publishedRevisionNumber", "latestDraftRevisionNumber", "hasNewerDraft" ] }, "BookingPricingPolicyBandDto": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable band identity. Must be trimmed and unique within the revision.", "example": "up-to-2-hours" }, "upperBoundMinutes": { "type": "number", "minimum": 1, "maximum": 527040, "description": "Inclusive upper duration bound in minutes. Bounds must strictly increase across the revision.", "example": 120 }, "factorBasisPoints": { "type": "number", "minimum": 1, "maximum": 1000000, "description": "Factor applied to the service base price (10000 = 100%). Factors must be non-decreasing across the revision.", "example": 15000 } }, "required": [ "id", "upperBoundMinutes", "factorBasisPoints" ] }, "BookingPricingPolicyRevisionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policyId": { "type": "string", "format": "uuid" }, "revisionNumber": { "type": "number", "minimum": 1 }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "SUPERSEDED" ] }, "durationBands": { "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyBandDto" } }, "minimumDurationMinutes": { "type": "number", "minimum": 0, "maximum": 527040 }, "graceMinutes": { "type": "number", "minimum": 0, "maximum": 1440 }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "supersededAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "policyId", "revisionNumber", "status", "durationBands", "minimumDurationMinutes", "graceMinutes", "publishedAt", "supersededAt", "createdAt" ] }, "BookingPricingPolicyListRowDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "revisionSummary": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionSummaryDto" }, "publishedRevision": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingPricingPolicyRevisionResponseDto" } ] } }, "required": [ "id", "name", "description", "archivedAt", "createdAt", "updatedAt", "revisionSummary", "publishedRevision" ] }, "BookingPricingPolicyListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyListRowDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingPricingPolicyDto": { "type": "object", "properties": { "durationBands": { "minItems": 1, "maxItems": 24, "description": "Ordered duration bands: strictly increasing upper bounds, non-decreasing factors, unique trimmed ids.", "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyBandDto" } }, "minimumDurationMinutes": { "type": "number", "minimum": 0, "maximum": 527040, "description": "Pre-grace minimum charged duration in minutes. Must not exceed the largest band upper bound." }, "graceMinutes": { "type": "number", "minimum": 0, "maximum": 1440, "description": "Grace allowance in minutes subtracted after the minimum is applied. Must stay below the largest band upper bound." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "nullable": true, "maxLength": 20000 } }, "required": [ "durationBands", "minimumDurationMinutes", "graceMinutes", "name" ] }, "BookingPricingPolicyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "archivedAt", "createdAt", "updatedAt" ] }, "BookingPricingPolicyWithRevisionResponseDto": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/BookingPricingPolicyResponseDto" }, "revision": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionResponseDto" } }, "required": [ "policy", "revision" ] }, "PreviewBookingPricingPolicyDto": { "type": "object", "properties": { "durationBands": { "minItems": 1, "maxItems": 24, "description": "Ordered duration bands: strictly increasing upper bounds, non-decreasing factors, unique trimmed ids.", "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyBandDto" } }, "minimumDurationMinutes": { "type": "number", "minimum": 0, "maximum": 527040, "description": "Pre-grace minimum charged duration in minutes. Must not exceed the largest band upper bound." }, "graceMinutes": { "type": "number", "minimum": 0, "maximum": 1440, "description": "Grace allowance in minutes subtracted after the minimum is applied. Must stay below the largest band upper bound." }, "basePriceInCents": { "type": "number", "minimum": 1, "maximum": 2147483647, "description": "Candidate BookingService base price in integer cents.", "example": 10001 }, "elapsedMinutesSamples": { "minItems": 1, "maxItems": 50, "description": "Elapsed reserved durations (integer minutes) to evaluate against the candidate revision.", "type": "array", "items": { "type": "number" } }, "commercialQuantity": { "type": "number", "minimum": 1, "maximum": 1000000, "default": 1, "description": "Commercial quantity multiplied into each line total." } }, "required": [ "durationBands", "minimumDurationMinutes", "graceMinutes", "basePriceInCents", "elapsedMinutesSamples" ] }, "BookingPricingPolicyPreviewSampleDto": { "type": "object", "properties": { "elapsedMinutes": { "type": "number", "minimum": 1, "maximum": 527040 }, "effectiveMinutes": { "type": "number", "nullable": true, "minimum": 1, "maximum": 527040 }, "bandId": { "type": "string", "nullable": true }, "factorBasisPoints": { "type": "number", "nullable": true, "minimum": 1, "maximum": 1000000 }, "derivedUnitPriceInCents": { "type": "number", "nullable": true, "minimum": 0, "maximum": 2147483647 }, "lineTotalInCents": { "type": "number", "nullable": true, "minimum": 0, "maximum": 2147483647 }, "reason": { "type": "string", "nullable": true, "description": "Machine reason code when this sample could not be priced (for example DURATION_OUTSIDE_POLICY); null when priced." }, "field": { "type": "string", "nullable": true, "description": "Offending input field for a failed sample; null when priced." } }, "required": [ "elapsedMinutes", "effectiveMinutes", "bandId", "factorBasisPoints", "derivedUnitPriceInCents", "lineTotalInCents", "reason", "field" ] }, "BookingPricingPolicyPreviewResponseDto": { "type": "object", "properties": { "basePriceInCents": { "type": "number", "minimum": 1, "maximum": 2147483647 }, "commercialQuantity": { "type": "number", "minimum": 1, "maximum": 1000000 }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyPreviewSampleDto" } } }, "required": [ "basePriceInCents", "commercialQuantity", "samples" ] }, "BookingPricingPolicyRevisionListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyRevisionResponseDto" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "data", "nextCursor" ] }, "CreateBookingPricingPolicyRevisionDto": { "type": "object", "properties": { "durationBands": { "minItems": 1, "maxItems": 24, "description": "Ordered duration bands: strictly increasing upper bounds, non-decreasing factors, unique trimmed ids.", "type": "array", "items": { "$ref": "#/components/schemas/BookingPricingPolicyBandDto" } }, "minimumDurationMinutes": { "type": "number", "minimum": 0, "maximum": 527040, "description": "Pre-grace minimum charged duration in minutes. Must not exceed the largest band upper bound." }, "graceMinutes": { "type": "number", "minimum": 0, "maximum": 1440, "description": "Grace allowance in minutes subtracted after the minimum is applied. Must stay below the largest band upper bound." } }, "required": [ "durationBands", "minimumDurationMinutes", "graceMinutes" ] }, "AttachBookingPricingPolicyDto": { "type": "object", "properties": { "policyId": { "type": "string", "format": "uuid", "description": "Pricing policy (owned by the active organization) to attach." } }, "required": [ "policyId" ] }, "BookingCustomerCommerceDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "displayNumber": { "type": "string", "nullable": true }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never a booking or payment gate." }, "currency": { "type": "string" }, "totalInCents": { "type": "integer" }, "amountPaidInCents": { "type": "integer" }, "balanceDueInCents": { "type": "integer" } }, "required": [ "type", "displayNumber", "commercialStatus", "paymentStatus", "signatureStatus", "currency", "totalInCents", "amountPaidInCents", "balanceDueInCents" ] }, "BookingCustomerActionAvailabilityDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "CUSTOMER_ALLOWED", "REQUEST_ONLY", "MERCHANT_ONLY" ] }, "available": { "type": "boolean", "description": "Whether this customer may submit the corresponding action/request now." }, "cutoffAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Policy cutoff instant, or null when no cutoff applies." }, "reason": { "type": "string", "enum": [ "AVAILABLE", "MERCHANT_ONLY", "STATUS", "CUTOFF", "PENDING_REQUEST", "CONSUMED", "GROUP_ACTION_REQUIRED" ], "description": "Stable explanation for the current availability decision." } }, "required": [ "mode", "available", "cutoffAt", "reason" ] }, "BookingCustomerActionsDto": { "type": "object", "properties": { "cancel": { "$ref": "#/components/schemas/BookingCustomerActionAvailabilityDto" }, "reschedule": { "$ref": "#/components/schemas/BookingCustomerActionAvailabilityDto" } }, "required": [ "cancel", "reschedule" ] }, "BookingCustomerChangeRequestDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "RESCHEDULE", "CANCEL" ] }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED", "WITHDRAWN" ] }, "requestedStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "requestedEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string", "nullable": true }, "reviewReason": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "status", "requestedStartsAt", "requestedEndsAt", "reason", "reviewReason", "createdAt" ] }, "BookingCustomerSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string", "nullable": true }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ], "nullable": true }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "delivery": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "commerce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerCommerceDto" } ] }, "actions": { "$ref": "#/components/schemas/BookingCustomerActionsDto" }, "changeRequest": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerChangeRequestDto" } ] } }, "required": [ "id", "serviceName", "bookingType", "startsAt", "endsAt", "timezone", "quantity", "status", "approvalStatus", "delivery", "commerce", "actions", "changeRequest" ] }, "CustomerBookingListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingCustomerSummaryDto" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 50 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "data", "page", "pageSize", "total" ] }, "BookingCustomerRevisionDto": { "type": "object", "properties": { "revisionNumber": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SUPERSEDED", "ACCEPTED", "VOIDED", "EXPIRED" ] }, "title": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "revisionNumber", "status", "title", "sentAt", "acceptedAt", "expiresAt" ] }, "BookingCustomerDocumentDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUOTE", "INVOICE", "ORDER" ] }, "displayNumber": { "type": "string", "nullable": true }, "commercialStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELLED", "VOIDED", "CONVERTED" ] }, "paymentStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "UNPAID", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "FAILED", "CANCELLED" ] }, "signatureStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ], "deprecated": true, "description": "Display-only agreement compatibility summary; never a booking or payment gate." }, "currency": { "type": "string" }, "totalInCents": { "type": "integer" }, "amountPaidInCents": { "type": "integer" }, "balanceDueInCents": { "type": "integer" }, "revision": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerRevisionDto" } ] } }, "required": [ "type", "displayNumber", "commercialStatus", "paymentStatus", "signatureStatus", "currency", "totalInCents", "amountPaidInCents", "balanceDueInCents", "revision" ] }, "BookingCustomerSignatureDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT", "INTERNAL" ] }, "status": { "type": "string", "enum": [ "PENDING", "SIGNED", "DECLINED", "EXPIRED", "CANCELLED" ] }, "signerName": { "type": "string", "nullable": true }, "signedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "role", "status", "signerName", "signedAt" ] }, "BookingCustomerContractDto": { "type": "object", "properties": { "displayNumber": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SIGNED", "DECLINED", "EXPIRED", "VOIDED" ] }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "signedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/BookingCustomerSignatureDto" } } }, "required": [ "displayNumber", "title", "status", "sentAt", "signedAt", "expiresAt", "signatures" ] }, "BookingCustomerDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string", "nullable": true }, "bookingType": { "type": "string", "enum": [ "APPOINTMENT", "RESOURCE_RENTAL", "EVENT", "CLASS" ], "nullable": true }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ACTIVE", "COMPLETED", "CANCELLED", "DRAFT", "REQUESTED", "PENDING_PAYMENT", "DECLINED", "EXPIRED" ] }, "approvalStatus": { "type": "string", "enum": [ "NOT_REQUIRED", "PENDING", "APPROVED", "DECLINED" ] }, "delivery": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingDeliverySelectionResponseDto" } ] }, "commerce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerCommerceDto" } ] }, "actions": { "$ref": "#/components/schemas/BookingCustomerActionsDto" }, "changeRequest": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerChangeRequestDto" } ] }, "pricingDetails": { "nullable": true, "description": "Read-only pricing evidence from the persisted current Commerce revision. Historical detail never resolves a live policy or recomputes a price.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PublicBookingPricingPresentationDto" } ] }, "quote": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/BookingCustomerDocumentDto" } ] }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/BookingCustomerDocumentDto" } }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/BookingCustomerContractDto" } }, "agreements": { "description": "Canonical native/external agreement history. Legacy contract packets remain projected separately.", "allOf": [ { "$ref": "#/components/schemas/CustomerAgreementHistoryResponseDto" } ] } }, "required": [ "id", "serviceName", "bookingType", "startsAt", "endsAt", "timezone", "quantity", "status", "approvalStatus", "delivery", "commerce", "actions", "changeRequest", "pricingDetails", "quote", "invoices", "contracts", "agreements" ] }, "CustomerBookingReasonDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "reason" ] }, "BookingChangeRequestResultDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "RESCHEDULE", "CANCEL" ] }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED", "WITHDRAWN" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "requiresMerchantReview": { "type": "boolean", "description": "Launch customer action endpoints submit a policy-checked request for merchant review." } }, "required": [ "type", "status", "requestedAt", "requiresMerchantReview" ] }, "BookingChangeRequestResponseDto": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/BookingCustomerDetailDto" }, "request": { "$ref": "#/components/schemas/BookingChangeRequestResultDto" } }, "required": [ "booking", "request" ] }, "CustomerBookingRescheduleRequestDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } }, "required": [ "reason", "startsAt", "endsAt" ] }, "BookingGroupRecoveryProofDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^b[a-z0-9]{25}$", "description": "Non-authorizing group correlation reference." }, "resumeToken": { "type": "string", "pattern": "^g[a-z0-9]{25}$", "description": "Fresh response-only scoped resume proof. The server persists only its SHA-256 digest." }, "resumeExpiresAt": { "format": "date-time", "type": "string" } }, "required": [ "publicRef", "resumeToken", "resumeExpiresAt" ] }, "CustomerBookingGroupMemberDto": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0 }, "callerReference": { "type": "string" }, "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string", "nullable": true }, "startsAt": { "format": "date-time", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "AGREEMENT_REQUIRED", "PENDING_REQUEST", "REQUESTED", "HELD", "PENDING_PAYMENT", "CONFIRMED", "DECLINED", "EXPIRED", "CANCELLED", "FAILED" ] } }, "required": [ "ordinal", "callerReference", "serviceId", "serviceName", "startsAt", "endsAt", "quantity", "status" ] }, "CustomerBookingGroupDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^b[a-z0-9]{25}$", "description": "Non-authorizing group correlation reference." }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_APPROVAL", "HELD", "AWAITING_PAYMENT", "CONFIRMING", "RECONCILIATION_REQUIRED", "CONFIRMED", "DECLINED", "EXPIRED", "CANCELLED", "FAILED" ] }, "settlementPosture": { "type": "string", "enum": [ "PAY_NOW", "APPROVE_THEN_PAY", "APPROVE_PAY_LATER" ] }, "currency": { "type": "string", "example": "USD" }, "expiresAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerBookingGroupMemberDto" } } }, "required": [ "publicRef", "status", "settlementPosture", "currency", "expiresAt", "createdAt", "members" ] }, "CustomerBookingGroupListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerBookingGroupDto" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 50 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "data", "page", "pageSize", "total" ] }, "ExchangeBookingGroupActionDto": { "type": "object", "properties": { "actionToken": { "type": "string", "pattern": "^a[a-z0-9]{25}$", "description": "Purpose-scoped booking-group recovery action token. It is transported in the request body, never in the URL." } }, "required": [ "actionToken" ], "additionalProperties": false }, "MerchantScheduledPlanChangeDto": { "type": "object", "properties": { "scheduledChangeRef": { "type": "string", "description": "Opaque, non-capability identity for this exact scheduled future-intent version. Submit it only in a scheduled-cancel JSON body.", "example": "sc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "pattern": "^sc_[a-f0-9]{64}$" }, "kind": { "type": "string", "enum": [ "CADENCE_CHANGE", "CANCELLATION" ] }, "targetPlan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ] }, "targetCadence": { "type": "string", "enum": [ "monthly", "yearly" ], "nullable": true }, "effectiveAt": { "type": "string", "format": "date-time" } }, "required": [ "scheduledChangeRef", "kind", "targetPlan", "targetCadence", "effectiveAt" ] }, "MerchantPlatformBillingOperationDto": { "type": "object", "properties": { "operationId": { "type": "string", "description": "Stable merchant-visible operation identity." }, "kind": { "type": "string", "enum": [ "CADENCE_CHANGE", "PLAN_CHANGE_PREPARATION", "CANCEL", "REACTIVATE", "CANCEL_SCHEDULED_CHANGE" ], "description": "`PLAN_CHANGE_PREPARATION` is a neutral merchant-safe projection of internal preparation that temporarily blocks another plan change; it does not identify the provider mechanism." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "AWAITING_PROVIDER_PAYMENT", "SUCCEEDED", "FAILED", "RECONCILIATION_REQUIRED" ] }, "targetPlan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ], "nullable": true, "description": "Requested destination plan, or null for neutral plan-change preparation." }, "targetCadence": { "type": "string", "enum": [ "monthly", "yearly" ], "nullable": true, "description": "Requested destination cadence, or null for neutral plan-change preparation." }, "effectiveAt": { "type": "string", "format": "date-time", "nullable": true }, "requestedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "operationId", "kind", "status", "targetPlan", "targetCadence", "effectiveAt", "requestedAt", "completedAt" ] }, "MerchantPlatformBillingTransitionDto": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "CHANGE_CADENCE", "CANCEL", "REACTIVATE", "CANCEL_SCHEDULED_CHANGE" ] }, "targetPlan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ], "nullable": true }, "targetCadence": { "type": "string", "enum": [ "monthly", "yearly" ], "nullable": true }, "timing": { "type": "string", "enum": [ "IMMEDIATE", "PERIOD_END" ] }, "requiresPreview": { "type": "boolean", "description": "Whether the action must first obtain a short-lived provider-authored preview and confirmation token." } }, "required": [ "action", "targetPlan", "targetCadence", "timing", "requiresPreview" ] }, "BillingStateDto": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ], "description": "The org's current platform plan." }, "status": { "type": "string", "enum": [ "NONE", "INCOMPLETE", "TRIALING", "ACTIVE", "PAST_DUE", "CANCELLED" ], "description": "Platform billing subscription status. `NONE` when the org has never started a platform subscription." }, "hasSubscription": { "type": "boolean", "description": "Whether a platform Stripe subscription is linked to this org." }, "cancelAtPeriodEnd": { "type": "boolean", "description": "Whether the subscription is set to cancel at the end of the current period (access retained until then)." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current billing period (ISO 8601), or null when there is no active subscription." }, "currentCadence": { "type": "string", "enum": [ "monthly", "yearly" ], "nullable": true, "description": "Cadence of the provider-confirmed current Pro price, or null when the organization has no proved current paid cadence." }, "scheduledChange": { "nullable": true, "description": "Current provider-confirmed period-end cadence change, or null when no paid transition is scheduled. This is future intent, not entitlement.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantScheduledPlanChangeDto" } ] }, "latestOperation": { "nullable": true, "description": "Latest merchant-safe operation projection. Provider correlation ids, staff identities, case notes, and recovery controls are never exposed. A live internal billing-mode migration appears only as neutral plan-change preparation; terminal internal migrations remain hidden.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantPlatformBillingOperationDto" } ] }, "availableTransitions": { "description": "Actions admitted by the current merchant-safe projection. Confirmation still performs a fresh, fail-closed provider and address check.", "type": "array", "items": { "$ref": "#/components/schemas/MerchantPlatformBillingTransitionDto" } }, "addressReady": { "type": "boolean", "description": "Whether the current billing-address version is confirmed at the provider and can be used for a confirmable quote." } }, "required": [ "plan", "status", "hasSubscription", "cancelAtPeriodEnd", "currentPeriodEnd", "currentCadence", "scheduledChange", "latestOperation", "availableTransitions", "addressReady" ] }, "MerchantPlanChangePreviewRequestDto": { "type": "object", "properties": { "targetCadence": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "yearly", "description": "Requested published Pro cadence. The active organization, current subscription, source price, and target price are all resolved server-side; provider identifiers are never accepted from the client." } }, "required": [ "targetCadence" ] }, "MerchantPlanChangeTaxDto": { "type": "object", "properties": { "amountInCents": { "type": "integer", "format": "int32" }, "taxBehavior": { "type": "string" }, "taxabilityReason": { "type": "string", "nullable": true }, "taxableAmountInCents": { "type": "integer", "format": "int32" }, "type": { "type": "string" } }, "required": [ "amountInCents", "taxBehavior", "taxabilityReason", "taxableAmountInCents", "type" ] }, "MerchantPlanChangeAutomaticTaxDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether Stripe Tax authored this preview." }, "status": { "type": "string" } }, "required": [ "enabled", "status" ] }, "MerchantPlanChangeMoneyDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotalInCents": { "type": "integer", "format": "int32" }, "totalInCents": { "type": "integer", "format": "int32" }, "amountDueInCents": { "type": "integer", "format": "int32", "minimum": 0 }, "totalTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPlanChangeTaxDto" } }, "automaticTax": { "$ref": "#/components/schemas/MerchantPlanChangeAutomaticTaxDto" } }, "required": [ "currency", "subtotalInCents", "totalInCents", "amountDueInCents", "totalTaxes", "automaticTax" ] }, "MerchantPlanChangePreviewDto": { "type": "object", "properties": { "currentPlan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ] }, "currentCadence": { "type": "string", "enum": [ "monthly", "yearly" ] }, "targetPlan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ] }, "targetCadence": { "type": "string", "enum": [ "monthly", "yearly" ] }, "direction": { "type": "string", "enum": [ "IMMEDIATE_MONTHLY_TO_YEARLY", "PERIOD_END_YEARLY_TO_MONTHLY" ] }, "timing": { "type": "string", "enum": [ "IMMEDIATE", "PERIOD_END" ] }, "effectiveAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Provider-fixed instant used for an immediate proration, or null for a period-end transition." }, "renewalAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Existing subscription renewal boundary for a period-end transition, or null for an immediate transition." }, "entitlementTiming": { "type": "string", "enum": [ "AFTER_PROVIDER_PAYMENT", "AT_PERIOD_END" ] }, "automaticRefund": { "type": "boolean", "enum": [ false ], "description": "Whether this ordinary self-serve transition automatically refunds unused time. The supported transition policy is false." }, "money": { "nullable": true, "description": "Stripe-authored immediate invoice and tax preview. Null for a period-end transition because no immediate invoice is created.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MerchantPlanChangeMoneyDto" } ] }, "quotedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "confirmationToken": { "type": "string", "pattern": "^q[a-z0-9]{25}$", "description": "Short-lived opaque confirmation token. It binds the exact fresh provider preview, subscription generation, scheduled intent, billing address version, authenticated Owner or Admin, and expiry without exposing those internal facts. The same authenticated user must confirm." } }, "required": [ "currentPlan", "currentCadence", "targetPlan", "targetCadence", "direction", "timing", "effectiveAt", "renewalAt", "entitlementTiming", "automaticRefund", "money", "quotedAt", "expiresAt", "confirmationToken" ] }, "MerchantPlanChangeConfirmRequestDto": { "type": "object", "properties": { "confirmationToken": { "type": "string", "description": "Short-lived, opaque confirmation token returned by preview. Send it only in this JSON body; never place it in a URL or log. The same authenticated Owner or Admin who requested the preview must confirm it; another user receives the neutral `REQUOTE_REQUIRED` response.", "example": "qaaaaaaaaaaaaaaaaaaaaaaaaa", "pattern": "^q[a-z0-9]{25}$" } }, "required": [ "confirmationToken" ] }, "MerchantScheduledPlanChangeCancelRequestDto": { "type": "object", "properties": { "scheduledChangeRef": { "type": "string", "description": "Opaque, non-capability reference from the exact scheduled change shown by the latest billing-state response. It identifies one internal future-intent version without exposing provider or mutation coordinates.", "example": "sc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "pattern": "^sc_[a-f0-9]{64}$" }, "cancellationRequestId": { "type": "string", "description": "Caller-generated canonical UUID-v4 for this cancellation intent. Reuse the same value only when recovering the same request; a new merchant action must use a new value.", "example": "7b7be394-fb9b-4d58-a444-147e15131900", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" } }, "required": [ "scheduledChangeRef", "cancellationRequestId" ] }, "MerchantBillingAddressDto": { "type": "object", "properties": { "address": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The stored address as-is, unvalidated. `{}` when the org has never set one, and possibly a legacy shape otherwise — read `usable`/`reason` rather than assuming the fields of a complete address are present.", "example": { "line1": "1120 S Rackham Way", "city": "Meridian", "state": "ID", "zip": "83642", "country": "US" } }, "usable": { "type": "boolean", "description": "True when this address is complete and in a supported jurisdiction, i.e. a subscribe would not be refused for tax reasons." }, "reason": { "type": "string", "nullable": true, "enum": [ "BILLING_ADDRESS_REQUIRED", "BILLING_ADDRESS_INVALID", "COUNTRY_NOT_SUPPORTED" ], "description": "Why the address is unusable, or `null` when it is usable." }, "supportedCountries": { "description": "ISO 3166-1 alpha-2 codes this platform can currently bill. Operator-maintained.", "example": [ "US" ], "type": "array", "items": { "type": "string" } } }, "required": [ "address", "usable", "reason", "supportedCountries" ] }, "UpdateMerchantBillingAddressDto": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/OrganizationAddressDto" } }, "required": [ "address" ] }, "SubscribeRequestDto": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "pro" ], "example": "pro", "description": "The self-serve plan to subscribe to. Only `pro` is accepted — Free needs no subscription and Enterprise is handled by sales." }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "monthly", "description": "Billing cadence for the subscription." }, "quoteId": { "type": "string", "description": "Opaque price-version quote from `/public/plan-pricing`. The subscribe mutation revalidates it against the fresh sellable CURRENT row.", "example": "ppq_v1_0123456789abcdef0123456789abcdef0123456789a", "pattern": "^ppq_v1_[A-Za-z0-9_-]{43}$" }, "currency": { "type": "string", "description": "Displayed ISO 4217 currency. Must exactly match the quoted CURRENT row.", "example": "usd", "pattern": "^[a-z]{3}$" }, "unitAmount": { "type": "integer", "format": "int32", "description": "Displayed price in minor currency units. Must exactly match the quoted CURRENT row.", "example": 9900, "minimum": 1 } }, "required": [ "plan", "cadence", "quoteId", "currency", "unitAmount" ] }, "SelectedPlatformPriceDto": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "Opaque identity of the selected price version." }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ] }, "currency": { "type": "string", "example": "usd" }, "unitAmount": { "type": "integer", "format": "int32", "example": 9900 } }, "required": [ "quoteId", "cadence", "currency", "unitAmount" ] }, "PlatformPaymentTermsDto": { "type": "object", "properties": { "amountDue": { "type": "integer", "format": "int32", "description": "Exact amount currently due on the invoice in minor currency units.", "example": 9900 }, "currency": { "type": "string", "description": "Invoice currency.", "example": "usd" }, "quoteId": { "type": "string", "nullable": true, "description": "Opaque identity of the subscription price when it maps to a known platform price version." }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ], "nullable": true }, "unitAmount": { "type": "integer", "format": "int32", "nullable": true } }, "required": [ "amountDue", "currency", "quoteId", "cadence", "unitAmount" ] }, "SubscribeResponseDto": { "type": "object", "properties": { "flow": { "type": "string", "enum": [ "new_subscription", "resume_payment" ], "description": "The explicit contract used. Recovery never adopts a newly selected cadence or public offer." }, "status": { "type": "string", "enum": [ "NONE", "INCOMPLETE", "TRIALING", "ACTIVE", "PAST_DUE", "CANCELLED" ], "description": "Platform billing status after the call. Typically `INCOMPLETE` until the first payment is confirmed (then the webhook advances it)." }, "stripeSubscriptionId": { "type": "string", "description": "The platform Stripe subscription id." }, "clientSecret": { "type": "string", "nullable": true, "description": "Stripe client secret for the first invoice — render the Payment Element against this. Null when there is nothing to confirm (a subscription was already active, or a $0 trial with no payment due). Forwarded to the browser only; never stored." }, "publishableKey": { "type": "string", "nullable": true, "description": "Browser-safe platform Stripe publishable key to initialize Stripe.js with (platform account — no `stripeAccount`). Null when there is no client secret to confirm. This is not a secret.", "example": "pk_test_123" }, "alreadyActive": { "type": "boolean", "description": "True when an active/trialing subscription already existed and was reused (no new subscription created, no payment needed)." }, "selectedPrice": { "nullable": true, "description": "Freshly validated CURRENT quote for a new sale. Null for recovery and for an already-active idempotent response.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SelectedPlatformPriceDto" } ] }, "paymentTerms": { "nullable": true, "description": "Authoritative current invoice terms shown before Payment Element is mounted. Null when there is no payment to confirm.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlatformPaymentTermsDto" } ] } }, "required": [ "flow", "status", "stripeSubscriptionId", "clientSecret", "publishableKey", "alreadyActive", "selectedPrice", "paymentTerms" ] }, "BillingCancellationDto": { "type": "object", "properties": { "cancelAtPeriodEnd": { "type": "boolean", "description": "Whether the subscription is now scheduled to end at the current period's end. True after cancel, false after resume." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current billing period (ISO 8601) — the date access ends when `cancelAtPeriodEnd` is true. Null when Stripe reported no period end." }, "status": { "type": "string", "enum": [ "NONE", "INCOMPLETE", "TRIALING", "ACTIVE", "PAST_DUE", "CANCELLED" ], "description": "Platform billing status. Scheduling a cancellation does NOT change this — the subscription remains ACTIVE until the period boundary." }, "unchanged": { "type": "boolean", "description": "MIRROR-DELTA: true when the state Stripe reported back matches what the local mirror held when the request started — i.e. nothing differs from the state you last read. It is NOT a provider-delta: establishing that would require retrieving the subscription before every update, doubling the Stripe calls on a money path for a cosmetic flag. Concretely: if the MIRROR already held the value you asked for while Stripe differed, this reads `true` even though the provider row did change. It can never mean \"we silently failed to apply your change\" — Stripe is always called, and a failure surfaces as 4xx/503 instead." } }, "required": [ "cancelAtPeriodEnd", "currentPeriodEnd", "status", "unchanged" ] }, "StartPaymentMethodUpdateDto": { "type": "object", "properties": { "setupIntentId": { "type": "string", "description": "SetupIntent id to pass back to the confirm route once the Payment Element reports success." }, "clientSecret": { "type": "string", "nullable": true, "description": "Payment Element client secret for confirming the new card. A bearer credential for this SetupIntent — do not log it or place it in a shared cache." }, "publishableKey": { "type": "string", "nullable": true, "description": "The PLATFORM account's publishable key. The Payment Element renders WITHOUT a `stripeAccount`, because this card pays litecommerce rather than the tenant's own connected account." } }, "required": [ "setupIntentId", "clientSecret", "publishableKey" ] }, "ConfirmPaymentMethodUpdateRequestDto": { "type": "object", "properties": { "setupIntentId": { "type": "string", "description": "The SetupIntent id returned when the update was started. The server retrieves it from Stripe and refuses unless it succeeded AND belongs to this organization's own billing customer — the id alone proves nothing." } }, "required": [ "setupIntentId" ] }, "ConfirmPaymentMethodUpdateDto": { "type": "object", "properties": { "paymentMethodId": { "type": "string", "description": "The payment method now set as the subscription default. Renewals bill this card from here on." } }, "required": [ "paymentMethodId" ] }, "BillingInvoiceDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stripe invoice id (`in_…`)." }, "status": { "type": "string", "nullable": true, "description": "Stripe invoice status — `draft`, `open`, `paid`, `uncollectible`, or `void`." }, "amountDueInCents": { "type": "number", "nullable": true, "description": "Amount due in minor units." }, "amountPaidInCents": { "type": "number", "nullable": true, "description": "Amount actually paid in minor units." }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 code." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Invoice creation time (ISO 8601)." }, "periodStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Start of the period this invoice covers (ISO 8601)." }, "periodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the period this invoice covers (ISO 8601)." }, "hostedInvoiceUrl": { "type": "string", "nullable": true, "description": "Stripe-hosted invoice page. A SIGNED, UNAUTHENTICATED URL — treat it as a credential: do not log it, embed it in a shared cache, or expose it to anyone but this merchant. Null for a draft invoice." }, "invoicePdfUrl": { "type": "string", "nullable": true, "description": "Stripe-hosted PDF receipt. Same signed-URL handling as `hostedInvoiceUrl`. Null for a draft invoice." } }, "required": [ "id", "status", "amountDueInCents", "amountPaidInCents", "currency", "createdAt", "periodStart", "periodEnd", "hostedInvoiceUrl", "invoicePdfUrl" ] }, "BillingInvoiceListDto": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoiceDto" } }, "hasMore": { "type": "boolean", "description": "Whether more invoices exist after this page." }, "nextStartingAfter": { "type": "string", "nullable": true, "description": "Pass as `startingAfter` to fetch the next page. Null when the history is complete or Stripe returned no safe cursor." } }, "required": [ "invoices", "hasMore", "nextStartingAfter" ] }, "CustomerSubscriptionPlanSummaryDto": { "type": "object", "properties": { "slug": { "type": "string", "description": "Customer-facing plan slug. This is not a database id." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "planType": { "type": "string", "enum": [ "PRODUCT", "MEMBERSHIP", "SERVICE_ACCESS" ] }, "requiresShipping": { "type": "boolean", "description": "Whether recurring fulfillment needs a shipping address." } }, "required": [ "slug", "name", "description", "planType", "requiresShipping" ] }, "CustomerSubscriptionSummaryDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^s[0-9a-f]{32}$", "example": "s0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe subscription handle." }, "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] }, "cancelAtPeriodEnd": { "type": "boolean", "description": "True when the subscription remains active through its current period and then ends." }, "currentPeriodStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "trialStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "trialEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "pausedAt": { "type": "string", "format": "date-time", "nullable": true }, "canceledAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "nextRenewalAt": { "type": "string", "format": "date-time", "nullable": true }, "gracePeriodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionPlanSummaryDto" } } }, "required": [ "publicRef", "status", "cancelAtPeriodEnd", "currentPeriodStartsAt", "currentPeriodEndsAt", "trialStartsAt", "trialEndsAt", "pausedAt", "canceledAt", "endedAt", "nextRenewalAt", "gracePeriodEndsAt", "createdAt", "updatedAt", "plans" ] }, "CustomerSubscriptionListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionSummaryDto" } }, "nextCursor": { "type": "string", "nullable": true, "pattern": "^s[0-9a-f]{32}$", "description": "Opaque cursor for the next page, or null on the final page." } }, "required": [ "data", "nextCursor" ] }, "CustomerSubscriptionPriceDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd", "description": "Lowercase ISO 4217 currency code." }, "unitAmountInCents": { "type": "integer", "minimum": 0, "description": "Recurring unit amount in the currency minor unit." }, "interval": { "type": "string", "enum": [ "DAY", "WEEK", "MONTH", "YEAR" ] }, "intervalCount": { "type": "integer", "minimum": 1 } }, "required": [ "currency", "unitAmountInCents", "interval", "intervalCount" ] }, "CustomerSubscriptionItemDto": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/CustomerSubscriptionPlanSummaryDto" }, "price": { "$ref": "#/components/schemas/CustomerSubscriptionPriceDto" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "plan", "price", "quantity" ] }, "CustomerSubscriptionRenewalAddressDto": { "type": "object", "properties": { "country": { "type": "string", "description": "Uppercase ISO 3166-1 alpha-2 country code.", "example": "US" }, "company": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true } }, "required": [ "country", "company", "state", "city", "postalCode", "line1", "line2" ] }, "CustomerSubscriptionPaymentRecoverySummaryDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PAYMENT_FAILED", "RETRY_SCHEDULED", "ACTION_REQUIRED", "RECOVERED", "EXHAUSTED" ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": "string", "format": "date-time", "nullable": true }, "customerMessage": { "type": "string", "nullable": true, "description": "Customer-safe explanation. Raw provider failure text is never exposed." }, "needsCustomerAction": { "type": "boolean", "description": "Whether the current normalized recovery state can benefit from customer action." }, "resolvedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "attemptCount", "nextRetryAt", "customerMessage", "needsCustomerAction", "resolvedAt" ] }, "CustomerSubscriptionDetailDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^s[0-9a-f]{32}$", "example": "s0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe subscription handle." }, "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] }, "cancelAtPeriodEnd": { "type": "boolean", "description": "True when the subscription remains active through its current period and then ends." }, "currentPeriodStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "trialStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "trialEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "pausedAt": { "type": "string", "format": "date-time", "nullable": true }, "canceledAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "nextRenewalAt": { "type": "string", "format": "date-time", "nullable": true }, "gracePeriodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionPlanSummaryDto" } }, "items": { "description": "Active recurring items only.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionItemDto" } }, "renewalShippingAddress": { "nullable": true, "description": "Sanitized subscription-specific shipping snapshot.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CustomerSubscriptionRenewalAddressDto" } ] }, "renewalBillingAddress": { "nullable": true, "description": "Sanitized subscription-specific billing snapshot.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CustomerSubscriptionRenewalAddressDto" } ] }, "latestPaymentRecovery": { "nullable": true, "description": "Latest normalized payment-recovery cycle, when one exists. Use the dedicated recovery API for the complete projection.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoverySummaryDto" } ] } }, "required": [ "publicRef", "status", "cancelAtPeriodEnd", "currentPeriodStartsAt", "currentPeriodEndsAt", "trialStartsAt", "trialEndsAt", "pausedAt", "canceledAt", "endedAt", "nextRenewalAt", "gracePeriodEndsAt", "createdAt", "updatedAt", "plans", "items", "renewalShippingAddress", "renewalBillingAddress", "latestPaymentRecovery" ] }, "CustomerSubscriptionReactivationDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^s[0-9a-f]{32}$", "example": "s0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe subscription handle." }, "status": { "type": "string", "enum": [ "ACTIVE", "TRIALING" ], "description": "The restored provider-backed lifecycle state." }, "cancelAtPeriodEnd": { "type": "boolean", "enum": [ false ], "description": "Always false after the scheduled period-end cancellation is cleared." }, "completedAt": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean", "description": "True when this response replays an already-completed idempotent command." }, "message": { "type": "string", "example": "Your subscription will renew as scheduled." } }, "required": [ "publicRef", "status", "cancelAtPeriodEnd", "completedAt", "replayed", "message" ] }, "CustomerSubscriptionBillingPeriodDto": { "type": "object", "properties": { "publicRef": { "type": "string", "pattern": "^h[0-9a-f]{32}$", "example": "h0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe billing-period handle." }, "status": { "type": "string", "enum": [ "OPEN", "PAID", "FAILED", "VOID", "CREDITED" ] }, "periodStartsAt": { "type": "string", "format": "date-time", "nullable": true }, "periodEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "amountDueInCents": { "type": "integer", "minimum": 0, "nullable": true }, "amountPaidInCents": { "type": "integer", "minimum": 0, "nullable": true }, "currency": { "type": "string", "nullable": true, "example": "usd" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "publicRef", "status", "periodStartsAt", "periodEndsAt", "amountDueInCents", "amountPaidInCents", "currency", "createdAt", "updatedAt" ] }, "CustomerSubscriptionBillingPeriodListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionBillingPeriodDto" } }, "nextCursor": { "type": "string", "nullable": true, "pattern": "^h[0-9a-f]{32}$", "description": "Opaque cursor for the next page, or null on the final page." } }, "required": [ "data", "nextCursor" ] }, "ExchangeSubscriptionPaymentRecoveryActionDto": { "type": "object", "properties": { "actionToken": { "type": "string", "pattern": "^a[a-z0-9]{25}$", "description": "Opaque action from the URL fragment. It is exchanged in a POST body and never belongs in a route or query string." } }, "required": [ "actionToken" ] }, "SubscriptionPaymentRecoveryProofDto": { "type": "object", "properties": { "recoveryId": { "type": "string", "description": "Local recovery-cycle correlation id." }, "paymentToken": { "type": "string", "pattern": "^p[a-z0-9]{25}$", "description": "Short-lived scoped proof. Hosted clients place it in an httpOnly cookie and never render or persist it." }, "paymentTokenExpiresAt": { "type": "string" } }, "required": [ "recoveryId", "paymentToken", "paymentTokenExpiresAt" ] }, "CustomerSubscriptionPaymentRecoveryResendRequestDto": { "type": "object", "properties": { "actionToken": { "type": "string", "pattern": "^a[a-z0-9]{25}$", "description": "Opaque action from the prior URL fragment. It authorizes only a neutral resend request and never belongs in a route or query string." } }, "required": [ "actionToken" ] }, "CustomerSubscriptionPaymentRecoveryResendDto": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Neutral confirmation shared by eligible, unknown, malformed, expired, revoked, consumed, exhausted, wrong-purpose, terminal, and cross-tenant actions." } }, "required": [ "ok", "message" ] }, "SubscriptionPaymentRecoverySubscriptionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Local subscription id." }, "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] }, "planNames": { "description": "Display names of the plans on this subscription.", "type": "array", "items": { "type": "string" } }, "currentPeriodEndsAt": { "type": "string", "nullable": true }, "nextRenewalAt": { "type": "string", "nullable": true } }, "required": [ "id", "status", "planNames", "currentPeriodEndsAt", "nextRenewalAt" ] }, "SubscriptionPaymentRecoveryBillingPeriodDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPEN", "PAID", "FAILED", "VOID", "CREDITED" ] }, "amountDueInCents": { "type": "number", "nullable": true }, "amountPaidInCents": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true, "example": "usd" }, "periodStartsAt": { "type": "string", "nullable": true }, "periodEndsAt": { "type": "string", "nullable": true }, "fulfillmentEligible": { "type": "boolean", "description": "True only after authoritative invoice payment. A confirmed physical-renewal fulfillment must not be created or presented when false." } }, "required": [ "status", "amountDueInCents", "amountPaidInCents", "currency", "periodStartsAt", "periodEndsAt", "fulfillmentEligible" ] }, "CustomerSubscriptionPaymentRecoveryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Local payment-recovery cycle id." }, "status": { "type": "string", "enum": [ "PAYMENT_FAILED", "RETRY_SCHEDULED", "ACTION_REQUIRED", "RECOVERED", "EXHAUSTED" ] }, "terminalAction": { "type": "string", "enum": [ "UNPAID", "CANCEL", "SUSPEND", "MANUAL_RECOVERY" ], "nullable": true, "description": "Effective exhausted-recovery result. Null until a terminal decision is selected." }, "terminalEntitlementBehavior": { "type": "string", "enum": [ "LAPSE_IMMEDIATELY", "FREEZE_BALANCES" ], "nullable": true, "description": "Snapshotted terminal balance treatment. It never grants unpaid access." }, "terminalSelfServeRecovery": { "type": "boolean", "nullable": true, "description": "Snapshotted tenant opt-in for customer self-serve terminal revival." }, "terminalActionAppliedAt": { "type": "string", "nullable": true }, "subscription": { "$ref": "#/components/schemas/SubscriptionPaymentRecoverySubscriptionDto" }, "billingPeriod": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryBillingPeriodDto" }, "attemptCount": { "type": "number", "minimum": 0 }, "nextRetryAt": { "type": "string", "nullable": true }, "failureVersion": { "type": "string", "nullable": true, "description": "Opaque replay-stable version for the currently projected failure." }, "customerMessage": { "type": "string", "nullable": true, "description": "Customer-safe explanation; raw provider text is never projected here." }, "needsCustomerAction": { "type": "boolean", "description": "Whether the current recovery state can benefit from customer action." }, "resolvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "terminalAction", "terminalEntitlementBehavior", "terminalSelfServeRecovery", "terminalActionAppliedAt", "subscription", "billingPeriod", "attemptCount", "nextRetryAt", "failureVersion", "customerMessage", "needsCustomerAction", "resolvedAt", "createdAt", "updatedAt" ] }, "SubscriptionPaymentRecoveryActionResponseDto": { "type": "object", "properties": { "recovery": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryDto" } }, "required": [ "recovery" ] }, "SubscriptionPaymentRecoveryHandoffDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PAYMENT", "WAITING", "RECOVERED" ] }, "clientSecret": { "type": "string", "nullable": true, "description": "Existing failed-invoice PaymentIntent client secret. Never persisted." }, "publishableKey": { "type": "string", "nullable": true }, "stripeAccountId": { "type": "string", "nullable": true, "description": "Persisted connected-account id required when initializing Stripe.js." }, "amountInCents": { "type": "number", "nullable": true, "minimum": 0 }, "currency": { "type": "string", "nullable": true, "example": "usd" }, "failureVersion": { "type": "string", "nullable": true, "description": "Opaque failure version captured before this confirmation attempt." } }, "required": [ "type", "clientSecret", "publishableKey", "stripeAccountId", "amountInCents", "currency", "failureVersion" ] }, "SubscriptionPaymentRecoveryPaymentResponseDto": { "type": "object", "properties": { "recovery": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryDto" }, "handoff": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryHandoffDto" } }, "required": [ "recovery", "handoff" ] }, "CustomerSubscriptionPaymentRecoveryListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSubscriptionPaymentRecoveryDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the final page." } }, "required": [ "data", "nextCursor" ] }, "MerchantResendSubscriptionPaymentRecoveryDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200, "description": "Stable client-generated key. Retrying with the same key replays the original outcome and sends no second reminder; reusing it for a different recovery returns 409." } }, "required": [ "idempotencyKey" ] }, "MerchantSubscriptionPaymentRecoveryResendDto": { "type": "object", "properties": { "recoveryId": { "type": "string" }, "notificationGeneration": { "type": "number", "description": "Delivery generation this command queued (or replayed)." }, "replayed": { "type": "boolean", "description": "True when this request replayed an earlier one and no new reminder was sent." }, "lastNotifiedAt": { "type": "string", "nullable": true }, "resendsRemainingInWindow": { "type": "number", "description": "Staff resends still allowed inside the current rolling window." }, "resendAvailableAt": { "type": "string", "nullable": true, "description": "When another resend becomes available; null when one is available now." } }, "required": [ "recoveryId", "notificationGeneration", "replayed", "lastNotifiedAt", "resendsRemainingInWindow", "resendAvailableAt" ] }, "MerchantPaymentRecoveryCustomerDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Local customer id." }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name" ] }, "MerchantSubscriptionPaymentRecoveryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Local payment-recovery cycle id." }, "status": { "type": "string", "enum": [ "PAYMENT_FAILED", "RETRY_SCHEDULED", "ACTION_REQUIRED", "RECOVERED", "EXHAUSTED" ] }, "terminalAction": { "type": "string", "enum": [ "UNPAID", "CANCEL", "SUSPEND", "MANUAL_RECOVERY" ], "nullable": true, "description": "Effective exhausted-recovery result. Null until a terminal decision is selected." }, "terminalEntitlementBehavior": { "type": "string", "enum": [ "LAPSE_IMMEDIATELY", "FREEZE_BALANCES" ], "nullable": true, "description": "Snapshotted terminal balance treatment. It never grants unpaid access." }, "terminalSelfServeRecovery": { "type": "boolean", "nullable": true, "description": "Snapshotted tenant opt-in for customer self-serve terminal revival." }, "terminalActionAppliedAt": { "type": "string", "nullable": true }, "subscription": { "$ref": "#/components/schemas/SubscriptionPaymentRecoverySubscriptionDto" }, "billingPeriod": { "$ref": "#/components/schemas/SubscriptionPaymentRecoveryBillingPeriodDto" }, "attemptCount": { "type": "number", "minimum": 0 }, "nextRetryAt": { "type": "string", "nullable": true }, "failureVersion": { "type": "string", "nullable": true, "description": "Opaque replay-stable version for the currently projected failure." }, "customerMessage": { "type": "string", "nullable": true, "description": "Customer-safe explanation; raw provider text is never projected here." }, "needsCustomerAction": { "type": "boolean", "description": "Whether the current recovery state can benefit from customer action." }, "resolvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "customer": { "$ref": "#/components/schemas/MerchantPaymentRecoveryCustomerDto" }, "failureCode": { "type": "string", "nullable": true, "description": "Latest bounded provider failure code for merchant diagnostics." }, "failureMessage": { "type": "string", "nullable": true, "description": "Latest bounded provider failure message for merchant diagnostics." }, "terminalConfiguredAction": { "type": "string", "enum": [ "UNPAID", "CANCEL", "SUSPEND", "MANUAL_RECOVERY" ], "nullable": true, "description": "Terminal action configured by the tenant before provider precedence is applied." }, "terminalActionSource": { "type": "string", "enum": [ "TENANT_POLICY", "PROVIDER_PREEMPTED" ], "nullable": true, "description": "Whether tenant policy applied or an irreversible provider result pre-empted it." }, "terminalActionClaimedAt": { "type": "string", "nullable": true }, "terminalActionAttemptCount": { "type": "number", "minimum": 0 }, "terminalActionLastAttemptAt": { "type": "string", "nullable": true }, "terminalActionLastError": { "type": "string", "nullable": true, "description": "Latest bounded terminal-application failure for operators." }, "lastNotifiedAt": { "type": "string", "nullable": true, "description": "When the customer was last successfully sent a reminder." }, "resendsRemainingInWindow": { "type": "number", "description": "Staff resends still allowed inside the current rolling window. Automatic reminders never consume it." }, "resendAvailableAt": { "type": "string", "nullable": true, "description": "When another staff resend becomes available; null when one is available now." }, "resendBlockedReason": { "type": "string", "nullable": true, "enum": [ "COOLDOWN", "RECOVERY_NOT_OPEN" ], "description": "Why a resend is currently unavailable, or null when it is available." } }, "required": [ "id", "status", "terminalAction", "terminalEntitlementBehavior", "terminalSelfServeRecovery", "terminalActionAppliedAt", "subscription", "billingPeriod", "attemptCount", "nextRetryAt", "failureVersion", "customerMessage", "needsCustomerAction", "resolvedAt", "createdAt", "updatedAt", "customer", "failureCode", "failureMessage", "terminalConfiguredAction", "terminalActionSource", "terminalActionClaimedAt", "terminalActionAttemptCount", "terminalActionLastAttemptAt", "terminalActionLastError", "lastNotifiedAt", "resendsRemainingInWindow", "resendAvailableAt", "resendBlockedReason" ] }, "MerchantSubscriptionPaymentRecoveryListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantSubscriptionPaymentRecoveryDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the final page." } }, "required": [ "data", "nextCursor" ] }, "CustomerAccountEntitlementSubscriptionSummaryDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] }, "posture": { "type": "string", "enum": [ "active", "grace", "frozen", "expired", "terminal", "never_activated", "no_window" ], "description": "Why this subscription does (or does not) contribute honored entitlements right now, derived from lifecycle status + tenant policy." }, "windowKey": { "type": "string", "nullable": true, "description": "Deterministic identity of the current grant window." }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "graceUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "Honor boundary when the posture is `grace`." }, "publicRef": { "type": "string", "pattern": "^s[0-9a-f]{32}$", "example": "s0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe subscription handle. Correlation only; not authorization." } }, "required": [ "status", "posture", "windowKey", "currentPeriodStart", "currentPeriodEnd", "graceUntil", "publicRef" ] }, "CustomerAccountEntitlementEntryDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Plan-authored capability key." }, "entitlementType": { "type": "string", "enum": [ "ACCESS", "DISCOUNT", "ALLOWANCE", "SERVICE_CREDIT", "LIMIT_OVERRIDE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "GRACE", "EXPIRED", "REVOKED", "FROZEN" ], "description": "The status this grant EFFECTIVELY has right now, derived from live subscription state + tenant policy (the projection converges the stored row onto the same answer)." }, "honored": { "type": "boolean", "description": "True only for ACTIVE / GRACE — the sole statuses a caller may honor. Display truth, never authorization for a mutation." }, "windowKey": { "type": "string", "description": "Grant window identity." }, "effectiveFrom": { "type": "string", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "format": "date-time", "nullable": true }, "graceUntil": { "type": "string", "format": "date-time", "nullable": true }, "percentOff": { "type": "number", "nullable": true }, "amountOffInCents": { "type": "number", "nullable": true }, "unitLabel": { "type": "string", "nullable": true }, "unitsGranted": { "type": "number", "nullable": true, "description": "Window balance fields — ALLOWANCE / SERVICE_CREDIT only." }, "unitsConsumed": { "type": "number", "nullable": true }, "unitsRemaining": { "type": "number", "nullable": true }, "limitKey": { "type": "string", "nullable": true }, "limitValue": { "type": "number", "nullable": true }, "issue": { "type": "string", "nullable": true, "enum": [ "invalid_config", "rollover_policy_unset" ], "description": "Fail-closed reason this entry cannot be honored (mirrors the projection’s operator-actionable reconciliation states)." }, "subscriptionPublicRef": { "type": "string", "pattern": "^s[0-9a-f]{32}$", "example": "s0123456789abcdef0123456789abcdef", "description": "Opaque customer-safe handle for the subscription that produced this grant. Correlation only; not authorization." } }, "required": [ "key", "entitlementType", "status", "honored", "windowKey", "effectiveFrom", "effectiveTo", "graceUntil", "percentOff", "amountOffInCents", "unitLabel", "unitsGranted", "unitsConsumed", "unitsRemaining", "limitKey", "limitValue", "issue", "subscriptionPublicRef" ] }, "EntitlementDiscountDto": { "type": "object", "properties": { "percentOff": { "type": "number", "nullable": true, "description": "Discount in basis points (1–10000), when percentage-based." }, "amountOffInCents": { "type": "number", "nullable": true, "description": "Fixed discount in cents, when amount-based." } }, "required": [ "percentOff", "amountOffInCents" ] }, "EffectiveEntitlementDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Plan-authored capability key." }, "entitlementType": { "type": "string", "enum": [ "ACCESS", "DISCOUNT", "ALLOWANCE", "SERVICE_CREDIT", "LIMIT_OVERRIDE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "GRACE" ], "description": "Honor ceiling across sources: ACTIVE beats GRACE." }, "graceUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest honor boundary when every source is in GRACE." }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementDiscountDto" } }, "unitsRemaining": { "type": "number", "nullable": true, "description": "Remaining units summed across honored windows." }, "unitLabel": { "type": "string", "nullable": true }, "limitKey": { "type": "string", "nullable": true }, "limitValue": { "type": "number", "nullable": true, "description": "Highest honored override for the key." } }, "required": [ "key", "entitlementType", "status", "graceUntil", "discounts", "unitsRemaining", "unitLabel", "limitKey", "limitValue" ] }, "CustomerAccountEntitlementsResponseDto": { "type": "object", "properties": { "evaluatedAt": { "type": "string", "format": "date-time" }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEntitlementSubscriptionSummaryDto" } }, "entries": { "description": "Every current-window grant, honored or not.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEntitlementEntryDto" } }, "effective": { "description": "Only honored capabilities, rolled up per key.", "type": "array", "items": { "$ref": "#/components/schemas/EffectiveEntitlementDto" } } }, "required": [ "evaluatedAt", "subscriptions", "entries", "effective" ] }, "EntitlementSubscriptionSummaryDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Local subscription identifier for merchant and server-to-server reads." }, "status": { "type": "string", "enum": [ "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCEL_AT_PERIOD_END", "CANCELED", "UNPAID" ] }, "posture": { "type": "string", "enum": [ "active", "grace", "frozen", "expired", "terminal", "never_activated", "no_window" ], "description": "Why this subscription does (or does not) contribute honored entitlements right now, derived from lifecycle status + tenant policy." }, "windowKey": { "type": "string", "nullable": true, "description": "Deterministic identity of the current grant window." }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "graceUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "Honor boundary when the posture is `grace`." } }, "required": [ "subscriptionId", "status", "posture", "windowKey", "currentPeriodStart", "currentPeriodEnd", "graceUntil" ] }, "EntitlementEntryDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Plan-authored capability key." }, "entitlementType": { "type": "string", "enum": [ "ACCESS", "DISCOUNT", "ALLOWANCE", "SERVICE_CREDIT", "LIMIT_OVERRIDE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "GRACE", "EXPIRED", "REVOKED", "FROZEN" ], "description": "The status this grant EFFECTIVELY has right now, derived from live subscription state + tenant policy (the projection converges the stored row onto the same answer)." }, "honored": { "type": "boolean", "description": "True only for ACTIVE / GRACE — the sole statuses a caller may honor. Display truth, never authorization for a mutation." }, "subscriptionId": { "type": "string", "description": "Local subscription identifier for merchant and server-to-server reads." }, "windowKey": { "type": "string", "description": "Grant window identity." }, "effectiveFrom": { "type": "string", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "format": "date-time", "nullable": true }, "graceUntil": { "type": "string", "format": "date-time", "nullable": true }, "percentOff": { "type": "number", "nullable": true }, "amountOffInCents": { "type": "number", "nullable": true }, "unitLabel": { "type": "string", "nullable": true }, "unitsGranted": { "type": "number", "nullable": true, "description": "Window balance fields — ALLOWANCE / SERVICE_CREDIT only." }, "unitsConsumed": { "type": "number", "nullable": true }, "unitsRemaining": { "type": "number", "nullable": true }, "limitKey": { "type": "string", "nullable": true }, "limitValue": { "type": "number", "nullable": true }, "issue": { "type": "string", "nullable": true, "enum": [ "invalid_config", "rollover_policy_unset" ], "description": "Fail-closed reason this entry cannot be honored (mirrors the projection’s operator-actionable reconciliation states)." } }, "required": [ "key", "entitlementType", "status", "honored", "subscriptionId", "windowKey", "effectiveFrom", "effectiveTo", "graceUntil", "percentOff", "amountOffInCents", "unitLabel", "unitsGranted", "unitsConsumed", "unitsRemaining", "limitKey", "limitValue", "issue" ] }, "CustomerEntitlementsResponseDto": { "type": "object", "properties": { "evaluatedAt": { "type": "string", "format": "date-time" }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementSubscriptionSummaryDto" } }, "entries": { "description": "Every current-window grant, honored or not.", "type": "array", "items": { "$ref": "#/components/schemas/EntitlementEntryDto" } }, "effective": { "description": "Only honored capabilities, rolled up per key.", "type": "array", "items": { "$ref": "#/components/schemas/EffectiveEntitlementDto" } } }, "required": [ "evaluatedAt", "subscriptions", "entries", "effective" ] }, "EntitlementCheckResponseDto": { "type": "object", "properties": { "key": { "type": "string", "description": "The checked entitlement key." }, "honored": { "type": "boolean", "description": "Authoritative live answer — true only when the key is honored for this customer at this instant." }, "checkedAt": { "type": "string", "format": "date-time" }, "matches": { "description": "Every honored compatible-definition rollup for the key (keys are plan-local — one key can name several distinct definitions). Empty when not honored.", "type": "array", "items": { "$ref": "#/components/schemas/EffectiveEntitlementDto" } } }, "required": [ "key", "honored", "checkedAt", "matches" ] }, "ConsumeEntitlementDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Plan-authored entitlement key to consume from.", "example": "monthly-washes" }, "units": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Units to consume from the current window." }, "idempotencyKey": { "type": "string", "description": "Caller-chosen replay key, scoped to the customer. Retrying with the same key returns the recorded outcome without consuming again — even after windows advanced or the entitlement stopped being honored; reusing it with a different request is rejected (409 ENTITLEMENT_NOT_CONSUMABLE / IDEMPOTENCY_CONFLICT).", "minLength": 1, "maxLength": 200 }, "entitlementType": { "type": "string", "enum": [ "ALLOWANCE", "SERVICE_CREDIT" ], "description": "Disambiguator: keys are plan-local, so one key may name several distinct balance definitions. Required (with or `unitLabel`) when the request would otherwise be ambiguous (409 AMBIGUOUS_DEFINITION)." }, "unitLabel": { "type": "string", "maxLength": 40, "description": "Disambiguator: restricts consumption to the definition carrying this unit label." } }, "required": [ "key", "units", "idempotencyKey" ] }, "EntitlementConsumptionResponseDto": { "type": "object", "properties": { "key": { "type": "string" }, "entitlementType": { "type": "string", "enum": [ "ALLOWANCE", "SERVICE_CREDIT" ] }, "subscriptionId": { "type": "string" }, "windowKey": { "type": "string" }, "unitsConsumed": { "type": "number", "description": "Units THIS request consumed (0 on a replayed request)." }, "unitsGranted": { "type": "number" }, "unitsConsumedTotal": { "type": "number", "description": "Total consumed on the window after this request." }, "unitsRemaining": { "type": "number" }, "consumedAt": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean", "description": "True when the idempotency key had already consumed — the recorded outcome was returned and no new units were spent." } }, "required": [ "key", "entitlementType", "subscriptionId", "windowKey", "unitsConsumed", "unitsGranted", "unitsConsumedTotal", "unitsRemaining", "consumedAt", "replayed" ] }, "EntitlementDisplayTokenResponseDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Signed JWS compact token (alg EdDSA / Ed25519) over the customer’s effective entitlements. READ/DISPLAY ONLY — the API never accepts it as authorization; verify against the published JWKS." }, "expiresAt": { "type": "string", "format": "date-time" }, "kid": { "type": "string", "description": "Key id the token was signed with." }, "algorithm": { "type": "string", "enum": [ "EdDSA" ] }, "jwksPath": { "type": "string", "description": "Where the verification keys are published.", "example": "/api/v1/public/entitlement-tokens/jwks" } }, "required": [ "token", "expiresAt", "kid", "algorithm", "jwksPath" ] }, "EntitlementTokenJwkDto": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "OKP" ] }, "crv": { "type": "string", "enum": [ "Ed25519" ] }, "x": { "type": "string", "description": "base64url raw Ed25519 public key." }, "kid": { "type": "string" }, "alg": { "type": "string", "enum": [ "EdDSA" ] }, "use": { "type": "string", "enum": [ "sig" ] } }, "required": [ "kty", "crv", "x", "kid", "alg", "use" ] }, "EntitlementTokenJwksResponseDto": { "type": "object", "properties": { "keys": { "description": "Empty when token signing is not configured in this environment (verifiers fail closed).", "type": "array", "items": { "$ref": "#/components/schemas/EntitlementTokenJwkDto" } } }, "required": [ "keys" ] }, "Plan": { "type": "string", "enum": [ "FREE_TRIAL", "PRO", "ENTERPRISE" ], "description": "Plan to price. Only PRO is self-serve priceable today." }, "PublishedPlanPriceDto": { "type": "object", "properties": { "plan": { "description": "The platform plan this price is for.", "allOf": [ { "$ref": "#/components/schemas/Plan" } ] }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ], "description": "Billing cadence." }, "currency": { "type": "string", "description": "ISO 4217 currency code, lowercase.", "example": "usd" }, "unitAmount": { "type": "integer", "format": "int32", "description": "Price in the currency's smallest (minor) unit — e.g. 9900 = $99.00 for USD cents. Do not assume a fixed /100 divisor: zero-decimal currencies (e.g. JPY) have no minor unit; apply the currency's own decimal rules.", "example": 9900 }, "displayLabel": { "type": "string", "description": "Optional human-readable label for the price.", "nullable": true }, "quoteId": { "type": "string", "description": "Opaque identity of this exact published price version. Not a Stripe or database id. Send it back with amount/currency when subscribing; stale quotes are rejected before any subscription mutation.", "example": "ppq_v1_0123456789abcdef0123456789abcdef0123456789a", "pattern": "^ppq_v1_[A-Za-z0-9_-]{43}$" } }, "required": [ "plan", "cadence", "currency", "unitAmount", "displayLabel", "quoteId" ] }, "ApiSchemaIdentityDto": { "type": "object", "properties": { "schemaDigest": { "type": "string", "description": "Content digest of the public OpenAPI document this build was generated from, as `sha256:<64 lowercase hex>`. Identical to `info.version` in the published API reference when that reference describes this runtime. Computed over the whole generated document except `servers` (environment presentation, rewritten per publication target) and `info.version` itself. Compare the two strings verbatim — the value is opaque and carries no ordering, so \"newer\" and \"older\" are not decidable from it.", "example": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "pattern": "^sha256:[0-9a-f]{64}$" } }, "required": [ "schemaDigest" ] }, "SearchSupportProviderCatalogDto": { "type": "object", "properties": { "query": { "type": "string", "description": "Customer product-discovery query. Tenant and audience are resolved from the connection credential, never from this body.", "minLength": 1, "maxLength": 200, "example": "natural deodorant for sensitive skin" } }, "required": [ "query" ] }, "SupportProviderCatalogProductDto": { "type": "object", "properties": { "slug": { "type": "string", "description": "Tenant-scoped public product slug." }, "name": { "type": "string" }, "description": { "type": "string", "description": "Bounded public storefront description. No metadata, staff fields, or private customer data is included." }, "product_type": { "type": "string", "enum": [ "SALE", "RENTAL", "SERVICE" ] }, "minimum_price_in_cents": { "type": "number", "description": "Lowest current public item/variant price, in the tenant currency minor unit." }, "maximum_price_in_cents": { "type": "number", "description": "Highest current public item/variant price, in the tenant currency minor unit." }, "currency": { "type": "string", "example": "USD" }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK", "AVAILABLE", "CHECK_REQUIRED" ], "description": "Public availability summary. Inventory quantities, thresholds, reservations, and capacity remain private." }, "image_url": { "type": "string", "nullable": true }, "product_url": { "type": "string", "description": "Environment-correct link to the tenant product page: the tenant storefront origin resolved at query time when one is configured for this environment, else the litecommerce redirect." }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "slug", "name", "description", "product_type", "minimum_price_in_cents", "maximum_price_in_cents", "currency", "availability", "image_url", "product_url", "updated_at" ] }, "SupportProviderCatalogSearchResponseDto": { "type": "object", "properties": { "catalog_status": { "type": "string", "enum": [ "AVAILABLE", "NO_MATCHES" ] }, "audience": { "type": "string", "enum": [ "PUBLIC_STOREFRONT" ] }, "freshness": { "type": "string", "enum": [ "LIVE_QUERY" ] }, "refreshed_at": { "type": "string", "format": "date-time" }, "fallback_message": { "type": "string", "nullable": true }, "products": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SupportProviderCatalogProductDto" } } }, "required": [ "catalog_status", "audience", "freshness", "refreshed_at", "fallback_message", "products" ] } } } }