# API reference The published REST operations, request schemas and response schemas. Stage: sandbox beta. Live purchasing requires explicit activation. ## A contract generated from the runtime Base URL: https://api.paperboy.now. API version: 2026-09-05. Authentication: Bearer key. All mutations require Idempotency-Key. Request schemas are shared with the runtime handlers; the contract describes the current sandbox and live gates. Download /v1/openapi.json for OpenAPI 3.1 tooling or use the operation details below. The MCP JSON-RPC endpoint is /v1/mcp and its schemas are exposed through tools/list. ```json { "openapi": "3.1.0", "info": { "title": "paperboy API", "version": "2026-09-05", "description": "The printer for AIs. Discover products, simulate document workflows, request reviewed 3D quotes and track physical orders through scoped REST and MCP tools.", "contact": { "name": "paperboy integration support", "email": "support@paperboy.now", "url": "https://paperboy.now/en/developers/docs/" } }, "externalDocs": { "url": "https://paperboy.now/en/developers/docs/", "description": "Quickstart, agent setup, billing and operations" }, "servers": [ { "url": "https://api.paperboy.now" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/manufacturing/services": { "get": { "operationId": "listManufacturingServices", "summary": "Find 3D printing providers", "tags": [ "catalog" ], "description": "Discover published custom-model services and provider-designed products. Empty results mean no supplier is published for that country. Required scope: catalog:read.", "x-paperboy-scope": "catalog:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Discover published custom-model services and provider-designed products. Empty results mean no supplier is published for that country.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Find 3D printing providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManufacturingServices" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/manufacturing/files": { "post": { "operationId": "uploadModel", "summary": "Upload a small 3D model", "tags": [ "files" ], "description": "Upload actual STL/3MF bytes as base64, up to 120 KiB. Use multipart upload for larger files. This creates a private application-owned file and requests no production. Required scope: files:write.", "x-paperboy-scope": "files:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Upload a small 3D model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelUpload" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/manufacturing/files/{id}/inspection": { "post": { "operationId": "inspectModel", "summary": "Check model dimensions", "tags": [ "files" ], "description": "Inspect an owned model with explicit STL units and scale. Read native 3MF units from the file. Confirm the displayed dimensions with the person. Geometric volume does not estimate sliced material or print time. Required scope: files:write.", "x-paperboy-scope": "files:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInspection" } } } }, "responses": { "200": { "description": "Check model dimensions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelGeometry" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/manufacturing/requests": { "post": { "operationId": "createManufacturingRequest", "summary": "Ask a provider to review a model", "tags": [ "quotes" ], "description": "Submit a real model with confirmed dimensions, material, quantity, intended use, fulfilment and prohibited-items policy acceptance. This creates a real request and can notify the provider. Wait for its reviewed quote before payment. Required scope: quotes:write.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManufacturingInput" } } } }, "responses": { "201": { "description": "Ask a provider to review a model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManufacturingRequest" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/manufacturing/requests/{id}": { "get": { "operationId": "getManufacturingRequest", "summary": "Read a model quote or question", "tags": [ "quotes" ], "description": "Read the exact reviewed model, price, expiry, provider question and human checkout link. A quoted status is an offer. Production starts after successful payment through ordinary checkout or an approved purchasing policy. Required scope: quotes:write.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Read a model quote or question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManufacturingRequest" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/manufacturing/requests/{id}/response": { "post": { "operationId": "respondToManufacturingRequest", "summary": "Revise or cancel a model request", "tags": [ "quotes" ], "description": "Answer a clarification with a complete replacement specification and optional replacement model, or cancel an unpaid request. A revised model needs fresh policy confirmation, provider review and quote. Required scope: quotes:write.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManufacturingResponse" } } } }, "responses": { "200": { "description": "Revise or cancel a model request", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/catalog/products": { "get": { "operationId": "listProducts", "summary": "List canonical products", "tags": [ "catalog" ], "description": "List canonical products Required scope: catalog:read.", "x-paperboy-scope": "catalog:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "Catalog language; defaults to en.", "schema": { "type": "string" } }, { "in": "header", "name": "If-None-Match", "description": "ETag from a previous catalog response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List canonical products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "304": { "description": "ETag matches; response has no body." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/catalog/changes": { "get": { "operationId": "getCatalogChanges", "summary": "Check catalog changes", "tags": [ "catalog" ], "description": "Check catalog changes Required scope: catalog:read.", "x-paperboy-scope": "catalog:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "Catalog language; defaults to en.", "schema": { "type": "string" } }, { "in": "header", "name": "If-None-Match", "description": "ETag from a previous catalog response.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Previously returned catalog_version.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check catalog changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogChange" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "304": { "description": "ETag matches; response has no body." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/catalog/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a canonical product", "tags": [ "catalog" ], "description": "Get a canonical product Required scope: catalog:read.", "x-paperboy-scope": "catalog:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "name": "locale", "in": "query", "required": false, "description": "Catalog language; defaults to en.", "schema": { "type": "string" } }, { "in": "header", "name": "If-None-Match", "description": "ETag from a previous catalog response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a canonical product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogProduct" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "304": { "description": "ETag matches; response has no body." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Check product and country capabilities", "tags": [ "catalog" ], "description": "available describes sandbox/entitlement access. ordering_enabled requires explicit live purchasing activation and an enabled saved-card policy; every imported quote still passes canonical route and production checks. Required scope: catalog:read.", "x-paperboy-scope": "catalog:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "Catalog language; defaults to en.", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "required": true, "description": "Canonical catalog product ID.", "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "required": true, "description": "Two-letter country code.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } } ], "responses": { "200": { "description": "Check product and country capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/files": { "post": { "operationId": "createFile", "summary": "Create a simulated file", "tags": [ "files" ], "description": "Records file metadata for simulation. Does not accept file bytes or examine a real PDF. Required scope: files:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "files:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileInput" } } } }, "responses": { "201": { "description": "Create a simulated file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/files/{id}/preflight": { "post": { "operationId": "preflightFile", "summary": "Simulate document preflight", "tags": [ "files" ], "description": "Simulate document preflight Required scope: files:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "files:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Simulate document preflight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preflight" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/quotes/import": { "post": { "operationId": "importVerifiedQuote", "summary": "Import a signed live paperboy quote", "tags": [ "quotes" ], "description": "Requires live purchasing activation. Reuses the existing human document/quote workflow and validates ownership, files, expiry, economics and route readiness. Does not charge. Required scope: quotes:write.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportQuoteInput" } } } }, "responses": { "201": { "description": "Import a signed live paperboy quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedQuote" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/purchasing-policy": { "get": { "operationId": "getPurchasingPolicy", "summary": "Read human-set purchasing policy", "tags": [ "orders" ], "description": "Read-only spending limits, approved recipient identities and reserved/paid totals. Only the human project creator can change the policy, card or exception approvals through their account session. Required scope: orders:read.", "x-paperboy-scope": "orders:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [], "responses": { "200": { "description": "Read human-set purchasing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasingPolicy" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}/submit": { "post": { "operationId": "submitApprovedOrder", "summary": "Submit the same approved purchase", "tags": [ "orders" ], "description": "Resume the same live purchase after human approval. Can charge a saved card and release production after confirmed payment. Never creates a second PSP identity for an uncertain request. Required scope: orders:write.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Submit the same approved purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/quotes": { "post": { "operationId": "createQuote", "summary": "Create an immutable sandbox quote", "tags": [ "quotes" ], "description": "Uses deterministic sandbox economics, rather than a live price. Configuration must match the catalog. Quote expires after 15 minutes. Required scope: quotes:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" } } } }, "responses": { "201": { "description": "Create an immutable sandbox quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/quotes/{id}": { "get": { "operationId": "getQuote", "summary": "Get an immutable quote", "tags": [ "quotes" ], "description": "Get an immutable quote Required scope: quotes:write.", "x-paperboy-scope": "quotes:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Get an immutable quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders": { "post": { "operationId": "createOrder", "summary": "Create an order from a quote", "tags": [ "orders" ], "description": "Sandbox returns a simulation (201). Activated live applications return a purchase projection (202), using an imported verified quote, saved-card consent and a human spending/recipient policy. Exceptions require exact human approval; payment is confirmed before production. Required scope: orders:write.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" } } } }, "responses": { "201": { "description": "Create an order from a quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "202": { "description": "Live purchase is pending approval, authentication or settlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get an order", "tags": [ "orders" ], "description": "Get an order Required scope: orders:read.", "x-paperboy-scope": "orders:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Get an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}/advance": { "post": { "operationId": "advanceSandboxOrder", "summary": "Advance the sandbox lifecycle once", "tags": [ "orders" ], "description": "Use a new key for each intended transition; replay the same key to recover a transition. Required scope: orders:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Advance the sandbox lifecycle once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel a sandbox order", "tags": [ "orders" ], "description": "Cancel a sandbox order Required scope: orders:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionInput" } } } }, "responses": { "200": { "description": "Cancel a sandbox order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}/replacement": { "post": { "operationId": "requestReplacement", "summary": "Request a sandbox replacement", "tags": [ "orders" ], "description": "Request a sandbox replacement Required scope: orders:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionInput" } } } }, "responses": { "202": { "description": "Request a sandbox replacement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Replacement" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{id}/refund": { "post": { "operationId": "refundSandboxOrder", "summary": "Simulate a refund", "tags": [ "orders" ], "description": "Simulate a refund Required scope: orders:write. Mutations are sandbox-only; live requests fail closed. Sandbox resources are simulated and never purchase production or delivery.", "x-paperboy-scope": "orders:write", "x-paperboy-environments": [ "sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionInput" } } } }, "responses": { "200": { "description": "Simulate a refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/production-jobs/{id}": { "get": { "operationId": "getProductionJob", "summary": "Get a production-job projection", "tags": [ "orders" ], "description": "Get a production-job projection Required scope: orders:read.", "x-paperboy-scope": "orders:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Get a production-job projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionJob" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/shipments/{id}": { "get": { "operationId": "getShipment", "summary": "Get a shipment projection", "tags": [ "orders" ], "description": "Get a shipment projection Required scope: orders:read.", "x-paperboy-scope": "orders:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Get a shipment projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List recoverable events", "tags": [ "orders" ], "description": "Newest first, ordered by creation time and ID. Consumers deduplicate event IDs and recover current resource state when events arrive out of order. Required scope: orders:read.", "x-paperboy-scope": "orders:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Use next_cursor from the previous page. Cursors belong to this application.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List recoverable events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/billing/usage": { "get": { "operationId": "getUsage", "summary": "Get immutable usage totals", "tags": [ "billing" ], "description": "All-time application totals grouped by meter/unit. Sandbox usage is simulated and creates no payment. Required scope: billing:read.", "x-paperboy-scope": "billing:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [], "responses": { "200": { "description": "Get immutable usage totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/billing/invoices": { "get": { "operationId": "listInvoices", "summary": "List order financial documents", "tags": [ "billing" ], "description": "List order financial documents Required scope: billing:read.", "x-paperboy-scope": "billing:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Use next_cursor from the previous page. Cursors belong to this application.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List order financial documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePage" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/billing/credit-balance": { "get": { "operationId": "getCreditBalance", "summary": "Get credit availability", "tags": [ "billing" ], "description": "Prepaid and net-term credit are disabled. This endpoint does not create or fund a wallet. Required scope: billing:read.", "x-paperboy-scope": "billing:read", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [], "responses": { "200": { "description": "Get credit availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "description": "List webhook endpoints Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Use next_cursor from the previous page. Cursors belong to this application.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointPage" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a signed webhook endpoint", "tags": [ "Webhooks" ], "description": "Requires activated signing-secret storage. Copy signing_secret immediately. Webhooks can make HTTPS requests to the configured endpoint, including for sandbox events. Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Create a signed webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook-endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "summary": "Disable a webhook endpoint", "tags": [ "Webhooks" ], "description": "Disable a webhook endpoint Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Disabled", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook-endpoints/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate webhook signing secret", "tags": [ "Webhooks" ], "description": "Returns a replacement secret with 24-hour dual-signature overlap. Verify raw bytes and accept any matching v1 signature. Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Rotate webhook signing secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRotation" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook delivery health", "tags": [ "Webhooks" ], "description": "List webhook delivery health Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Use next_cursor from the previous page. Cursors belong to this application.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List webhook delivery health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook-deliveries/{id}/replay": { "post": { "operationId": "replayWebhookDelivery", "summary": "Replay a webhook delivery", "tags": [ "Webhooks" ], "description": "Replay a webhook delivery Required scope: webhooks:write.", "x-paperboy-scope": "webhooks:write", "x-paperboy-environments": [ "sandbox", "live" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Replay a webhook delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplay" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Correlation ID for support and logs." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in this scope's current window." } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Server-side pb_test_ or approved pb_live_ key. Live purchasing requires separate activation and human purchasing policy. OAuth is not enabled on this API." } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable identity for this intended mutation. Same application/operation/key/body replays the saved response; a different body conflicts. Never change keys merely to retry an uncertain request.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "schemas": { "ManufacturingInput": { "type": "object", "properties": { "service_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "file_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "model": { "type": "object", "properties": { "unit": { "default": "millimeter", "type": "string", "enum": [ "millimeter", "centimeter", "inch" ] }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "material": { "type": "string", "minLength": 1, "maxLength": 120 }, "colour": { "type": "string", "minLength": 1, "maxLength": 120 }, "process": { "default": "fdm", "type": "string", "enum": [ "fdm", "sla", "sls", "mjf", "metal" ] }, "intendedUse": { "type": "string", "minLength": 3, "maxLength": 2000 }, "dimensionsConfirmed": { "type": "boolean", "const": true }, "prohibitedItemsConfirmed": { "type": "boolean", "const": true }, "manufacturingPolicyVersion": { "type": "string", "const": "2026-11-04" } }, "required": [ "material", "colour", "intendedUse", "dimensionsConfirmed", "prohibitedItemsConfirmed", "manufacturingPolicyVersion" ], "additionalProperties": false }, "choices": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "fulfilment": { "type": "string", "enum": [ "pickup", "courier", "post" ] }, "protective_packaging_requested": { "default": true, "type": "boolean" }, "delivery_address": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "recipient_name": { "type": "string", "maxLength": 200 }, "recipient_email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "recipient_phone": { "type": "string", "maxLength": 80 }, "note": { "type": "string", "maxLength": 2000 }, "personalisation": { "type": "string", "maxLength": 4000 } }, "required": [ "service_id", "file_id", "quantity", "model", "fulfilment" ], "additionalProperties": false }, "ManufacturingResponse": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "cancel" } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "revise" }, "file_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "model": { "type": "object", "properties": { "unit": { "default": "millimeter", "type": "string", "enum": [ "millimeter", "centimeter", "inch" ] }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "material": { "type": "string", "minLength": 1, "maxLength": 120 }, "colour": { "type": "string", "minLength": 1, "maxLength": 120 }, "process": { "default": "fdm", "type": "string", "enum": [ "fdm", "sla", "sls", "mjf", "metal" ] }, "intendedUse": { "type": "string", "minLength": 3, "maxLength": 2000 }, "dimensionsConfirmed": { "type": "boolean", "const": true }, "prohibitedItemsConfirmed": { "type": "boolean", "const": true }, "manufacturingPolicyVersion": { "type": "string", "const": "2026-11-04" } }, "required": [ "unit", "scale", "material", "colour", "process", "intendedUse", "dimensionsConfirmed", "prohibitedItemsConfirmed", "manufacturingPolicyVersion" ], "additionalProperties": false }, "message": { "type": "string", "maxLength": 2000 } }, "required": [ "action", "model" ], "additionalProperties": false } ] }, "ManufacturingRequest": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "manufacturing_request" }, "environment": { "type": "string", "const": "live" }, "status": { "type": "string" }, "checkout_url": { "type": "string" } }, "required": [ "id", "object", "environment", "status", "checkout_url" ], "additionalProperties": {} }, "ModelUpload": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "file" }, "environment": { "type": "string", "const": "live" }, "artifact_id": { "type": "string" }, "checksum_sha256": { "type": "string" }, "geometry": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "object", "environment", "artifact_id", "checksum_sha256", "geometry" ], "additionalProperties": {} }, "ModelInspection": { "type": "object", "properties": { "unit": { "default": "millimeter", "type": "string", "enum": [ "millimeter", "centimeter", "inch" ] }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "unit", "scale" ], "additionalProperties": false }, "ModelGeometry": { "type": "object", "properties": { "id": { "type": "string" }, "geometry": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "geometry" ], "additionalProperties": {} }, "ManufacturingServices": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "services" ], "additionalProperties": {} }, "ImportQuoteInput": { "type": "object", "properties": { "quote_token": { "type": "string", "minLength": 1, "maxLength": 500000 } }, "required": [ "quote_token" ], "additionalProperties": false }, "VerifiedQuote": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "quote" }, "environment": { "type": "string", "const": "live" }, "status": { "type": "string", "const": "ready" }, "currency": { "type": "string" }, "total_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expires_at": { "type": "string" }, "recipient": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "document_summary": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "id", "object", "environment", "status", "currency", "total_minor", "expires_at", "recipient", "document_summary" ], "additionalProperties": false }, "PurchasingPolicy": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "currency": { "type": "string" }, "per_order_limit_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "daily_limit_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "monthly_limit_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reserved_and_paid": { "type": "object", "properties": { "daily": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "monthly": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "daily", "monthly" ], "additionalProperties": false }, "approved_recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string" }, "address_id": { "type": "string" } }, "required": [ "contact_id", "address_id" ], "additionalProperties": false } } }, "required": [ "enabled", "currency", "per_order_limit_minor", "daily_limit_minor", "monthly_limit_minor", "reserved_and_paid", "approved_recipients" ], "additionalProperties": false }, "FileInput": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mime_type": { "type": "string", "minLength": 3, "maxLength": 128 }, "size_bytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000 }, "checksum_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "scenario": { "description": "Sandbox only: success, preflight_failure, provider_decline, broker_fallback, payment_failure, split_production, late_shipment, undeliverable_mail, cancellation, refund. Defaults to success.", "type": "string", "maxLength": 64 } }, "required": [ "filename", "mime_type", "size_bytes", "checksum_sha256" ], "additionalProperties": false }, "QuoteInput": { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1 }, "configuration": { "default": {}, "description": "Canonical product attributes from the catalog. JSON is limited to 100,000 characters.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "destination": { "type": "object", "properties": { "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "type": "string", "maxLength": 32 } }, "required": [ "country_code" ], "additionalProperties": false }, "file_ids": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string" } }, "scenario": { "type": "string", "maxLength": 64 }, "external_reference": { "type": "string", "maxLength": 200 } }, "required": [ "product_id", "quantity", "destination" ], "additionalProperties": false }, "OrderInput": { "type": "object", "properties": { "quote_id": { "type": "string", "minLength": 1 }, "external_reference": { "type": "string", "maxLength": 200 }, "metadata": { "default": {}, "maxProperties": 20, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "quote_id" ], "additionalProperties": false }, "OrderActionInput": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 2, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint; redirects and private destinations are rejected." }, "description": { "type": "string", "maxLength": 200 }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+(?:\\.[a-z_*]+)+$" } } }, "required": [ "url", "events" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "field", "retryable", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "file" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checksum_sha256": { "type": "string" }, "status": { "type": "string" }, "scenario": { "type": "string" }, "preflight": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "passed", "failed" ] }, "policy_version": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "page": { "type": "number" }, "retryable": { "type": "boolean" } }, "required": [ "code", "severity" ], "additionalProperties": {} } } }, "required": [ "id", "status", "policy_version", "findings" ], "additionalProperties": {} } }, "required": [ "id", "object", "filename", "mime_type", "size_bytes", "checksum_sha256", "status", "scenario" ], "additionalProperties": {} }, "Preflight": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "passed", "failed" ] }, "policy_version": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "page": { "type": "number" }, "retryable": { "type": "boolean" } }, "required": [ "code", "severity" ], "additionalProperties": {} } } }, "required": [ "id", "status", "policy_version", "findings" ], "additionalProperties": {} }, "Quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "quote" }, "status": { "type": "string" }, "currency": { "type": "string" }, "subtotal_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "delivery_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "tax_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "total_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." }, "product_id": { "type": "string" }, "configuration": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "destination": { "type": "object", "properties": { "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "type": "string", "maxLength": 32 } }, "required": [ "country_code" ], "additionalProperties": false }, "file_ids": { "type": "array", "items": { "type": "string" } }, "scenario": { "type": "string" }, "assumptions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "object", "status", "currency", "subtotal_minor", "delivery_minor", "tax_minor", "total_minor", "expires_at", "product_id", "configuration", "quantity", "destination", "file_ids", "scenario", "assumptions" ], "additionalProperties": {} }, { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "quote" }, "environment": { "type": "string", "const": "live" }, "status": { "type": "string", "const": "ready" }, "currency": { "type": "string" }, "total_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expires_at": { "type": "string" }, "recipient": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "document_summary": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "id", "object", "environment", "status", "currency", "total_minor", "expires_at", "recipient", "document_summary" ], "additionalProperties": false } ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "order" }, "status": { "type": "string" }, "quote_id": { "type": "string" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "currency": { "type": "string" }, "scenario": { "type": "string" }, "purchase_authorization_id": { "type": "string" }, "approval_url": { "type": "string" }, "approval_reasons": { "type": "array", "items": { "type": "string" } }, "payment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quote_hash": { "type": "string" }, "production_jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "order_id": { "type": "string" }, "object": { "type": "string", "const": "production_job" } }, "required": [ "id", "status" ], "additionalProperties": {} } }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "order_id": { "type": "string" }, "tracking_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "shipment" } }, "required": [ "id", "status" ], "additionalProperties": {} } }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." } }, "required": [ "id", "object", "status", "quote_id", "external_reference", "metadata", "amount_minor", "currency", "production_jobs", "shipments", "updated_at" ], "additionalProperties": {} }, "Replacement": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "replacement_request" }, "order_id": { "type": "string" }, "status": { "type": "string", "const": "requested" }, "reason": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." } }, "required": [ "id", "object", "order_id", "status", "reason", "created_at" ], "additionalProperties": {} }, "Catalog": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "categoryId": { "type": "string" }, "resolvedLocale": { "type": "string" }, "specificationFamily": { "type": "string" }, "specificationVersion": { "type": "string" }, "madeToOrder": { "type": "boolean" }, "customDimensionsAllowed": { "type": "boolean" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "helpText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dataType": { "type": "string" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "required": { "type": "boolean" }, "allowMultiple": { "type": "boolean" }, "allowCustom": { "type": "boolean" }, "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "string" }, "name": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "value", "name", "metadata" ], "additionalProperties": {} } } }, "required": [ "key", "name", "helpText", "role", "required", "allowMultiple", "allowCustom", "rules", "values" ], "additionalProperties": {} } }, "brandIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "slug", "name", "description", "categoryId", "resolvedLocale", "specificationFamily", "specificationVersion", "madeToOrder", "customDimensionsAllowed", "attributes", "brandIds" ], "additionalProperties": {} } }, "categories": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "brands": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "catalog_version": { "type": "string" } }, "required": [ "data", "categories", "brands", "catalog_version" ], "additionalProperties": false }, "CatalogProduct": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "categoryId": { "type": "string" }, "resolvedLocale": { "type": "string" }, "specificationFamily": { "type": "string" }, "specificationVersion": { "type": "string" }, "madeToOrder": { "type": "boolean" }, "customDimensionsAllowed": { "type": "boolean" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "helpText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dataType": { "type": "string" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "required": { "type": "boolean" }, "allowMultiple": { "type": "boolean" }, "allowCustom": { "type": "boolean" }, "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "string" }, "name": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "value", "name", "metadata" ], "additionalProperties": {} } } }, "required": [ "key", "name", "helpText", "role", "required", "allowMultiple", "allowCustom", "rules", "values" ], "additionalProperties": {} } }, "brandIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "slug", "name", "description", "categoryId", "resolvedLocale", "specificationFamily", "specificationVersion", "madeToOrder", "customDimensionsAllowed", "attributes", "brandIds" ], "additionalProperties": {} }, "catalog_version": { "type": "string" } }, "required": [ "data", "catalog_version" ], "additionalProperties": false }, "CatalogChange": { "type": "object", "properties": { "object": { "type": "string", "const": "catalog_change" }, "catalog_version": { "type": "string" }, "changed": { "type": "boolean" }, "refetch": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "catalog_version", "changed", "refetch" ], "additionalProperties": false }, "Capability": { "type": "object", "properties": { "object": { "type": "string", "const": "capability" }, "product_id": { "type": "string" }, "product_family": { "type": "string" }, "country_code": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "available": { "type": "boolean" }, "ordering_enabled": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "object", "product_id", "product_family", "country_code", "environment", "available", "ordering_enabled", "reason" ], "additionalProperties": false }, "ProductionJob": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "order_id": { "type": "string" }, "object": { "type": "string", "const": "production_job" } }, "required": [ "id", "status" ], "additionalProperties": {} }, "Shipment": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "order_id": { "type": "string" }, "tracking_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "shipment" } }, "required": [ "id", "status" ], "additionalProperties": {} }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "api_version": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." }, "project_id": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "data": { "type": "object", "properties": { "object": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "object" ], "additionalProperties": false } }, "required": [ "id", "type", "api_version", "created_at", "project_id", "environment", "data" ], "additionalProperties": {} }, "EventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "api_version": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." }, "project_id": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "data": { "type": "object", "properties": { "object": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "object" ], "additionalProperties": false } }, "required": [ "id", "type", "api_version", "created_at", "project_id", "environment", "data" ], "additionalProperties": {} } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "meter": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" } }, "required": [ "meter", "unit", "quantity" ], "additionalProperties": false } }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "data", "environment" ], "additionalProperties": false }, "InvoicePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "document_number": { "type": "string" }, "kind": { "type": "string" }, "order_id": { "type": "string" }, "currency": { "type": "string" }, "subtotal_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "tax_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "total_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Amount in the currency's minor units." }, "content_hash": { "type": "string" }, "issued_at": { "type": "string", "description": "ISO 8601 timestamp in UTC." } }, "required": [ "id", "document_number", "kind", "order_id", "currency", "subtotal_minor", "tax_minor", "total_minor", "content_hash", "issued_at" ], "additionalProperties": {} } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false }, "CreditBalance": { "type": "object", "properties": { "object": { "type": "string", "const": "credit_balance" }, "enabled": { "type": "boolean", "const": false }, "available_minor": { "type": "number", "const": 0 }, "currency": { "type": "string" }, "billing_mode": { "type": "string", "const": "per_order_payment" }, "reason": { "type": "string" } }, "required": [ "object", "enabled", "available_minor", "currency", "billing_mode", "reason" ], "additionalProperties": false }, "WebhookEndpointPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "id", "url", "events", "status" ], "additionalProperties": {} } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "signing_secret": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "id", "url", "events", "status", "signing_secret", "warning" ], "additionalProperties": {} }, "WebhookRotation": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint_secret" }, "signing_secret": { "type": "string" }, "previous_secret_valid_until": { "type": "string", "description": "ISO 8601 timestamp in UTC." }, "warning": { "type": "string" } }, "required": [ "id", "object", "signing_secret", "previous_secret_valid_until", "warning" ], "additionalProperties": false }, "WebhookDeliveryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string" }, "attemptCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "responseStatus": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "latencyMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "errorExcerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC." } }, "required": [ "id", "endpointId", "eventId", "status", "attemptCount", "responseStatus", "latencyMs", "errorExcerpt", "deliveredAt", "createdAt" ], "additionalProperties": {} } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false }, "WebhookReplay": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "pending" } }, "required": [ "id", "status" ], "additionalProperties": false } }, "responses": { "Error": { "description": "Machine-readable failure; inspect code, field, retryable and request_id. 429 includes Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } ```