{ "openapi": "3.1.0", "info": { "title": "Sample Orders API", "version": "1.0.0", "summary": "A fictional orders API for a small bakery. Illustrative only.", "description": "ILLUSTRATIVE SAMPLE. This is a fictional API written to show API design and documentation style. There is no live service behind it, no real data, and the host names use the reserved .invalid and example domains. Demo with sample data.\n\nHuman-readable version: https://tonimaxx.com/demo/api/", "license": { "name": "Demonstration content, no license granted", "url": "https://tonimaxx.com/demo/api/" }, "contact": { "name": "Toni Maxx", "url": "https://tonimaxx.com/demo/#contact" }, "x-demo-notice": "Demo with sample data. Not a live service." }, "externalDocs": { "description": "Documentation page for this sample", "url": "https://tonimaxx.com/demo/api/" }, "servers": [ { "url": "https://api.example.invalid/v1", "description": "Illustrative placeholder host. Not a live service." } ], "tags": [ { "name": "Products", "description": "Items you sell. Prices are integer cents." }, { "name": "Customers", "description": "People who place orders." }, { "name": "Orders", "description": "Orders and their lifecycle." }, { "name": "Webhook endpoints", "description": "Where your events are delivered." } ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [] }, { "OpenID": [] } ], "paths": { "/products": { "get": { "operationId": "listProducts", "tags": [ "Products" ], "summary": "List products", "description": "Returns products, newest first, in cursor pages. Combine filters freely; q matches name and SKU.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "products:read" ] }, { "OpenID": [ "products:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "category", "in": "query", "description": "One of bread, pastry, cake, drink.", "schema": { "type": "string", "enum": [ "bread", "pastry", "cake", "drink" ] }, "example": "bread" }, { "name": "in_stock", "in": "query", "description": "true to hide sold-out products.", "schema": { "type": "boolean" }, "example": true }, { "name": "q", "in": "query", "description": "Text search on name and SKU.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of products.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "example": { "data": [ { "id": "prod_01JB8M3Q", "sku": "SOUR-LOAF-800", "name": "Sourdough loaf", "description": "Naturally leavened, baked every morning.", "category": "bread", "price_cents": 650, "currency": "usd", "in_stock": true, "stock_quantity": 24, "created_at": "2026-10-02T08:15:00Z", "updated_at": "2026-11-09T06:30:00Z" }, { "id": "prod_01JB8M4W", "sku": "BUTTER-CROIS", "name": "Butter croissant", "description": "Laminated dough, 27 layers.", "category": "pastry", "price_cents": 375, "currency": "usd", "in_stock": true, "stock_quantity": 60, "created_at": "2026-10-02T08:17:00Z", "updated_at": "2026-11-09T06:30:00Z" } ], "page": { "next_cursor": "eyJpZCI6InByb2RfMDFKQjhNNFcifQ", "has_more": true } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "post": { "operationId": "createProduct", "tags": [ "Products" ], "summary": "Create a product", "description": "Adds a product to the catalogue. The SKU must be unique; a duplicate returns 409.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "products:write" ] }, { "OpenID": [ "products:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" }, "example": { "sku": "RYE-LOAF-600", "name": "Seeded rye", "category": "bread", "price_cents": 720, "stock_quantity": 12 } } } }, "responses": { "201": { "description": "The new product.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_01JB8M9K", "sku": "RYE-LOAF-600", "name": "Seeded rye", "description": null, "category": "bread", "price_cents": 720, "currency": "usd", "in_stock": true, "stock_quantity": 12, "created_at": "2026-11-09T10:20:00Z", "updated_at": "2026-11-09T10:20:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/products/{product_id}": { "get": { "operationId": "getProduct", "tags": [ "Products" ], "summary": "Retrieve a product", "description": "Returns one product by id.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "products:read" ] }, { "OpenID": [ "products:read" ] } ], "parameters": [ { "name": "product_id", "in": "path", "description": "Product id, prefix prod_.", "schema": { "type": "string" }, "required": true, "example": "prod_01JB8M3Q" } ], "responses": { "200": { "description": "The product.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_01JB8M3Q", "sku": "SOUR-LOAF-800", "name": "Sourdough loaf", "description": "Naturally leavened, baked every morning.", "category": "bread", "price_cents": 650, "currency": "usd", "in_stock": true, "stock_quantity": 24, "created_at": "2026-10-02T08:15:00Z", "updated_at": "2026-11-09T06:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "patch": { "operationId": "updateProduct", "tags": [ "Products" ], "summary": "Update a product", "description": "Changes only the fields you send. Sending the same values twice has the same result, so it is safe to retry.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "products:write" ] }, { "OpenID": [ "products:write" ] } ], "parameters": [ { "name": "product_id", "in": "path", "description": "Product id.", "schema": { "type": "string" }, "required": true, "example": "prod_01JB8M3Q" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" }, "example": { "price_cents": 690, "stock_quantity": 30 } } } }, "responses": { "200": { "description": "The updated product.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_01JB8M3Q", "sku": "SOUR-LOAF-800", "name": "Sourdough loaf", "description": "Naturally leavened, baked every morning.", "category": "bread", "price_cents": 690, "currency": "usd", "in_stock": true, "stock_quantity": 30, "created_at": "2026-10-02T08:15:00Z", "updated_at": "2026-11-09T11:05:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "delete": { "operationId": "archiveProduct", "tags": [ "Products" ], "summary": "Archive a product", "description": "Removes the product from the catalogue. Existing orders keep their line items. Archiving twice returns 204 both times.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "products:write" ] }, { "OpenID": [ "products:write" ] } ], "parameters": [ { "name": "product_id", "in": "path", "description": "Product id.", "schema": { "type": "string" }, "required": true, "example": "prod_01JB8M3Q" } ], "responses": { "204": { "description": "Archived. No body.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/customers": { "get": { "operationId": "listCustomers", "tags": [ "Customers" ], "summary": "List customers", "description": "Returns customers, newest first. Filter by exact e-mail to look one up.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "customers:read" ] }, { "OpenID": [ "customers:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "email", "in": "query", "description": "Exact match, case-insensitive.", "schema": { "type": "string", "format": "email" }, "example": "alex@example.com" } ], "responses": { "200": { "description": "A page of customers.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "example": { "data": [ { "id": "cus_01JB8K2P", "name": "Alex Example", "email": "alex@example.com", "marketing_opt_in": false, "created_at": "2026-10-21T14:02:00Z" } ], "page": { "next_cursor": null, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "post": { "operationId": "createCustomer", "tags": [ "Customers" ], "summary": "Create a customer", "description": "Creates a customer. The e-mail must be unique within your account.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "customers:write" ] }, { "OpenID": [ "customers:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" }, "example": { "name": "Sam Sample", "email": "sam@example.com", "marketing_opt_in": true } } } }, "responses": { "201": { "description": "The new customer.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_01JB8K5D", "name": "Sam Sample", "email": "sam@example.com", "marketing_opt_in": true, "created_at": "2026-10-28T10:44:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/customers/{customer_id}": { "get": { "operationId": "getCustomer", "tags": [ "Customers" ], "summary": "Retrieve a customer", "description": "Returns one customer by id.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "customers:read" ] }, { "OpenID": [ "customers:read" ] } ], "parameters": [ { "name": "customer_id", "in": "path", "description": "Customer id, prefix cus_.", "schema": { "type": "string" }, "required": true, "example": "cus_01JB8K2P" } ], "responses": { "200": { "description": "The customer.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_01JB8K2P", "name": "Alex Example", "email": "alex@example.com", "marketing_opt_in": false, "created_at": "2026-10-21T14:02:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "patch": { "operationId": "updateCustomer", "tags": [ "Customers" ], "summary": "Update a customer", "description": "Changes only the fields you send.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "customers:write" ] }, { "OpenID": [ "customers:write" ] } ], "parameters": [ { "name": "customer_id", "in": "path", "description": "Customer id.", "schema": { "type": "string" }, "required": true, "example": "cus_01JB8K2P" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" }, "example": { "marketing_opt_in": true } } } }, "responses": { "200": { "description": "The updated customer.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_01JB8K2P", "name": "Alex Example", "email": "alex@example.com", "marketing_opt_in": true, "created_at": "2026-10-21T14:02:00Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/orders": { "get": { "operationId": "listOrders", "tags": [ "Orders" ], "summary": "List orders", "description": "Returns orders, newest first. Use created_after to sync incrementally.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "orders:read" ] }, { "OpenID": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "description": "pending, paid, fulfilled or cancelled.", "schema": { "type": "string", "enum": [ "pending", "paid", "fulfilled", "cancelled" ] }, "example": "paid" }, { "name": "customer_id", "in": "query", "description": "Only this customer's orders.", "schema": { "type": "string" }, "example": "cus_01JB8K2P" }, { "name": "created_after", "in": "query", "description": "RFC 3339 timestamp, exclusive.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-01T00:00:00Z" } ], "responses": { "200": { "description": "A page of orders.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "example": { "data": [ { "id": "ord_01JB8N7R", "status": "paid", "customer_id": "cus_01JB8K2P", "items": [ { "product_id": "prod_01JB8M3Q", "name": "Sourdough loaf", "quantity": 2, "unit_price_cents": 650, "line_total_cents": 1300 }, { "product_id": "prod_01JB8M4W", "name": "Butter croissant", "quantity": 4, "unit_price_cents": 375, "line_total_cents": 1500 } ], "subtotal_cents": 2800, "tax_cents": 224, "total_cents": 3024, "currency": "usd", "note": "Pick-up at 8:30, please slice the loaves.", "created_at": "2026-11-09T09:41:12Z", "updated_at": "2026-11-09T09:41:30Z" } ], "page": { "next_cursor": null, "has_more": false } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "post": { "operationId": "createOrder", "tags": [ "Orders" ], "summary": "Create an order", "description": "Creates an order in the pending state and reserves stock. Always send an Idempotency-Key: a retry after a timeout then returns the first result instead of a second order.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "orders:write" ] }, { "OpenID": [ "orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "example": { "customer_id": "cus_01JB8K2P", "items": [ { "product_id": "prod_01JB8M3Q", "quantity": 2 }, { "product_id": "prod_01JB8M4W", "quantity": 4 } ], "note": "Pick-up at 8:30, please slice the loaves." } } } }, "responses": { "201": { "description": "The new order. Prices and tax are fixed by the server.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_01JB8N7R", "status": "pending", "customer_id": "cus_01JB8K2P", "items": [ { "product_id": "prod_01JB8M3Q", "name": "Sourdough loaf", "quantity": 2, "unit_price_cents": 650, "line_total_cents": 1300 }, { "product_id": "prod_01JB8M4W", "name": "Butter croissant", "quantity": 4, "unit_price_cents": 375, "line_total_cents": 1500 } ], "subtotal_cents": 2800, "tax_cents": 224, "total_cents": 3024, "currency": "usd", "note": "Pick-up at 8:30, please slice the loaves.", "created_at": "2026-11-09T09:41:12Z", "updated_at": "2026-11-09T09:41:12Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/orders/{order_id}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Retrieve an order", "description": "Returns one order by id.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "orders:read" ] }, { "OpenID": [ "orders:read" ] } ], "parameters": [ { "name": "order_id", "in": "path", "description": "Order id, prefix ord_.", "schema": { "type": "string" }, "required": true, "example": "ord_01JB8N7R" } ], "responses": { "200": { "description": "The order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_01JB8N7R", "status": "paid", "customer_id": "cus_01JB8K2P", "items": [ { "product_id": "prod_01JB8M3Q", "name": "Sourdough loaf", "quantity": 2, "unit_price_cents": 650, "line_total_cents": 1300 }, { "product_id": "prod_01JB8M4W", "name": "Butter croissant", "quantity": 4, "unit_price_cents": 375, "line_total_cents": 1500 } ], "subtotal_cents": 2800, "tax_cents": 224, "total_cents": 3024, "currency": "usd", "note": "Pick-up at 8:30, please slice the loaves.", "created_at": "2026-11-09T09:41:12Z", "updated_at": "2026-11-09T09:41:30Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/orders/{order_id}/cancel": { "post": { "operationId": "cancelOrder", "tags": [ "Orders" ], "summary": "Cancel an order", "description": "Cancels a pending or paid order and releases stock. A fulfilled order cannot be cancelled (409).", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "orders:write" ] }, { "OpenID": [ "orders:write" ] } ], "parameters": [ { "name": "order_id", "in": "path", "description": "Order id.", "schema": { "type": "string" }, "required": true, "example": "ord_01JB8N7R" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The cancelled order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_01JB8N7R", "status": "cancelled", "customer_id": "cus_01JB8K2P", "items": [ { "product_id": "prod_01JB8M3Q", "name": "Sourdough loaf", "quantity": 2, "unit_price_cents": 650, "line_total_cents": 1300 }, { "product_id": "prod_01JB8M4W", "name": "Butter croissant", "quantity": 4, "unit_price_cents": 375, "line_total_cents": 1500 } ], "subtotal_cents": 2800, "tax_cents": 224, "total_cents": 3024, "currency": "usd", "note": "Pick-up at 8:30, please slice the loaves.", "created_at": "2026-11-09T09:41:12Z", "updated_at": "2026-11-09T10:02:44Z" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhook endpoints" ], "summary": "List webhook endpoints", "description": "Returns your registered endpoints. The signing secret is never shown again.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "webhooks:manage" ] }, { "OpenID": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of endpoints.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "example": { "data": [ { "id": "whe_01JB8P1T", "url": "https://shop.example.com/hooks/orders", "events": [ "order.created", "order.paid" ], "status": "enabled", "created_at": "2026-11-01T12:00:00Z" } ], "page": { "next_cursor": null, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "429": { "$ref": "#/components/responses/Problem429" } } }, "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Create a webhook endpoint", "description": "Registers an HTTPS URL. The response includes signing_secret once; store it now.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "webhooks:manage" ] }, { "OpenID": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" }, "example": { "url": "https://shop.example.com/hooks/orders", "events": [ "order.created", "order.paid" ] } } } }, "responses": { "201": { "description": "The endpoint, with its signing secret.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "whe_01JB8P1T", "url": "https://shop.example.com/hooks/orders", "events": [ "order.created", "order.paid" ], "status": "enabled", "created_at": "2026-11-01T12:00:00Z", "signing_secret": "whsec_example_not_a_real_secret" } } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/webhook-endpoints/{endpoint_id}": { "delete": { "operationId": "deleteWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Delete a webhook endpoint", "description": "Stops deliveries to this endpoint. Events already queued are dropped.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "webhooks:manage" ] }, { "OpenID": [ "webhooks:manage" ] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "description": "Endpoint id, prefix whe_.", "schema": { "type": "string" }, "required": true, "example": "whe_01JB8P1T" } ], "responses": { "204": { "description": "Deleted. No body.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Problem401" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } } } }, "webhooks": { "orderEvent": { "post": { "operationId": "receiveEvent", "summary": "Event delivery (sent by the API to your endpoint)", "description": "POST with an Event body and a Sample-Signature header (t=,v1=.\">). Verify the signature on the raw body before parsing. Reply 2xx within 10 seconds; anything else is retried with exponential backoff for up to 24 hours.", "parameters": [ { "name": "Sample-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" }, "example": "t=1731144072,v1=40e9198e148b032bfc5d6a0c205e547d8dea4f51409377c6e8bd022efd3e9bc0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_01JB8Q9V", "type": "order.paid", "created_at": "2026-11-09T09:41:30Z", "data": { "object": { "id": "ord_01JB8N7R", "status": "paid", "total_cents": 3024, "currency": "usd" } } } } } }, "responses": { "2XX": { "description": "Event accepted. Body is ignored." }, "4XX": { "description": "Rejected. Will be retried unless 410 Gone." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Server-side key sent in a header. Never in a query string." }, "OAuth2": { "type": "oauth2", "description": "Client credentials. Access tokens last 900 seconds.", "flows": { "clientCredentials": { "tokenUrl": "https://auth.example.invalid/oauth/token", "scopes": { "products:read": "Read products.", "products:write": "Create, update and archive products.", "customers:read": "Read customers.", "customers:write": "Create and update customers.", "orders:read": "Read orders.", "orders:write": "Create and cancel orders.", "webhooks:manage": "Manage webhook endpoints." } } } }, "OpenID": { "type": "openIdConnect", "openIdConnectUrl": "https://auth.example.invalid/.well-known/openid-configuration", "description": "Bearer access token issued by an OpenID Connect provider (JWT). The API validates iss, aud, exp and scope." } }, "schemas": { "Timestamp": { "type": "string", "format": "date-time", "description": "UTC time, RFC 3339.", "examples": [ "2026-11-09T09:41:12Z" ] }, "PageInfo": { "type": "object", "required": [ "next_cursor", "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null on the last page." }, "has_more": { "type": "boolean", "description": "True when another page exists." } } }, "Product": { "type": "object", "required": [ "id", "sku", "name", "category", "price_cents", "currency", "in_stock", "stock_quantity", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Product id, prefix prod_." }, "sku": { "type": "string", "description": "Your stock-keeping unit. Unique." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": [ "string", "null" ], "description": "Optional text, up to 500 characters." }, "category": { "type": "string", "enum": [ "bread", "pastry", "cake", "drink" ], "description": "Product category." }, "price_cents": { "type": "integer", "minimum": 0, "description": "Unit price in the smallest currency unit." }, "currency": { "type": "string", "enum": [ "usd" ], "description": "ISO 4217 code, lower case." }, "in_stock": { "type": "boolean", "description": "False when stock_quantity is 0." }, "stock_quantity": { "type": "integer", "minimum": 0, "description": "Units on hand." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ProductCreate": { "type": "object", "required": [ "sku", "name", "category", "price_cents" ], "properties": { "sku": { "type": "string", "maxLength": 40, "description": "Unique SKU." }, "name": { "type": "string", "maxLength": 120, "description": "Display name." }, "description": { "type": "string", "maxLength": 500, "description": "Optional text." }, "category": { "type": "string", "enum": [ "bread", "pastry", "cake", "drink" ], "description": "Category." }, "price_cents": { "type": "integer", "minimum": 0, "description": "Unit price in cents." }, "stock_quantity": { "type": "integer", "minimum": 0, "default": 0, "description": "Initial stock." } } }, "ProductUpdate": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "maxLength": 120, "description": "New display name." }, "description": { "type": "string", "maxLength": 500, "description": "New text." }, "price_cents": { "type": "integer", "minimum": 0, "description": "New unit price in cents." }, "stock_quantity": { "type": "integer", "minimum": 0, "description": "Set the stock level." } } }, "Customer": { "type": "object", "required": [ "id", "name", "email", "marketing_opt_in", "created_at" ], "properties": { "id": { "type": "string", "description": "Customer id, prefix cus_." }, "name": { "type": "string", "description": "Full name." }, "email": { "type": "string", "format": "email", "description": "Unique per account." }, "marketing_opt_in": { "type": "boolean", "description": "True only after explicit consent." }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "CustomerCreate": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Full name." }, "email": { "type": "string", "format": "email", "description": "Unique per account." }, "marketing_opt_in": { "type": "boolean", "default": false, "description": "Consent flag." } } }, "CustomerUpdate": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "maxLength": 120, "description": "New name." }, "email": { "type": "string", "format": "email", "description": "New e-mail." }, "marketing_opt_in": { "type": "boolean", "description": "Consent flag." } } }, "OrderItem": { "type": "object", "required": [ "product_id", "name", "quantity", "unit_price_cents", "line_total_cents" ], "properties": { "product_id": { "type": "string", "description": "Product id." }, "name": { "type": "string", "description": "Name at the time of the order." }, "quantity": { "type": "integer", "minimum": 1, "description": "Units ordered." }, "unit_price_cents": { "type": "integer", "description": "Price at the time of the order." }, "line_total_cents": { "type": "integer", "description": "quantity x unit_price_cents." } } }, "Order": { "type": "object", "required": [ "id", "status", "customer_id", "items", "subtotal_cents", "tax_cents", "total_cents", "currency", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Order id, prefix ord_." }, "status": { "type": "string", "enum": [ "pending", "paid", "fulfilled", "cancelled" ], "description": "Lifecycle state." }, "customer_id": { "type": "string", "description": "Customer id." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "description": "Line items." }, "subtotal_cents": { "type": "integer", "description": "Sum of line totals." }, "tax_cents": { "type": "integer", "description": "Tax computed by the server." }, "total_cents": { "type": "integer", "description": "subtotal_cents + tax_cents." }, "currency": { "type": "string", "enum": [ "usd" ], "description": "Currency." }, "note": { "type": [ "string", "null" ], "description": "Free text from the customer." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "OrderCreate": { "type": "object", "required": [ "customer_id", "items" ], "properties": { "customer_id": { "type": "string", "description": "Existing customer id." }, "items": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Items as {product_id, quantity}.", "items": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "string", "description": "Product id." }, "quantity": { "type": "integer", "minimum": 1, "description": "Units." } } } }, "note": { "type": "string", "maxLength": 300, "description": "Optional note." } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "events", "status", "created_at" ], "properties": { "id": { "type": "string", "description": "Endpoint id, prefix whe_." }, "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives events." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Disabled after repeated delivery failures." }, "signing_secret": { "type": "string", "description": "Returned once, on creation only." }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "WebhookEndpointCreate": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS only." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Event types, see the webhooks section." } } }, "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable identifier of the problem kind. Branch on this." }, "title": { "type": "string", "description": "Short, human-readable summary." }, "status": { "type": "integer", "description": "HTTP status, repeated." }, "detail": { "type": "string", "description": "Explanation of this occurrence. Do not parse." }, "instance": { "type": "string", "description": "Path of the request." }, "request_id": { "type": "string", "description": "Quote this when you contact support." }, "errors": { "type": "array", "description": "Field errors, validation problems only.", "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "Event": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event id, prefix evt_. Use it to de-duplicate." }, "type": { "type": "string", "description": "Event type, for example order.paid." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "description": "The resource as it was when the event happened." } } } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Page size, 1 to 100. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "Cursor": { "name": "cursor", "in": "query", "description": "next_cursor from the previous page.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Unique string, up to 64 characters. UUID v4 recommended. See Idempotency.", "schema": { "type": "string", "maxLength": 64 }, "example": "6f1d3c0e-8d6a-4a57-9a0b-2f2c6e3b9d11" } }, "responses": { "Problem400": { "description": "Malformed request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/bad-request", "title": "Malformed request", "status": 400, "detail": "The request body is not valid JSON.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } }, "Problem401": { "description": "Invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/invalid-credentials", "title": "Invalid credentials", "status": 401, "detail": "The API key or access token is missing, expired or revoked.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } }, "Problem403": { "description": "Insufficient scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/insufficient-scope", "title": "Insufficient scope", "status": 403, "detail": "This credential does not include the orders:write scope.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } }, "Problem404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/not-found", "title": "Resource not found", "status": 404, "detail": "No order exists with the id ord_01JB8NXXXX.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } }, "Problem409": { "description": "Not enough stock.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/out-of-stock", "title": "Not enough stock", "status": 409, "detail": "Only 3 units of prod_01JB8M4W are available.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } }, "Problem422": { "description": "Validation failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/validation-failed", "title": "Validation failed", "status": 422, "detail": "One or more fields are invalid.", "instance": "/v1/orders", "request_id": "req_01JB8QX7", "errors": [ { "field": "items[0].quantity", "code": "min", "message": "Must be at least 1." } ] } } } }, "Problem429": { "description": "Too many requests.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.example.invalid/problems/rate-limited", "title": "Too many requests", "status": 429, "detail": "Rate limit exceeded. Retry after 12 seconds.", "instance": "/v1/orders", "request_id": "req_01JB8QX7" } } } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" }, "example": 600 }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" }, "example": 598 }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" }, "example": 41 } } } }