{ "openapi": "3.1.0", "info": { "title": "CentriPOS Retail API", "version": "2026-08", "description": "Comprehensive, versioned retail operations contract. All examples are synthetic. Public Storefront operations are live. Private reads marked authenticated-live are operational only for explicitly entitled tenants. Storefront checkout operations marked certified-live require a separately approved tenant-and-client certification. Generic POS mutations remain controlled rollout.", "termsOfService": "https://getcentri.com/terms", "contact": { "name": "CentriPOS Developer Support", "url": "https://support.centripos.com/support", "email": "support@getcentri.com" } }, "externalDocs": { "description": "CentriPOS Developer Platform", "url": "https://support.centripos.com/developers/" }, "servers": [ { "url": "https://pos.getcentri.com", "description": "Branded CentriPOS edge. Entitled reads and separately certified storefront checkout operations are live; all non-enabled operations fail closed." } ], "tags": [ { "name": "Sales & receipts", "description": "Transactions, line items, tenders, returns, receipts, shifts, and closures." }, { "name": "Catalog", "description": "Products, variants, taxonomy, media, attributes, custom fields, and price books." }, { "name": "Inventory", "description": "Levels, reservations, movements, adjustments, counts, transfers, and serials." }, { "name": "Customers", "description": "People, companies, households, groups, addresses, balances, notes, and history." }, { "name": "Invoicing", "description": "Account invoices, line items, payments, balances, billing schedules, and project links." }, { "name": "Service Center", "description": "Service tickets, visits, work orders, charges, time, warranties, and recurring plans." }, { "name": "Projects & work", "description": "Projects, boards, milestones, tasks, dependencies, comments, approvals, and linked billing." }, { "name": "Orders & fulfillment", "description": "Orders, pickup, delivery, shipping, capacity, shipments, and tracking events." }, { "name": "Purchasing", "description": "Suppliers, purchase orders, receiving, cost lists, and supplier returns." }, { "name": "Pricing & tax", "description": "Price books, promotions, coupons, taxes, and eligibility evaluation." }, { "name": "Merchant setup", "description": "Merchant projection, locations, registers, users, roles, and payment types." }, { "name": "Reports & exports", "description": "Approved aggregates, saved reports, asynchronous exports, and register summaries." }, { "name": "Webhooks & audit", "description": "Subscriptions, immutable events, delivery attempts, redelivery, and request logs." }, { "name": "Public storefront", "description": "Published, browser-safe catalog and theme projections." } ], "paths": { "/api/retail/v1/sales": { "get": { "tags": [ "Sales & receipts" ], "summary": "List sales", "description": "List sales", "operationId": "list_sales", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Opaque customer identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List sales response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePage" }, "example": { "api_version": "2026-08", "data": [ { "id": "sale_test_01J9EXAMPLE", "object": "sale", "status": "synthetic_example", "name": "Example sale", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_sale_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "sales:read" }, "post": { "tags": [ "Sales & receipts" ], "summary": "Create a sale", "description": "Create a sale Requires Idempotency-Key. Payment capture is a separately certified surface.", "operationId": "create_sale", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string" }, "register_id": { "type": "string" }, "customer_id": { "type": "string" }, "currency": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "variant_id", "quantity" ], "additionalProperties": false } } }, "required": [ "location_id", "register_id", "customer_id", "currency", "line_items" ], "additionalProperties": false }, "example": { "location_id": "loc_test_01J9NORTHSTAR", "register_id": "reg_test_01J9FRONT01", "customer_id": "cus_test_01J9ALEXMORGAN", "currency": "USD", "line_items": [ { "variant_id": "var_test_01J9HARBORQUEEN", "quantity": 1 } ] } } } }, "responses": { "201": { "description": "Create a sale response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "sal_test_01J9NEWSALE", "object": "sale", "status": "accepted", "name": "Example sale", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_sale_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:write" } }, "/api/retail/v1/sales/{sale_id}": { "get": { "tags": [ "Sales & receipts" ], "summary": "Get a complete sale", "description": "Retrieve the full whitelisted transaction projection, including line snapshots, discounts, taxes, tenders, fulfillment, returns, and invoice links.", "operationId": "get_sale", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a complete sale response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "sal_test_01J9SALE10482", "sale_number": "S-10482", "status": "completed", "channel": "in_store", "currency": "USD", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "register": { "id": "reg_test_01J9FRONT01", "name": "Front Register", "code": "FRONT-1" }, "register_session": { "id": "rsn_test_01J9SHIFT7", "opened_at": "2026-08-24T13:00:00Z" }, "cashier": { "id": "usr_test_01J9CASEY", "display_name": "Casey Reed" }, "associate": { "id": "usr_test_01J9JORDAN", "display_name": "Jordan Lee", "attribution": "sale" }, "customer": { "id": "cus_test_01J9ALEXMORGAN", "first_name": "Alex", "last_name": "Morgan", "display_name": "Alex Morgan", "email": "alex.morgan@example.test", "phone": "+1-555-010-0184", "customer_group": { "id": "cgrp_test_household", "name": "Household" }, "marketing_consent": { "email": true, "sms": false, "updated_at": "2026-08-20T14:22:19Z" } }, "totals": { "subtotal": 1699, "discount_total": 100, "shipping_total": 0, "tax_total": 128.72, "total": 1727.72, "amount_paid": 1727.72, "balance_due": 0, "change_given": 0 }, "line_items": [ { "id": "line_test_01J9SALE10482A", "sort_order": 1, "quantity": 1, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress", "brand": "Northstar Sleep" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ] }, "unit_price": 1699, "quantity_price": 1699, "discount_total": 100, "tax_total": 128.72, "line_total": 1727.72, "discounts": [ { "id": "promo_test_100OFF", "name": "Synthetic launch offer", "type": "fixed", "amount": 100 } ], "tax_lines": [ { "id": "tax_test_state_local", "name": "Combined sales tax", "rate": 0.0805, "taxable_amount": 1599, "amount": 128.72 } ], "fulfillment": { "type": "pickup", "status": "ready", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "promised_at": "2026-08-26T18:00:00Z" }, "inventory_commitment": { "state": "backordered", "reserved_quantity": 0, "backorder_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "backorder": { "object": "commerce_backorder_commitment", "id": "boc_test_01J9SALE10482A", "status": "awaiting_stock", "requested_quantity": 1, "initially_reserved_quantity": 0, "backorder_quantity": 1, "allocated_quantity": 0, "remaining_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days.", "allocated_at": null, "fulfilled_at": null, "cancelled_at": null, "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:31:02Z" }, "warranty": { "term_years": 15, "registered": false }, "note": null } ], "payments": [ { "id": "pay_test_01J9SALE10482A", "tender_type": "card", "status": "completed", "amount": 1727.72, "currency": "USD", "processed_at": "2026-08-24T14:36:18Z", "processor": { "provider": "synthetic_gateway", "card_brand": "visa", "last_four": "4242", "authorization_code": "DEMO42", "provider_reference": "payref_test_01J9EXAMPLE" } } ], "returns": [], "fulfillment": { "status": "ready", "order_ids": [ "ful_test_01J9PICKUP10482" ] }, "receipt": { "id": "rec_test_01J9RECEIPT10482", "receipt_number": "R-10482", "resource_url": "/api/retail/v1/receipts/rec_test_01J9RECEIPT10482", "document_url": "/api/retail/v1/receipts/rec_test_01J9RECEIPT10482/document" }, "source": { "type": "register", "external_reference": null }, "note": "Synthetic sandbox transaction for documentation.", "created_at": "2026-08-24T14:31:02Z", "completed_at": "2026-08-24T14:36:18Z", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_01J9DOCSSALE", "environment": "test", "expansions": [ "line_items", "payments", "customer", "fulfillment", "receipt" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "sales:read" } }, "/api/retail/v1/sales/{sale_id}/complete": { "post": { "tags": [ "Sales & receipts" ], "summary": "Complete a sale", "description": "Complete a sale Requires Idempotency-Key and canonical completed payment evidence.", "operationId": "complete_sale", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "payment_ids" ], "additionalProperties": false }, "example": { "payment_ids": [ "pay_test_01J9SALE10482A" ] } } } }, "responses": { "200": { "description": "Complete a sale response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "sal_test_01J9SALE10482", "object": "sale", "status": "accepted", "name": "Example sale", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_sale_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:write" } }, "/api/retail/v1/sales/{sale_id}/void": { "post": { "tags": [ "Sales & receipts" ], "summary": "Void a sale", "description": "Void a sale Production-impacting action. Requires a permitted sale state and Idempotency-Key.", "operationId": "void_sale", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Synthetic duplicate transaction" } } } }, "responses": { "200": { "description": "Void a sale response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "sal_test_01J9SALE10482", "object": "sale", "status": "accepted", "name": "Example sale", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_sale_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:write" } }, "/api/retail/v1/sales/{sale_id}/line-items": { "get": { "tags": [ "Sales & receipts" ], "summary": "List sale line items", "description": "Returns whitelisted immutable sale-line snapshots, including product, pricing, tax, return, and fulfillment fields. Cost remains independently scope-gated.", "operationId": "sale_lines", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List sale line items response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "line_test_01J9SALE10482A", "sort_order": 1, "quantity": 1, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress", "brand": "Northstar Sleep" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ] }, "unit_price": 1699, "quantity_price": 1699, "discount_total": 100, "tax_total": 128.72, "line_total": 1727.72, "discounts": [ { "id": "promo_test_100OFF", "name": "Synthetic launch offer", "type": "fixed", "amount": 100 } ], "tax_lines": [ { "id": "tax_test_state_local", "name": "Combined sales tax", "rate": 0.0805, "taxable_amount": 1599, "amount": 128.72 } ], "fulfillment": { "type": "pickup", "status": "ready", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "promised_at": "2026-08-26T18:00:00Z" }, "inventory_commitment": { "state": "backordered", "reserved_quantity": 0, "backorder_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "backorder": { "object": "commerce_backorder_commitment", "id": "boc_test_01J9SALE10482A", "status": "awaiting_stock", "requested_quantity": 1, "initially_reserved_quantity": 0, "backorder_quantity": 1, "allocated_quantity": 0, "remaining_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days.", "allocated_at": null, "fulfilled_at": null, "cancelled_at": null, "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:31:02Z" }, "warranty": { "term_years": 15, "registered": false }, "note": null } ], "meta": { "request_id": "req_test_01J9DOCSSALE", "environment": "test", "expansions": [ "line_items", "payments", "customer", "fulfillment", "receipt" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "sales:read" } }, "/api/retail/v1/sales/{sale_id}/payments": { "get": { "tags": [ "Sales & receipts" ], "summary": "List payment summaries", "description": "Returns permitted tender summaries and masked provider references, never raw card, bank, terminal, token, merchant, or provider payload data.", "operationId": "sale_payments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List payment summaries response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "pay_test_01J9SALE10482A", "tender_type": "card", "status": "completed", "amount": 1727.72, "currency": "USD", "processed_at": "2026-08-24T14:36:18Z", "processor": { "provider": "synthetic_gateway", "card_brand": "visa", "last_four": "4242", "authorization_code": "DEMO42", "provider_reference": "payref_test_01J9EXAMPLE" } } ], "meta": { "request_id": "req_test_01J9DOCSSALE", "environment": "test", "expansions": [ "line_items", "payments", "customer", "fulfillment", "receipt" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "sales:read" } }, "/api/retail/v1/sales/{sale_id}/returns": { "post": { "tags": [ "Sales & receipts" ], "summary": "Create a return", "description": "Create a return Requires Idempotency-Key. Refund execution requires certified payment permissions.", "operationId": "create_return", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "line_item_id": { "type": "string" }, "quantity": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "line_item_id", "quantity", "reason" ], "additionalProperties": false } }, "refund_method": { "type": "string" } }, "required": [ "lines", "refund_method" ], "additionalProperties": false }, "example": { "lines": [ { "line_item_id": "line_test_01J9SALE10482A", "quantity": 1, "reason": "Unopened return" } ], "refund_method": "original_tender" } } } }, "responses": { "201": { "description": "Create a return response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "ret_test_01J9RETURN1", "object": "return", "status": "accepted", "name": "Example return", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_return_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:write" }, "get": { "tags": [ "Sales & receipts" ], "summary": "List sale returns", "description": "List sale returns", "operationId": "list_returns", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sale_id", "in": "path", "required": true, "description": "Opaque sale id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List sale returns response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "return_test_01J9EXAMPLE", "object": "return", "status": "synthetic_example", "name": "Example return", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_return_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:read" } }, "/api/retail/v1/receipts/{receipt_id}": { "get": { "tags": [ "Sales & receipts" ], "summary": "Get receipt data", "description": "Retrieve the complete canonical receipt read model for a sale without payment credentials.", "operationId": "get_receipt", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "description": "Opaque receipt id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get receipt data response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "rec_test_01J9RECEIPT10482", "receipt_number": "R-10482", "sale_id": "sal_test_01J9SALE10482", "sale_number": "S-10482", "status": "issued", "issued_at": "2026-08-24T14:36:19Z", "merchant": { "display_name": "Northstar Home & Sleep", "location": { "name": "Northstar Main Store", "address": "100 Example Avenue, Sample City, IL 60000" }, "phone": "+1-555-010-0100", "tax_identifier_display": "**-***6789" }, "customer": { "id": "cus_test_01J9ALEXMORGAN", "display_name": "Alex Morgan", "email": "alex.morgan@example.test" }, "cashier": { "id": "usr_test_01J9CASEY", "display_name": "Casey Reed" }, "line_items": [ { "id": "line_test_01J9SALE10482A", "sort_order": 1, "quantity": 1, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress", "brand": "Northstar Sleep" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ] }, "unit_price": 1699, "quantity_price": 1699, "discount_total": 100, "tax_total": 128.72, "line_total": 1727.72, "discounts": [ { "id": "promo_test_100OFF", "name": "Synthetic launch offer", "type": "fixed", "amount": 100 } ], "tax_lines": [ { "id": "tax_test_state_local", "name": "Combined sales tax", "rate": 0.0805, "taxable_amount": 1599, "amount": 128.72 } ], "fulfillment": { "type": "pickup", "status": "ready", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "promised_at": "2026-08-26T18:00:00Z" }, "inventory_commitment": { "state": "backordered", "reserved_quantity": 0, "backorder_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "backorder": { "object": "commerce_backorder_commitment", "id": "boc_test_01J9SALE10482A", "status": "awaiting_stock", "requested_quantity": 1, "initially_reserved_quantity": 0, "backorder_quantity": 1, "allocated_quantity": 0, "remaining_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days.", "allocated_at": null, "fulfilled_at": null, "cancelled_at": null, "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:31:02Z" }, "warranty": { "term_years": 15, "registered": false }, "note": null } ], "tenders": [ { "type": "card", "label": "Visa ending 4242", "amount": 1727.72, "status": "completed" } ], "totals": { "subtotal": 1699, "discount_total": 100, "shipping_total": 0, "tax_total": 128.72, "total": 1727.72, "amount_paid": 1727.72, "balance_due": 0, "change_given": 0 }, "tax_summary": [ { "name": "Combined sales tax", "rate": 0.0805, "taxable_amount": 1599, "amount": 128.72 } ], "fulfillment_summary": "Pickup at Northstar Main Store on Aug 26, 2026", "return_summary": { "returnable_until": "2026-09-23T23:59:59Z", "returned_total": 0 }, "links": { "self": "/api/retail/v1/receipts/rec_test_01J9RECEIPT10482", "sale": "/api/retail/v1/sales/sal_test_01J9SALE10482", "document": "/api/retail/v1/receipts/rec_test_01J9RECEIPT10482/document" } }, "meta": { "request_id": "req_test_01J9DOCSRECEIPT", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:read" } }, "/api/retail/v1/receipts/{receipt_id}/document": { "get": { "tags": [ "Sales & receipts" ], "summary": "Download receipt document", "description": "Download receipt document", "operationId": "get_receipt_document", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "description": "Opaque receipt id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Download receipt document response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "rec_test_01J9RECEIPT10482", "content_type": "application/pdf", "expires_at": "2026-08-24T14:51:19Z", "download_url": "https://downloads.example.test/receipt-synthetic.pdf" }, "meta": { "request_id": "req_test_receipt_document", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:read" } }, "/api/retail/v1/register-closures": { "get": { "tags": [ "Sales & receipts" ], "summary": "List register closures", "description": "List register closures", "operationId": "list_register_closures", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "register_id", "in": "query", "required": false, "description": "Filter by register id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "closed_since", "in": "query", "required": false, "description": "Filter by closed since.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List register closures response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "register_closure_test_01J9EXAMPLE", "object": "register_closure", "status": "synthetic_example", "name": "Example register closure", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_register_closure_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:read" } }, "/api/retail/v1/products": { "get": { "tags": [ "Catalog" ], "summary": "List products", "description": "List products", "operationId": "list_products", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "sku", "in": "query", "required": false, "description": "Filter by sku.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "brand_id", "in": "query", "required": false, "description": "Filter by brand id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "updated_since", "in": "query", "required": false, "description": "Return records updated at or after this RFC 3339 timestamp.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List products response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "product_test_01J9EXAMPLE", "object": "product", "status": "synthetic_example", "name": "Example product", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_product_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "catalog:read" }, "post": { "tags": [ "Catalog" ], "summary": "Create a product", "description": "Create a product", "operationId": "create_product", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "brand_id": { "type": "string" }, "category_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "name", "brand_id", "category_id", "status" ], "additionalProperties": false }, "example": { "name": "Harbor 12-inch Hybrid Mattress", "brand_id": "brd_test_northstar", "category_id": "cat_test_mattresses", "status": "draft" } } } }, "responses": { "201": { "description": "Create a product response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prd_test_01J9NEWPRODUCT", "object": "product", "status": "accepted", "name": "Example product", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_product_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:write" } }, "/api/retail/v1/products/{product_id}": { "get": { "tags": [ "Catalog" ], "summary": "Get a product", "description": "Retrieve the supported product resource with variants, media, approved custom fields, taxonomy, and warranty links.", "operationId": "get_product", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Opaque product id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a product response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prd_test_01J9HARBOR12", "handle": "harbor-12-hybrid-mattress", "name": "Harbor 12-inch Hybrid Mattress", "brand": { "id": "brd_test_northstar", "name": "Northstar Sleep" }, "status": "active", "sellable": true, "online_backorder_policy": { "mode": "allow_notify", "max_backorder_quantity": 2, "eta_days": 10, "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "description": "A balanced hybrid with responsive support and a quilted comfort surface.", "category": { "id": "cat_test_mattresses", "name": "Mattresses", "slug": "mattresses" }, "tags": [ { "id": "tag_test_hybrid", "name": "Hybrid", "slug": "hybrid" } ], "variants": [ { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "barcode": "000000000001", "price": { "amount": 1699, "currency": "USD" }, "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ], "inventory": { "tracked": true, "available": 6, "reserved": 1, "incoming": 4 }, "online_backorder_policy": { "mode": "inherit", "max_backorder_quantity": null, "eta_days": null, "customer_message": null } } ], "custom_fields": { "price_area": [ { "key": "warranty_years", "label": "Warranty", "value": 15, "value_type": "number" } ], "description": [ { "key": "construction", "label": "Construction", "value": "Hybrid", "value_type": "text" } ], "specifications": [ { "key": "profile_height", "label": "Profile height", "value": 12, "unit": "in", "value_type": "number" }, { "key": "firmness_level", "label": "Firmness level", "value": 6, "value_type": "number" } ] }, "media": [ { "id": "med_test_01J9HARBORFRONT", "type": "image", "role": "primary", "alt": "Synthetic Harbor mattress product render", "url": "https://pos.getcentri.com/media/product/demo/harbor-12-front.webp" } ], "created_at": "2026-07-14T16:03:11Z", "updated_at": "2026-08-22T19:45:02Z" }, "meta": { "request_id": "req_test_product", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "catalog:read" }, "patch": { "tags": [ "Catalog" ], "summary": "Update a product", "description": "Update a product", "operationId": "update_product", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Opaque product id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" } }, "required": [ "description" ], "additionalProperties": false }, "example": { "description": "Updated synthetic description." } } } }, "responses": { "200": { "description": "Update a product response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prd_test_01J9HARBOR12", "object": "product", "status": "accepted", "name": "Example product", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_product_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:write" } }, "/api/retail/v1/products/{product_id}/variants": { "get": { "tags": [ "Catalog" ], "summary": "List product variants", "description": "List product variants", "operationId": "list_variants", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Opaque product id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List product variants response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "barcode": "000000000001", "price": { "amount": 1699, "currency": "USD" }, "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ], "inventory": { "tracked": true, "available": 6, "reserved": 1, "incoming": 4 }, "online_backorder_policy": { "mode": "inherit", "max_backorder_quantity": null, "eta_days": null, "customer_message": null } } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_variants", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" }, "post": { "tags": [ "Catalog" ], "summary": "Create a variant", "description": "Create a variant", "operationId": "create_variant", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Opaque product id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "name", "sku", "options" ], "additionalProperties": false }, "example": { "name": "King / Medium", "sku": "DEMO-HBR-K-MED", "options": [ { "name": "Size", "value": "King" }, { "name": "Feel", "value": "Medium" } ] } } } }, "responses": { "201": { "description": "Create a variant response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "var_test_01J9NEWVARIANT", "object": "variant", "status": "accepted", "name": "Example variant", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_variant_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:write" } }, "/api/retail/v1/categories": { "get": { "tags": [ "Catalog" ], "summary": "List categories", "description": "List categories", "operationId": "list_categories", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "parent_id", "in": "query", "required": false, "description": "Filter by parent id.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List categories response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "category_test_01J9EXAMPLE", "object": "category", "status": "synthetic_example", "name": "Example category", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_category_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" } }, "/api/retail/v1/brands": { "get": { "tags": [ "Catalog" ], "summary": "List brands", "description": "List brands", "operationId": "list_brands", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List brands response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "brand_test_01J9EXAMPLE", "object": "brand", "status": "synthetic_example", "name": "Example brand", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_brand_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" } }, "/api/retail/v1/tags": { "get": { "tags": [ "Catalog" ], "summary": "List tags", "description": "List tags", "operationId": "list_tags", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List tags response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "tag_test_01J9EXAMPLE", "object": "tag", "status": "synthetic_example", "name": "Example tag", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_tag_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" } }, "/api/retail/v1/custom-field-groups": { "get": { "tags": [ "Catalog" ], "summary": "List custom field groups", "description": "List custom field groups", "operationId": "list_custom_fields", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "entity_type", "in": "query", "required": false, "description": "Filter by entity type.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List custom field groups response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "custom_field_group_test_01J9EXAMPLE", "object": "custom_field_group", "status": "synthetic_example", "name": "Example custom field group", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_custom_field_group_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" } }, "/api/retail/v1/products/{product_id}/media": { "get": { "tags": [ "Catalog" ], "summary": "List product media", "description": "List product media", "operationId": "list_media", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Opaque product id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List product media response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "med_test_01J9HARBORFRONT", "type": "image", "role": "primary", "alt": "Synthetic Harbor mattress product render", "url": "https://pos.getcentri.com/media/product/demo/harbor-12-front.webp" } ], "meta": { "request_id": "req_test_media", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "catalog:read" } }, "/api/retail/v1/inventory/stock": { "get": { "tags": [ "Inventory" ], "summary": "List inventory stock", "description": "List inventory stock", "operationId": "list_stock", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "product_id", "in": "query", "required": false, "description": "Filter by product id.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List inventory stock response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryLevelPage" }, "example": { "api_version": "2026-08", "data": [ { "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "sku": "DEMO-HBR-Q-MED", "name": "Queen / Medium" }, "on_hand": 7, "reserved": 1, "available": 6, "incoming": 4, "reorder_point": 2, "updated_at": "2026-08-24T14:29:08Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_01J9DOCSINVENTORY", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "inventory:read" } }, "/api/retail/v1/inventory/levels": { "get": { "tags": [ "Inventory" ], "summary": "Get authoritative product inventory levels", "description": "Return every variant at every tenant location, effective reservations, available quantities, per-location totals, and separate unassigned product-level stock. product_id is required.", "operationId": "list_levels", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "description": "Filter by product id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Get authoritative product inventory levels response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryLevelsEnvelope" }, "example": { "api_version": "2026-08", "data": { "object": "inventory_levels", "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress", "sku": "DEMO-HBR", "track_inventory": true }, "inventory_model": "variant", "locations": [ { "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "internal_name": "Northstar Main Store", "type": "retail", "is_active": true }, "unassigned_product_level": { "id": null, "stock_on_hand": 0, "reserved_quantity": 0, "inventory_reserved_quantity": 0, "commerce_reserved_quantity": 0, "available_quantity": 0, "reorder_point": null, "reorder_quantity": null, "updated_at": null }, "variants": [ { "id": "stock_test_01J9HARBORQUEEN", "object": "inventory_level", "stock_type": "variant", "location_id": "loc_test_01J9NORTHSTAR", "product_id": "prd_test_01J9HARBOR12", "variant_id": "var_test_01J9HARBORQUEEN", "variant_name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "attributes": { "Size": "Queen", "Feel": "Medium" }, "variant_enabled": true, "stock_on_hand": 7, "reserved_quantity": 1, "inventory_reserved_quantity": 1, "commerce_reserved_quantity": 0, "available_quantity": 6, "reorder_point": 2, "reorder_quantity": 4, "updated_at": "2026-08-24T14:29:08Z" } ], "variant_totals": { "stock_on_hand": 7, "reserved_quantity": 1, "available_quantity": 6 } } ], "totals": { "variants": { "stock_on_hand": 7, "reserved_quantity": 1, "available_quantity": 6 }, "unassigned_product_level": { "stock_on_hand": 0, "reserved_quantity": 0, "available_quantity": 0 } } }, "meta": { "request_id": "req_test_01J9DOCSINVENTORYLEVELS", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "inventory:read" } }, "/api/retail/v1/inventory/levels/{location_id}/{variant_id}": { "get": { "tags": [ "Inventory" ], "summary": "Get one inventory level", "description": "Get one inventory level", "operationId": "get_level", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "description": "Opaque location id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "variant_id", "in": "path", "required": true, "description": "Opaque variant id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get one inventory level response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryLevelEnvelope" }, "example": { "api_version": "2026-08", "data": { "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "sku": "DEMO-HBR-Q-MED", "name": "Queen / Medium" }, "on_hand": 7, "reserved": 1, "available": 6, "incoming": 4, "reorder_point": 2, "updated_at": "2026-08-24T14:29:08Z" }, "meta": { "request_id": "req_test_01J9DOCSINVENTORY", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:read" } }, "/api/retail/v1/inventory/movements": { "get": { "tags": [ "Inventory" ], "summary": "List inventory movements", "description": "List inventory movements", "operationId": "list_movements", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "product_id", "in": "query", "required": false, "description": "Filter by product id.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List inventory movements response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "inventory_movement_test_01J9EXAMPLE", "object": "inventory_movement", "status": "synthetic_example", "name": "Example inventory movement", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_inventory_movement_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "inventory:read" } }, "/api/retail/v1/inventory/adjustments": { "post": { "tags": [ "Inventory" ], "summary": "Create an inventory adjustment", "description": "Create an inventory adjustment Requires Idempotency-Key and an auditable reason.", "operationId": "create_adjustment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string" }, "variant_id": { "type": "string" }, "quantity_delta": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "location_id", "variant_id", "quantity_delta", "reason" ], "additionalProperties": false }, "example": { "location_id": "loc_test_01J9NORTHSTAR", "variant_id": "var_test_01J9HARBORQUEEN", "quantity_delta": -1, "reason": "Synthetic cycle count correction" } } } }, "responses": { "201": { "description": "Create an inventory adjustment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "adj_test_01J9EXAMPLE", "object": "inventory_adjustment", "status": "accepted", "name": "Example inventory adjustment", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_adjustment_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:write" } }, "/api/retail/v1/inventory/counts": { "get": { "tags": [ "Inventory" ], "summary": "List inventory counts", "description": "List inventory counts", "operationId": "list_counts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List inventory counts response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "inventory_count_test_01J9EXAMPLE", "object": "inventory_count", "status": "synthetic_example", "name": "Example inventory count", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_inventory_count_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:read" }, "post": { "tags": [ "Inventory" ], "summary": "Start an inventory count", "description": "Start an inventory count", "operationId": "create_count", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "location_id", "name" ], "additionalProperties": false }, "example": { "location_id": "loc_test_01J9NORTHSTAR", "name": "Synthetic August count" } } } }, "responses": { "201": { "description": "Start an inventory count response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "cnt_test_01J9EXAMPLE", "object": "inventory_count", "status": "accepted", "name": "Example inventory count", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_count_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:write" } }, "/api/retail/v1/inventory/transfers": { "get": { "tags": [ "Inventory" ], "summary": "List inventory transfers", "description": "List inventory transfers", "operationId": "list_transfers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "source_location_id", "in": "query", "required": false, "description": "Filter by source location id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "destination_location_id", "in": "query", "required": false, "description": "Filter by destination location id.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List inventory transfers response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "inventory_transfer_test_01J9EXAMPLE", "object": "inventory_transfer", "status": "synthetic_example", "name": "Example inventory transfer", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_inventory_transfer_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:read" }, "post": { "tags": [ "Inventory" ], "summary": "Create an inventory transfer", "description": "Create an inventory transfer", "operationId": "create_transfer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_location_id": { "type": "string" }, "destination_location_id": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "variant_id", "quantity" ], "additionalProperties": false } } }, "required": [ "source_location_id", "destination_location_id", "lines" ], "additionalProperties": false }, "example": { "source_location_id": "loc_test_01J9NORTHSTAR", "destination_location_id": "loc_test_01J9SECOND", "lines": [ { "variant_id": "var_test_01J9HARBORQUEEN", "quantity": 2 } ] } } } }, "responses": { "201": { "description": "Create an inventory transfer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "trn_test_01J9EXAMPLE", "object": "inventory_transfer", "status": "accepted", "name": "Example inventory transfer", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_transfer_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:write" } }, "/api/retail/v1/inventory/transfers/{transfer_id}/dispatch": { "post": { "tags": [ "Inventory" ], "summary": "Dispatch a transfer", "description": "Dispatch a transfer", "operationId": "dispatch_transfer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "description": "Opaque transfer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dispatched_at": { "type": "string" } }, "required": [ "dispatched_at" ], "additionalProperties": false }, "example": { "dispatched_at": "2026-08-25T14:00:00Z" } } } }, "responses": { "200": { "description": "Dispatch a transfer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "trn_test_01J9EXAMPLE", "object": "inventory_transfer", "status": "accepted", "name": "Example inventory transfer", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_transfer_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:write" } }, "/api/retail/v1/inventory/transfers/{transfer_id}/receive": { "post": { "tags": [ "Inventory" ], "summary": "Receive a transfer", "description": "Receive a transfer", "operationId": "receive_transfer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "description": "Opaque transfer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string" }, "quantity_received": { "type": "integer" } }, "required": [ "variant_id", "quantity_received" ], "additionalProperties": false } } }, "required": [ "lines" ], "additionalProperties": false }, "example": { "lines": [ { "variant_id": "var_test_01J9HARBORQUEEN", "quantity_received": 2 } ] } } } }, "responses": { "200": { "description": "Receive a transfer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "trn_test_01J9EXAMPLE", "object": "inventory_transfer", "status": "accepted", "name": "Example inventory transfer", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_transfer_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "inventory:write" } }, "/api/retail/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "List customers", "operationId": "list_customers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "updated_since", "in": "query", "required": false, "description": "Return records updated at or after this RFC 3339 timestamp.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List customers response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "customer_test_01J9EXAMPLE", "object": "customer", "status": "synthetic_example", "name": "Example customer", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_customer_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "customers:read" }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "description": "Create a customer", "operationId": "create_customer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "first_name", "last_name", "email", "phone" ], "additionalProperties": false }, "example": { "first_name": "Alex", "last_name": "Morgan", "email": "alex.morgan@example.test", "phone": "+1-555-010-0184" } } } }, "responses": { "201": { "description": "Create a customer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "cus_test_01J9ALEXMORGAN", "object": "customer", "status": "accepted", "name": "Example customer", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_customer_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "customers:write" } }, "/api/retail/v1/customers/{customer_id}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer", "description": "Retrieve the supported, scope-limited customer account projection.", "operationId": "get_customer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Opaque customer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a customer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "cus_test_01J9ALEXMORGAN", "first_name": "Alex", "last_name": "Morgan", "display_name": "Alex Morgan", "email": "alex.morgan@example.test", "phone": "+1-555-010-0184", "customer_group": { "id": "cgrp_test_household", "name": "Household" }, "marketing_consent": { "email": true, "sms": false, "updated_at": "2026-08-20T14:22:19Z" }, "addresses": [ { "id": "addr_test_01J9ALEXHOME", "type": "home", "line1": "200 Example Street", "city": "Sample City", "region": "IL", "postal_code": "60000", "country": "US" } ], "balances": { "account_balance": 0, "store_credit": 75, "loyalty_points": 240 }, "lifetime": { "completed_sales": 4, "net_sales": 4836.18, "last_sale_at": "2026-08-24T14:36:18Z" }, "created_at": "2025-11-03T17:44:20Z", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_01J9DOCSCUSTOMER", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "customers:read" }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Update a customer", "operationId": "update_customer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Opaque customer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" } }, "required": [ "phone" ], "additionalProperties": false }, "example": { "phone": "+1-555-010-0184" } } } }, "responses": { "200": { "description": "Update a customer response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "cus_test_01J9ALEXMORGAN", "object": "customer", "status": "accepted", "name": "Example customer", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_customer_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "customers:write" } }, "/api/retail/v1/customers/{customer_id}/addresses": { "get": { "tags": [ "Customers" ], "summary": "List customer addresses", "description": "List customer addresses", "operationId": "customer_addresses", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Opaque customer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List customer addresses response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "addr_test_01J9ALEXHOME", "type": "home", "line1": "200 Example Street", "city": "Sample City", "region": "IL", "postal_code": "60000", "country": "US" } ], "meta": { "request_id": "req_test_01J9DOCSCUSTOMER", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "customers:read" } }, "/api/retail/v1/customers/{customer_id}/sales": { "get": { "tags": [ "Customers" ], "summary": "List customer sales", "description": "List customer sales", "operationId": "customer_sales", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "Opaque customer id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "created_since", "in": "query", "required": false, "description": "Return records created at or after this RFC 3339 timestamp.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List customer sales response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePage" }, "example": { "api_version": "2026-08", "data": [ { "id": "sale_test_01J9EXAMPLE", "object": "sale", "status": "synthetic_example", "name": "Example sale", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_sale_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "sales:read" } }, "/api/retail/v1/customer-groups": { "get": { "tags": [ "Customers" ], "summary": "List customer groups", "description": "List customer groups", "operationId": "list_customer_groups", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List customer groups response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "customer_group_test_01J9EXAMPLE", "object": "customer_group", "status": "synthetic_example", "name": "Example customer group", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_customer_group_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "customers:read" } }, "/api/retail/v1/households": { "get": { "tags": [ "Customers" ], "summary": "List households", "description": "List households", "operationId": "list_households", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List households response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "household_test_01J9EXAMPLE", "object": "household", "status": "synthetic_example", "name": "Example household", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_household_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "customers:read" } }, "/api/retail/v1/invoices": { "get": { "tags": [ "Invoicing" ], "summary": "List invoices", "description": "List invoices", "operationId": "list_invoices", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Opaque customer identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List invoices response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePage" }, "example": { "api_version": "2026-08", "data": [ { "id": "inv_test_01J9INVOICE10482", "object": "invoice", "invoice_number": "INV-10482", "status": "open", "customer_id": "cus_test_01J9ALEXMORGAN", "customer_name": "Alex Morgan", "customer_email": "alex.morgan@example.test", "sale_id": "sal_test_01J9SALE10482", "totals": { "subtotal": 2400, "tax": 193.2, "total": 2593.2, "amount_paid": 1000, "balance_due": 1593.2 }, "notes": "Synthetic account invoice for documentation.", "issued_at": "2026-08-24T14:36:18Z", "due_date": "2026-09-23", "paid_at": null, "line_items": [ { "id": "invl_test_01J9LABOR", "description": "Installation labor", "quantity": 8, "unit_price": 150, "amount": 1200, "sort_order": 1, "created_at": "2026-08-24T14:36:18Z" }, { "id": "invl_test_01J9MATERIAL", "description": "Approved materials", "quantity": 1, "unit_price": 1200, "amount": 1200, "sort_order": 2, "created_at": "2026-08-24T14:36:18Z" } ], "payments": [ { "id": "invpay_test_01J9DEPOSIT", "amount": 1000, "payment_type_id": "paytype_test_ach", "notes": "Synthetic deposit", "created_at": "2026-08-24T14:40:00Z" } ], "project_links": [ { "id": "pinv_test_01J9LINK", "project_id": "prj_test_01J9INSTALL", "invoice_id": "inv_test_01J9INVOICE10482", "created_at": "2026-08-24T14:36:18Z" } ], "created_at": "2026-08-24T14:36:18Z", "updated_at": "2026-08-24T14:40:00Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_invoice_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "invoices:read" }, "post": { "tags": [ "Invoicing" ], "summary": "Create an invoice", "description": "Create an invoice Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_invoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "due_date": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" } }, "required": [ "description", "quantity", "unit_price" ], "additionalProperties": false } }, "project_id": { "type": "string" } }, "required": [ "customer_id", "due_date", "line_items", "project_id" ], "additionalProperties": false }, "example": { "customer_id": "cus_test_01J9ALEXMORGAN", "due_date": "2026-09-23", "line_items": [ { "description": "Installation labor", "quantity": 8, "unit_price": 150 } ], "project_id": "prj_test_01J9INSTALL" } } } }, "responses": { "201": { "description": "Create an invoice response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "inv_test_01J9NEWINVOICE", "object": "invoice", "status": "accepted", "name": "Example invoice", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_invoice_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "invoices:write" } }, "/api/retail/v1/invoices/{invoice_id}": { "get": { "tags": [ "Invoicing" ], "summary": "Get a complete invoice", "description": "Retrieve the supported invoice header, totals, line items, payments, balance, sale relationship, and project links.", "operationId": "get_invoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Opaque invoice id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a complete invoice response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "inv_test_01J9INVOICE10482", "object": "invoice", "invoice_number": "INV-10482", "status": "open", "customer_id": "cus_test_01J9ALEXMORGAN", "customer_name": "Alex Morgan", "customer_email": "alex.morgan@example.test", "sale_id": "sal_test_01J9SALE10482", "totals": { "subtotal": 2400, "tax": 193.2, "total": 2593.2, "amount_paid": 1000, "balance_due": 1593.2 }, "notes": "Synthetic account invoice for documentation.", "issued_at": "2026-08-24T14:36:18Z", "due_date": "2026-09-23", "paid_at": null, "line_items": [ { "id": "invl_test_01J9LABOR", "description": "Installation labor", "quantity": 8, "unit_price": 150, "amount": 1200, "sort_order": 1, "created_at": "2026-08-24T14:36:18Z" }, { "id": "invl_test_01J9MATERIAL", "description": "Approved materials", "quantity": 1, "unit_price": 1200, "amount": 1200, "sort_order": 2, "created_at": "2026-08-24T14:36:18Z" } ], "payments": [ { "id": "invpay_test_01J9DEPOSIT", "amount": 1000, "payment_type_id": "paytype_test_ach", "notes": "Synthetic deposit", "created_at": "2026-08-24T14:40:00Z" } ], "project_links": [ { "id": "pinv_test_01J9LINK", "project_id": "prj_test_01J9INSTALL", "invoice_id": "inv_test_01J9INVOICE10482", "created_at": "2026-08-24T14:36:18Z" } ], "created_at": "2026-08-24T14:36:18Z", "updated_at": "2026-08-24T14:40:00Z" }, "meta": { "request_id": "req_test_01J9DOCSINVOICE", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Invoicing" ], "summary": "Update an invoice", "description": "Update an invoice Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "update_invoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Opaque invoice id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "due_date": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "due_date", "notes" ], "additionalProperties": false }, "example": { "due_date": "2026-09-30", "notes": "Synthetic revised terms." } } } }, "responses": { "200": { "description": "Update an invoice response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "inv_test_01J9INVOICE10482", "object": "invoice", "status": "accepted", "name": "Example invoice", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_invoice_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "invoices:write" } }, "/api/retail/v1/invoices/{invoice_id}/payments": { "post": { "tags": [ "Invoicing" ], "summary": "Record an invoice payment", "description": "Record an invoice payment Requires Idempotency-Key and canonical payment evidence.", "operationId": "record_invoice_payment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Opaque invoice id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer" }, "payment_type_id": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "amount", "payment_type_id", "notes" ], "additionalProperties": false }, "example": { "amount": 500, "payment_type_id": "paytype_test_ach", "notes": "Synthetic payment" } } } }, "responses": { "201": { "description": "Record an invoice payment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "invpay_test_01J9PAYMENT", "object": "invoice_payment", "status": "accepted", "name": "Example invoice payment", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_invoice_payment_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "invoices:write" }, "get": { "tags": [ "Invoicing" ], "summary": "List invoice payments", "description": "Returns tenant-bound invoice payment records with amounts, approved payment-type references, notes, and timestamps.", "operationId": "list_invoice_payments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Opaque invoice id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "List invoice payments response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "invpay_test_01J9DEPOSIT", "amount": 1000, "payment_type_id": "paytype_test_ach", "notes": "Synthetic deposit", "created_at": "2026-08-24T14:40:00Z" } ], "meta": { "request_id": "req_test_01J9DOCSINVOICE", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "invoices:read" } }, "/api/retail/v1/service/tickets": { "get": { "tags": [ "Service Center" ], "summary": "List service tickets", "description": "List service tickets", "operationId": "list_service_tickets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "priority", "in": "query", "required": false, "description": "Filter by priority.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Opaque customer identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List service tickets response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceTicketPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "svc_test_01J9TICKET01", "object": "service_ticket", "ticket_number": "SVC-2081", "ticket_type": "installation", "status": "scheduled", "priority": "normal", "lifecycle_stage": "work_order", "origin_channel": "phone", "customer": { "id": "cus_test_01J9ALEXMORGAN", "name": "Alex Morgan", "phone": "+1-555-010-0184", "email": "alex.morgan@example.test" }, "service_address": { "street": "300 Example Boulevard", "street_2": null, "city": "Sample City", "state": "IL", "postal_code": "60000" }, "location_id": "loc_test_01J9NORTHSTAR", "product_id": "prd_test_01J9HARBOR12", "variant_id": "var_test_01J9HARBORQUEEN", "linked_sale_id": "sal_test_01J9SALE10482", "converted_sale_id": null, "assigned_profile_id": "usr_test_01J9TECH01", "assigned_team_function": "field_service", "project_id": "prj_test_01J9INSTALL", "work_item_id": "work_test_01J9INSTALL", "warranty": { "provider": "Example Manufacturer", "claim_number": null }, "billing": { "billable": true, "estimated_charge": 450, "approved_charge": 450, "charge_status": "approved", "quote_status": "accepted", "quote_total": 450 }, "work_order_status": "scheduled", "summary": "Install and verify adjustable base", "details": "Synthetic service detail for documentation.", "requested_resolution": "Complete installation and customer walkthrough.", "customer_concern": null, "resolution_summary": null, "scheduled_at": "2026-08-28T14:00:00Z", "next_follow_up_at": "2026-08-29T15:00:00Z", "completed_at": null, "closed_at": null, "visits": [ { "id": "visit_test_01J9SITE01", "object": "service_visit", "service_ticket_id": "svc_test_01J9TICKET01", "visit_type": "onsite", "status": "scheduled", "assigned_profile_id": "usr_test_01J9TECH01", "scheduled_start": "2026-08-28T14:00:00Z", "scheduled_end": "2026-08-28T16:00:00Z", "en_route_at": null, "arrived_at": null, "departed_at": null, "completed_at": null, "address": { "line1": "300 Example Boulevard", "city": "Sample City", "region": "IL", "postal_code": "60000" }, "customer_present": true, "sentiment": null, "billable": true, "notes": "Synthetic scheduled visit.", "technician_notes": null, "customer_notes": "Call on arrival.", "checklist": [ { "id": "svci_test_01J9CHECK01", "label": "Confirm work area", "is_complete": false, "completed_by": null, "completed_at": null, "sort_order": 1 } ], "created_at": "2026-08-24T15:00:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "items": [ { "id": "svcitm_test_01J9BASE", "product_id": "prd_test_01J9HARBOR12", "variant_id": "var_test_01J9HARBORQUEEN", "product_name": "Harbor 12-inch Hybrid Mattress", "variant_name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "item_kind": "installed_product", "allocation_status": "allocated", "quantity": 1, "unit_price": 1699, "line_total": 1699, "note": null, "sort_order": 1 } ], "charges": [ { "id": "svcchg_test_01J9LABOR", "charge_type": "labor", "description": "Installation labor", "quantity": 2, "unit_rate": 150, "amount": 300, "status": "approved", "invoice_id": "inv_test_01J9INVOICE10482" } ], "time_entries": [ { "id": "svctime_test_01J9PLAN", "profile_id": "usr_test_01J9TECH01", "entry_type": "planned", "status": "approved", "minutes": 120, "billable": true, "hourly_rate": 150 } ], "warranty_claim": null, "events": [ { "id": "svcevt_test_01J9SCHEDULED", "event_type": "scheduled", "actor_profile_id": "usr_test_01J9CASEY", "note": "Synthetic schedule event", "created_at": "2026-08-24T15:00:00Z" } ], "created_at": "2026-08-24T14:50:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_service_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" }, "post": { "tags": [ "Service Center" ], "summary": "Create a service ticket", "description": "Create a service ticket Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_service_ticket", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket_type": { "type": "string" }, "customer_id": { "type": "string" }, "summary": { "type": "string" }, "priority": { "type": "string" } }, "required": [ "ticket_type", "customer_id", "summary", "priority" ], "additionalProperties": false }, "example": { "ticket_type": "installation", "customer_id": "cus_test_01J9ALEXMORGAN", "summary": "Install and verify adjustable base", "priority": "normal" } } } }, "responses": { "201": { "description": "Create a service ticket response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "svc_test_01J9NEWTICKET", "object": "service_ticket", "status": "accepted", "name": "Example service ticket", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_ticket_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/service/tickets/{ticket_id}": { "get": { "tags": [ "Service Center" ], "summary": "Get a complete service ticket", "description": "Retrieve the supported ticket with customer and address snapshots, items, visits, charges, time entries, warranty claim, work links, and lifecycle events.", "operationId": "get_service_ticket", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "description": "Opaque ticket id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a complete service ticket response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceTicketEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "svc_test_01J9TICKET01", "object": "service_ticket", "ticket_number": "SVC-2081", "ticket_type": "installation", "status": "scheduled", "priority": "normal", "lifecycle_stage": "work_order", "origin_channel": "phone", "customer": { "id": "cus_test_01J9ALEXMORGAN", "name": "Alex Morgan", "phone": "+1-555-010-0184", "email": "alex.morgan@example.test" }, "service_address": { "street": "300 Example Boulevard", "street_2": null, "city": "Sample City", "state": "IL", "postal_code": "60000" }, "location_id": "loc_test_01J9NORTHSTAR", "product_id": "prd_test_01J9HARBOR12", "variant_id": "var_test_01J9HARBORQUEEN", "linked_sale_id": "sal_test_01J9SALE10482", "converted_sale_id": null, "assigned_profile_id": "usr_test_01J9TECH01", "assigned_team_function": "field_service", "project_id": "prj_test_01J9INSTALL", "work_item_id": "work_test_01J9INSTALL", "warranty": { "provider": "Example Manufacturer", "claim_number": null }, "billing": { "billable": true, "estimated_charge": 450, "approved_charge": 450, "charge_status": "approved", "quote_status": "accepted", "quote_total": 450 }, "work_order_status": "scheduled", "summary": "Install and verify adjustable base", "details": "Synthetic service detail for documentation.", "requested_resolution": "Complete installation and customer walkthrough.", "customer_concern": null, "resolution_summary": null, "scheduled_at": "2026-08-28T14:00:00Z", "next_follow_up_at": "2026-08-29T15:00:00Z", "completed_at": null, "closed_at": null, "visits": [ { "id": "visit_test_01J9SITE01", "object": "service_visit", "service_ticket_id": "svc_test_01J9TICKET01", "visit_type": "onsite", "status": "scheduled", "assigned_profile_id": "usr_test_01J9TECH01", "scheduled_start": "2026-08-28T14:00:00Z", "scheduled_end": "2026-08-28T16:00:00Z", "en_route_at": null, "arrived_at": null, "departed_at": null, "completed_at": null, "address": { "line1": "300 Example Boulevard", "city": "Sample City", "region": "IL", "postal_code": "60000" }, "customer_present": true, "sentiment": null, "billable": true, "notes": "Synthetic scheduled visit.", "technician_notes": null, "customer_notes": "Call on arrival.", "checklist": [ { "id": "svci_test_01J9CHECK01", "label": "Confirm work area", "is_complete": false, "completed_by": null, "completed_at": null, "sort_order": 1 } ], "created_at": "2026-08-24T15:00:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "items": [ { "id": "svcitm_test_01J9BASE", "product_id": "prd_test_01J9HARBOR12", "variant_id": "var_test_01J9HARBORQUEEN", "product_name": "Harbor 12-inch Hybrid Mattress", "variant_name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "item_kind": "installed_product", "allocation_status": "allocated", "quantity": 1, "unit_price": 1699, "line_total": 1699, "note": null, "sort_order": 1 } ], "charges": [ { "id": "svcchg_test_01J9LABOR", "charge_type": "labor", "description": "Installation labor", "quantity": 2, "unit_rate": 150, "amount": 300, "status": "approved", "invoice_id": "inv_test_01J9INVOICE10482" } ], "time_entries": [ { "id": "svctime_test_01J9PLAN", "profile_id": "usr_test_01J9TECH01", "entry_type": "planned", "status": "approved", "minutes": 120, "billable": true, "hourly_rate": 150 } ], "warranty_claim": null, "events": [ { "id": "svcevt_test_01J9SCHEDULED", "event_type": "scheduled", "actor_profile_id": "usr_test_01J9CASEY", "note": "Synthetic schedule event", "created_at": "2026-08-24T15:00:00Z" } ], "created_at": "2026-08-24T14:50:00Z", "updated_at": "2026-08-24T15:00:00Z" }, "meta": { "request_id": "req_test_01J9DOCSSERVICE", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" }, "patch": { "tags": [ "Service Center" ], "summary": "Update a service ticket", "description": "Update a service ticket Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "update_service_ticket", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "description": "Opaque ticket id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "scheduled_at": { "type": "string" } }, "required": [ "status", "scheduled_at" ], "additionalProperties": false }, "example": { "status": "scheduled", "scheduled_at": "2026-08-28T14:00:00Z" } } } }, "responses": { "200": { "description": "Update a service ticket response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "svc_test_01J9TICKET01", "object": "service_ticket", "status": "accepted", "name": "Example service ticket", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_ticket_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/service/visits": { "get": { "tags": [ "Service Center" ], "summary": "List service visits", "description": "List service visits", "operationId": "list_service_visits", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List service visits response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceVisitPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "visit_test_01J9SITE01", "object": "service_visit", "service_ticket_id": "svc_test_01J9TICKET01", "visit_type": "onsite", "status": "scheduled", "assigned_profile_id": "usr_test_01J9TECH01", "scheduled_start": "2026-08-28T14:00:00Z", "scheduled_end": "2026-08-28T16:00:00Z", "en_route_at": null, "arrived_at": null, "departed_at": null, "completed_at": null, "address": { "line1": "300 Example Boulevard", "city": "Sample City", "region": "IL", "postal_code": "60000" }, "customer_present": true, "sentiment": null, "billable": true, "notes": "Synthetic scheduled visit.", "technician_notes": null, "customer_notes": "Call on arrival.", "checklist": [ { "id": "svci_test_01J9CHECK01", "label": "Confirm work area", "is_complete": false, "completed_by": null, "completed_at": null, "sort_order": 1 } ], "created_at": "2026-08-24T15:00:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_visit_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" }, "post": { "tags": [ "Service Center" ], "summary": "Schedule a service visit", "description": "Schedule a service visit Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_service_visit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_ticket_id": { "type": "string" }, "visit_type": { "type": "string" }, "scheduled_start": { "type": "string" }, "scheduled_end": { "type": "string" } }, "required": [ "service_ticket_id", "visit_type", "scheduled_start", "scheduled_end" ], "additionalProperties": false }, "example": { "service_ticket_id": "svc_test_01J9TICKET01", "visit_type": "onsite", "scheduled_start": "2026-08-28T14:00:00Z", "scheduled_end": "2026-08-28T16:00:00Z" } } } }, "responses": { "201": { "description": "Schedule a service visit response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "visit_test_01J9NEWVISIT", "object": "service_visit", "status": "accepted", "name": "Example service visit", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_visit_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/service/visits/{visit_id}": { "get": { "tags": [ "Service Center" ], "summary": "Get a service visit", "description": "Retrieve the visit schedule, assignment, route timestamps, notes, and checklist.", "operationId": "get_service_visit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "Opaque visit id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a service visit response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceVisitEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "visit_test_01J9SITE01", "object": "service_visit", "service_ticket_id": "svc_test_01J9TICKET01", "visit_type": "onsite", "status": "scheduled", "assigned_profile_id": "usr_test_01J9TECH01", "scheduled_start": "2026-08-28T14:00:00Z", "scheduled_end": "2026-08-28T16:00:00Z", "en_route_at": null, "arrived_at": null, "departed_at": null, "completed_at": null, "address": { "line1": "300 Example Boulevard", "city": "Sample City", "region": "IL", "postal_code": "60000" }, "customer_present": true, "sentiment": null, "billable": true, "notes": "Synthetic scheduled visit.", "technician_notes": null, "customer_notes": "Call on arrival.", "checklist": [ { "id": "svci_test_01J9CHECK01", "label": "Confirm work area", "is_complete": false, "completed_by": null, "completed_at": null, "sort_order": 1 } ], "created_at": "2026-08-24T15:00:00Z", "updated_at": "2026-08-24T15:00:00Z" }, "meta": { "request_id": "req_test_visit", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" }, "patch": { "tags": [ "Service Center" ], "summary": "Update a service visit", "description": "Update a service visit Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "update_service_visit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "Opaque visit id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "completed_at": { "type": "string" } }, "required": [ "status", "completed_at" ], "additionalProperties": false }, "example": { "status": "completed", "completed_at": "2026-08-28T15:42:00Z" } } } }, "responses": { "200": { "description": "Update a service visit response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "visit_test_01J9SITE01", "object": "service_visit", "status": "accepted", "name": "Example service visit", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_visit_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/service/plans": { "get": { "tags": [ "Service Center" ], "summary": "List service plans", "description": "List service plans", "operationId": "list_service_plans", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List service plans response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "service_plan_test_01J9EXAMPLE", "object": "service_plan", "status": "synthetic_example", "name": "Example service plan", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_service_plan_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" } }, "/api/retail/v1/service/enrollments": { "get": { "tags": [ "Service Center" ], "summary": "List service-plan enrollments", "description": "List service-plan enrollments", "operationId": "list_service_enrollments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Opaque customer identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List service-plan enrollments response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "service_plan_enrollment_test_01J9EXAMPLE", "object": "service_plan_enrollment", "status": "synthetic_example", "name": "Example service plan enrollment", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_service_plan_enrollment_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "service:read" } }, "/api/retail/v1/service/tickets/{ticket_id}/charges": { "post": { "tags": [ "Service Center" ], "summary": "Add a service charge", "description": "Add a service charge Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_service_charge", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "description": "Opaque ticket id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "charge_type": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_rate": { "type": "integer" } }, "required": [ "charge_type", "description", "quantity", "unit_rate" ], "additionalProperties": false }, "example": { "charge_type": "labor", "description": "Installation labor", "quantity": 2, "unit_rate": 150 } } } }, "responses": { "201": { "description": "Add a service charge response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "svcchg_test_01J9NEWCHARGE", "object": "service_charge", "status": "accepted", "name": "Example service charge", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_charge_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/service/tickets/{ticket_id}/time-entries": { "post": { "tags": [ "Service Center" ], "summary": "Add a service time entry", "description": "Add a service time entry Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_service_time_entry", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "description": "Opaque ticket id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_id": { "type": "string" }, "minutes": { "type": "integer" }, "billable": { "type": "boolean" }, "hourly_rate": { "type": "integer" } }, "required": [ "profile_id", "minutes", "billable", "hourly_rate" ], "additionalProperties": false }, "example": { "profile_id": "usr_test_01J9TECH01", "minutes": 120, "billable": true, "hourly_rate": 150 } } } }, "responses": { "201": { "description": "Add a service time entry response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "svctime_test_01J9NEWENTRY", "object": "service_time_entry", "status": "accepted", "name": "Example service time entry", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_service_time_entry_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "service:write" } }, "/api/retail/v1/projects": { "get": { "tags": [ "Projects & work" ], "summary": "List projects", "description": "List projects", "operationId": "list_projects", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Opaque customer identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List projects response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "prj_test_01J9INSTALL", "object": "project", "project_number": "PRJ-1042", "name": "Primary bedroom installation", "description": "Synthetic customer installation project.", "project_type": "installation", "status": "active", "health": "on_track", "location_id": "loc_test_01J9NORTHSTAR", "engagement_id": null, "template_id": "template_test_installation", "customer_id": "cus_test_01J9ALEXMORGAN", "linked_sale_id": "sal_test_01J9SALE10482", "owner_profile_id": "usr_test_01J9CASEY", "start_on": "2026-08-24", "due_on": "2026-08-28", "completed_at": null, "boards": [ { "id": "board_test_01J9INSTALL", "name": "Installation", "is_default": true, "sort_order": 1, "columns": [ { "id": "column_test_01J9READY", "name": "Ready", "status_key": "ready", "sort_order": 2, "wip_limit": null, "is_done": false } ] } ], "milestones": [ { "id": "mile_test_01J9DELIVERY", "title": "Delivery and setup", "status": "open", "owner_profile_id": "usr_test_01J9TECH01", "due_on": "2026-08-28", "completed_at": null, "sort_order": 1 } ], "work_items": [ { "id": "work_test_01J9INSTALL", "object": "work_item", "project_id": "prj_test_01J9INSTALL", "board_id": "board_test_01J9INSTALL", "column_id": "column_test_01J9READY", "milestone_id": "mile_test_01J9DELIVERY", "parent_item_id": null, "item_number": "TASK-14", "item_type": "task", "title": "Complete installation", "description": "Install, inspect, and walk the customer through operation.", "status": "ready", "priority": "normal", "assigned_profile_id": "usr_test_01J9TECH01", "start_on": "2026-08-28", "due_at": "2026-08-28T16:00:00Z", "completed_at": null, "estimated_minutes": 120, "actual_minutes": null, "recurrence_rule": null, "sort_order": 14, "checklist": [ { "id": "workcheck_test_01J9VERIFY", "title": "Verify final operation", "is_complete": false, "sort_order": 1 } ], "dependencies": [], "comments": [ { "id": "workcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "approvals": [ { "id": "workapproval_test_01J9CUSTOMER", "status": "pending", "request_note": "Customer sign-off", "decision_note": null, "decided_at": null } ], "created_at": "2026-08-24T14:45:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "comments": [ { "id": "prjcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "contact_links": [ { "id": "prjcontact_test_01J9CUSTOMER", "contact_id": "cus_test_01J9ALEXMORGAN", "role": "customer", "is_primary": true } ], "invoice_links": [ { "id": "pinv_test_01J9LINK", "invoice_id": "inv_test_01J9INVOICE10482", "created_at": "2026-08-24T14:36:18Z" } ], "created_at": "2026-08-24T14:40:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_project_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "projects:read" }, "post": { "tags": [ "Projects & work" ], "summary": "Create a project", "description": "Create a project Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_project", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "project_type": { "type": "string" }, "customer_id": { "type": "string" }, "start_on": { "type": "string" }, "due_on": { "type": "string" } }, "required": [ "name", "project_type", "customer_id", "start_on", "due_on" ], "additionalProperties": false }, "example": { "name": "Primary bedroom installation", "project_type": "installation", "customer_id": "cus_test_01J9ALEXMORGAN", "start_on": "2026-08-24", "due_on": "2026-08-28" } } } }, "responses": { "201": { "description": "Create a project response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prj_test_01J9NEWPROJECT", "object": "project", "status": "accepted", "name": "Example project", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_project_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/projects/{project_id}": { "get": { "tags": [ "Projects & work" ], "summary": "Get a complete project", "description": "Retrieve the supported project with boards and columns, milestones, work items, comments, contacts, invoice links, and ownership.", "operationId": "get_project", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Opaque project id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a complete project response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prj_test_01J9INSTALL", "object": "project", "project_number": "PRJ-1042", "name": "Primary bedroom installation", "description": "Synthetic customer installation project.", "project_type": "installation", "status": "active", "health": "on_track", "location_id": "loc_test_01J9NORTHSTAR", "engagement_id": null, "template_id": "template_test_installation", "customer_id": "cus_test_01J9ALEXMORGAN", "linked_sale_id": "sal_test_01J9SALE10482", "owner_profile_id": "usr_test_01J9CASEY", "start_on": "2026-08-24", "due_on": "2026-08-28", "completed_at": null, "boards": [ { "id": "board_test_01J9INSTALL", "name": "Installation", "is_default": true, "sort_order": 1, "columns": [ { "id": "column_test_01J9READY", "name": "Ready", "status_key": "ready", "sort_order": 2, "wip_limit": null, "is_done": false } ] } ], "milestones": [ { "id": "mile_test_01J9DELIVERY", "title": "Delivery and setup", "status": "open", "owner_profile_id": "usr_test_01J9TECH01", "due_on": "2026-08-28", "completed_at": null, "sort_order": 1 } ], "work_items": [ { "id": "work_test_01J9INSTALL", "object": "work_item", "project_id": "prj_test_01J9INSTALL", "board_id": "board_test_01J9INSTALL", "column_id": "column_test_01J9READY", "milestone_id": "mile_test_01J9DELIVERY", "parent_item_id": null, "item_number": "TASK-14", "item_type": "task", "title": "Complete installation", "description": "Install, inspect, and walk the customer through operation.", "status": "ready", "priority": "normal", "assigned_profile_id": "usr_test_01J9TECH01", "start_on": "2026-08-28", "due_at": "2026-08-28T16:00:00Z", "completed_at": null, "estimated_minutes": 120, "actual_minutes": null, "recurrence_rule": null, "sort_order": 14, "checklist": [ { "id": "workcheck_test_01J9VERIFY", "title": "Verify final operation", "is_complete": false, "sort_order": 1 } ], "dependencies": [], "comments": [ { "id": "workcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "approvals": [ { "id": "workapproval_test_01J9CUSTOMER", "status": "pending", "request_note": "Customer sign-off", "decision_note": null, "decided_at": null } ], "created_at": "2026-08-24T14:45:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "comments": [ { "id": "prjcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "contact_links": [ { "id": "prjcontact_test_01J9CUSTOMER", "contact_id": "cus_test_01J9ALEXMORGAN", "role": "customer", "is_primary": true } ], "invoice_links": [ { "id": "pinv_test_01J9LINK", "invoice_id": "inv_test_01J9INVOICE10482", "created_at": "2026-08-24T14:36:18Z" } ], "created_at": "2026-08-24T14:40:00Z", "updated_at": "2026-08-24T15:00:00Z" }, "meta": { "request_id": "req_test_01J9DOCSPROJECT", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "projects:read" }, "patch": { "tags": [ "Projects & work" ], "summary": "Update a project", "description": "Update a project Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "update_project", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Opaque project id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "health": { "type": "string" }, "due_on": { "type": "string" } }, "required": [ "health", "due_on" ], "additionalProperties": false }, "example": { "health": "on_track", "due_on": "2026-08-29" } } } }, "responses": { "200": { "description": "Update a project response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "prj_test_01J9INSTALL", "object": "project", "status": "accepted", "name": "Example project", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_project_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/projects/{project_id}/items": { "get": { "tags": [ "Projects & work" ], "summary": "List project work items", "description": "List project work items", "operationId": "list_project_items", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Opaque project id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List project work items response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkItemPage" }, "example": { "api_version": "2026-08", "data": [ { "id": "work_test_01J9INSTALL", "object": "work_item", "project_id": "prj_test_01J9INSTALL", "board_id": "board_test_01J9INSTALL", "column_id": "column_test_01J9READY", "milestone_id": "mile_test_01J9DELIVERY", "parent_item_id": null, "item_number": "TASK-14", "item_type": "task", "title": "Complete installation", "description": "Install, inspect, and walk the customer through operation.", "status": "ready", "priority": "normal", "assigned_profile_id": "usr_test_01J9TECH01", "start_on": "2026-08-28", "due_at": "2026-08-28T16:00:00Z", "completed_at": null, "estimated_minutes": 120, "actual_minutes": null, "recurrence_rule": null, "sort_order": 14, "checklist": [ { "id": "workcheck_test_01J9VERIFY", "title": "Verify final operation", "is_complete": false, "sort_order": 1 } ], "dependencies": [], "comments": [ { "id": "workcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "approvals": [ { "id": "workapproval_test_01J9CUSTOMER", "status": "pending", "request_note": "Customer sign-off", "decision_note": null, "decided_at": null } ], "created_at": "2026-08-24T14:45:00Z", "updated_at": "2026-08-24T15:00:00Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_project_items", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "projects:read" }, "post": { "tags": [ "Projects & work" ], "summary": "Create a work item", "description": "Create a work item Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_work_item", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Opaque project id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "item_type": { "type": "string" }, "priority": { "type": "string" }, "due_at": { "type": "string" } }, "required": [ "title", "item_type", "priority", "due_at" ], "additionalProperties": false }, "example": { "title": "Complete installation", "item_type": "task", "priority": "normal", "due_at": "2026-08-28T16:00:00Z" } } } }, "responses": { "201": { "description": "Create a work item response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "work_test_01J9NEWITEM", "object": "work_item", "status": "accepted", "name": "Example work item", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_work_item_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/work-items/{work_item_id}": { "get": { "tags": [ "Projects & work" ], "summary": "Get a complete work item", "description": "Retrieve the work item with checklist, dependencies, comments, approvals, estimates, assignment, and completion state.", "operationId": "get_work_item", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "work_item_id", "in": "path", "required": true, "description": "Opaque work item id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a complete work item response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkItemEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "work_test_01J9INSTALL", "object": "work_item", "project_id": "prj_test_01J9INSTALL", "board_id": "board_test_01J9INSTALL", "column_id": "column_test_01J9READY", "milestone_id": "mile_test_01J9DELIVERY", "parent_item_id": null, "item_number": "TASK-14", "item_type": "task", "title": "Complete installation", "description": "Install, inspect, and walk the customer through operation.", "status": "ready", "priority": "normal", "assigned_profile_id": "usr_test_01J9TECH01", "start_on": "2026-08-28", "due_at": "2026-08-28T16:00:00Z", "completed_at": null, "estimated_minutes": 120, "actual_minutes": null, "recurrence_rule": null, "sort_order": 14, "checklist": [ { "id": "workcheck_test_01J9VERIFY", "title": "Verify final operation", "is_complete": false, "sort_order": 1 } ], "dependencies": [], "comments": [ { "id": "workcomment_test_01J9NOTE", "body": "Synthetic project note.", "author_profile_id": "usr_test_01J9CASEY", "created_at": "2026-08-24T15:00:00Z" } ], "approvals": [ { "id": "workapproval_test_01J9CUSTOMER", "status": "pending", "request_note": "Customer sign-off", "decision_note": null, "decided_at": null } ], "created_at": "2026-08-24T14:45:00Z", "updated_at": "2026-08-24T15:00:00Z" }, "meta": { "request_id": "req_test_work_item", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "projects:read" }, "patch": { "tags": [ "Projects & work" ], "summary": "Update a work item", "description": "Update a work item Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "update_work_item", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "work_item_id", "in": "path", "required": true, "description": "Opaque work item id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "completed_at": { "type": "string" } }, "required": [ "status", "completed_at" ], "additionalProperties": false }, "example": { "status": "done", "completed_at": "2026-08-28T15:42:00Z" } } } }, "responses": { "200": { "description": "Update a work item response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "work_test_01J9INSTALL", "object": "work_item", "status": "accepted", "name": "Example work item", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_work_item_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/work-items/{work_item_id}/comments": { "post": { "tags": [ "Projects & work" ], "summary": "Add a work-item comment", "description": "Add a work-item comment Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "create_work_comment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "work_item_id", "in": "path", "required": true, "description": "Opaque work item id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ], "additionalProperties": false }, "example": { "body": "Synthetic completion note." } } } }, "responses": { "201": { "description": "Add a work-item comment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "workcomment_test_01J9NEWCOMMENT", "object": "work_comment", "status": "accepted", "name": "Example work comment", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_work_comment_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/work-items/{work_item_id}/approvals": { "post": { "tags": [ "Projects & work" ], "summary": "Request work approval", "description": "Request work approval Requires Idempotency-Key. Production mutation remains operation-gated.", "operationId": "request_work_approval", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "work_item_id", "in": "path", "required": true, "description": "Opaque work item id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approver_profile_id": { "type": "string" }, "request_note": { "type": "string" } }, "required": [ "approver_profile_id", "request_note" ], "additionalProperties": false }, "example": { "approver_profile_id": "usr_test_01J9MANAGER", "request_note": "Review completed installation." } } } }, "responses": { "201": { "description": "Request work approval response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "workapproval_test_01J9NEWAPPROVAL", "object": "work_approval", "status": "accepted", "name": "Example work approval", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_work_approval_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "projects:write" } }, "/api/retail/v1/fulfillment/orders": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "List fulfillment orders", "description": "Lists operational fulfillment orders from the native sale and line-item model, including an explicit online-store channel link when the order originated in CentriPOS commerce.", "operationId": "list_orders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "type", "in": "query", "required": false, "description": "Filter by type.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "promised_since", "in": "query", "required": false, "description": "Filter by promised since.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List fulfillment orders response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "018f6f54-a4dc-7c99-8f44-111111111111", "object": "fulfillment_order", "sale_id": "018f6f54-a4dc-7c99-8f44-111111111111", "sale_number": "S-10482", "status": "ready", "sale_status": "completed", "channel": "online_store", "storefront_order": { "id": "018f6f54-a4dc-7c99-8f44-222222222222", "order_number": "WEB-10482", "status": "paid" }, "customer_id": "cus_test_01J9ALEXMORGAN", "location_id": "loc_test_01J9NORTHSTAR", "fulfillment": { "type": "pickup", "status": "ready", "promised_date": "2026-08-26", "time_preference": "Afternoon", "source_location_id": "loc_test_01J9NORTHSTAR", "pickup_location_id": "loc_test_01J9NORTHSTAR", "pickup_method_id": "018f6f54-a4dc-7c99-8f44-333333333333", "ship_to_location_id": null, "shipping_method": null, "delivery_address": null, "delivery_phone": "+1-555-010-0184" }, "totals": { "total": 1727.72, "amount_paid": 1727.72, "balance_due": 0 }, "item_summary": { "line_count": 1, "quantity": 1, "open_line_count": 1 }, "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_01J9DOCSFULFILLMENTLIST", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "fulfillment:read" } }, "/api/retail/v1/fulfillment/orders/{order_id}": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "Get a fulfillment order", "description": "Returns the complete whitelisted fulfillment projection with line snapshots, customer delivery contact, online-order linkage, and safe shipment summaries.", "operationId": "get_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Opaque order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a fulfillment order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": { "id": "018f6f54-a4dc-7c99-8f44-111111111111", "object": "fulfillment_order", "sale_id": "018f6f54-a4dc-7c99-8f44-111111111111", "sale_number": "S-10482", "status": "ready", "sale_status": "completed", "channel": "online_store", "storefront_order": { "id": "018f6f54-a4dc-7c99-8f44-222222222222", "order_number": "WEB-10482", "status": "paid" }, "customer_id": "cus_test_01J9ALEXMORGAN", "location_id": "loc_test_01J9NORTHSTAR", "fulfillment": { "type": "pickup", "status": "ready", "promised_date": "2026-08-26", "time_preference": "Afternoon", "source_location_id": "loc_test_01J9NORTHSTAR", "pickup_location_id": "loc_test_01J9NORTHSTAR", "pickup_method_id": "018f6f54-a4dc-7c99-8f44-333333333333", "ship_to_location_id": null, "shipping_method": null, "delivery_address": null, "delivery_phone": "+1-555-010-0184" }, "totals": { "total": 1727.72, "amount_paid": 1727.72, "balance_due": 0 }, "item_summary": { "line_count": 1, "quantity": 1, "open_line_count": 1 }, "line_items": [ { "id": "line_test_01J9SALE10482A", "sort_order": 1, "quantity": 1, "product": { "id": "prd_test_01J9HARBOR12", "name": "Harbor 12-inch Hybrid Mattress", "brand": "Northstar Sleep" }, "variant": { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ] }, "unit_price": 1699, "quantity_price": 1699, "discount_total": 100, "tax_total": 128.72, "line_total": 1727.72, "discounts": [ { "id": "promo_test_100OFF", "name": "Synthetic launch offer", "type": "fixed", "amount": 100 } ], "tax_lines": [ { "id": "tax_test_state_local", "name": "Combined sales tax", "rate": 0.0805, "taxable_amount": 1599, "amount": 128.72 } ], "fulfillment": { "type": "pickup", "status": "ready", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "promised_at": "2026-08-26T18:00:00Z" }, "inventory_commitment": { "state": "backordered", "reserved_quantity": 0, "backorder_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "backorder": { "object": "commerce_backorder_commitment", "id": "boc_test_01J9SALE10482A", "status": "awaiting_stock", "requested_quantity": 1, "initially_reserved_quantity": 0, "backorder_quantity": 1, "allocated_quantity": 0, "remaining_quantity": 1, "policy": "allow_notify", "eta_date": "2026-09-03", "customer_message": "Available on backorder. Estimated fulfillment in 10 days.", "allocated_at": null, "fulfilled_at": null, "cancelled_at": null, "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:31:02Z" }, "warranty": { "term_years": 15, "registered": false }, "note": null } ], "customer": { "id": "cus_test_01J9ALEXMORGAN", "first_name": "Alex", "last_name": "Morgan", "email": "alex.morgan@example.test", "phone": "+1-555-010-0184" }, "online_order": { "id": "018f6f54-a4dc-7c99-8f44-222222222222", "order_number": "WEB-10482", "status": "paid", "shipping_address": null, "fulfillment_type": "pickup", "fulfillment_date": "2026-08-26", "delivery_method_id": null, "pickup_location_id": "loc_test_01J9NORTHSTAR", "shipping_method_id": null, "totals": { "subtotal": 1599, "shipping": 0, "tax": 128.72, "total": 1727.72 }, "tax_breakdown": [ { "name": "Combined sales tax", "amount": 128.72 } ], "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:36:18Z" }, "shipments": [], "created_at": "2026-08-24T14:31:02Z", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_01J9DOCSFULFILLMENT", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "fulfillment:read" }, "patch": { "tags": [ "Orders & fulfillment" ], "summary": "Update fulfillment status", "description": "Update fulfillment status", "operationId": "update_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Opaque order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "note": { "type": "string" } }, "required": [ "status", "note" ], "additionalProperties": false }, "example": { "status": "ready", "note": "Synthetic order staged at pickup desk." } } } }, "responses": { "200": { "description": "Update fulfillment status response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "ful_test_01J9PICKUP10482", "object": "fulfillment_order", "status": "accepted", "name": "Example fulfillment order", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_fulfillment_order_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "fulfillment:write" } }, "/api/retail/v1/delivery-methods": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "List delivery methods", "description": "Returns tenant-defined delivery pricing, coverage, availability, and online eligibility without private provider configuration.", "operationId": "list_delivery_methods", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List delivery methods response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "018f6f54-a4dc-7c99-8f44-444444444444", "object": "delivery_method", "name": "Local delivery", "description": "Synthetic local delivery method.", "is_enabled": true, "online_enabled": true, "price": { "enabled": true, "base": 79, "apply_tax": false, "mode": "flat", "distance_multiplier": null, "distance_adjustment": null, "rounding_mode": "nearest_cent" }, "availability_behavior": "scheduled", "coverage": { "mode": "distance", "minimum_distance_miles": 0, "maximum_distance_miles": 30 }, "sort_order": 1, "created_at": "2026-08-20T14:00:00Z", "updated_at": "2026-08-24T14:00:00Z" } ], "meta": { "request_id": "req_test_01J9DOCSDELIVERY", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "fulfillment:read" } }, "/api/retail/v1/shipping-methods": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "List shipping methods", "description": "Returns tenant-defined shipping methods, pricing, tax behavior, coverage, and online eligibility.", "operationId": "list_shipping_methods", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List shipping methods response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "018f6f54-a4dc-7c99-8f44-555555555555", "object": "shipping_method", "name": "Ground shipping", "description": "Synthetic ground service.", "is_enabled": true, "online_enabled": true, "base_price": 49, "apply_tax": false, "coverage_mode": "configured_zones", "sort_order": 1, "created_at": "2026-08-20T14:00:00Z", "updated_at": "2026-08-24T14:00:00Z" } ], "meta": { "request_id": "req_test_01J9DOCSSHIPPING", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "fulfillment:read" } }, "/api/retail/v1/fulfillment/availability": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "Get fulfillment availability", "description": "Get fulfillment availability", "operationId": "get_availability", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by type.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "postal_code", "in": "query", "required": false, "description": "Filter by postal code.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "from", "in": "query", "required": false, "description": "Filter by from.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "to", "in": "query", "required": false, "description": "Filter by to.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Get fulfillment availability response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "type": "pickup", "location": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "dates": [ { "date": "2026-08-26", "remaining_capacity": 8 }, { "date": "2026-08-27", "remaining_capacity": 5 } ] }, "meta": { "request_id": "req_test_availability", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "fulfillment:read" } }, "/api/retail/v1/shipments": { "post": { "tags": [ "Orders & fulfillment" ], "summary": "Create a shipment", "description": "Create a shipment", "operationId": "create_shipment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fulfillment_order_id": { "type": "string" }, "shipping_method_id": { "type": "string" }, "packages": { "type": "array", "items": { "type": "object", "properties": { "weight": { "type": "integer" }, "weight_unit": { "type": "string" } }, "required": [ "weight", "weight_unit" ], "additionalProperties": false } } }, "required": [ "fulfillment_order_id", "shipping_method_id", "packages" ], "additionalProperties": false }, "example": { "fulfillment_order_id": "ful_test_01J9SHIP10483", "shipping_method_id": "shp_method_test_ground", "packages": [ { "weight": 82, "weight_unit": "lb" } ] } } } }, "responses": { "201": { "description": "Create a shipment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "shp_test_01J9EXAMPLE", "object": "shipment", "status": "accepted", "name": "Example shipment", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_shipment_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "fulfillment:write" } }, "/api/retail/v1/shipments/{shipment_id}": { "get": { "tags": [ "Orders & fulfillment" ], "summary": "Get a shipment", "description": "Returns safe shipment and tracking state without labels, credentials, provider requests, rate payloads, or raw responses.", "operationId": "get_shipment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "description": "Opaque shipment id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a shipment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08-24", "data": { "id": "018f6f54-a4dc-7c99-8f44-666666666666", "object": "shipment", "sale_id": "sal_test_01J9SALE10482", "location_id": "loc_test_01J9NORTHSTAR", "provider": "synthetic_carrier_api", "status": "in_transit", "carrier": "Example Carrier", "service": "ground", "tracking_number": "DEMO123456789", "tracking_url": "https://tracking.example.test/DEMO123456789", "parcel": { "weight": 82, "weight_unit": "lb" }, "ship_to": { "city": "Sample City", "region": "IL", "postal_code": "60000", "country": "US" }, "ship_from": { "city": "Sample City", "region": "IL", "postal_code": "60001", "country": "US" }, "purchased_at": "2026-08-24T15:00:00Z", "voided_at": null, "created_at": "2026-08-24T14:50:00Z", "updated_at": "2026-08-25T10:00:00Z" }, "meta": { "request_id": "req_test_01J9DOCSSHIPMENT", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "fulfillment:read" } }, "/api/retail/v1/suppliers": { "get": { "tags": [ "Purchasing" ], "summary": "List suppliers", "description": "List suppliers", "operationId": "list_suppliers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List suppliers response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "supplier_test_01J9EXAMPLE", "object": "supplier", "status": "synthetic_example", "name": "Example supplier", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_supplier_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:read" } }, "/api/retail/v1/suppliers/{supplier_id}": { "get": { "tags": [ "Purchasing" ], "summary": "Get a supplier", "description": "Get a supplier", "operationId": "get_supplier", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "supplier_id", "in": "path", "required": true, "description": "Opaque supplier id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a supplier response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "sup_test_01J9EXAMPLE", "object": "supplier", "status": "synthetic_example", "name": "Example supplier", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_supplier", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:read" } }, "/api/retail/v1/purchase-orders": { "get": { "tags": [ "Purchasing" ], "summary": "List purchase orders", "description": "List purchase orders", "operationId": "list_purchase_orders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Filter by supplier id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List purchase orders response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "purchase_order_test_01J9EXAMPLE", "object": "purchase_order", "status": "synthetic_example", "name": "Example purchase order", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_purchase_order_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:read" }, "post": { "tags": [ "Purchasing" ], "summary": "Create a purchase order", "description": "Create a purchase order", "operationId": "create_purchase_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string" }, "destination_location_id": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string" }, "quantity": { "type": "integer" }, "unit_cost": { "type": "integer" } }, "required": [ "variant_id", "quantity", "unit_cost" ], "additionalProperties": false } } }, "required": [ "supplier_id", "destination_location_id", "lines" ], "additionalProperties": false }, "example": { "supplier_id": "sup_test_01J9EXAMPLE", "destination_location_id": "loc_test_01J9NORTHSTAR", "lines": [ { "variant_id": "var_test_01J9HARBORQUEEN", "quantity": 4, "unit_cost": 725 } ] } } } }, "responses": { "201": { "description": "Create a purchase order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "po_test_01J9EXAMPLE", "object": "purchase_order", "status": "accepted", "name": "Example purchase order", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_purchase_order_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:write" } }, "/api/retail/v1/purchase-orders/{purchase_order_id}": { "get": { "tags": [ "Purchasing" ], "summary": "Get a purchase order", "description": "Get a purchase order", "operationId": "get_purchase_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Opaque purchase order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a purchase order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "po_test_01J9EXAMPLE", "object": "purchase_order", "status": "synthetic_example", "name": "Example purchase order", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_purchase_order", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:read" } }, "/api/retail/v1/purchase-orders/{purchase_order_id}/submit": { "post": { "tags": [ "Purchasing" ], "summary": "Submit a purchase order", "description": "Submit a purchase order", "operationId": "submit_purchase_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Opaque purchase order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "submitted_at": { "type": "string" } }, "required": [ "submitted_at" ], "additionalProperties": false }, "example": { "submitted_at": "2026-08-25T15:00:00Z" } } } }, "responses": { "200": { "description": "Submit a purchase order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "po_test_01J9EXAMPLE", "object": "purchase_order", "status": "accepted", "name": "Example purchase order", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_purchase_order_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:write" } }, "/api/retail/v1/purchase-orders/{purchase_order_id}/receivings": { "post": { "tags": [ "Purchasing" ], "summary": "Receive purchase-order inventory", "description": "Receive purchase-order inventory", "operationId": "receive_purchase_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Opaque purchase order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string" }, "quantity_received": { "type": "integer" } }, "required": [ "variant_id", "quantity_received" ], "additionalProperties": false } } }, "required": [ "location_id", "lines" ], "additionalProperties": false }, "example": { "location_id": "loc_test_01J9NORTHSTAR", "lines": [ { "variant_id": "var_test_01J9HARBORQUEEN", "quantity_received": 4 } ] } } } }, "responses": { "201": { "description": "Receive purchase-order inventory response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "rcv_test_01J9EXAMPLE", "object": "receiving", "status": "accepted", "name": "Example receiving", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_receiving_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "purchasing:write" } }, "/api/retail/v1/price-books": { "get": { "tags": [ "Pricing & tax" ], "summary": "List price books", "description": "List price books", "operationId": "list_price_books", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "channel", "in": "query", "required": false, "description": "Filter by channel.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List price books response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "price_book_test_01J9EXAMPLE", "object": "price_book", "status": "synthetic_example", "name": "Example price book", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_price_book_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "pricing:read" } }, "/api/retail/v1/price-books/{price_book_id}": { "get": { "tags": [ "Pricing & tax" ], "summary": "Get a price book", "description": "Get a price book", "operationId": "get_price_book", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_book_id", "in": "path", "required": true, "description": "Opaque price book id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a price book response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "pb_test_01J9EXAMPLE", "object": "price_book", "status": "synthetic_example", "name": "Example price book", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_price_book", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "pricing:read" } }, "/api/retail/v1/promotions": { "get": { "tags": [ "Pricing & tax" ], "summary": "List promotions", "description": "List promotions", "operationId": "list_promotions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "channel", "in": "query", "required": false, "description": "Filter by channel.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active_at", "in": "query", "required": false, "description": "Filter by active at.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List promotions response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "promotion_test_01J9EXAMPLE", "object": "promotion", "status": "synthetic_example", "name": "Example promotion", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_promotion_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "pricing:read" }, "post": { "tags": [ "Pricing & tax" ], "summary": "Create a promotion", "description": "Create a promotion", "operationId": "create_promotion", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "channel": { "type": "string" }, "action": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "type", "amount" ], "additionalProperties": false } }, "required": [ "name", "channel", "action" ], "additionalProperties": false }, "example": { "name": "Synthetic weekend offer", "channel": "in_store_and_online", "action": { "type": "fixed_discount", "amount": 100 } } } } }, "responses": { "201": { "description": "Create a promotion response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "promo_test_01J9EXAMPLE", "object": "promotion", "status": "accepted", "name": "Example promotion", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_promotion_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "pricing:write" } }, "/api/retail/v1/tax-rates": { "get": { "tags": [ "Pricing & tax" ], "summary": "List tax rates", "description": "List tax rates", "operationId": "list_tax_rates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List tax rates response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "tax_rate_test_01J9EXAMPLE", "object": "tax_rate", "status": "synthetic_example", "name": "Example tax rate", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_tax_rate_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "pricing:read" } }, "/api/retail/v1/merchant": { "get": { "tags": [ "Merchant setup" ], "summary": "Get merchant projection", "description": "Get merchant projection", "operationId": "get_merchant", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Get merchant projection response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "mrc_test_01J9NORTHSTAR", "display_name": "Northstar Home & Sleep", "currency": "USD", "timezone": "America/Chicago", "environment": "test" }, "meta": { "request_id": "req_test_merchant", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "merchant:read" } }, "/api/retail/v1/locations": { "get": { "tags": [ "Merchant setup" ], "summary": "List locations", "description": "List locations", "operationId": "list_locations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List locations response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_locations", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "locations:read" } }, "/api/retail/v1/locations/{location_id}": { "get": { "tags": [ "Merchant setup" ], "summary": "Get a location", "description": "Get a location", "operationId": "get_location", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "description": "Opaque location id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a location response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "loc_test_01J9NORTHSTAR", "name": "Northstar Main Store", "code": "MAIN", "timezone": "America/Chicago" }, "meta": { "request_id": "req_test_location", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "authenticated-live", "x-required-scope": "locations:read" } }, "/api/retail/v1/registers": { "get": { "tags": [ "Merchant setup" ], "summary": "List registers", "description": "List registers", "operationId": "list_registers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List registers response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "reg_test_01J9FRONT01", "name": "Front Register", "code": "FRONT-1" } ], "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }, "meta": { "request_id": "req_test_registers", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "locations:read" } }, "/api/retail/v1/users": { "get": { "tags": [ "Merchant setup" ], "summary": "List users", "description": "List users", "operationId": "list_users", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "role_id", "in": "query", "required": false, "description": "Filter by role id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List users response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "user_test_01J9EXAMPLE", "object": "user", "status": "synthetic_example", "name": "Example user", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_user_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "users:read" } }, "/api/retail/v1/roles": { "get": { "tags": [ "Merchant setup" ], "summary": "List roles", "description": "List roles", "operationId": "list_roles", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List roles response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "role_test_01J9EXAMPLE", "object": "role", "status": "synthetic_example", "name": "Example role", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_role_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "users:read" } }, "/api/retail/v1/payment-types": { "get": { "tags": [ "Merchant setup" ], "summary": "List payment types", "description": "List payment types", "operationId": "list_payment_types", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List payment types response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "payment_type_test_01J9EXAMPLE", "object": "payment_type", "status": "synthetic_example", "name": "Example payment type", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_payment_type_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "merchant:read" } }, "/api/retail/v1/reports/sales-summary": { "get": { "tags": [ "Reports & exports" ], "summary": "Read sales summary", "description": "Read sales summary", "operationId": "sales_summary", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "from", "in": "query", "required": false, "description": "Filter by from.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "to", "in": "query", "required": false, "description": "Filter by to.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "group_by", "in": "query", "required": false, "description": "Filter by group by.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Read sales summary response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "currency": "USD", "period": { "from": "2026-08-01", "to": "2026-08-24" }, "gross_sales": 128450.32, "discounts": 6830.15, "returns": 4210.5, "net_sales": 117409.67, "tax": 9446.48, "transactions": 241 }, "meta": { "request_id": "req_test_sales_report", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "reports:read" } }, "/api/retail/v1/reports/inventory-valuation": { "get": { "tags": [ "Reports & exports" ], "summary": "Read inventory valuation", "description": "Read inventory valuation", "operationId": "inventory_valuation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "location_id", "in": "query", "required": false, "description": "Opaque location identifier visible to the authenticated API client.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "as_of", "in": "query", "required": false, "description": "Filter by as of.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "group_by", "in": "query", "required": false, "description": "Filter by group by.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Read inventory valuation response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "report_test_01J9EXAMPLE", "object": "inventory_valuation", "status": "synthetic_example", "name": "Example inventory valuation", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_inventory_valuation", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "reports:read" } }, "/api/retail/v1/exports": { "post": { "tags": [ "Reports & exports" ], "summary": "Create an asynchronous export", "description": "Create an asynchronous export", "operationId": "create_export", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "format": { "type": "string" }, "filters": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "required": [ "resource", "format", "filters" ], "additionalProperties": false }, "example": { "resource": "sales", "format": "csv", "filters": { "from": "2026-08-01", "to": "2026-08-24" } } } } }, "responses": { "201": { "description": "Create an asynchronous export response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "exp_test_01J9EXAMPLE", "object": "export", "status": "accepted", "name": "Example export", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_export_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "reports:export" } }, "/api/retail/v1/exports/{export_id}": { "get": { "tags": [ "Reports & exports" ], "summary": "Get export status", "description": "Get export status", "operationId": "get_export", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "export_id", "in": "path", "required": true, "description": "Opaque export id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get export status response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "exp_test_01J9EXAMPLE", "status": "completed", "format": "csv", "expires_at": "2026-08-25T14:36:18Z", "download_url": "https://downloads.example.test/export-synthetic.csv" }, "meta": { "request_id": "req_test_export", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "reports:export" } }, "/api/retail/v1/webhook-subscriptions": { "get": { "tags": [ "Webhooks & audit" ], "summary": "List webhook subscriptions", "description": "List webhook subscriptions", "operationId": "list_webhooks", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List webhook subscriptions response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "webhook_subscription_test_01J9EXAMPLE", "object": "webhook_subscription", "status": "synthetic_example", "name": "Example webhook subscription", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_webhook_subscription_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:read" }, "post": { "tags": [ "Webhooks & audit" ], "summary": "Create a webhook subscription", "description": "Create a webhook subscription Signing secret is shown once. Requires Idempotency-Key.", "operationId": "create_webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "events" ], "additionalProperties": false }, "example": { "url": "https://integrator.example.test/webhooks/centripos", "events": [ "sale.completed", "inventory.level.changed", "commerce_backorder.created", "commerce_backorder.updated" ] } } } }, "responses": { "201": { "description": "Create a webhook subscription response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "whsub_test_01J9EXAMPLE", "object": "webhook_subscription", "status": "accepted", "name": "Example webhook subscription", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_webhook_subscription_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:write" } }, "/api/retail/v1/webhook-subscriptions/{subscription_id}": { "get": { "tags": [ "Webhooks & audit" ], "summary": "Get a webhook subscription", "description": "Get a webhook subscription", "operationId": "get_webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Opaque subscription id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get a webhook subscription response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "whsub_test_01J9EXAMPLE", "object": "webhook_subscription", "status": "synthetic_example", "name": "Example webhook subscription", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_webhook_subscription", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:read" }, "patch": { "tags": [ "Webhooks & audit" ], "summary": "Update a webhook subscription", "description": "Update a webhook subscription", "operationId": "update_webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Opaque subscription id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "events" ], "additionalProperties": false }, "example": { "events": [ "sale.completed", "sale.returned", "inventory.level.changed", "commerce_backorder.created", "commerce_backorder.updated" ] } } } }, "responses": { "200": { "description": "Update a webhook subscription response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "whsub_test_01J9EXAMPLE", "object": "webhook_subscription", "status": "accepted", "name": "Example webhook subscription", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_webhook_subscription_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:write" }, "delete": { "tags": [ "Webhooks & audit" ], "summary": "Delete a webhook subscription", "description": "Delete a webhook subscription", "operationId": "delete_webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Opaque subscription id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "responses": { "204": { "description": "Resource deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:write" } }, "/api/retail/v1/webhook-events": { "get": { "tags": [ "Webhooks & audit" ], "summary": "List webhook events", "description": "List webhook events", "operationId": "list_webhook_events", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "event", "in": "query", "required": false, "description": "Filter by event.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "created_since", "in": "query", "required": false, "description": "Return records created at or after this RFC 3339 timestamp.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List webhook events response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "webhook_event_test_01J9EXAMPLE", "object": "webhook_event", "status": "synthetic_example", "name": "Example webhook event", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_webhook_event_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:read" } }, "/api/retail/v1/webhook-deliveries": { "get": { "tags": [ "Webhooks & audit" ], "summary": "List webhook deliveries", "description": "List webhook deliveries", "operationId": "list_webhook_deliveries", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "subscription_id", "in": "query", "required": false, "description": "Filter by subscription id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "event_id", "in": "query", "required": false, "description": "Filter by event id.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List webhook deliveries response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "webhook_delivery_test_01J9EXAMPLE", "object": "webhook_delivery", "status": "synthetic_example", "name": "Example webhook delivery", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_webhook_delivery_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:read" } }, "/api/retail/v1/webhook-deliveries/{delivery_id}/redeliver": { "post": { "tags": [ "Webhooks & audit" ], "summary": "Redeliver a webhook event", "description": "Redeliver a webhook event", "operationId": "redeliver_webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "description": "Opaque delivery id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. Replays with the same normalized request return the original result.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Synthetic integration replay test" } } } }, "responses": { "200": { "description": "Redeliver a webhook event response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "id": "whdel_test_01J9EXAMPLE", "object": "webhook_delivery", "status": "accepted", "name": "Example webhook delivery", "updated_at": "2026-08-24T14:36:18Z" }, "meta": { "request_id": "req_test_webhook_delivery_mutation", "environment": "test", "idempotency": { "key": "doc-example-7f404326", "replayed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "webhooks:write" } }, "/api/retail/v1/request-logs": { "get": { "tags": [ "Webhooks & audit" ], "summary": "List API request logs", "description": "List API request logs", "operationId": "list_request_logs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the documented resource status.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "method", "in": "query", "required": false, "description": "Filter by method.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "route", "in": "query", "required": false, "description": "Filter by route.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "created_since", "in": "query", "required": false, "description": "Return records created at or after this RFC 3339 timestamp.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "List API request logs response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": [ { "id": "request_log_test_01J9EXAMPLE", "object": "request_log", "status": "synthetic_example", "name": "Example request log", "updated_at": "2026-08-24T14:36:18Z" } ], "pagination": { "next_cursor": "cur_test_NEXT_PAGE", "has_more": true, "limit": 50 }, "meta": { "request_id": "req_test_request_log_list", "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "audit:read" } }, "/api/retail/v1/request-logs/{request_id}": { "get": { "tags": [ "Webhooks & audit" ], "summary": "Get an API request log", "description": "Get an API request log", "operationId": "get_request_log", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "Opaque request id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get an API request log response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEnvelope" }, "example": { "api_version": "2026-08", "data": { "request_id": "req_test_01J9DOCSSALE", "method": "GET", "route_template": "/sales/{sale_id}", "status": 200, "duration_ms": 84, "scope": "sales:read", "idempotency": null, "created_at": "2026-08-24T14:36:18Z" }, "meta": { "environment": "test" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "controlled-rollout", "x-required-scope": "audit:read" } }, "/api/storefront/v1/{storefront_slug}": { "get": { "tags": [ "Public storefront" ], "summary": "Get storefront feed", "description": "Read one merchant-published browser-safe storefront projection.", "operationId": "public_storefront_feed", "security": [], "parameters": [ { "name": "storefront_slug", "in": "path", "required": true, "description": "Opaque storefront slug. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get storefront feed response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontEnvelope" }, "example": { "api_version": "2026-08-24", "storefront": { "slug": "northstar-sleep-demo", "name": "Northstar Home & Sleep" }, "catalog": { "products": [ { "id": "prd_test_01J9HARBOR12", "handle": "harbor-12-hybrid-mattress", "name": "Harbor 12-inch Hybrid Mattress", "brand": { "id": "brd_test_northstar", "name": "Northstar Sleep" }, "status": "active", "sellable": true, "online_backorder_policy": { "mode": "allow_notify", "max_backorder_quantity": 2, "eta_days": 10, "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "description": "A balanced hybrid with responsive support and a quilted comfort surface.", "category": { "id": "cat_test_mattresses", "name": "Mattresses", "slug": "mattresses" }, "tags": [ { "id": "tag_test_hybrid", "name": "Hybrid", "slug": "hybrid" } ], "variants": [ { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "barcode": "000000000001", "price": { "amount": 1699, "currency": "USD" }, "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ], "inventory": { "tracked": true, "available": 6, "reserved": 1, "incoming": 4 }, "online_backorder_policy": { "mode": "inherit", "max_backorder_quantity": null, "eta_days": null, "customer_message": null } } ], "custom_fields": { "price_area": [ { "key": "warranty_years", "label": "Warranty", "value": 15, "value_type": "number" } ], "description": [ { "key": "construction", "label": "Construction", "value": "Hybrid", "value_type": "text" } ], "specifications": [ { "key": "profile_height", "label": "Profile height", "value": 12, "unit": "in", "value_type": "number" }, { "key": "firmness_level", "label": "Firmness level", "value": 6, "value_type": "number" } ] }, "media": [ { "id": "med_test_01J9HARBORFRONT", "type": "image", "role": "primary", "alt": "Synthetic Harbor mattress product render", "url": "https://pos.getcentri.com/media/product/demo/harbor-12-front.webp" } ], "created_at": "2026-07-14T16:03:11Z", "updated_at": "2026-08-22T19:45:02Z" } ] }, "links": { "self": "https://pos.getcentri.com/api/storefront/v1/northstar-sleep-demo" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "live", "x-required-scope": "Public" } }, "/api/storefront/v1/{storefront_slug}/catalog": { "get": { "tags": [ "Public storefront" ], "summary": "List published catalog", "description": "Read published products, variants, taxonomy, filters, facets, and approved commerce fields.", "operationId": "public_storefront_catalog", "security": [], "parameters": [ { "name": "storefront_slug", "in": "path", "required": true, "description": "Opaque storefront slug. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "search", "in": "query", "required": false, "description": "Filter by search.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "brand", "in": "query", "required": false, "description": "Filter by brand.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "tag", "in": "query", "required": false, "description": "Filter by tag.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "min_price", "in": "query", "required": false, "description": "Filter by min price.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "max_price", "in": "query", "required": false, "description": "Filter by max price.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "in_stock", "in": "query", "required": false, "description": "Filter by in stock.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "page", "in": "query", "required": false, "description": "Filter by page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. The contract default is 50 and maximum is 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "List published catalog response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogEnvelope" }, "example": { "api_version": "2026-08-24", "data": [ { "id": "prd_test_01J9HARBOR12", "handle": "harbor-12-hybrid-mattress", "name": "Harbor 12-inch Hybrid Mattress", "brand": { "id": "brd_test_northstar", "name": "Northstar Sleep" }, "status": "active", "sellable": true, "online_backorder_policy": { "mode": "allow_notify", "max_backorder_quantity": 2, "eta_days": 10, "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "description": "A balanced hybrid with responsive support and a quilted comfort surface.", "category": { "id": "cat_test_mattresses", "name": "Mattresses", "slug": "mattresses" }, "tags": [ { "id": "tag_test_hybrid", "name": "Hybrid", "slug": "hybrid" } ], "variants": [ { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "barcode": "000000000001", "price": { "amount": 1699, "currency": "USD" }, "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ], "inventory": { "tracked": true, "available": 6, "reserved": 1, "incoming": 4 }, "online_backorder_policy": { "mode": "inherit", "max_backorder_quantity": null, "eta_days": null, "customer_message": null } } ], "custom_fields": { "price_area": [ { "key": "warranty_years", "label": "Warranty", "value": 15, "value_type": "number" } ], "description": [ { "key": "construction", "label": "Construction", "value": "Hybrid", "value_type": "text" } ], "specifications": [ { "key": "profile_height", "label": "Profile height", "value": 12, "unit": "in", "value_type": "number" }, { "key": "firmness_level", "label": "Firmness level", "value": 6, "value_type": "number" } ] }, "media": [ { "id": "med_test_01J9HARBORFRONT", "type": "image", "role": "primary", "alt": "Synthetic Harbor mattress product render", "url": "https://pos.getcentri.com/media/product/demo/harbor-12-front.webp" } ], "created_at": "2026-07-14T16:03:11Z", "updated_at": "2026-08-22T19:45:02Z" } ], "pagination": { "page": 1, "limit": 24, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "live", "x-required-scope": "Public" } }, "/api/storefront/v1/{storefront_slug}/products/{product_slug}": { "get": { "tags": [ "Public storefront" ], "summary": "Get published product", "description": "Read one published product addressed by its customer-facing slug.", "operationId": "public_storefront_product", "security": [], "parameters": [ { "name": "storefront_slug", "in": "path", "required": true, "description": "Opaque storefront slug. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } }, { "name": "product_slug", "in": "path", "required": true, "description": "Opaque product slug. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "minLength": 3, "maxLength": 160 } } ], "responses": { "200": { "description": "Get published product response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontProductEnvelope" }, "example": { "api_version": "2026-08-24", "data": { "id": "prd_test_01J9HARBOR12", "handle": "harbor-12-hybrid-mattress", "name": "Harbor 12-inch Hybrid Mattress", "brand": { "id": "brd_test_northstar", "name": "Northstar Sleep" }, "status": "active", "sellable": true, "online_backorder_policy": { "mode": "allow_notify", "max_backorder_quantity": 2, "eta_days": 10, "customer_message": "Available on backorder. Estimated fulfillment in 10 days." }, "description": "A balanced hybrid with responsive support and a quilted comfort surface.", "category": { "id": "cat_test_mattresses", "name": "Mattresses", "slug": "mattresses" }, "tags": [ { "id": "tag_test_hybrid", "name": "Hybrid", "slug": "hybrid" } ], "variants": [ { "id": "var_test_01J9HARBORQUEEN", "name": "Queen / Medium", "sku": "DEMO-HBR-Q-MED", "barcode": "000000000001", "price": { "amount": 1699, "currency": "USD" }, "options": [ { "name": "Size", "value": "Queen" }, { "name": "Feel", "value": "Medium" } ], "inventory": { "tracked": true, "available": 6, "reserved": 1, "incoming": 4 }, "online_backorder_policy": { "mode": "inherit", "max_backorder_quantity": null, "eta_days": null, "customer_message": null } } ], "custom_fields": { "price_area": [ { "key": "warranty_years", "label": "Warranty", "value": 15, "value_type": "number" } ], "description": [ { "key": "construction", "label": "Construction", "value": "Hybrid", "value_type": "text" } ], "specifications": [ { "key": "profile_height", "label": "Profile height", "value": 12, "unit": "in", "value_type": "number" }, { "key": "firmness_level", "label": "Firmness level", "value": 6, "value_type": "number" } ] }, "media": [ { "id": "med_test_01J9HARBORFRONT", "type": "image", "role": "primary", "alt": "Synthetic Harbor mattress product render", "url": "https://pos.getcentri.com/media/product/demo/harbor-12-front.webp" } ], "created_at": "2026-07-14T16:03:11Z", "updated_at": "2026-08-22T19:45:02Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "live", "x-required-scope": "Public" } }, "/api/retail/v1/storefront/resolve": { "get": { "tags": [ "Public storefront" ], "summary": "Resolve certified storefront checkout", "description": "Resolve checkout capabilities from the tenant-bound credential. The caller cannot select a tenant, data plane, hostname, or storefront slug. Certified server integration only; activation is bound to the approved tenant and API client.", "operationId": "certified_storefront_resolve", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Resolve certified storefront checkout response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertifiedStorefrontResolveEnvelope" }, "example": { "data": { "tenant_name": "Northstar Home & Sleep", "storefront": { "slug": "northstar-sleep-demo", "store_name": "Northstar Home & Sleep", "store_description": "Synthetic storefront used only for documentation.", "primary_color": "#16324f", "accent_color": "#d08b3e", "seo_title": "Northstar Home & Sleep", "seo_description": "Synthetic sleep products.", "logo_url": null, "hero_image_url": null, "custom_css": null, "is_published": true }, "checkout": { "pickup_locations": [], "delivery_methods": [], "shipping_methods": [], "gateway": null, "financing": [], "fulfillment_available": { "pickup": false, "local_delivery": false, "shipping": false }, "shipping_schedule": { "mode": "open_ended", "date_intent": "ship_on" } } }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_resolve" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "storefront:read", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false } } }, "/api/retail/v1/storefront/quotes": { "post": { "tags": [ "Public storefront" ], "summary": "Create authoritative storefront quote", "description": "Reprice inventory, address eligibility, promotions, tax, shipping or delivery fees, and line-level fulfillment on CentriPOS servers. Cart methods are the intersection of every line; split packages are not supported. Requires Idempotency-Key. Retry only with the byte-identical raw JSON request body; any byte difference conflicts. Stored replays carry Idempotency-Replayed: true. Client prices, tax, fees, inventory, promotions, and fulfillment eligibility are never authoritative.", "operationId": "certified_storefront_quote", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. A retry replays only when its raw JSON request body is byte-identical; any byte difference conflicts.", "schema": { "type": "string", "minLength": 16, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]{16,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items", "customer", "fulfillment_type" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "variant_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99 } } } }, "customer": { "type": "object", "additionalProperties": false, "required": [ "firstName", "email" ], "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "address": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "maxLength": 64 }, "zip": { "type": "string", "maxLength": 20 } } }, "fulfillment_type": { "type": "string", "enum": [ "pickup", "local_delivery", "shipping" ] }, "fulfillment_date": { "type": "string", "format": "date" }, "fulfillment_time": { "type": "string", "maxLength": 64 }, "promotion_code": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]*$" }, "shipping_method_id": { "type": "string", "format": "uuid" }, "delivery_method_id": { "type": "string", "format": "uuid" }, "pickup_location_id": { "type": "string", "format": "uuid" }, "shipping_address": { "type": "object", "additionalProperties": false, "required": [ "address", "city", "state", "zip" ], "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "maxLength": 64 }, "zip": { "type": "string", "minLength": 1, "maxLength": 20 } } } }, "allOf": [ { "if": { "properties": { "fulfillment_type": { "const": "shipping" } } }, "then": { "required": [ "shipping_method_id", "shipping_address" ], "not": { "anyOf": [ { "required": [ "delivery_method_id" ] }, { "required": [ "pickup_location_id" ] } ] } } }, { "if": { "properties": { "fulfillment_type": { "const": "local_delivery" } } }, "then": { "required": [ "delivery_method_id", "shipping_address", "fulfillment_date" ], "not": { "anyOf": [ { "required": [ "shipping_method_id" ] }, { "required": [ "pickup_location_id" ] } ] } } }, { "if": { "properties": { "fulfillment_type": { "const": "pickup" } } }, "then": { "required": [ "pickup_location_id", "fulfillment_date" ], "not": { "anyOf": [ { "required": [ "shipping_method_id" ] }, { "required": [ "delivery_method_id" ] }, { "required": [ "shipping_address" ] } ] } } }, { "if": { "properties": { "fulfillment_time": { "minLength": 1 } }, "required": [ "fulfillment_time" ] }, "then": { "required": [ "fulfillment_date" ] } } ] }, "example": { "items": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "quantity": 2 } ], "customer": { "firstName": "Alex", "lastName": "Morgan", "email": "alex.morgan@example.test", "phone": "+1-555-010-0184", "address": "100 Example Street", "city": "Sample City", "state": "IL", "zip": "60000" }, "fulfillment_type": "shipping", "shipping_method_id": "33333333-3333-4333-8333-333333333333", "shipping_address": { "address": "100 Example Street", "city": "Sample City", "state": "IL", "zip": "60000" } } } } }, "responses": { "200": { "description": "Create authoritative storefront quote response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" }, "Idempotency-Replayed": { "description": "Present with value true only when CentriPOS returns the stored response for a byte-identical idempotent replay.", "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertifiedStorefrontQuoteEnvelope" }, "example": { "data": { "quote": { "id": "44444444-4444-4444-8444-444444444444", "status": "open", "items": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "original_unit_price": null, "price_source": { "type": "catalog" }, "line_total": 1598, "shipping_fee": 100, "fulfillment": { "packaging": "boxed", "allowed_methods": [ "pickup", "local_delivery", "shipping" ], "nationwide_shipping": { "available": true, "pricing_type": "flat", "fee": 50, "region": "continental_us" } }, "fulfillment_badges": [ "Ships in a Box", "Nationwide Shipping — $50", "Local delivery", "Pickup" ], "tax_rate": 0.075, "tax_amount": 119.84, "inventory": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "policy": null, "eta_date": null, "customer_notice": false, "customer_message": null } } ], "fulfillment": { "type": "shipping", "shipping_method_id": "33333333-3333-4333-8333-333333333333", "method_name": "Synthetic ground shipping", "date": null, "time": null, "shipping_address": { "address": "100 Example Street", "city": "Sample City", "state": "IL", "zip": "60000" } }, "subtotal": 1598, "discount_total": 0, "promotions": [], "promotion_code": null, "shipping_total": 100, "tax_total": 119.84, "total": 1817.84, "inventory": { "has_backorders": false, "backorder_quantity": 0 }, "expires_at": "2026-08-25T16:15:00Z" } }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_quote" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "checkout:write", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false }, "x-idempotency-required": true } }, "/api/retail/v1/storefront/checkouts/{quote_id}/prepare": { "post": { "tags": [ "Public storefront" ], "summary": "Prepare storefront order", "description": "Prepare one order and return the exact prepared-sale public card tokenization and 3DS configuration resolved from its processor register scope. The response exposes browser-safe public keys only, never processor security keys, credentials, posted capabilities, or raw payment data. Requires Idempotency-Key and an active per-tenant checkout certification. Retry only with the byte-identical raw JSON request body; stored replays carry Idempotency-Replayed: true.", "operationId": "certified_storefront_prepare", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "Opaque quote id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "format": "uuid", "example": "44444444-4444-4444-8444-444444444444" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. A retry replays only when its raw JSON request body is byte-identical; any byte difference conflicts.", "schema": { "type": "string", "minLength": 16, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]{16,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Prepare storefront order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" }, "Idempotency-Replayed": { "description": "Present with value true only when CentriPOS returns the stored response for a byte-identical idempotent replay.", "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CertifiedStorefrontOrderEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "payment_configuration" ] } } } ] }, "example": { "data": { "id": "55555555-5555-4555-8555-555555555555", "object": "storefront_order", "order_number": "WEB-TEST-10482", "status": "pending", "payment_status": "pending", "total": 1817.84, "fulfillment": { "type": "shipping", "date": null, "delivery_method_id": null, "pickup_location_id": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333" }, "totals": { "subtotal": 1598, "shipping": 100, "tax": 119.84, "total": 1817.84 }, "inventory": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0 } ], "items": [ { "id": "66666666-6666-4666-8666-666666666666", "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "line_total": 1598, "fulfillment": { "type": "shipping", "status": "unfulfilled", "date": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333", "delivery_method_id": null, "pickup_location_id": null }, "inventory_commitment": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "eta_date": null, "customer_message": null } } ], "created_at": "2026-08-25T15:45:00Z", "updated_at": "2026-08-25T15:45:00Z", "payment_configuration": { "card": { "provider": "centripay_gateway", "is_connected": true, "tokenization_key": "synthetic_public_collectjs_key", "three_ds_tokenization_key": "synthetic_public_3ds_key", "three_ds_enabled": true } } }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_prepare" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "checkout:write", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false }, "x-idempotency-required": true } }, "/api/retail/v1/storefront/checkouts/{quote_id}/payments/card": { "post": { "tags": [ "Public storefront" ], "summary": "Handoff certified card payment", "description": "Submit only an opaque token from the certified payment surface plus bounded 3DS evidence. PAN, CVV, reusable credentials, and raw processor responses are prohibited. An already completed order may add operation-specific meta.replayed; gateway request replay is signaled only by Idempotency-Replayed: true. Requires Idempotency-Key. Retry only with the byte-identical raw JSON request body; stored replays carry Idempotency-Replayed: true. Card data must be tokenized by the certified browser payment surface and never pass through the website server.", "operationId": "certified_storefront_card", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "Opaque quote id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "format": "uuid", "example": "44444444-4444-4444-8444-444444444444" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. A retry replays only when its raw JSON request body is byte-identical; any byte difference conflicts.", "schema": { "type": "string", "minLength": 16, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]{16,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payment_token" ], "properties": { "payment_token": { "type": "string", "minLength": 10, "maxLength": 4096, "pattern": "^[A-Za-z0-9._~-]+$", "not": { "pattern": "^(?:[\\s._~-]*\\d){12,19}[\\s._~-]*$" }, "description": "Opaque token from the certified payment surface; never PAN or CVV." }, "three_ds": { "type": "object", "additionalProperties": false, "required": [], "properties": { "cavv": { "type": "string", "maxLength": 4096 }, "eci": { "type": "string", "maxLength": 4096 }, "xid": { "type": "string", "maxLength": 4096 }, "cardholder_auth": { "type": "string", "maxLength": 4096 }, "three_ds_version": { "type": "string", "maxLength": 4096 }, "directory_server_id": { "type": "string", "maxLength": 4096 } } } } }, "example": { "payment_token": "tok_test_01J9OPAQUEPAYMENT42", "three_ds": { "cavv": "cavv_test_01J9", "eci": "05", "xid": "xid_test_01J9CHECKOUT42", "cardholder_auth": "authenticated", "three_ds_version": "2.2.0", "directory_server_id": "ds_test_01J9CHECKOUT42" } } } } }, "responses": { "200": { "description": "Handoff certified card payment response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" }, "Idempotency-Replayed": { "description": "Present with value true only when CentriPOS returns the stored response for a byte-identical idempotent replay.", "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CertifiedStorefrontOrderEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "not": { "anyOf": [ { "required": [ "payment_configuration" ] } ] } } } } ] }, "example": { "data": { "id": "55555555-5555-4555-8555-555555555555", "object": "storefront_order", "order_number": "WEB-TEST-10482", "status": "paid", "payment_status": "paid", "total": 1817.84, "fulfillment": { "type": "shipping", "date": null, "delivery_method_id": null, "pickup_location_id": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333" }, "totals": { "subtotal": 1598, "shipping": 100, "tax": 119.84, "total": 1817.84 }, "inventory": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "state": "committed", "reserved_quantity": 2, "backorder_quantity": 0 } ], "items": [ { "id": "66666666-6666-4666-8666-666666666666", "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "line_total": 1598, "fulfillment": { "type": "shipping", "status": "unfulfilled", "date": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333", "delivery_method_id": null, "pickup_location_id": null }, "inventory_commitment": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "eta_date": null, "customer_message": null } } ], "created_at": "2026-08-25T15:45:00Z", "updated_at": "2026-08-25T15:52:00Z" }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_order" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "checkout:write", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false }, "x-idempotency-required": true } }, "/api/retail/v1/storefront/checkouts/{quote_id}/financing/paytomorrow": { "post": { "tags": [ "Public storefront" ], "summary": "Initiate PayTomorrow financing", "description": "Initiate the certified PayTomorrow handoff from the prepared authoritative quote; CentriPOS owns provider state and quote totals. Requires Idempotency-Key and tenant-certified financing configuration. Retry only with the byte-identical raw JSON request body; stored replays carry Idempotency-Replayed: true. A tenant without an active provider configuration receives an explicit unavailable response.", "operationId": "certified_storefront_paytomorrow", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "Opaque quote id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "format": "uuid", "example": "44444444-4444-4444-8444-444444444444" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. A retry replays only when its raw JSON request body is byte-identical; any byte difference conflicts.", "schema": { "type": "string", "minLength": 16, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]{16,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Initiate PayTomorrow financing response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" }, "Idempotency-Replayed": { "description": "Present with value true only when CentriPOS returns the stored response for a byte-identical idempotent replay.", "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertifiedStorefrontFinancingEnvelope" }, "example": { "data": { "provider": "paytomorrow", "financing_application_id": "finapp_test_01J9CHECKOUT42", "redirect_url": "https://financing.example.test/applications/finapp_test_01J9CHECKOUT42", "status": "pending", "replayed": false, "order": { "id": "55555555-5555-4555-8555-555555555555", "object": "storefront_order", "order_number": "WEB-TEST-10482", "status": "pending", "payment_status": "processing", "total": 1817.84, "fulfillment": { "type": "shipping", "date": null, "delivery_method_id": null, "pickup_location_id": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333" }, "totals": { "subtotal": 1598, "shipping": 100, "tax": 119.84, "total": 1817.84 }, "inventory": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0 } ], "items": [ { "id": "66666666-6666-4666-8666-666666666666", "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "line_total": 1598, "fulfillment": { "type": "shipping", "status": "unfulfilled", "date": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333", "delivery_method_id": null, "pickup_location_id": null }, "inventory_commitment": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "eta_date": null, "customer_message": null } } ], "created_at": "2026-08-25T15:45:00Z", "updated_at": "2026-08-25T15:48:00Z" } }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_financing" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "checkout:write", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false }, "x-idempotency-required": true } }, "/api/retail/v1/storefront/checkouts/{quote_id}/finalize": { "post": { "tags": [ "Public storefront" ], "summary": "Finalize storefront order", "description": "Finalize the prepared order only after CentriPOS validates the persisted certified payment or financing state against the authoritative quote. Requires Idempotency-Key. Retry only with the byte-identical raw JSON request body; stored replays carry Idempotency-Replayed: true and cannot duplicate the sale.", "operationId": "certified_storefront_finalize", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "Opaque quote id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "format": "uuid", "example": "44444444-4444-4444-8444-444444444444" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique caller-generated key. A retry replays only when its raw JSON request body is byte-identical; any byte difference conflicts.", "schema": { "type": "string", "minLength": 16, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]{16,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Finalize storefront order response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" }, "Idempotency-Replayed": { "description": "Present with value true only when CentriPOS returns the stored response for a byte-identical idempotent replay.", "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CertifiedStorefrontOrderEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "not": { "anyOf": [ { "required": [ "payment_configuration" ] } ] } } } } ] }, "example": { "data": { "id": "55555555-5555-4555-8555-555555555555", "object": "storefront_order", "order_number": "WEB-TEST-10482", "status": "paid", "payment_status": "paid", "total": 1817.84, "fulfillment": { "type": "shipping", "date": null, "delivery_method_id": null, "pickup_location_id": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333" }, "totals": { "subtotal": 1598, "shipping": 100, "tax": 119.84, "total": 1817.84 }, "inventory": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "state": "committed", "reserved_quantity": 2, "backorder_quantity": 0 } ], "items": [ { "id": "66666666-6666-4666-8666-666666666666", "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "line_total": 1598, "fulfillment": { "type": "shipping", "status": "unfulfilled", "date": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333", "delivery_method_id": null, "pickup_location_id": null }, "inventory_commitment": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "eta_date": null, "customer_message": null } } ], "created_at": "2026-08-25T15:45:00Z", "updated_at": "2026-08-25T15:52:00Z" }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_order" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "checkout:write", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false }, "x-idempotency-required": true } }, "/api/retail/v1/storefront/orders/{order_id}": { "get": { "tags": [ "Public storefront" ], "summary": "Get storefront order status", "description": "Read the credential-bound order, payment, totals, line fulfillment, and common cart fulfillment status. payment_status distinguishes pending, processing, reconciliation_required, and paid without exposing processor state. Certified server integration only; the credential cannot read another tenant or data plane.", "operationId": "certified_storefront_order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Opaque order id. Tenant and data-plane identifiers are never accepted.", "schema": { "type": "string", "format": "uuid", "example": "55555555-5555-4555-8555-555555555555" } } ], "responses": { "200": { "description": "Get storefront order status response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-CentriPOS-API-Version": { "description": "Date-pinned certified storefront contract version.", "schema": { "type": "string", "const": "2026-08-24" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateRemaining" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CertifiedStorefrontOrderEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "not": { "anyOf": [ { "required": [ "payment_configuration" ] } ] } } } } ] }, "example": { "data": { "id": "55555555-5555-4555-8555-555555555555", "object": "storefront_order", "order_number": "WEB-TEST-10482", "status": "pending", "payment_status": "reconciliation_required", "total": 1817.84, "fulfillment": { "type": "shipping", "date": null, "delivery_method_id": null, "pickup_location_id": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333" }, "totals": { "subtotal": 1598, "shipping": 100, "tax": 119.84, "total": 1817.84 }, "inventory": [ { "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0 } ], "items": [ { "id": "66666666-6666-4666-8666-666666666666", "product_id": "11111111-1111-4111-8111-111111111111", "variant_id": "22222222-2222-4222-8222-222222222222", "name": "Synthetic Boxed Mattress", "variant_name": "Queen", "sku": "SYN-BOX-Q", "quantity": 2, "unit_price": 799, "line_total": 1598, "fulfillment": { "type": "shipping", "status": "unfulfilled", "date": null, "shipping_method_id": "33333333-3333-4333-8333-333333333333", "delivery_method_id": null, "pickup_location_id": null }, "inventory_commitment": { "state": "reserved", "reserved_quantity": 2, "backorder_quantity": 0, "eta_date": null, "customer_message": null } } ], "created_at": "2026-08-25T15:45:00Z", "updated_at": "2026-08-25T15:50:00Z" }, "meta": { "api_version": "2026-08-24", "environment": "test", "request_id": "req_test_storefront_order_status" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-centripos-status": "certified-live", "x-required-scope": "orders:read", "x-centripos-certification": { "required": true, "activation": "tenant-and-client-bound", "browser_secret_allowed": false } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "CentriPOS restricted key", "description": "Use a tenant-bound cp_test_ or cp_live_ key from a server-side secret store. The raw secret is shown once and is never sent in a URL." } }, "headers": { "RequestId": { "description": "Safe request correlation identifier.", "schema": { "type": "string" } }, "ApiVersion": { "description": "Date-pinned contract version.", "schema": { "type": "string", "example": "2026-08" } }, "RateLimit": { "description": "Request budget for this credential and operation class.", "schema": { "type": "integer" } }, "RateRemaining": { "description": "Remaining requests in the current window.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid request shape or parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Missing, malformed, expired, or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Credential is valid but lacks the required scope or tenant policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "Resource was not found in the credential-bound tenant and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Conflict": { "description": "State, version, sandbox, or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "Unavailable": { "description": "Private API is not enabled or an approved dependency is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "SalePage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list sales response projection." }, "SaleEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" }, "idempotency": { "type": "object", "properties": { "key": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "key", "replayed" ], "additionalProperties": false } }, "required": [ "request_id", "environment", "idempotency" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted create a sale response projection." }, "ResourceEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" }, "idempotency": { "type": "object", "properties": { "key": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "key", "replayed" ], "additionalProperties": false } }, "required": [ "request_id", "environment", "idempotency" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted complete a sale response projection." }, "ReceiptEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "receipt_number": { "type": "string" }, "sale_id": { "type": "string" }, "sale_number": { "type": "string" }, "status": { "type": "string" }, "issued_at": { "type": "string" }, "merchant": { "type": "object", "properties": { "display_name": { "type": "string" }, "location": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "name", "address" ], "additionalProperties": false }, "phone": { "type": "string" }, "tax_identifier_display": { "type": "string" } }, "required": [ "display_name", "location", "phone", "tax_identifier_display" ], "additionalProperties": false }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "display_name", "email" ], "additionalProperties": false }, "cashier": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ], "additionalProperties": false }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sort_order": { "type": "integer" }, "quantity": { "type": "integer" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" } }, "required": [ "id", "name", "brand" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "id", "name", "sku", "options" ], "additionalProperties": false }, "unit_price": { "type": "integer" }, "quantity_price": { "type": "integer" }, "discount_total": { "type": "integer" }, "tax_total": { "type": "number" }, "line_total": { "type": "number" }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "id", "name", "type", "amount" ], "additionalProperties": false } }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rate": { "type": "number" }, "taxable_amount": { "type": "integer" }, "amount": { "type": "number" } }, "required": [ "id", "name", "rate", "taxable_amount", "amount" ], "additionalProperties": false } }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "id", "name", "code", "timezone" ], "additionalProperties": false }, "promised_at": { "type": "string" } }, "required": [ "type", "status", "location", "promised_at" ], "additionalProperties": false }, "inventory_commitment": { "type": "object", "properties": { "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" }, "policy": { "type": "string" }, "eta_date": { "type": "string" }, "customer_message": { "type": "string" } }, "required": [ "state", "reserved_quantity", "backorder_quantity", "policy", "eta_date", "customer_message" ], "additionalProperties": false }, "backorder": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" }, "requested_quantity": { "type": "integer" }, "initially_reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" }, "allocated_quantity": { "type": "integer" }, "remaining_quantity": { "type": "integer" }, "policy": { "type": "string" }, "eta_date": { "type": "string" }, "customer_message": { "type": "string" }, "allocated_at": {}, "fulfilled_at": {}, "cancelled_at": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "status", "requested_quantity", "initially_reserved_quantity", "backorder_quantity", "allocated_quantity", "remaining_quantity", "policy", "eta_date", "customer_message", "allocated_at", "fulfilled_at", "cancelled_at", "created_at", "updated_at" ], "additionalProperties": false }, "warranty": { "type": "object", "properties": { "term_years": { "type": "integer" }, "registered": { "type": "boolean" } }, "required": [ "term_years", "registered" ], "additionalProperties": false }, "note": {} }, "required": [ "id", "sort_order", "quantity", "product", "variant", "unit_price", "quantity_price", "discount_total", "tax_total", "line_total", "discounts", "tax_lines", "fulfillment", "inventory_commitment", "backorder", "warranty", "note" ], "additionalProperties": false } }, "tenders": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" } }, "required": [ "type", "label", "amount", "status" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "discount_total": { "type": "integer" }, "shipping_total": { "type": "integer" }, "tax_total": { "type": "number" }, "total": { "type": "number" }, "amount_paid": { "type": "number" }, "balance_due": { "type": "integer" }, "change_given": { "type": "integer" } }, "required": [ "subtotal", "discount_total", "shipping_total", "tax_total", "total", "amount_paid", "balance_due", "change_given" ], "additionalProperties": false }, "tax_summary": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "rate": { "type": "number" }, "taxable_amount": { "type": "integer" }, "amount": { "type": "number" } }, "required": [ "name", "rate", "taxable_amount", "amount" ], "additionalProperties": false } }, "fulfillment_summary": { "type": "string" }, "return_summary": { "type": "object", "properties": { "returnable_until": { "type": "string" }, "returned_total": { "type": "integer" } }, "required": [ "returnable_until", "returned_total" ], "additionalProperties": false }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "sale": { "type": "string" }, "document": { "type": "string" } }, "required": [ "self", "sale", "document" ], "additionalProperties": false } }, "required": [ "id", "receipt_number", "sale_id", "sale_number", "status", "issued_at", "merchant", "customer", "cashier", "line_items", "tenders", "totals", "tax_summary", "fulfillment_summary", "return_summary", "links" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get receipt data response projection." }, "DocumentEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "content_type": { "type": "string" }, "expires_at": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "content_type", "expires_at", "download_url" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted download receipt document response projection." }, "ProductPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list products response projection." }, "ProductEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" }, "idempotency": { "type": "object", "properties": { "key": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "key", "replayed" ], "additionalProperties": false } }, "required": [ "request_id", "environment", "idempotency" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted create a product response projection." }, "InventoryLevelPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "id", "name", "code", "timezone" ], "additionalProperties": false }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "sku", "name" ], "additionalProperties": false }, "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "available": { "type": "integer" }, "incoming": { "type": "integer" }, "reorder_point": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "location", "product", "variant", "on_hand", "reserved", "available", "incoming", "reorder_point", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list inventory stock response projection." }, "InventoryLevelsEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "object": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "track_inventory": { "type": "boolean" } }, "required": [ "id", "name", "sku", "track_inventory" ], "additionalProperties": false }, "inventory_model": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "internal_name": { "type": "string" }, "type": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "id", "name", "internal_name", "type", "is_active" ], "additionalProperties": false }, "unassigned_product_level": { "type": "object", "properties": { "id": {}, "stock_on_hand": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "inventory_reserved_quantity": { "type": "integer" }, "commerce_reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" }, "reorder_point": {}, "reorder_quantity": {}, "updated_at": {} }, "required": [ "id", "stock_on_hand", "reserved_quantity", "inventory_reserved_quantity", "commerce_reserved_quantity", "available_quantity", "reorder_point", "reorder_quantity", "updated_at" ], "additionalProperties": false }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "stock_type": { "type": "string" }, "location_id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "attributes": { "type": "object", "properties": { "Size": { "type": "string" }, "Feel": { "type": "string" } }, "required": [ "Size", "Feel" ], "additionalProperties": false }, "variant_enabled": { "type": "boolean" }, "stock_on_hand": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "inventory_reserved_quantity": { "type": "integer" }, "commerce_reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" }, "reorder_point": { "type": "integer" }, "reorder_quantity": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "stock_type", "location_id", "product_id", "variant_id", "variant_name", "sku", "attributes", "variant_enabled", "stock_on_hand", "reserved_quantity", "inventory_reserved_quantity", "commerce_reserved_quantity", "available_quantity", "reorder_point", "reorder_quantity", "updated_at" ], "additionalProperties": false } }, "variant_totals": { "type": "object", "properties": { "stock_on_hand": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" } }, "required": [ "stock_on_hand", "reserved_quantity", "available_quantity" ], "additionalProperties": false } }, "required": [ "location", "unassigned_product_level", "variants", "variant_totals" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "variants": { "type": "object", "properties": { "stock_on_hand": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" } }, "required": [ "stock_on_hand", "reserved_quantity", "available_quantity" ], "additionalProperties": false }, "unassigned_product_level": { "type": "object", "properties": { "stock_on_hand": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" } }, "required": [ "stock_on_hand", "reserved_quantity", "available_quantity" ], "additionalProperties": false } }, "required": [ "variants", "unassigned_product_level" ], "additionalProperties": false } }, "required": [ "object", "product", "inventory_model", "locations", "totals" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get authoritative product inventory levels response projection." }, "InventoryLevelEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "id", "name", "code", "timezone" ], "additionalProperties": false }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "variant": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "sku", "name" ], "additionalProperties": false }, "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "available": { "type": "integer" }, "incoming": { "type": "integer" }, "reorder_point": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "location", "product", "variant", "on_hand", "reserved", "available", "incoming", "reorder_point", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get one inventory level response projection." }, "CustomerPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list customers response projection." }, "CustomerEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "status", "name", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" }, "idempotency": { "type": "object", "properties": { "key": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "key", "replayed" ], "additionalProperties": false } }, "required": [ "request_id", "environment", "idempotency" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted create a customer response projection." }, "InvoicePage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "customer_id": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string" }, "sale_id": { "type": "string" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "tax": { "type": "number" }, "total": { "type": "number" }, "amount_paid": { "type": "integer" }, "balance_due": { "type": "number" } }, "required": [ "subtotal", "tax", "total", "amount_paid", "balance_due" ], "additionalProperties": false }, "notes": { "type": "string" }, "issued_at": { "type": "string" }, "due_date": { "type": "string" }, "paid_at": {}, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "amount": { "type": "integer" }, "sort_order": { "type": "integer" }, "created_at": { "type": "string" } }, "required": [ "id", "description", "quantity", "unit_price", "amount", "sort_order", "created_at" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "integer" }, "payment_type_id": { "type": "string" }, "notes": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "amount", "payment_type_id", "notes", "created_at" ], "additionalProperties": false } }, "project_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "project_id", "invoice_id", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "invoice_number", "status", "customer_id", "customer_name", "customer_email", "sale_id", "totals", "notes", "issued_at", "due_date", "paid_at", "line_items", "payments", "project_links", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list invoices response projection." }, "InvoiceEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "customer_id": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string" }, "sale_id": { "type": "string" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "tax": { "type": "number" }, "total": { "type": "number" }, "amount_paid": { "type": "integer" }, "balance_due": { "type": "number" } }, "required": [ "subtotal", "tax", "total", "amount_paid", "balance_due" ], "additionalProperties": false }, "notes": { "type": "string" }, "issued_at": { "type": "string" }, "due_date": { "type": "string" }, "paid_at": {}, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "amount": { "type": "integer" }, "sort_order": { "type": "integer" }, "created_at": { "type": "string" } }, "required": [ "id", "description", "quantity", "unit_price", "amount", "sort_order", "created_at" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "integer" }, "payment_type_id": { "type": "string" }, "notes": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "amount", "payment_type_id", "notes", "created_at" ], "additionalProperties": false } }, "project_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "project_id", "invoice_id", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "invoice_number", "status", "customer_id", "customer_name", "customer_email", "sale_id", "totals", "notes", "issued_at", "due_date", "paid_at", "line_items", "payments", "project_links", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get a complete invoice response projection." }, "ServiceTicketPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "ticket_number": { "type": "string" }, "ticket_type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "origin_channel": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "phone", "email" ], "additionalProperties": false }, "service_address": { "type": "object", "properties": { "street": { "type": "string" }, "street_2": {}, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "street", "street_2", "city", "state", "postal_code" ], "additionalProperties": false }, "location_id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "linked_sale_id": { "type": "string" }, "converted_sale_id": {}, "assigned_profile_id": { "type": "string" }, "assigned_team_function": { "type": "string" }, "project_id": { "type": "string" }, "work_item_id": { "type": "string" }, "warranty": { "type": "object", "properties": { "provider": { "type": "string" }, "claim_number": {} }, "required": [ "provider", "claim_number" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "billable": { "type": "boolean" }, "estimated_charge": { "type": "integer" }, "approved_charge": { "type": "integer" }, "charge_status": { "type": "string" }, "quote_status": { "type": "string" }, "quote_total": { "type": "integer" } }, "required": [ "billable", "estimated_charge", "approved_charge", "charge_status", "quote_status", "quote_total" ], "additionalProperties": false }, "work_order_status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "string" }, "requested_resolution": { "type": "string" }, "customer_concern": {}, "resolution_summary": {}, "scheduled_at": { "type": "string" }, "next_follow_up_at": { "type": "string" }, "completed_at": {}, "closed_at": {}, "visits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "service_ticket_id": { "type": "string" }, "visit_type": { "type": "string" }, "status": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "scheduled_start": { "type": "string" }, "scheduled_end": { "type": "string" }, "en_route_at": {}, "arrived_at": {}, "departed_at": {}, "completed_at": {}, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "line1", "city", "region", "postal_code" ], "additionalProperties": false }, "customer_present": { "type": "boolean" }, "sentiment": {}, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "technician_notes": {}, "customer_notes": { "type": "string" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "is_complete": { "type": "boolean" }, "completed_by": {}, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "label", "is_complete", "completed_by", "completed_at", "sort_order" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "service_ticket_id", "visit_type", "status", "assigned_profile_id", "scheduled_start", "scheduled_end", "en_route_at", "arrived_at", "departed_at", "completed_at", "address", "customer_present", "sentiment", "billable", "notes", "technician_notes", "customer_notes", "checklist", "created_at", "updated_at" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "product_name": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "item_kind": { "type": "string" }, "allocation_status": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" }, "note": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "product_id", "variant_id", "product_name", "variant_name", "sku", "item_kind", "allocation_status", "quantity", "unit_price", "line_total", "note", "sort_order" ], "additionalProperties": false } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "charge_type": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_rate": { "type": "integer" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "invoice_id": { "type": "string" } }, "required": [ "id", "charge_type", "description", "quantity", "unit_rate", "amount", "status", "invoice_id" ], "additionalProperties": false } }, "time_entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "profile_id": { "type": "string" }, "entry_type": { "type": "string" }, "status": { "type": "string" }, "minutes": { "type": "integer" }, "billable": { "type": "boolean" }, "hourly_rate": { "type": "integer" } }, "required": [ "id", "profile_id", "entry_type", "status", "minutes", "billable", "hourly_rate" ], "additionalProperties": false } }, "warranty_claim": {}, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_type": { "type": "string" }, "actor_profile_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "event_type", "actor_profile_id", "note", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "ticket_number", "ticket_type", "status", "priority", "lifecycle_stage", "origin_channel", "customer", "service_address", "location_id", "product_id", "variant_id", "linked_sale_id", "converted_sale_id", "assigned_profile_id", "assigned_team_function", "project_id", "work_item_id", "warranty", "billing", "work_order_status", "summary", "details", "requested_resolution", "customer_concern", "resolution_summary", "scheduled_at", "next_follow_up_at", "completed_at", "closed_at", "visits", "items", "charges", "time_entries", "warranty_claim", "events", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list service tickets response projection." }, "ServiceTicketEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "ticket_number": { "type": "string" }, "ticket_type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "origin_channel": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "phone", "email" ], "additionalProperties": false }, "service_address": { "type": "object", "properties": { "street": { "type": "string" }, "street_2": {}, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "street", "street_2", "city", "state", "postal_code" ], "additionalProperties": false }, "location_id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "linked_sale_id": { "type": "string" }, "converted_sale_id": {}, "assigned_profile_id": { "type": "string" }, "assigned_team_function": { "type": "string" }, "project_id": { "type": "string" }, "work_item_id": { "type": "string" }, "warranty": { "type": "object", "properties": { "provider": { "type": "string" }, "claim_number": {} }, "required": [ "provider", "claim_number" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "billable": { "type": "boolean" }, "estimated_charge": { "type": "integer" }, "approved_charge": { "type": "integer" }, "charge_status": { "type": "string" }, "quote_status": { "type": "string" }, "quote_total": { "type": "integer" } }, "required": [ "billable", "estimated_charge", "approved_charge", "charge_status", "quote_status", "quote_total" ], "additionalProperties": false }, "work_order_status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "string" }, "requested_resolution": { "type": "string" }, "customer_concern": {}, "resolution_summary": {}, "scheduled_at": { "type": "string" }, "next_follow_up_at": { "type": "string" }, "completed_at": {}, "closed_at": {}, "visits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "service_ticket_id": { "type": "string" }, "visit_type": { "type": "string" }, "status": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "scheduled_start": { "type": "string" }, "scheduled_end": { "type": "string" }, "en_route_at": {}, "arrived_at": {}, "departed_at": {}, "completed_at": {}, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "line1", "city", "region", "postal_code" ], "additionalProperties": false }, "customer_present": { "type": "boolean" }, "sentiment": {}, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "technician_notes": {}, "customer_notes": { "type": "string" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "is_complete": { "type": "boolean" }, "completed_by": {}, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "label", "is_complete", "completed_by", "completed_at", "sort_order" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "service_ticket_id", "visit_type", "status", "assigned_profile_id", "scheduled_start", "scheduled_end", "en_route_at", "arrived_at", "departed_at", "completed_at", "address", "customer_present", "sentiment", "billable", "notes", "technician_notes", "customer_notes", "checklist", "created_at", "updated_at" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "product_name": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "item_kind": { "type": "string" }, "allocation_status": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" }, "note": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "product_id", "variant_id", "product_name", "variant_name", "sku", "item_kind", "allocation_status", "quantity", "unit_price", "line_total", "note", "sort_order" ], "additionalProperties": false } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "charge_type": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_rate": { "type": "integer" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "invoice_id": { "type": "string" } }, "required": [ "id", "charge_type", "description", "quantity", "unit_rate", "amount", "status", "invoice_id" ], "additionalProperties": false } }, "time_entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "profile_id": { "type": "string" }, "entry_type": { "type": "string" }, "status": { "type": "string" }, "minutes": { "type": "integer" }, "billable": { "type": "boolean" }, "hourly_rate": { "type": "integer" } }, "required": [ "id", "profile_id", "entry_type", "status", "minutes", "billable", "hourly_rate" ], "additionalProperties": false } }, "warranty_claim": {}, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_type": { "type": "string" }, "actor_profile_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "event_type", "actor_profile_id", "note", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "ticket_number", "ticket_type", "status", "priority", "lifecycle_stage", "origin_channel", "customer", "service_address", "location_id", "product_id", "variant_id", "linked_sale_id", "converted_sale_id", "assigned_profile_id", "assigned_team_function", "project_id", "work_item_id", "warranty", "billing", "work_order_status", "summary", "details", "requested_resolution", "customer_concern", "resolution_summary", "scheduled_at", "next_follow_up_at", "completed_at", "closed_at", "visits", "items", "charges", "time_entries", "warranty_claim", "events", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get a complete service ticket response projection." }, "ServiceVisitPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "service_ticket_id": { "type": "string" }, "visit_type": { "type": "string" }, "status": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "scheduled_start": { "type": "string" }, "scheduled_end": { "type": "string" }, "en_route_at": {}, "arrived_at": {}, "departed_at": {}, "completed_at": {}, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "line1", "city", "region", "postal_code" ], "additionalProperties": false }, "customer_present": { "type": "boolean" }, "sentiment": {}, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "technician_notes": {}, "customer_notes": { "type": "string" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "is_complete": { "type": "boolean" }, "completed_by": {}, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "label", "is_complete", "completed_by", "completed_at", "sort_order" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "service_ticket_id", "visit_type", "status", "assigned_profile_id", "scheduled_start", "scheduled_end", "en_route_at", "arrived_at", "departed_at", "completed_at", "address", "customer_present", "sentiment", "billable", "notes", "technician_notes", "customer_notes", "checklist", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list service visits response projection." }, "ServiceVisitEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "service_ticket_id": { "type": "string" }, "visit_type": { "type": "string" }, "status": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "scheduled_start": { "type": "string" }, "scheduled_end": { "type": "string" }, "en_route_at": {}, "arrived_at": {}, "departed_at": {}, "completed_at": {}, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "line1", "city", "region", "postal_code" ], "additionalProperties": false }, "customer_present": { "type": "boolean" }, "sentiment": {}, "billable": { "type": "boolean" }, "notes": { "type": "string" }, "technician_notes": {}, "customer_notes": { "type": "string" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "is_complete": { "type": "boolean" }, "completed_by": {}, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "label", "is_complete", "completed_by", "completed_at", "sort_order" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "service_ticket_id", "visit_type", "status", "assigned_profile_id", "scheduled_start", "scheduled_end", "en_route_at", "arrived_at", "departed_at", "completed_at", "address", "customer_present", "sentiment", "billable", "notes", "technician_notes", "customer_notes", "checklist", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get a service visit response projection." }, "ProjectPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_number": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "project_type": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "location_id": { "type": "string" }, "engagement_id": {}, "template_id": { "type": "string" }, "customer_id": { "type": "string" }, "linked_sale_id": { "type": "string" }, "owner_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_on": { "type": "string" }, "completed_at": {}, "boards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "sort_order": { "type": "integer" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status_key": { "type": "string" }, "sort_order": { "type": "integer" }, "wip_limit": {}, "is_done": { "type": "boolean" } }, "required": [ "id", "name", "status_key", "sort_order", "wip_limit", "is_done" ], "additionalProperties": false } } }, "required": [ "id", "name", "is_default", "sort_order", "columns" ], "additionalProperties": false } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "owner_profile_id": { "type": "string" }, "due_on": { "type": "string" }, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "status", "owner_profile_id", "due_on", "completed_at", "sort_order" ], "additionalProperties": false } }, "work_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_id": { "type": "string" }, "board_id": { "type": "string" }, "column_id": { "type": "string" }, "milestone_id": { "type": "string" }, "parent_item_id": {}, "item_number": { "type": "string" }, "item_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_at": { "type": "string" }, "completed_at": {}, "estimated_minutes": { "type": "integer" }, "actual_minutes": {}, "recurrence_rule": {}, "sort_order": { "type": "integer" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "is_complete": { "type": "boolean" }, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "is_complete", "sort_order" ], "additionalProperties": false } }, "dependencies": { "type": "array", "items": {} }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "request_note": { "type": "string" }, "decision_note": {}, "decided_at": {} }, "required": [ "id", "status", "request_note", "decision_note", "decided_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_id", "board_id", "column_id", "milestone_id", "parent_item_id", "item_number", "item_type", "title", "description", "status", "priority", "assigned_profile_id", "start_on", "due_at", "completed_at", "estimated_minutes", "actual_minutes", "recurrence_rule", "sort_order", "checklist", "dependencies", "comments", "approvals", "created_at", "updated_at" ], "additionalProperties": false } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "contact_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contact_id": { "type": "string" }, "role": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "id", "contact_id", "role", "is_primary" ], "additionalProperties": false } }, "invoice_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "invoice_id", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_number", "name", "description", "project_type", "status", "health", "location_id", "engagement_id", "template_id", "customer_id", "linked_sale_id", "owner_profile_id", "start_on", "due_on", "completed_at", "boards", "milestones", "work_items", "comments", "contact_links", "invoice_links", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list projects response projection." }, "ProjectEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_number": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "project_type": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "location_id": { "type": "string" }, "engagement_id": {}, "template_id": { "type": "string" }, "customer_id": { "type": "string" }, "linked_sale_id": { "type": "string" }, "owner_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_on": { "type": "string" }, "completed_at": {}, "boards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "sort_order": { "type": "integer" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status_key": { "type": "string" }, "sort_order": { "type": "integer" }, "wip_limit": {}, "is_done": { "type": "boolean" } }, "required": [ "id", "name", "status_key", "sort_order", "wip_limit", "is_done" ], "additionalProperties": false } } }, "required": [ "id", "name", "is_default", "sort_order", "columns" ], "additionalProperties": false } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "owner_profile_id": { "type": "string" }, "due_on": { "type": "string" }, "completed_at": {}, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "status", "owner_profile_id", "due_on", "completed_at", "sort_order" ], "additionalProperties": false } }, "work_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_id": { "type": "string" }, "board_id": { "type": "string" }, "column_id": { "type": "string" }, "milestone_id": { "type": "string" }, "parent_item_id": {}, "item_number": { "type": "string" }, "item_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_at": { "type": "string" }, "completed_at": {}, "estimated_minutes": { "type": "integer" }, "actual_minutes": {}, "recurrence_rule": {}, "sort_order": { "type": "integer" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "is_complete": { "type": "boolean" }, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "is_complete", "sort_order" ], "additionalProperties": false } }, "dependencies": { "type": "array", "items": {} }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "request_note": { "type": "string" }, "decision_note": {}, "decided_at": {} }, "required": [ "id", "status", "request_note", "decision_note", "decided_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_id", "board_id", "column_id", "milestone_id", "parent_item_id", "item_number", "item_type", "title", "description", "status", "priority", "assigned_profile_id", "start_on", "due_at", "completed_at", "estimated_minutes", "actual_minutes", "recurrence_rule", "sort_order", "checklist", "dependencies", "comments", "approvals", "created_at", "updated_at" ], "additionalProperties": false } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "contact_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contact_id": { "type": "string" }, "role": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "id", "contact_id", "role", "is_primary" ], "additionalProperties": false } }, "invoice_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "invoice_id", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_number", "name", "description", "project_type", "status", "health", "location_id", "engagement_id", "template_id", "customer_id", "linked_sale_id", "owner_profile_id", "start_on", "due_on", "completed_at", "boards", "milestones", "work_items", "comments", "contact_links", "invoice_links", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get a complete project response projection." }, "WorkItemPage": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_id": { "type": "string" }, "board_id": { "type": "string" }, "column_id": { "type": "string" }, "milestone_id": { "type": "string" }, "parent_item_id": {}, "item_number": { "type": "string" }, "item_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_at": { "type": "string" }, "completed_at": {}, "estimated_minutes": { "type": "integer" }, "actual_minutes": {}, "recurrence_rule": {}, "sort_order": { "type": "integer" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "is_complete": { "type": "boolean" }, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "is_complete", "sort_order" ], "additionalProperties": false } }, "dependencies": { "type": "array", "items": {} }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "request_note": { "type": "string" }, "decision_note": {}, "decided_at": {} }, "required": [ "id", "status", "request_note", "decision_note", "decided_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_id", "board_id", "column_id", "milestone_id", "parent_item_id", "item_number", "item_type", "title", "description", "status", "priority", "assigned_profile_id", "start_on", "due_at", "completed_at", "estimated_minutes", "actual_minutes", "recurrence_rule", "sort_order", "checklist", "dependencies", "comments", "approvals", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": {}, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "limit" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination", "meta" ], "additionalProperties": false, "description": "Whitelisted list project work items response projection." }, "WorkItemEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "project_id": { "type": "string" }, "board_id": { "type": "string" }, "column_id": { "type": "string" }, "milestone_id": { "type": "string" }, "parent_item_id": {}, "item_number": { "type": "string" }, "item_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigned_profile_id": { "type": "string" }, "start_on": { "type": "string" }, "due_at": { "type": "string" }, "completed_at": {}, "estimated_minutes": { "type": "integer" }, "actual_minutes": {}, "recurrence_rule": {}, "sort_order": { "type": "integer" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "is_complete": { "type": "boolean" }, "sort_order": { "type": "integer" } }, "required": [ "id", "title", "is_complete", "sort_order" ], "additionalProperties": false } }, "dependencies": { "type": "array", "items": {} }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author_profile_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author_profile_id", "created_at" ], "additionalProperties": false } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "request_note": { "type": "string" }, "decision_note": {}, "decided_at": {} }, "required": [ "id", "status", "request_note", "decision_note", "decided_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "project_id", "board_id", "column_id", "milestone_id", "parent_item_id", "item_number", "item_type", "title", "description", "status", "priority", "assigned_profile_id", "start_on", "due_at", "completed_at", "estimated_minutes", "actual_minutes", "recurrence_rule", "sort_order", "checklist", "dependencies", "comments", "approvals", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "request_id", "environment" ], "additionalProperties": false } }, "required": [ "api_version", "data", "meta" ], "additionalProperties": false, "description": "Whitelisted get a complete work item response projection." }, "StorefrontEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "storefront": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "catalog": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "status": { "type": "string" }, "sellable": { "type": "boolean" }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": { "type": "integer" }, "eta_days": { "type": "integer" }, "customer_message": { "type": "string" } }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false }, "description": { "type": "string" }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "inventory": { "type": "object", "properties": { "tracked": { "type": "boolean" }, "available": { "type": "integer" }, "reserved": { "type": "integer" }, "incoming": { "type": "integer" } }, "required": [ "tracked", "available", "reserved", "incoming" ], "additionalProperties": false }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": {}, "eta_days": {}, "customer_message": {} }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false } }, "required": [ "id", "name", "sku", "barcode", "price", "options", "inventory", "online_backorder_policy" ], "additionalProperties": false } }, "custom_fields": { "type": "object", "properties": { "price_area": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "description": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "specifications": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "unit": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "unit", "value_type" ], "additionalProperties": false } } }, "required": [ "price_area", "description", "specifications" ], "additionalProperties": false }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "role": { "type": "string" }, "alt": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "type", "role", "alt", "url" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "handle", "name", "brand", "status", "sellable", "online_backorder_policy", "description", "category", "tags", "variants", "custom_fields", "media", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "products" ], "additionalProperties": false }, "links": { "type": "object", "properties": { "self": { "type": "string" } }, "required": [ "self" ], "additionalProperties": false } }, "required": [ "api_version", "storefront", "catalog", "links" ], "additionalProperties": false, "description": "Whitelisted get storefront feed response projection." }, "StorefrontCatalogEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "status": { "type": "string" }, "sellable": { "type": "boolean" }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": { "type": "integer" }, "eta_days": { "type": "integer" }, "customer_message": { "type": "string" } }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false }, "description": { "type": "string" }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "inventory": { "type": "object", "properties": { "tracked": { "type": "boolean" }, "available": { "type": "integer" }, "reserved": { "type": "integer" }, "incoming": { "type": "integer" } }, "required": [ "tracked", "available", "reserved", "incoming" ], "additionalProperties": false }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": {}, "eta_days": {}, "customer_message": {} }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false } }, "required": [ "id", "name", "sku", "barcode", "price", "options", "inventory", "online_backorder_policy" ], "additionalProperties": false } }, "custom_fields": { "type": "object", "properties": { "price_area": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "description": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "specifications": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "unit": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "unit", "value_type" ], "additionalProperties": false } } }, "required": [ "price_area", "description", "specifications" ], "additionalProperties": false }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "role": { "type": "string" }, "alt": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "type", "role", "alt", "url" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "handle", "name", "brand", "status", "sellable", "online_backorder_policy", "description", "category", "tags", "variants", "custom_fields", "media", "created_at", "updated_at" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "page", "limit", "total" ], "additionalProperties": false } }, "required": [ "api_version", "data", "pagination" ], "additionalProperties": false, "description": "Whitelisted list published catalog response projection." }, "StorefrontProductEnvelope": { "type": "object", "properties": { "api_version": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "status": { "type": "string" }, "sellable": { "type": "boolean" }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": { "type": "integer" }, "eta_days": { "type": "integer" }, "customer_message": { "type": "string" } }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false }, "description": { "type": "string" }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "inventory": { "type": "object", "properties": { "tracked": { "type": "boolean" }, "available": { "type": "integer" }, "reserved": { "type": "integer" }, "incoming": { "type": "integer" } }, "required": [ "tracked", "available", "reserved", "incoming" ], "additionalProperties": false }, "online_backorder_policy": { "type": "object", "properties": { "mode": { "type": "string" }, "max_backorder_quantity": {}, "eta_days": {}, "customer_message": {} }, "required": [ "mode", "max_backorder_quantity", "eta_days", "customer_message" ], "additionalProperties": false } }, "required": [ "id", "name", "sku", "barcode", "price", "options", "inventory", "online_backorder_policy" ], "additionalProperties": false } }, "custom_fields": { "type": "object", "properties": { "price_area": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "description": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "value_type" ], "additionalProperties": false } }, "specifications": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "integer" }, "unit": { "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value", "unit", "value_type" ], "additionalProperties": false } } }, "required": [ "price_area", "description", "specifications" ], "additionalProperties": false }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "role": { "type": "string" }, "alt": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "type", "role", "alt", "url" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "handle", "name", "brand", "status", "sellable", "online_backorder_policy", "description", "category", "tags", "variants", "custom_fields", "media", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "api_version", "data" ], "additionalProperties": false, "description": "Whitelisted get published product response projection." }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "details" ], "additionalProperties": false, "properties": { "code": { "type": "string", "example": "insufficient_scope" }, "message": { "type": "string", "example": "This operation requires sales:read." }, "request_id": { "type": "string", "example": "req_test_01J9EXAMPLE" }, "details": { "type": "array", "items": {} } } } } }, "CertifiedStorefrontResolveEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenant_name": { "type": "string" }, "storefront": { "type": "object", "properties": { "slug": { "type": "string" }, "store_name": { "type": "string" }, "store_description": { "type": "string" }, "primary_color": { "type": "string" }, "accent_color": { "type": "string" }, "seo_title": { "type": "string" }, "seo_description": { "type": "string" }, "logo_url": {}, "hero_image_url": {}, "custom_css": {}, "is_published": { "type": "boolean" } }, "required": [ "slug", "store_name", "store_description", "primary_color", "accent_color", "seo_title", "seo_description", "logo_url", "hero_image_url", "custom_css", "is_published" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "pickup_locations": { "type": "array", "items": {} }, "delivery_methods": { "type": "array", "items": {} }, "shipping_methods": { "type": "array", "items": {} }, "gateway": {}, "financing": { "type": "array", "items": {} }, "fulfillment_available": { "type": "object", "properties": { "pickup": { "type": "boolean" }, "local_delivery": { "type": "boolean" }, "shipping": { "type": "boolean" } }, "required": [ "pickup", "local_delivery", "shipping" ], "additionalProperties": false }, "shipping_schedule": { "type": "object", "properties": { "mode": { "type": "string" }, "date_intent": { "type": "string" } }, "required": [ "mode", "date_intent" ], "additionalProperties": false } }, "required": [ "pickup_locations", "delivery_methods", "shipping_methods", "gateway", "financing", "fulfillment_available", "shipping_schedule" ], "additionalProperties": false } }, "required": [ "tenant_name", "storefront", "checkout" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "const": "2026-08-24" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "request_id": { "type": "string" } }, "required": [ "api_version", "environment", "request_id" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "description": "Whitelisted resolve certified storefront checkout response projection." }, "CertifiedStorefrontQuoteEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "name": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "original_unit_price": {}, "price_source": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "line_total": { "type": "integer" }, "shipping_fee": { "type": "integer" }, "fulfillment": { "type": "object", "properties": { "packaging": { "type": "string" }, "allowed_methods": { "type": "array", "items": { "type": "string" } }, "nationwide_shipping": { "type": "object", "properties": { "available": { "type": "boolean" }, "pricing_type": { "type": "string" }, "fee": { "type": "integer" }, "region": { "type": "string" } }, "required": [ "available", "pricing_type", "fee", "region" ], "additionalProperties": false } }, "required": [ "packaging", "allowed_methods", "nationwide_shipping" ], "additionalProperties": false }, "fulfillment_badges": { "type": "array", "items": { "type": "string" } }, "tax_rate": { "type": "number" }, "tax_amount": { "type": "number" }, "inventory": { "type": "object", "properties": { "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" }, "policy": {}, "eta_date": {}, "customer_notice": { "type": "boolean" }, "customer_message": {} }, "required": [ "state", "reserved_quantity", "backorder_quantity", "policy", "eta_date", "customer_notice", "customer_message" ], "additionalProperties": false } }, "required": [ "product_id", "variant_id", "name", "variant_name", "sku", "quantity", "unit_price", "original_unit_price", "price_source", "line_total", "shipping_fee", "fulfillment", "fulfillment_badges", "tax_rate", "tax_amount", "inventory" ], "additionalProperties": false } }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "shipping_method_id": { "type": "string" }, "method_name": { "type": "string" }, "date": {}, "time": {}, "shipping_address": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "required": [ "address", "city", "state", "zip" ], "additionalProperties": false } }, "required": [ "type", "shipping_method_id", "method_name", "date", "time", "shipping_address" ], "additionalProperties": false }, "subtotal": { "type": "integer" }, "discount_total": { "type": "integer" }, "promotions": { "type": "array", "items": {} }, "promotion_code": {}, "shipping_total": { "type": "integer" }, "tax_total": { "type": "number" }, "total": { "type": "number" }, "inventory": { "type": "object", "properties": { "has_backorders": { "type": "boolean" }, "backorder_quantity": { "type": "integer" } }, "required": [ "has_backorders", "backorder_quantity" ], "additionalProperties": false }, "expires_at": { "type": "string" } }, "required": [ "id", "status", "items", "fulfillment", "subtotal", "discount_total", "promotions", "promotion_code", "shipping_total", "tax_total", "total", "inventory", "expires_at" ], "additionalProperties": false } }, "required": [ "quote" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "const": "2026-08-24" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "request_id": { "type": "string" } }, "required": [ "api_version", "environment", "request_id" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "description": "Whitelisted create authoritative storefront quote response projection." }, "CertifiedStorefrontOrderEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string", "enum": [ "pending", "processing", "reconciliation_required", "paid" ], "description": "Authoritative payment lifecycle. reconciliation_required means a provider-approved or captured payment is durably claimed but the CentriPOS order still requires safe reconciliation." }, "total": { "type": "number" }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "date": {}, "delivery_method_id": {}, "pickup_location_id": {}, "shipping_method_id": { "type": "string" } }, "required": [ "type", "date", "delivery_method_id", "pickup_location_id", "shipping_method_id" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "shipping": { "type": "integer" }, "tax": { "type": "number" }, "total": { "type": "number" } }, "required": [ "subtotal", "shipping", "tax", "total" ], "additionalProperties": false }, "inventory": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" } }, "required": [ "product_id", "variant_id", "state", "reserved_quantity", "backorder_quantity" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "name": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "string" }, "date": {}, "shipping_method_id": { "type": "string" }, "delivery_method_id": {}, "pickup_location_id": {} }, "required": [ "type", "status", "date", "shipping_method_id", "delivery_method_id", "pickup_location_id" ], "additionalProperties": false }, "inventory_commitment": { "type": "object", "properties": { "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" }, "eta_date": {}, "customer_message": {} }, "required": [ "state", "reserved_quantity", "backorder_quantity", "eta_date", "customer_message" ], "additionalProperties": false } }, "required": [ "id", "product_id", "variant_id", "name", "variant_name", "sku", "quantity", "unit_price", "line_total", "fulfillment", "inventory_commitment" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_configuration": { "type": "object", "properties": { "card": { "type": "object", "properties": { "provider": { "type": "string", "const": "centripay_gateway" }, "is_connected": { "type": "boolean", "const": true }, "tokenization_key": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Browser-safe public Collect.js tokenization key resolved for the prepared sale. This is not a processor security key." }, "three_ds_tokenization_key": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4096, "description": "Optional browser-safe public 3DS tokenization/authentication key for the prepared sale." }, "three_ds_enabled": { "type": "boolean" } }, "required": [ "provider", "is_connected", "tokenization_key", "three_ds_tokenization_key", "three_ds_enabled" ], "additionalProperties": false } }, "required": [ "card" ], "additionalProperties": false } }, "required": [ "id", "object", "order_number", "status", "payment_status", "total", "fulfillment", "totals", "inventory", "items", "created_at", "updated_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "const": "2026-08-24" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "request_id": { "type": "string" }, "replayed": { "type": "boolean", "description": "Optional operation-specific signal that card capture found and safely returned an already completed order. Gateway idempotency replay is signaled separately by Idempotency-Replayed: true." } }, "required": [ "api_version", "environment", "request_id" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "description": "Whitelisted prepare storefront order response projection." }, "CertifiedStorefrontFinancingEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": "string" }, "financing_application_id": { "type": "string" }, "redirect_url": { "type": "string" }, "status": { "type": "string" }, "replayed": { "type": "boolean" }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string", "enum": [ "pending", "processing", "reconciliation_required", "paid" ], "description": "Authoritative payment lifecycle. reconciliation_required means a provider-approved or captured payment is durably claimed but the CentriPOS order still requires safe reconciliation." }, "total": { "type": "number" }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "date": {}, "delivery_method_id": {}, "pickup_location_id": {}, "shipping_method_id": { "type": "string" } }, "required": [ "type", "date", "delivery_method_id", "pickup_location_id", "shipping_method_id" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "shipping": { "type": "integer" }, "tax": { "type": "number" }, "total": { "type": "number" } }, "required": [ "subtotal", "shipping", "tax", "total" ], "additionalProperties": false }, "inventory": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" } }, "required": [ "product_id", "variant_id", "state", "reserved_quantity", "backorder_quantity" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "variant_id": { "type": "string" }, "name": { "type": "string" }, "variant_name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" }, "fulfillment": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "string" }, "date": {}, "shipping_method_id": { "type": "string" }, "delivery_method_id": {}, "pickup_location_id": {} }, "required": [ "type", "status", "date", "shipping_method_id", "delivery_method_id", "pickup_location_id" ], "additionalProperties": false }, "inventory_commitment": { "type": "object", "properties": { "state": { "type": "string" }, "reserved_quantity": { "type": "integer" }, "backorder_quantity": { "type": "integer" }, "eta_date": {}, "customer_message": {} }, "required": [ "state", "reserved_quantity", "backorder_quantity", "eta_date", "customer_message" ], "additionalProperties": false } }, "required": [ "id", "product_id", "variant_id", "name", "variant_name", "sku", "quantity", "unit_price", "line_total", "fulfillment", "inventory_commitment" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "order_number", "status", "payment_status", "total", "fulfillment", "totals", "inventory", "items", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "provider", "financing_application_id", "redirect_url", "status", "replayed", "order" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "const": "2026-08-24" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "request_id": { "type": "string" } }, "required": [ "api_version", "environment", "request_id" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "description": "Whitelisted initiate paytomorrow financing response projection." } } }, "x-centripos-contract-status": { "public_storefront": "live", "private_retail_reads": "authenticated-live-for-entitled-tenants", "certified_storefront_checkout": "certified-live-for-approved-tenant-and-client", "private_retail_mutations": "controlled-rollout", "example_data": "synthetic-only" }, "x-centripos-commerce-backorders": { "policy_precedence": [ "variant", "product", "tenant" ], "modes": [ "deny", "allow_notify", "allow" ], "inventory_semantics": "Physical storefront availability and policy-approved purchasability are separate server-authoritative fields.", "reservation_semantics": "A quote reserves available physical stock first and snapshots any approved shortage as a durable backorder commitment.", "sale_line_snapshot": [ "state", "reserved_quantity", "backorder_quantity", "policy", "eta_date", "customer_message" ], "events": [ "commerce_backorder.created", "commerce_backorder.updated" ], "event_payload_boundary": "Signed identity-only notifications; retrieve the current supported sale resource with a separately scoped key." }, "x-centripos-storefront-checkout": { "authority": [ "inventory", "address_eligibility", "promotions", "tax", "shipping_and_delivery_fees", "line_fulfillment" ], "mixed_cart_policy": "common-method-intersection", "split_packages_supported": false, "payment_boundary": "Opaque tokenized card or certified financing evidence only; raw PAN, CVV, reusable credentials, and raw processor responses are prohibited.", "idempotency_body_match": "byte-identical-raw-json", "shipping_fee_semantics": "Product flat nationwide shipping fees are multiplied by purchased line quantity." } }