{ "openapi": "3.1.0", "info": { "title": "Commerce (usage ingest + subscriptions)", "description": "The Commerce API owns usage-event ingest plus subscription, payment, and invoicing state. It stores immutable usage events with ingest checkpoints, run receipts, and quarantine for invalid rows; manages billing accounts, products and versioned prices, Stripe-backed subscriptions, monthly invoices with line items, and durable retry queues for entitlement sync and API-credential issuance after checkout. Stripe webhook signature verification fails closed. Uses cursor pagination, flat envelopes, and RFC 7807 errors.", "version": "1.0" }, "tags": [ { "name": "Billing account", "description": "Maps an Incept accountId onto the platform4 tenant that owns commerce ledger rows for that account. Subscriptions and invoices reference this accountId; mapping fields stay identity/status only." }, { "name": "Credential issuance task", "description": "Durable retry queue for issuing an applications authClient after API-customer checkout. Subscription mutations commit independently of the outbound applications register call; processCredentialIssuanceTask drives delivery. Idempotency key is stable per subscription (credential-issuance:{subscriptionId}) so repeated webhook events do not create duplicate tasks. clientId, applicationId, and serviceRoles are immutable for that key — identical checkout coordinates may re-arm pending/failed/blocked; a changed API customer requires a new subscription/task key (do not overwrite payload or reset into an applications 422 Idempotency-Key reuse loop). Never stores client secrets." }, { "name": "Entitlement sync task", "description": "Durable retry queue for converging an Incept account plan to the desired plan after subscription activate / past_due / canceled transitions. Subscription mutations commit independently of the outbound Incept call; processEntitlementSyncTask drives delivery. Idempotency key is stable per subscription so repeated webhook events do not create duplicate tasks." }, { "name": "Ingest checkpoint", "description": "Stored opaque cursor and last-run metadata for one usage-events sourceIdentity. Advanced atomically in the same transaction as a successful page's ledger writes. Never advanced on transport failure." }, { "name": "Ingest run receipt", "description": "One receipt per page-ingestion invocation (ingestUsageEventsPage / one CLI pagination iteration), not one receipt for an entire multi-page scheduled run. Records started/finished times, events seen/inserted/deduped/quarantined, and terminal status. The ingestUsageEvents command is the API ingest door; the scheduled pagination CLI shares the same product logic and writes one receipt per page attempt." }, { "name": "Invoice", "description": "Calendar-month UTC billing invoice for one billingAccount. Natural primary key is tenant-scoped composite-natural (tenantId, invoiceId). Period-close invoiceId is deterministically derived from tenant/account/month so closeInvoice is idempotent without a global (accountId, periodMonth) unique index. Period close rates unbilled usageEvents into immutable invoiceLines using effective-dated placeholder prices, then marks the invoice closed. Closed invoices are immutable — reruns of closeInvoice are a no-op; late-arriving events for a closed month land on the next open month; corrections are negative-line credit memos on a new invoice with a distinct invoiceId (invoiceKind=credit_memo can coexist with period_close for the same account/month; no update/delete of closed evidence). USD-only v1; taxes out of scope (subtotalCents === totalCents). Monetary fields are integer cents." }, { "name": "Invoice line", "description": "Immutable invoice line — usage rating or negative-line credit memo. Append-only: no public create/update/delete doors (internal create + list/get only). Usage lines reference a usageEvent idempotency key (unique per tenant so an event is billed at most once) and store a full effective-dated price snapshot. Credit lines carry negative amountCents and creditOf* references on a credit_memo invoice that uses a distinct invoiceId (not a period-close rerun); closed invoices are never mutated. Rating: amountCents = tokensTotal * unitAmountCents (cents per token). USD-only; taxes out of scope." }, { "name": "Price", "description": "Versioned authoritative price for a product. USD-only in v1 with placeholder unit amounts; live Stripe price points remain gated. Incept quota config is not stored here. Natural key is priceId — each row is one immutable version. Effective-dated selection across versions uses distinct priceIds that share productId (do not pretend one priceId holds multiple versions). Invoice rating treats unitAmountCents as cents per usage token (amountCents = usageEvent.tokensTotal * unitAmountCents)." }, { "name": "Product", "description": "Authoritative commerce product catalog entry. Platform4 owns product identity for subscription pricing; Incept quota/plan config in plans.json stays Incept-owned and is not mirrored here." }, { "name": "Stripe processed event", "description": "Durable per-tenant idempotency ledger for inbound Stripe webhook event ids. The processStripeWebhook x-handler verifies the Stripe-Signature over the exact raw body, then records one row per (tenant, stripeEventId) so duplicates are a no-op. Unsupported event types and invalid signature/payload write NO ledger row and mutate no subscription state." }, { "name": "Subscription", "description": "Tenant-scoped subscription binding a billingAccount to a price with Stripe payment-rail references. Status transitions are driven by the Stripe webhook x-handler: checkout.session.completed / invoice.paid → active, invoice.payment_failed → past_due, customer.subscription.deleted → canceled. Later invoice events do not resurrect a canceled subscription." }, { "name": "Usage event", "description": "Immutable ingested Incept UsageEvent row (contract incept.usageEvents.v1). Natural key is idempotencyKey (UNIQUE per platform4 tenant). Append-only ledger — no update/delete. Stores source usageEventId, Incept account/tenant ids, period week/month, tokens, skill/mode/model/overage, occurredAt, plus rawPayload jsonb, payloadHash, contractVersion, sourceIdentity, and ingestedAt." }, { "name": "Usage event quarantine", "description": "Schema-invalid usage-event payloads retained with reason. Malformed events never block valid siblings in the same page and are never silently dropped." } ], "paths": { "/commerce/v1/billing-accounts": { "get": { "operationId": "listBillingAccounts", "summary": "List billing account mappings", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Billing account" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAccount" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createBillingAccount", "summary": "Register an Incept accountId → platform4 tenant mapping", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Billing account" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBillingAccountRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccount" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/billing-accounts/{accountId}": { "get": { "operationId": "getBillingAccount", "summary": "Get one billing account mapping", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Billing account" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccount" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (billing_account_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateBillingAccount", "summary": "Update billing account status or display name", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Billing account" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBillingAccountRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccount" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (billing_account_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/credential-issuance-tasks": { "get": { "operationId": "listCredentialIssuanceTasks", "summary": "List credential issuance tasks", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Credential issuance task" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "in_progress", "succeeded", "failed", "blocked" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "subscriptionId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "subscriptionId", "operator": "eq" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "accountId", "operator": "eq" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "clientId", "operator": "eq" } }, { "name": "idempotencyKey", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "idempotencyKey", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialIssuanceTask" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/credential-issuance-tasks/{taskId}": { "get": { "operationId": "getCredentialIssuanceTask", "summary": "Get one credential issuance task", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Credential issuance task" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssuanceTask" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (credential_issuance_task_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/credential-issuance-tasks/commands/process": { "post": { "operationId": "processCredentialIssuanceTask", "summary": "Process one credential issuance task against the real applications auth-client register seam", "description": "Loads the task (by taskId, or the most recently updated task for subscriptionId — no status filter), claims it under SELECT … FOR UPDATE, then re-reads status: terminal succeeded is returned without a duplicate register call; other ineligible current statuses are returned; pending/failed/blocked may call POST /applications/v1/auth-client/register with Idempotency-Key derived from the durable task and update attempt/status. Tradeoff: applications I/O stays inside the write transaction (compiler write-hook shape), so the row lock is held for the bounded ~10s network window rather than splitting claim/commit from delivery — subscription commit is unaffected (enqueue already committed). Missing APPLICATIONS_BASE_URL blocks the task (status=blocked) without fabricating success. Transport and non-2xx failures leave the task retryable (status=failed) with bounded lastError. Never persists or returns client secrets.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Credential issuance task" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "description": "Task to process. Provide taskId or subscriptionId." }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resolve the most recently updated task for this subscription when taskId is omitted (updated_at DESC, any status)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssuanceTask" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (credential_issuance_task_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (credential_issuance_process_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/entitlement-sync-tasks": { "get": { "operationId": "listEntitlementSyncTasks", "summary": "List entitlement sync tasks", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Entitlement sync task" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "in_progress", "succeeded", "failed", "blocked" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "subscriptionId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "subscriptionId", "operator": "eq" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "accountId", "operator": "eq" } }, { "name": "idempotencyKey", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "idempotencyKey", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementSyncTask" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/entitlement-sync-tasks/{taskId}": { "get": { "operationId": "getEntitlementSyncTask", "summary": "Get one entitlement sync task", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Entitlement sync task" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementSyncTask" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (entitlement_sync_task_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/entitlement-sync-tasks/commands/process": { "post": { "operationId": "processEntitlementSyncTask", "summary": "Process one entitlement sync task against the real Incept entitlement seam", "description": "Loads the task (by taskId, or the most recently updated task for subscriptionId — no status filter), claims it under SELECT … FOR UPDATE, then re-reads status: terminal succeeded is returned; other ineligible current statuses are returned; pending/failed/blocked may call the real Incept PUT /internal/billing/accounts/{accountId}/entitlement seam and update attempt/status. Tradeoff: Incept I/O stays inside the write transaction (compiler write-hook shape), so the row lock is held for the bounded ~10s network window rather than splitting claim/commit from delivery — subscription commit is unaffected (enqueue already committed). Missing INCEPT_BASE_URL blocks the task (status=blocked) without fabricating success. Transport and non-2xx failures leave the task retryable (status=failed) with bounded lastError.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Entitlement sync task" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "description": "Task to process. Provide taskId or subscriptionId." }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resolve the most recently updated task for this subscription when taskId is omitted (updated_at DESC, any status)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementSyncTask" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (entitlement_sync_task_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (entitlement_sync_process_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/verification/entitlement-sync": { "get": { "operationId": "verifyEntitlementSync", "summary": "Verification read — compare platform desired plan to Incept account plan", "description": "Calls the real Incept GET /internal/billing/accounts/{accountId}/entitlement seam and reports whether the remote planCode matches the task/subscription target. Fails clearly (422) when INCEPT_BASE_URL is unset or Incept returns a non-2xx — never fabricates a local-only match.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Entitlement sync task" ], "parameters": [ { "name": "taskId", "in": "query", "required": false, "description": "Task whose targetInceptPlanId / accountId to verify. Provide taskId or subscriptionId.", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "query", "required": false, "description": "Resolve the entitlement sync task for this subscription when taskId is omitted.", "schema": { "type": "string", "minLength": 1 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string" }, "accountId": { "type": "string" }, "desiredPlanId": { "type": "string", "description": "Opaque plan id from the platform task (targetInceptPlanId)." }, "observedPlanId": { "type": "string", "description": "Opaque plan id returned by Incept GET entitlement." }, "match": { "type": "boolean", "description": "True when observedPlanId equals desiredPlanId." }, "subscriptionStatus": { "type": "string", "enum": [ "active", "past_due", "canceled" ], "description": "Current platform subscription status for context." } }, "required": [ "taskId", "subscriptionId", "accountId", "desiredPlanId", "observedPlanId", "match", "subscriptionStatus" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (entitlement_sync_task_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (entitlement_sync_verify_failed).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/ingest-checkpoints": { "get": { "operationId": "listIngestCheckpoints", "summary": "List ingest checkpoints", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Ingest checkpoint" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestCheckpoint" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/ingest-checkpoints/{sourceIdentity}": { "get": { "operationId": "getIngestCheckpoint", "summary": "Get checkpoint for one sourceIdentity", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Ingest checkpoint" ], "parameters": [ { "name": "sourceIdentity", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestCheckpoint" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (ingest_checkpoint_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/ingest-runs": { "get": { "operationId": "listIngestRunReceipts", "summary": "List ingest run receipts", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Ingest run receipt" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "running", "succeeded", "failed", "skipped" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestRunReceipt" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/ingest-runs/{runId}": { "get": { "operationId": "getIngestRunReceipt", "summary": "Get one ingest run receipt", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Ingest run receipt" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRunReceipt" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (ingest_run_receipt_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/ingest-runs/commands/ingest-usage-events": { "post": { "operationId": "ingestUsageEvents", "summary": "Ingest one usage-events page (fixture transport or supplied page)", "description": "Product-layer ingest door for one usage-events page (API submit or operator replay). Validates each event against the strict UsageEvent contract (additionalProperties false), inserts valid rows via ledger append (identical idempotencyKey replay dedupes; differing payloadHash quarantines as an idempotency collision), quarantines malformed rows, writes exactly one receipt for this page attempt, and advances the checkpoint only on success. A multi-page scheduled CLI run invokes this once per page (one receipt per page). simulateTransportFailure forces a failed receipt without checkpoint advance. Under RLS this door only sees the current tenant's billingAccount rows and, when no mapping is visible, falls back to the single visible tenant; the admin scheduled CLI additionally rejects mappings owned by another tenant.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Ingest run receipt" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ingest source identity." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Page of UsageEvent-shaped objects. Malformed objects are written to quarantine rather than accepted." }, "nextCursor": { "type": "string", "description": "Producer nextCursor for this page. Null/absent means drained after this page.", "nullable": true }, "schemaVersion": { "type": "string", "description": "Page schemaVersion; must be incept.usageEvents.v1 when present." }, "held": { "type": "boolean", "description": "Producer held flag accepted on the wire; currently not persisted or acted on." }, "simulateTransportFailure": { "type": "boolean", "description": "When true, abort before writes and return a failed receipt without advancing the checkpoint (errorSummary uses transportFailureReason when supplied, otherwise the explicit simulation text)." }, "transportFailureReason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Real or test transport-failure detail written to the failed receipt errorSummary. When set (with or without simulateTransportFailure), ingest records a failed receipt and does not advance the checkpoint." }, "simulateMidBatchFailureAfter": { "type": "integer", "minimum": 0, "description": "Test-only: after this many events have been written inside the page transaction, abort with an error so the transaction rolls back (no partial ledger rows, no checkpoint advance)." }, "runId": { "type": "string", "format": "uuid", "description": "Optional client-supplied run id." } }, "required": [ "sourceIdentity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRunReceipt" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (usage_events_ingest_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Invoice" ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "accountId", "operator": "eq" } }, { "name": "periodMonth", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "x-filter": { "column": "periodMonth", "operator": "eq" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/invoices/{invoiceId}": { "get": { "operationId": "getInvoice", "summary": "Get one invoice", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Invoice" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (invoice_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/invoices/commands/close": { "post": { "operationId": "closeInvoice", "summary": "Close a calendar-month UTC invoice (idempotent period close)", "description": "Rates unbilled usageEvents into immutable invoiceLines for one account + periodMonth (YYYY-MM UTC), then closes the invoice under the tenant-scoped natural key (tenantId, invoiceId).\n\n## Rating rule (explicit)\nquantity = usageEvent.tokensTotal (integer tokens). unitAmountCents = effective price.unitAmountCents (cents per token). amountCents = quantity * unitAmountCents (integer cents; overflow fails closed). Resolve the account subscription, take productId from the subscription's bound price, then select the catalog price effective at the event's UTC occurredAt: effectiveFrom <= occurredAt AND (effectiveTo is null OR occurredAt < effectiveTo). Tie-break: effectiveFrom DESC, version DESC, priceId ASC. Each priceId is one immutable version row — effective dating uses distinct priceIds sharing a productId (not multiple versions on one priceId). Missing subscription or unmatched price fails closed (no zero-price invention).\n\n## Late events\nNever mutate a closed invoice. Lines carry usageEventIdempotencyKey so already-billed events are excluded. Close for month M includes unbilled events with periodMonth=M, plus late events whose recorded periodMonth < M when that earlier month's invoice is already closed (original occurredAt / service period preserved on the line). Events from an earlier month whose invoice is still open are not pulled forward — close months in calendar order.\n\n## Idempotency / concurrency\nPeriod-close invoiceId is deterministically derived from tenant/account/month. If that invoice is already closed, return it unchanged (no new lines). Concurrent closes serialize on the composite-natural PK (INSERT … ON CONFLICT (tenant_id, invoice_id) DO NOTHING + SELECT … FOR UPDATE on tenant/account/month). The account/month secondary index is non-unique so credit_memo invoices with distinct invoiceIds can coexist for the same account/month. USD-only; taxes out of scope (totalCents = subtotalCents).\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Invoice" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "billingAccount.accountId to close." }, "periodMonth": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$", "description": "UTC calendar month YYYY-MM to close." } }, "required": [ "accountId", "periodMonth" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (billing_account_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (invoice_close_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/invoice-lines": { "get": { "operationId": "listInvoiceLines", "summary": "List immutable invoice lines", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Invoice line" ], "parameters": [ { "name": "invoiceId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "invoiceId", "operator": "eq" } }, { "name": "lineKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "usage", "credit" ] }, "x-filter": { "column": "lineKind", "operator": "eq" } }, { "name": "usageEventIdempotencyKey", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "x-filter": { "column": "usageEventIdempotencyKey", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/invoice-lines/{invoiceLineId}": { "get": { "operationId": "getInvoiceLine", "summary": "Get one invoice line", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Invoice line" ], "parameters": [ { "name": "invoiceLineId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLine" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (invoice_line_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/prices": { "get": { "operationId": "listPrices", "summary": "List prices", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Price" ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "productId", "operator": "eq" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createPrice", "summary": "Create a versioned placeholder price", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Price" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePriceRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/prices/{priceId}": { "get": { "operationId": "getPrice", "summary": "Get one price", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Price" ], "parameters": [ { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (price_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updatePrice", "summary": "Update mutable price fields (status, effectiveTo, stripePriceId)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Price" ], "parameters": [ { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePriceRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (price_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/products": { "get": { "operationId": "listProducts", "summary": "List products", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Product" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createProduct", "summary": "Create a product catalog entry", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Product" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/products/{productId}": { "get": { "operationId": "getProduct", "summary": "Get one product", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Product" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (product_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateProduct", "summary": "Update mutable product fields", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Product" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (product_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/stripe-processed-events": { "get": { "operationId": "listStripeProcessedEvents", "summary": "List processed Stripe webhook events", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Stripe processed event" ], "parameters": [ { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "eventType", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripeProcessedEvent" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/stripe-processed-events/{stripeEventId}": { "get": { "operationId": "getStripeProcessedEvent", "summary": "Get one processed Stripe event by id", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Stripe processed event" ], "parameters": [ { "name": "stripeEventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeProcessedEvent" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (stripe_processed_event_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/stripe-webhooks/commands/process": { "post": { "operationId": "processStripeWebhook", "summary": "Process one inbound Stripe webhook event (JSON envelope — not Stripe's native wire format)", "description": "GENERATED public command door — NOT Stripe's native webhook wire format.\n\nCompiler limitation (current compiler pin): WRITE x-handler operations cannot declare header parameters or a raw-body seam as typed hook inputs (headers are not projected; command inputs must live in requestBody). Therefore this operation accepts a JSON envelope `{ rawBody, stripeSignature }` rather than Stripe's raw event JSON + `Stripe-Signature` header.\n\nConcrete adapter path (hand-owned, wired for deploy + harness): `shared/stripe-webhook-envelope-adapter.ts` accepts Stripe's native POST at `/commerce/v1/stripe-webhooks` (raw body + Stripe-Signature header) and forwards into this envelope command. Wired from `infra/bootstrap/server-prod.ts` and `test-harness/lib/harness-hono-serve-shim.mjs`.\n\nVerification: STRIPE_WEBHOOK_SECRET (fail closed). Processes checkout.session.completed → active, invoice.paid → active, invoice.payment_failed → past_due, and customer.subscription.deleted → canceled. Unsupported event types return outcome=ignored with NO durable stripeProcessedEvent row and no subscription mutation. Invalid signature/payload fail before any write. Duplicate stripeEventId (same tenant) uses atomic ON CONFLICT DO NOTHING insert-or-read and returns outcome=duplicate. When a tenant can be resolved for a processable event, the ledger row and any subscription mutation commit in one transaction.\n\n> **Open:** no authentication required — this operation is public.", "tags": [ "Stripe processed event" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rawBody": { "type": "string", "minLength": 1, "description": "Exact UTF-8 Stripe event JSON bytes that were signed (must match the Stripe-Signature payload). Supplied by the native-wire adapter or by callers of this envelope command." }, "stripeSignature": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Value of the Stripe-Signature request header (t=…,v1=…). Not read from HTTP headers by this generated door — see adapter path in the operation description." } }, "required": [ "rawBody", "stripeSignature" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stripeEventId": { "type": "string", "description": "Stripe event id." }, "eventType": { "type": "string", "description": "Stripe event.type." }, "outcome": { "type": "string", "enum": [ "applied", "ignored", "duplicate" ], "description": "applied = subscription state mutated; ignored = no subscription mutation; duplicate = durable event id already seen." }, "subscriptionId": { "type": "string", "description": "Subscription id when applicable.", "nullable": true }, "detail": { "type": "string", "description": "Optional detail (ignored reason, etc.).", "nullable": true } }, "required": [ "stripeEventId", "eventType", "outcome" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (stripe_webhook_signature_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (stripe_webhook_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/subscriptions": { "get": { "operationId": "listSubscriptions", "summary": "List subscriptions", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Subscription" ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "accountId", "operator": "eq" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "past_due", "canceled" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "stripeSubscriptionId", "in": "query", "required": false, "schema": { "type": "string" }, "x-filter": { "column": "stripeSubscriptionId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createSubscription", "summary": "Create a subscription row (operator/admin; webhooks also create via processStripeWebhook)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Subscription" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/subscriptions/{subscriptionId}": { "get": { "operationId": "getSubscription", "summary": "Get one subscription", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Subscription" ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (subscription_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateSubscription", "summary": "Update mutable subscription fields", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Subscription" ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (subscription_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/usage-events": { "get": { "operationId": "listUsageEvents", "summary": "List ingested usage events", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Usage event" ], "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Filter by Incept accountId.", "schema": { "type": "string" }, "x-filter": { "column": "accountId", "operator": "eq" } }, { "name": "periodMonth", "in": "query", "required": false, "description": "Filter by billing month (YYYY-MM).", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "x-filter": { "column": "periodMonth", "operator": "eq" } }, { "name": "periodWeek", "in": "query", "required": false, "description": "Filter by billing week (YYYY-Www).", "schema": { "type": "string", "pattern": "^[0-9]{4}-W[0-9]{2}$" }, "x-filter": { "column": "periodWeek", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEvent" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/usage-events/{idempotencyKey}": { "get": { "operationId": "getUsageEvent", "summary": "Get one ingested usage event by idempotencyKey", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Usage event" ], "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEvent" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (usage_event_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/verification/account-usage-totals": { "get": { "operationId": "getAccountUsageTotals", "summary": "Verification read — per-account usage totals by period", "description": "Returns event count and tokensTotal summed from the immutable usageEvent ledger for one account and period (week or month). This is a verification read against the platform4 ledger — not source watermark matching with Incept.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Usage event" ], "parameters": [ { "name": "accountId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "periodWeek", "in": "query", "required": false, "description": "Optional week grain. Provide exactly one of periodWeek or periodMonth.", "schema": { "type": "string", "pattern": "^[0-9]{4}-W[0-9]{2}$" } }, { "name": "periodMonth", "in": "query", "required": false, "description": "Optional month grain. Provide exactly one of periodWeek or periodMonth.", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "periodKind": { "type": "string", "enum": [ "week", "month" ] }, "period": { "type": "string" }, "eventCount": { "type": "integer", "minimum": 0 }, "tokensTotal": { "type": "integer", "minimum": 0 } }, "required": [ "accountId", "periodKind", "period", "eventCount", "tokensTotal" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (usage_totals_query_invalid).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/usage-event-quarantines": { "get": { "operationId": "listUsageEventQuarantines", "summary": "List quarantined usage-event payloads", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Usage event quarantine" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEventQuarantine" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commerce/v1/usage-event-quarantines/{quarantineId}": { "get": { "operationId": "getUsageEventQuarantine", "summary": "Get one quarantine row", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Usage event quarantine" ], "parameters": [ { "name": "quarantineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventQuarantine" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (usage_event_quarantine_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "BillingAccount": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Incept accountId. UNIQUE per platform4 tenant; the tenantId on the row is the mapped platform4 tenant." }, "status": { "type": "string", "enum": [ "active", "suspended", "closed" ], "description": "Operational status for this billing account mapping.", "default": "active" }, "displayName": { "type": "string", "maxLength": 256, "description": "Optional operator-facing label.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "accountId", "status", "createdAt", "updatedAt" ] }, "CredentialIssuanceTask": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "description": "Stable task identity (UUID)." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable per-subscription key (credential-issuance:{subscriptionId}). Unique per tenant; repeated checkout events upsert this row instead of creating duplicates. Also the applications registerAuthClient Idempotency-Key — body (clientId/applicationId/serviceRoles) must stay coherent with this key." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Billing account whose checkout requested credential issuance.", "x-references": "billingAccount.accountId" }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Subscription whose checkout requested this credential issuance.", "x-references": "subscription.subscriptionId" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque applications authClient clientId target from Stripe checkout metadata. Immutable for the task's idempotencyKey once enqueued. Never a secret." }, "applicationId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque applications applicationId target from Stripe checkout metadata. Immutable for the task's idempotencyKey once enqueued. Must be an active application when processed." }, "serviceRoles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "description": "Service-identity roles forwarded to applications registerAuthClient. Normalized (trim/dedupe/sort; default [system] when omitted). Immutable for the task's idempotencyKey once enqueued." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "succeeded", "failed", "blocked" ], "description": "Queue status. pending/failed are retryable; blocked means missing APPLICATIONS_BASE_URL (not a fake success); succeeded is terminal." }, "attemptCount": { "type": "integer", "minimum": 0, "description": "Number of processCredentialIssuanceTask delivery attempts completed against applications." }, "lastAttemptAt": { "type": "string", "format": "date-time", "description": "When the most recent delivery attempt started.", "nullable": true }, "nextAttemptAt": { "type": "string", "format": "date-time", "description": "Earliest time a worker should retry after a failed attempt (null when pending for immediate processing or terminal).", "nullable": true }, "lastError": { "type": "string", "maxLength": 4000, "description": "Bounded real transport/configuration/error detail from the last failed or blocked attempt. Never includes client secrets.", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "description": "When status became succeeded.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "taskId", "idempotencyKey", "accountId", "subscriptionId", "clientId", "applicationId", "serviceRoles", "status", "attemptCount", "createdAt", "updatedAt" ] }, "EntitlementSyncTask": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "description": "Stable task identity (UUID)." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable per-subscription key (entitlement-sync:{subscriptionId}). Unique per tenant; repeated subscription events upsert this row instead of creating duplicates." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Incept accountId / billingAccount.accountId whose plan must converge.", "x-references": "billingAccount.accountId" }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Subscription whose status change requested this entitlement sync.", "x-references": "subscription.subscriptionId" }, "targetInceptPlanId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Opaque Incept plan identifier to set on the account (plan identity only — not quota limits or plans.json contents)." }, "trigger": { "type": "string", "enum": [ "activate", "delinquency", "cancel" ], "description": "Subscription transition that enqueued/updated this task: activate (active), delinquency (past_due), cancel (canceled)." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "succeeded", "failed", "blocked" ], "description": "Queue status. pending/failed are retryable; blocked means missing Incept configuration (not a fake success); succeeded is terminal." }, "attemptCount": { "type": "integer", "minimum": 0, "description": "Number of processEntitlementSyncTask delivery attempts completed against Incept." }, "lastAttemptAt": { "type": "string", "format": "date-time", "description": "When the most recent delivery attempt started.", "nullable": true }, "nextAttemptAt": { "type": "string", "format": "date-time", "description": "Earliest time a worker should retry after a failed attempt (null when pending for immediate processing or terminal).", "nullable": true }, "lastError": { "type": "string", "maxLength": 4000, "description": "Bounded real transport/configuration/error detail from the last failed or blocked attempt.", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "description": "When status became succeeded.", "nullable": true }, "observedInceptPlanId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Opaque plan identifier last observed from Incept (set/verify read), when known.", "nullable": true }, "observedAt": { "type": "string", "format": "date-time", "description": "When observedInceptPlanId was last read from Incept.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "taskId", "idempotencyKey", "accountId", "subscriptionId", "targetInceptPlanId", "trigger", "status", "attemptCount", "createdAt", "updatedAt" ] }, "IngestCheckpoint": { "type": "object", "properties": { "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable ingest source identity this checkpoint belongs to (one row per sourceIdentity per tenant)." }, "cursor": { "type": "string", "maxLength": 4096, "description": "Opaque producer cursor. Null means start-from-empty (full replay is safe via idempotency).", "nullable": true }, "lastRunId": { "type": "string", "format": "uuid", "description": "ingestRunReceipt.runId of the last successful page that advanced this checkpoint.", "nullable": true }, "lastStatus": { "type": "string", "enum": [ "empty", "advanced", "drained" ], "description": "empty = never advanced; advanced = cursor moved; drained = last page omitted nextCursor." }, "lastAdvancedAt": { "type": "string", "format": "date-time", "description": "Instant the checkpoint cursor/status was last advanced by a successful page." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourceIdentity", "lastStatus", "lastAdvancedAt", "createdAt", "updatedAt" ] }, "IngestRunReceipt": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "description": "Stable identifier for this page-ingestion invocation (one receipt / one page attempt)." }, "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ingest source identity (matches ingestCheckpoint.sourceIdentity)." }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "skipped" ], "description": "Terminal (or in-flight) status. skipped = env-gated clean exit (no base URL). failed = transport or unexpected error without checkpoint advance." }, "startedAt": { "type": "string", "format": "date-time", "description": "When this page-ingestion invocation started." }, "finishedAt": { "type": "string", "format": "date-time", "description": "When this page-ingestion invocation reached a terminal status.", "nullable": true }, "eventsSeen": { "type": "integer", "minimum": 0, "description": "Events observed on the page (valid + malformed)." }, "eventsInserted": { "type": "integer", "minimum": 0, "description": "New ledger rows inserted." }, "eventsDeduped": { "type": "integer", "minimum": 0, "description": "Valid events skipped by ON CONFLICT DO NOTHING / ledger append conflict." }, "eventsQuarantined": { "type": "integer", "minimum": 0, "description": "Malformed events written to usageEventQuarantine." }, "cursorBefore": { "type": "string", "maxLength": 4096, "description": "Checkpoint cursor at the start of this page.", "nullable": true }, "cursorAfter": { "type": "string", "maxLength": 4096, "description": "Checkpoint cursor after a successful page (null when unchanged or failed).", "nullable": true }, "errorSummary": { "type": "string", "maxLength": 4000, "description": "Human-readable failure summary when status=failed.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "runId", "sourceIdentity", "status", "startedAt", "eventsSeen", "eventsInserted", "eventsDeduped", "eventsQuarantined", "createdAt" ] }, "Invoice": { "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Tenant-scoped natural invoice id (composite PK with tenantId). For period_close, deterministically derived from tenant/account/month at first close attempt. Credit memos must use a distinct invoiceId (not a period-close rerun)." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "FK to billingAccount.accountId.", "x-references": "billingAccount.accountId" }, "periodMonth": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$", "description": "Billing window month (YYYY-MM) in UTC. Indexed with accountId for reads (non-unique — credit memos may share account/month with a period_close invoice)." }, "periodStart": { "type": "string", "format": "date-time", "description": "Inclusive UTC start of the calendar month (YYYY-MM-01T00:00:00.000Z)." }, "periodEnd": { "type": "string", "format": "date-time", "description": "Exclusive UTC end of the calendar month (first instant of the next month)." }, "currency": { "type": "string", "enum": [ "USD" ], "description": "ISO currency. USD-only in v1." }, "status": { "type": "string", "enum": [ "open", "closed" ], "description": "open while being built inside closeInvoice; closed is terminal and immutable." }, "subtotalCents": { "type": "integer", "description": "Sum of invoiceLine.amountCents in integer cents (may be negative when the invoice carries only credit lines)." }, "totalCents": { "type": "integer", "description": "Invoice total in integer cents. Equals subtotalCents in v1 (taxes out of scope)." }, "lineCount": { "type": "integer", "minimum": 0, "description": "Number of immutable invoice lines on this invoice." }, "invoiceKind": { "type": "string", "enum": [ "period_close", "credit_memo" ], "description": "period_close = usage rating for the month; credit_memo = correction invoice carrying negative credit lines only on a distinct invoiceId (not a period-close rerun). credit_memo rows may coexist with period_close for the same account/month; closed invoices are never mutated." }, "closedAt": { "type": "string", "format": "date-time", "description": "When status became closed; null while open.", "nullable": true }, "creditOfInvoiceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "When invoiceKind=credit_memo, the closed invoice this credit memo corrects. Null for period_close invoices.", "x-references": "invoice.invoiceId", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "invoiceId", "accountId", "periodMonth", "periodStart", "periodEnd", "currency", "status", "subtotalCents", "totalCents", "lineCount", "invoiceKind", "createdAt", "updatedAt" ] }, "InvoiceLine": { "type": "object", "properties": { "invoiceLineId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural invoice line id." }, "invoiceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Owning invoice.", "x-references": "invoice.invoiceId" }, "lineKind": { "type": "string", "enum": [ "usage", "credit" ], "description": "usage = rated usageEvent; credit = negative-line credit memo correction (never mutates a closed invoice)." }, "usageEventIdempotencyKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "usageEvent.idempotencyKey for usage lines (unique per tenant — an event is billed at most once). Null for credit lines.", "nullable": true }, "usageEventId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Source usageEvent.usageEventId when lineKind=usage.", "nullable": true }, "servicePeriodMonth": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$", "description": "Original usageEvent.periodMonth (preserved for late events billed on a later invoice).", "nullable": true }, "occurredAt": { "type": "string", "format": "date-time", "description": "Original usageEvent.occurredAt (UTC) used for effective price selection; preserved for late events.", "nullable": true }, "creditOfInvoiceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Closed invoice being corrected when lineKind=credit.", "x-references": "invoice.invoiceId", "nullable": true }, "creditOfInvoiceLineId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional specific line on the corrected invoice when lineKind=credit.", "x-references": "invoiceLine.invoiceLineId", "nullable": true }, "description": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable line description." }, "quantity": { "type": "integer", "minimum": 0, "description": "For usage lines: usageEvent.tokensTotal. For credit lines: the quantity being credited (non-negative); sign lives on amountCents." }, "unitAmountCents": { "type": "integer", "minimum": 0, "description": "Snapshot unit amount in integer cents per token (from effective price at occurredAt)." }, "amountCents": { "type": "integer", "description": "Line amount in integer cents. Usage: quantity * unitAmountCents (>= 0). Credit: negative. Overflow fails closed at write time." }, "currency": { "type": "string", "enum": [ "USD" ], "description": "ISO currency. USD-only in v1." }, "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Price snapshot: effective price.priceId at rating time." }, "productId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Price snapshot: productId." }, "priceVersion": { "type": "integer", "minimum": 1, "description": "Price snapshot: price.version." }, "priceEffectiveFrom": { "type": "string", "format": "date-time", "description": "Price snapshot: price.effectiveFrom." }, "priceEffectiveTo": { "type": "string", "format": "date-time", "description": "Price snapshot: price.effectiveTo (exclusive end; null = open-ended).", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "invoiceLineId", "invoiceId", "lineKind", "description", "quantity", "unitAmountCents", "amountCents", "currency", "priceId", "productId", "priceVersion", "priceEffectiveFrom", "createdAt" ] }, "Price": { "type": "object", "properties": { "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural price id (authoritative commerce price key)." }, "productId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "FK to product.productId.", "x-references": "product.productId" }, "version": { "type": "integer", "minimum": 1, "description": "Monotonic version number for this price row within its productId lineage. Because natural key is priceId, successive effective-dated versions are distinct priceId rows (e.g. price_…_v1, price_…_v2) sharing productId, each carrying its own version integer." }, "currency": { "type": "string", "enum": [ "USD" ], "description": "ISO currency. USD-only in v1." }, "unitAmountCents": { "type": "integer", "minimum": 0, "description": "Placeholder unit amount in integer cents per usage token (live price points gated). Invoice rating: amountCents = tokensTotal * unitAmountCents." }, "stripePriceId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional Stripe Price id when linked in test mode.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether new subscriptions may bind to this price.", "default": "active" }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "Instant this price version becomes effective (UTC)." }, "effectiveTo": { "type": "string", "format": "date-time", "description": "Exclusive end of effectiveness; null means open-ended.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "priceId", "productId", "version", "currency", "unitAmountCents", "status", "effectiveFrom", "createdAt", "updatedAt" ] }, "Product": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural product id (authoritative commerce catalog key)." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Operator-facing product name." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional product description.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether this product may be referenced by new prices/subscriptions.", "default": "active" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "productId", "name", "status", "createdAt", "updatedAt" ] }, "StripeProcessedEvent": { "type": "object", "properties": { "stripeEventId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe event id (evt_…). Natural key for webhook idempotency within the tenant." }, "eventType": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stripe event.type string (e.g. checkout.session.completed)." }, "outcome": { "type": "string", "enum": [ "applied", "ignored" ], "description": "Processing outcome for the first accepted delivery of this event id." }, "processedAt": { "type": "string", "format": "date-time", "description": "When this event was first accepted by processStripeWebhook." }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Subscription touched by this event when outcome=applied.", "nullable": true }, "detail": { "type": "string", "maxLength": 2000, "description": "Optional operator-facing note (e.g. ignored reason).", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "stripeEventId", "eventType", "outcome", "processedAt", "createdAt" ] }, "Subscription": { "type": "object", "properties": { "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural subscription id." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "FK to billingAccount.accountId (Incept account mapped to this tenant).", "x-references": "billingAccount.accountId" }, "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "FK to price.priceId currently bound to this subscription.", "x-references": "price.priceId" }, "status": { "type": "string", "enum": [ "active", "past_due", "canceled" ], "description": "Subscription billing status driven by Stripe webhook events." }, "currentPeriodStart": { "type": "string", "format": "date-time", "description": "Start of the current paid period (UTC), from Stripe.", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "description": "End of the current paid period (UTC), from Stripe.", "nullable": true }, "stripeCustomerId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Customer id (cus_…).", "nullable": true }, "stripeSubscriptionId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Subscription id (sub_…).", "nullable": true }, "stripeCheckoutSessionId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Checkout Session id (cs_…) that activated this subscription, when known.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "subscriptionId", "accountId", "priceId", "status", "createdAt", "updatedAt" ] }, "UsageEvent": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Incept UsageEvent.idempotencyKey (64-hex). UNIQUE per platform4 tenant; the ledger append conflict key." }, "usageEventId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Source UsageEvent.usageEventId from Incept." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Incept accountId; mapped to this platform4 tenant via billingAccount." }, "sourceTenantId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Incept UsageEvent.tenantId (producer tenant). Distinct from the platform4 RLS tenantId claim on the row." }, "periodWeek": { "type": "string", "pattern": "^[0-9]{4}-W[0-9]{2}$", "description": "Billing week period (YYYY-Www) from UsageEvent.period.week." }, "periodMonth": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$", "description": "Billing month period (YYYY-MM) from UsageEvent.period.month." }, "tokensTotal": { "type": "integer", "minimum": 0, "description": "Token total for this usage event." }, "skill": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Skill identifier from the UsageEvent." }, "mode": { "type": "string", "enum": [ "basic", "brainlift" ], "description": "Usage mode from the UsageEvent." }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Model identifier from the UsageEvent." }, "overage": { "type": "boolean", "description": "Whether this event is marked overage by Incept." }, "occurredAt": { "type": "string", "format": "date-time", "description": "Instant the usage occurred (UsageEvent.occurredAt)." }, "rawPayload": { "type": "object", "description": "Exact JSON object received for this event (lossless audit).", "additionalProperties": true }, "payloadHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "SHA-256 hash of the canonical JSON payload (sha256:)." }, "contractVersion": { "type": "string", "enum": [ "incept.usageEvents.v1" ], "description": "Frozen contract version for this row." }, "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable identity of the ingest source (e.g. incept.private.usage-events)." }, "ingestedAt": { "type": "string", "format": "date-time", "description": "Instant this row was written by the commerce ingestor." }, "eventCount": { "type": "integer", "minimum": 1, "maximum": 1, "description": "Ledger measure column (always 1) so additive append can fold event counts." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "idempotencyKey", "usageEventId", "accountId", "sourceTenantId", "periodWeek", "periodMonth", "tokensTotal", "skill", "mode", "model", "overage", "occurredAt", "rawPayload", "payloadHash", "contractVersion", "sourceIdentity", "ingestedAt", "eventCount", "createdAt" ] }, "UsageEventQuarantine": { "type": "object", "properties": { "quarantineId": { "type": "string", "format": "uuid", "description": "Stable quarantine row id." }, "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ingest source identity that produced this payload." }, "runId": { "type": "string", "format": "uuid", "description": "ingestRunReceipt.runId for the invocation that quarantined this payload." }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the payload failed the strict UsageEvent contract." }, "rawPayload": { "type": "object", "description": "Exact JSON object as received (or a wrapper when the item was non-object).", "additionalProperties": true }, "idempotencyKey": { "type": "string", "maxLength": 128, "description": "Best-effort idempotencyKey extracted from the payload when present.", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the quarantine row was written." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "quarantineId", "sourceIdentity", "runId", "reason", "rawPayload", "receivedAt", "createdAt" ] }, "CreateBillingAccountRequest": { "type": "object", "description": "Create-BillingAccount request body (readOnly/server-managed fields excluded).", "required": [ "accountId", "status" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Incept accountId. UNIQUE per platform4 tenant; the tenantId on the row is the mapped platform4 tenant." }, "status": { "type": "string", "enum": [ "active", "suspended", "closed" ], "description": "Operational status for this billing account mapping.", "default": "active" }, "displayName": { "type": "string", "maxLength": 256, "description": "Optional operator-facing label.", "nullable": true } } }, "UpdateBillingAccountRequest": { "type": "object", "description": "Update-BillingAccount request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "active", "suspended", "closed" ], "description": "Operational status for this billing account mapping.", "default": "active" }, "displayName": { "type": [ "string", "null" ], "maxLength": 256, "description": "Optional operator-facing label.", "nullable": true } } }, "CreatePriceRequest": { "type": "object", "description": "Create-Price request body (readOnly/server-managed fields excluded).", "required": [ "priceId", "productId", "version", "currency", "unitAmountCents", "status", "effectiveFrom" ], "additionalProperties": false, "properties": { "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural price id (authoritative commerce price key)." }, "productId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "FK to product.productId.", "x-references": "product.productId" }, "version": { "type": "integer", "minimum": 1, "description": "Monotonic version number for this price row within its productId lineage. Because natural key is priceId, successive effective-dated versions are distinct priceId rows (e.g. price_…_v1, price_…_v2) sharing productId, each carrying its own version integer." }, "currency": { "type": "string", "enum": [ "USD" ], "description": "ISO currency. USD-only in v1." }, "unitAmountCents": { "type": "integer", "minimum": 0, "description": "Placeholder unit amount in integer cents per usage token (live price points gated). Invoice rating: amountCents = tokensTotal * unitAmountCents." }, "stripePriceId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional Stripe Price id when linked in test mode.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether new subscriptions may bind to this price.", "default": "active" }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "Instant this price version becomes effective (UTC)." }, "effectiveTo": { "type": "string", "format": "date-time", "description": "Exclusive end of effectiveness; null means open-ended.", "nullable": true } } }, "UpdatePriceRequest": { "type": "object", "description": "Update-Price request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "stripePriceId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Optional Stripe Price id when linked in test mode.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether new subscriptions may bind to this price.", "default": "active" }, "effectiveTo": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive end of effectiveness; null means open-ended.", "nullable": true } } }, "CreateProductRequest": { "type": "object", "description": "Create-Product request body (readOnly/server-managed fields excluded).", "required": [ "productId", "name", "status" ], "additionalProperties": false, "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural product id (authoritative commerce catalog key)." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Operator-facing product name." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional product description.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether this product may be referenced by new prices/subscriptions.", "default": "active" } } }, "UpdateProductRequest": { "type": "object", "description": "Update-Product request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Operator-facing product name." }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Optional product description.", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether this product may be referenced by new prices/subscriptions.", "default": "active" } } }, "CreateSubscriptionRequest": { "type": "object", "description": "Create-Subscription request body (readOnly/server-managed fields excluded).", "required": [ "subscriptionId", "accountId", "priceId", "status" ], "additionalProperties": false, "properties": { "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable natural subscription id." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "FK to billingAccount.accountId (Incept account mapped to this tenant).", "x-references": "billingAccount.accountId" }, "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "FK to price.priceId currently bound to this subscription.", "x-references": "price.priceId" }, "status": { "type": "string", "enum": [ "active", "past_due", "canceled" ], "description": "Subscription billing status driven by Stripe webhook events." }, "currentPeriodStart": { "type": "string", "format": "date-time", "description": "Start of the current paid period (UTC), from Stripe.", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "description": "End of the current paid period (UTC), from Stripe.", "nullable": true }, "stripeCustomerId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Customer id (cus_…).", "nullable": true }, "stripeSubscriptionId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Subscription id (sub_…).", "nullable": true }, "stripeCheckoutSessionId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe Checkout Session id (cs_…) that activated this subscription, when known.", "nullable": true } } }, "UpdateSubscriptionRequest": { "type": "object", "description": "Update-Subscription request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "priceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "FK to price.priceId currently bound to this subscription.", "x-references": "price.priceId" }, "status": { "type": "string", "enum": [ "active", "past_due", "canceled" ], "description": "Subscription billing status driven by Stripe webhook events." }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the current paid period (UTC), from Stripe.", "nullable": true }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the current paid period (UTC), from Stripe.", "nullable": true }, "stripeCustomerId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Stripe Customer id (cus_…).", "nullable": true }, "stripeSubscriptionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Stripe Subscription id (sub_…).", "nullable": true }, "stripeCheckoutSessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Stripe Checkout Session id (cs_…) that activated this subscription, when known.", "nullable": true } } }, "Problem": { "type": "object", "description": "RFC 7807 problem details.", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI identifying the problem type." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "format": "uri", "description": "A URI identifying this occurrence." } }, "required": [ "title", "status" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://alpha.platform4.alphaschool.dev" } ] }