API reference
The published REST operations, request schemas and response schemas.
Sandbox betaTest with simulated documents and orders. Live headless ordering is disabled.
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.
REST operations
GET/v1/manufacturing/servicesFind 3D printing providers
Discover published custom-model services and provider-designed products. Empty results mean no supplier is published for that country. Required scope: catalog:read.
Required scope: catalog:read
{
"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"
}
}
}POST/v1/manufacturing/filesUpload a small 3D model
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.
Required scope: files:write
{
"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"
}
}
}
}
}
}
}POST/v1/manufacturing/files/{id}/inspectionCheck model dimensions
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.
Required scope: files:write
{
"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"
}
}
}POST/v1/manufacturing/requestsAsk a provider to review a model
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.
Required scope: quotes:write
{
"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"
}
}
}GET/v1/manufacturing/requests/{id}Read a model quote or question
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.
Required scope: quotes:write
{
"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"
}
}
}POST/v1/manufacturing/requests/{id}/responseRevise or cancel a model request
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.
Required scope: quotes:write
{
"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"
}
}
}GET/v1/catalog/productsList canonical products
List canonical products Required scope: catalog:read.
Required scope: catalog:read
{
"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"
}
}
}GET/v1/catalog/changesCheck catalog changes
Check catalog changes Required scope: catalog:read.
Required scope: catalog:read
{
"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"
}
}
}GET/v1/catalog/products/{id}Get a canonical product
Get a canonical product Required scope: catalog:read.
Required scope: catalog:read
{
"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"
}
}
}GET/v1/capabilitiesCheck product and country capabilities
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.
Required scope: catalog:read
{
"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"
}
}
}POST/v1/filesCreate a simulated file
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.
Required scope: files:write
{
"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"
}
}
}POST/v1/files/{id}/preflightSimulate document preflight
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.
Required scope: files:write
{
"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"
}
}
}POST/v1/quotes/importImport a signed live paperboy quote
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.
Required scope: quotes:write
{
"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"
}
}
}GET/v1/purchasing-policyRead human-set purchasing policy
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.
Required scope: orders:read
{
"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"
}
}
}POST/v1/orders/{id}/submitSubmit the same approved purchase
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.
Required scope: orders:write
{
"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"
}
}
}POST/v1/quotesCreate an immutable sandbox quote
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.
Required scope: quotes:write
{
"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"
}
}
}GET/v1/quotes/{id}Get an immutable quote
Get an immutable quote Required scope: quotes:write.
Required scope: quotes:write
{
"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"
}
}
}POST/v1/ordersCreate an order from a quote
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.
Required scope: orders:write
{
"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"
}
}
}GET/v1/orders/{id}Get an order
Get an order Required scope: orders:read.
Required scope: orders:read
{
"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"
}
}
}POST/v1/orders/{id}/advanceAdvance the sandbox lifecycle once
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.
Required scope: orders:write
{
"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"
}
}
}POST/v1/orders/{id}/cancelCancel a sandbox order
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.
Required scope: orders:write
{
"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"
}
}
}POST/v1/orders/{id}/replacementRequest a sandbox replacement
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.
Required scope: orders:write
{
"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"
}
}
}POST/v1/orders/{id}/refundSimulate a refund
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.
Required scope: orders:write
{
"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"
}
}
}GET/v1/production-jobs/{id}Get a production-job projection
Get a production-job projection Required scope: orders:read.
Required scope: orders:read
{
"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"
}
}
}GET/v1/shipments/{id}Get a shipment projection
Get a shipment projection Required scope: orders:read.
Required scope: orders:read
{
"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"
}
}
}GET/v1/eventsList recoverable events
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.
Required scope: orders:read
{
"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"
}
}
}GET/v1/billing/usageGet immutable usage totals
All-time application totals grouped by meter/unit. Sandbox usage is simulated and creates no payment. Required scope: billing:read.
Required scope: billing:read
{
"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"
}
}
}GET/v1/billing/invoicesList order financial documents
List order financial documents Required scope: billing:read.
Required scope: billing:read
{
"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"
}
}
}GET/v1/billing/credit-balanceGet credit availability
Prepaid and net-term credit are disabled. This endpoint does not create or fund a wallet. Required scope: billing:read.
Required scope: billing:read
{
"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"
}
}
}GET/v1/webhook-endpointsList webhook endpoints
List webhook endpoints Required scope: webhooks:write.
Required scope: webhooks:write
{
"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/v1/webhook-endpointsCreate a signed webhook endpoint
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.
Required scope: webhooks:write
{
"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"
}
}
}DELETE/v1/webhook-endpoints/{id}Disable a webhook endpoint
Disable a webhook endpoint Required scope: webhooks:write.
Required scope: webhooks:write
{
"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"
}
}
}POST/v1/webhook-endpoints/{id}/rotate-secretRotate webhook signing secret
Returns a replacement secret with 24-hour dual-signature overlap. Verify raw bytes and accept any matching v1 signature. Required scope: webhooks:write.
Required scope: webhooks:write
{
"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"
}
}
}GET/v1/webhook-deliveriesList webhook delivery health
List webhook delivery health Required scope: webhooks:write.
Required scope: webhooks:write
{
"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"
}
}
}POST/v1/webhook-deliveries/{id}/replayReplay a webhook delivery
Replay a webhook delivery Required scope: webhooks:write.
Required scope: webhooks:write
{
"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"
}
}
}Shared 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
}