{ "openapi": "3.1.0", "info": { "title": "yRecurring API", "description": "The yRecurring API is a typed JSON REST API served at `https://app.yrecurring.com/v1`.\n\n## Authentication\n\nEvery request needs an API key, passed as a bearer token:\n\n Authorization: Bearer yr_...\n\nCreate and revoke keys on the dashboard's API keys page. The raw key is shown exactly once, at creation. Key management is dashboard-only and is never exposed over the API.\n\n## Scopes\n\nEvery key carries scopes that limit what it can do. A scope is an action — `read` or `write` (write implies read) — optionally narrowed to a resource as `\u003cresource\u003e:\u003caction\u003e`. So `invoices:read` can read only invoices, `customers:write` can create and update only customers, and a bare `read` grants read across every resource. A key with no scopes has full access. A request outside a key's scopes is rejected with `403`. Choose the narrowest scopes an integration needs.\n\n## Idempotency\n\nEvery mutating endpoint accepts an `Idempotency-Key` header. Retrying a request with the same key replays the original response (marked with the `Idempotent-Replayed: true` header) instead of re-executing, so network retries can never double-charge or double-create.\n\n## Errors\n\nErrors are RFC 7807 `application/problem+json` documents carrying an HTTP status, a human-readable `detail`, and a stable `type` URI (`https://yrecurring.com/problems/\u003cslug\u003e`) you can branch on in code instead of string-matching `detail`. Slugs include `not-found`, `validation-failed`, `already-exists`, `invalid-request`, `insufficient-scope`, `rate-limited`, and `plan-limit`. Some errors add structured fields — plan-limit denials include the feature, limit, and an upgrade URL; a blocked customer delete includes the blocking counts.\n\n## Pagination\n\nList endpoints accept `limit` and `offset` query parameters and return `{\"data\": [...], \"total\": n}`, where `total` counts all matching records.\n\n## Rate limits\n\nRequests are rate-limited per API key. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (seconds until the window refills). Over the limit, the API returns `429 Too Many Requests` with a `Retry-After` header — back off for that many seconds and retry. Read the headers rather than hard-coding a rate.\n\n## Custom fields \u0026 metadata\n\nMost resources carry two free-form JSON objects: `metadata` (yours to use, opaque to yRecurring) and `custom_fields` (typed fields defined per-org in the dashboard, validated on write).\n\n## Webhooks\n\nSubscribe an HTTPS endpoint to events and yRecurring POSTs a signed JSON envelope when a subscribed event occurs. Every delivery carries an `X-yRecurring-Signature` header — an HMAC-SHA256 over `\u003ctimestamp\u003e.\u003craw_body\u003e` — so you can verify it came from us before trusting the body. Return any 2xx to acknowledge; non-2xx responses and timeouts are retried with backoff over roughly three days, and any delivery can be replayed from the dashboard. The **Webhook Events** section below lists every event type and the exact payload we send; the Outbound webhooks guide walks through the signature scheme with a verification snippet.", "version": "v1" }, "servers": [ { "url": "https://app.yrecurring.com/v1" } ], "paths": { "/billing-runs": { "post": { "tags": [ "Billing Runs" ], "summary": "Run billing for the organization", "description": "Bills every subscription in the caller's organization that is due now: generates each invoice and advances its term, reporting per-subscription failures without aborting the run (the nightly scheduler calls the same operation). While another run holds the org's run lock, returns 409 — retry shortly.", "operationId": "runBilling", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkout_sessions": { "get": { "tags": [ "Checkouts" ], "summary": "List checkout sessions", "operationId": "listCheckoutSessions", "parameters": [ { "name": "checkout_id", "in": "query", "description": "Only sessions for this checkout page (UUID).", "schema": { "description": "Only sessions for this checkout page (UUID).", "type": "string" } }, { "name": "status", "in": "query", "description": "Only sessions in this state.", "schema": { "description": "Only sessions in this state.", "enum": [ "open", "completed", "expired" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum rows to return (default 50).", "schema": { "description": "Maximum rows to return (default 50).", "type": "integer" } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "description": "Rows to skip.", "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Checkouts" ], "summary": "Open a checkout session", "description": "Creates a single-use link to a checkout page for one buyer, with their details prefilled and your decisions pinned server-side. Use it to send a named buyer to a page that already knows them, to sell an upgrade to a customer who already exists (`customer_id`), to pin a term or seat count agreed off-page (`plan_price_id`, `plan_quantity`), or to attach your own `client_reference_id` so you can tie the resulting subscription back to your records.\n\n**The `url` contains a bearer credential.** Anyone holding that link can complete the checkout, so deliver it over a channel you trust. It stops working once the buyer completes it, or when it expires.", "operationId": "createCheckoutSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkout_sessions/{id}": { "get": { "tags": [ "Checkouts" ], "summary": "Retrieve a checkout session", "description": "Once a buyer has completed the session, the response carries `resulting_customer_id`, `resulting_subscription_id` and `resulting_invoice_id` — the reconciliation path back from your `client_reference_id` to what it produced.\n\n`link_activity` reports whether the session's URL has been opened (absent until the first open, and only on this single-session read). `views` counts page loads — a mail scanner's prefetch counts too — so treat it as \"the link was reached\", not \"the buyer read it\".", "operationId": "getCheckoutSession", "parameters": [ { "name": "id", "in": "path", "description": "Checkout session id (UUID).", "required": true, "schema": { "description": "Checkout session id (UUID).", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkout_sessions/{id}/expire": { "post": { "tags": [ "Checkouts" ], "summary": "Expire a checkout session", "description": "Revokes the link before its deadline. Fails with 409 if it has already been completed or expired.", "operationId": "expireCheckoutSession", "parameters": [ { "name": "id", "in": "path", "description": "Checkout session id (UUID).", "required": true, "schema": { "description": "Checkout session id (UUID).", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkouts": { "get": { "tags": [ "Checkouts" ], "summary": "List checkout pages", "operationId": "listCheckouts", "parameters": [ { "name": "status", "in": "query", "description": "Return only checkouts in this state.", "schema": { "description": "Return only checkouts in this state.", "enum": [ "draft", "active", "archived" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Checkouts" ], "summary": "Create a checkout page", "description": "Creates the page as a **draft**. A page that started taking payments the instant it was created would turn a mistyped price id into a live mispriced offer, so publish it explicitly with the activate endpoint. Omit `slug` to have a URL generated from the name, or supply one for a vanity link.", "operationId": "createCheckout", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkouts/{id}": { "get": { "tags": [ "Checkouts" ], "summary": "Retrieve a checkout page", "operationId": "getCheckout", "parameters": [ { "name": "id", "in": "path", "description": "Checkout id (UUID).", "required": true, "schema": { "description": "Checkout id (UUID).", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "tags": [ "Checkouts" ], "summary": "Replace a checkout page's configuration", "description": "REPLACES the configuration — the same semantics the dashboard form has — so a partial body clears what it omits. Send the full desired state. Updating a live page does not unpublish it.", "operationId": "updateCheckout", "parameters": [ { "name": "id", "in": "path", "description": "Checkout id (UUID).", "required": true, "schema": { "description": "Checkout id (UUID).", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCheckoutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkouts/{id}/activate": { "post": { "tags": [ "Checkouts" ], "summary": "Activate a checkout page", "description": "Takes the page live at its URL so it accepts signups.", "operationId": "activateCheckout", "parameters": [ { "name": "id", "in": "path", "description": "Checkout id (UUID).", "required": true, "schema": { "description": "Checkout id (UUID).", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/checkouts/{id}/archive": { "post": { "tags": [ "Checkouts" ], "summary": "Archive a checkout page", "description": "The page's URL stops accepting signups. Subscriptions already created through it are unaffected.", "operationId": "archiveCheckout", "parameters": [ { "name": "id", "in": "path", "description": "Checkout id (UUID).", "required": true, "schema": { "description": "Checkout id (UUID).", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/copilot/questions": { "post": { "tags": [ "Copilot" ], "summary": "Ask the copilot a question", "description": "Records the question and starts answering in the background. Returns 202 with the pending answer's id; poll the thread until the answer's status is `ok` or `failed`. One answered question counts once against the plan's monthly allowance, however many internal steps it takes; failed answers never count. An ask over the allowance is refused with 429 before anything is recorded (402 when the plan has no allowance at all).", "operationId": "askCopilot", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskCopilotRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskCopilotResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/copilot/threads": { "get": { "tags": [ "Copilot" ], "summary": "List copilot threads", "description": "Threads are private to the asking principal: a session user sees their own; an API key sees the threads it created.", "operationId": "listCopilotThreads", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotThreadResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/copilot/threads/{id}": { "get": { "tags": [ "Copilot" ], "summary": "Get a copilot thread with its messages", "description": "Answer messages carry a status (`pending`, `running`, `ok`, `failed`); an `ok` answer's content holds the narrative, sources, presentation data, and the tool transcript.", "operationId": "getCopilotThread", "parameters": [ { "name": "id", "in": "path", "description": "The thread id.", "required": true, "schema": { "description": "The thread id.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotConversationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons", "operationId": "listCoupons", "parameters": [ { "name": "status", "in": "query", "description": "Filter by admin-controlled lifecycle status.", "schema": { "description": "Filter by admin-controlled lifecycle status.", "enum": [ "active", "archived" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Coupons" ], "summary": "Create a coupon", "operationId": "createCoupon", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCouponRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/coupons/{id}": { "get": { "tags": [ "Coupons" ], "summary": "Retrieve a coupon", "operationId": "getCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Coupon id.", "required": true, "schema": { "description": "Coupon id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/coupons/{id}/archive": { "post": { "tags": [ "Coupons" ], "summary": "Archive a coupon", "description": "An archived coupon can no longer be applied to subscriptions; existing applications keep discounting. Archiving an already-archived coupon fails with 409.", "operationId": "archiveCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Coupon id.", "required": true, "schema": { "description": "Coupon id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/coupons/{id}/unarchive": { "post": { "tags": [ "Coupons" ], "summary": "Unarchive a coupon", "description": "Unarchiving a coupon that is not archived fails with 409.", "operationId": "unarchiveCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Coupon id.", "required": true, "schema": { "description": "Coupon id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit-notes": { "get": { "tags": [ "Credit Notes" ], "summary": "List credit notes", "operationId": "listCreditNotes", "parameters": [ { "name": "customer_id", "in": "query", "description": "Only credit notes for this customer.", "schema": { "description": "Only credit notes for this customer.", "format": "uuid", "type": "string" } }, { "name": "source_invoice_id", "in": "query", "description": "Only credit notes crediting this invoice.", "schema": { "description": "Only credit notes crediting this invoice.", "format": "uuid", "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "draft", "issued", "voided" ], "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by credit kind.", "schema": { "description": "Filter by credit kind.", "enum": [ "adjustment", "refundable", "promotional" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Credit Notes" ], "summary": "Create a credit note", "description": "Creates a draft credit note against a customer (optionally linked to a past invoice). The Service computes per-line and total amounts with calculation traces. Drafts carry no number or issued_at until issued.", "operationId": "createCreditNote", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCreditNoteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit-notes/{id}": { "get": { "tags": [ "Credit Notes" ], "summary": "Retrieve a credit note", "operationId": "getCreditNote", "parameters": [ { "name": "id", "in": "path", "description": "Credit note id.", "required": true, "schema": { "description": "Credit note id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit-notes/{id}/issue": { "post": { "tags": [ "Credit Notes" ], "summary": "Issue a credit note", "description": "Finalizes a draft: assigns its number and stamps issued_at, making the credit effective on the customer's balance. Only a draft can be issued; any other status returns 422.", "operationId": "issueCreditNote", "parameters": [ { "name": "id", "in": "path", "description": "Credit note id.", "required": true, "schema": { "description": "Credit note id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit-notes/{id}/void": { "post": { "tags": [ "Credit Notes" ], "summary": "Void a credit note", "description": "Voids an issued credit note, stamping voided_at and removing its effect from the customer's balance. Only an issued note can be voided; any other status returns 422.", "operationId": "voidCreditNote", "parameters": [ { "name": "id", "in": "path", "description": "Credit note id.", "required": true, "schema": { "description": "Credit note id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/custom/{module}": { "get": { "tags": [ "Custom Modules" ], "summary": "List records", "operationId": "listCustomRecords", "parameters": [ { "name": "q", "in": "query", "description": "Case-insensitive substring match on the record name.", "schema": { "description": "Case-insensitive substring match on the record name.", "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } }, { "name": "module", "in": "path", "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "required": true, "schema": { "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRecordResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Custom Modules" ], "summary": "Create a record", "description": "Creates a record in a custom module. Field values are validated against the module's field definitions. A key scoped `module:\u003capi_name\u003e` (or `module:*`) can only reach its module's records.", "operationId": "createCustomRecord", "parameters": [ { "name": "module", "in": "path", "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "required": true, "schema": { "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomRecordRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRecordResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/custom/{module}/{id}": { "get": { "tags": [ "Custom Modules" ], "summary": "Retrieve a record", "operationId": "getCustomRecord", "parameters": [ { "name": "module", "in": "path", "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "required": true, "schema": { "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "type": "string" } }, { "name": "id", "in": "path", "description": "Record id.", "required": true, "schema": { "description": "Record id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRecordResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Custom Modules" ], "summary": "Delete a record", "description": "The module's on-delete rules apply: a restrict reference vetoes the delete with a 409 naming the referrers.", "operationId": "deleteCustomRecord", "parameters": [ { "name": "module", "in": "path", "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "required": true, "schema": { "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "type": "string" } }, { "name": "id", "in": "path", "description": "Record id.", "required": true, "schema": { "description": "Record id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Custom Modules" ], "summary": "Update a record", "description": "Partial update: only provided fields change; a null or empty field value clears it.", "operationId": "updateCustomRecord", "parameters": [ { "name": "module", "in": "path", "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "required": true, "schema": { "description": "The module's api_name, e.g. \"projects\". Modules are defined per-organization in the dashboard (Settings → Modules); only active modules are served.", "type": "string" } }, { "name": "id", "in": "path", "description": "Record id.", "required": true, "schema": { "description": "Record id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomRecordRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRecordResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "operationId": "listCustomers", "parameters": [ { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "active", "archived" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "operationId": "createCustomer", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer", "operationId": "getCustomer", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "operationId": "updateCustomer", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/archive": { "post": { "tags": [ "Customers" ], "summary": "Archive a customer", "description": "Archiving hides the customer from active lists and blocks new subscriptions; existing state is preserved and the customer can be unarchived at any time.", "operationId": "archiveCustomer", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/balance": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer's balance", "description": "The customer's net account balance derived from the ledger: positive means the customer owes you, negative means they are in credit.", "operationId": "getCustomerBalance", "parameters": [ { "name": "currency", "in": "query", "description": "Three-letter ISO 4217 code to compute the balance in. Defaults to the customer's own currency.", "schema": { "description": "Three-letter ISO 4217 code to compute the balance in. Defaults to the customer's own currency.", "type": "string" } }, { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBalanceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/comments": { "get": { "tags": [ "Customers" ], "summary": "List a customer's comments", "operationId": "listCustomerComments", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } }, { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Add a comment to a customer", "operationId": "addCustomerComment", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCustomerCommentRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/comments/{commentId}": { "delete": { "tags": [ "Customers" ], "summary": "Delete a customer comment", "operationId": "deleteCustomerComment", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment id.", "required": true, "schema": { "description": "Comment id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/contacts": { "get": { "tags": [ "Customers" ], "summary": "List a customer's contacts", "operationId": "listCustomerContacts", "parameters": [ { "name": "include_removed", "in": "query", "description": "true includes soft-deleted (removed) contacts.", "schema": { "description": "true includes soft-deleted (removed) contacts.", "type": "boolean" } }, { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Add a contact to a customer", "operationId": "addCustomerContact", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContactRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/contacts/{contactId}": { "delete": { "tags": [ "Customers" ], "summary": "Remove a customer contact", "description": "A soft delete: the contact's status flips to removed and it drops out of default lists, but billing history referencing it stays resolvable. Returns the removed contact.", "operationId": "removeCustomerContact", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "contactId", "in": "path", "description": "Contact id.", "required": true, "schema": { "description": "Contact id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer contact", "operationId": "updateCustomerContact", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "contactId", "in": "path", "description": "Contact id.", "required": true, "schema": { "description": "Contact id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/hard-delete": { "post": { "tags": [ "Customers" ], "summary": "Permanently delete a customer", "description": "The exception to the soft-delete default. Refuses with 409 (and a `blocks` map of counts) while any subscription, invoice, or unbilled charge references the customer. Contacts and comments are cascaded; their counts are returned.", "operationId": "hardDeleteCustomer", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HardDeleteCustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/statement": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer's statement", "description": "The account statement for a time window: opening balance, every ledger entry (invoices, payments, credit notes, refunds, write-offs, adjustments) with a running balance, and the closing balance.", "operationId": "getCustomerStatement", "parameters": [ { "name": "currency", "in": "query", "description": "Three-letter ISO 4217 code to compute the statement in. Defaults to the customer's own currency.", "schema": { "description": "Three-letter ISO 4217 code to compute the statement in. Defaults to the customer's own currency.", "type": "string" } }, { "name": "from", "in": "query", "description": "Window start, RFC 3339 or YYYY-MM-DD. Omit to start at the beginning of history (opening balance 0).", "schema": { "description": "Window start, RFC 3339 or YYYY-MM-DD. Omit to start at the beginning of history (opening balance 0).", "type": "string" } }, { "name": "to", "in": "query", "description": "Window end, RFC 3339 or YYYY-MM-DD (a date-only value means through the end of that day). Defaults to now.", "schema": { "description": "Window end, RFC 3339 or YYYY-MM-DD (a date-only value means through the end of that day). Defaults to now.", "type": "string" } }, { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerStatementResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/unarchive": { "post": { "tags": [ "Customers" ], "summary": "Unarchive a customer", "operationId": "unarchiveCustomer", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/customers/{id}/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List a customer's wallets", "description": "Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "listCustomerWallets", "parameters": [ { "name": "id", "in": "path", "description": "Customer id.", "required": true, "schema": { "description": "Customer id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dunning_runs": { "get": { "tags": [ "Dunning" ], "summary": "List recovery campaigns", "description": "Every failed-payment recovery campaign in the organization, in-flight first. A campaign (run) tracks one invoice's automatic retries: its state, attempts made, and when the next retry fires.", "operationId": "listDunningRuns", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningRunResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dunning_runs/{id}": { "get": { "tags": [ "Dunning" ], "summary": "Retrieve a recovery campaign", "description": "One campaign with its full attempt history. Every attempt carries the decision that followed it — which rule scheduled the next retry (or parked/closed the run) and why. No retry is ever scheduled silently.", "operationId": "getDunningRun", "parameters": [ { "name": "id", "in": "path", "description": "Dunning run id.", "required": true, "schema": { "description": "Dunning run id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningRunDetailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dunning_runs/{id}/pause": { "post": { "tags": [ "Dunning" ], "summary": "Pause a campaign", "description": "Stops automated retries on an in-flight campaign until resumed. Paused campaigns are also excluded from card-saved instant recovery.", "operationId": "pauseDunningRun", "parameters": [ { "name": "id", "in": "path", "description": "Dunning run id.", "required": true, "schema": { "description": "Dunning run id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dunning_runs/{id}/resume": { "post": { "tags": [ "Dunning" ], "summary": "Resume a paused campaign", "description": "Re-activates a paused campaign and schedules an immediate retry.", "operationId": "resumeDunningRun", "parameters": [ { "name": "id", "in": "path", "description": "Dunning run id.", "required": true, "schema": { "description": "Dunning run id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dunning_runs/{id}/retry": { "post": { "tags": [ "Dunning" ], "summary": "Retry a campaign now", "description": "Re-arms an in-flight campaign for an immediate charge — the operator override for \"the customer says it's fixed\". Paused campaigns are untouched; resume them instead.", "operationId": "retryDunningRun", "parameters": [ { "name": "id", "in": "path", "description": "Dunning run id.", "required": true, "schema": { "description": "Dunning run id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/entitlements": { "get": { "tags": [ "Entitlements" ], "summary": "Retrieve your plan's entitlements", "description": "The authenticated organization's resolved entitlements on its yRecurring plan — what your plan with us unlocks. Read-only, so it stays reachable even when an expired trial blocks mutations. Always returns the full set.", "operationId": "getEntitlements", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/exports": { "get": { "tags": [ "Exports" ], "summary": "List exports", "description": "Returns the org's export runs, newest first.", "operationId": "listExports", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of runs to return (default 50).", "schema": { "description": "Maximum number of runs to return (default 50).", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRunResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/exports/{id}": { "get": { "tags": [ "Exports" ], "summary": "Retrieve an export", "operationId": "getExport", "parameters": [ { "name": "id", "in": "path", "description": "The export run id.", "required": true, "schema": { "description": "The export run id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRunResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/exports/{id}/download": { "get": { "tags": [ "Exports" ], "summary": "Download an export file", "description": "Streams a completed export's CSV (text/csv). 409 while the run is still pending or running; 410 once it has expired (past its 7-day retention).", "operationId": "downloadExport", "parameters": [ { "name": "id", "in": "path", "description": "The export run id.", "required": true, "schema": { "description": "The export run id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/features": { "get": { "tags": [ "Features" ], "summary": "List features", "operationId": "listFeatures", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Features" ], "summary": "Create a feature", "description": "Defines a feature in your organization's entitlement catalog. Attach it to plan products as a default and override it per subscription; your app gates on the feature's code.", "operationId": "createFeature", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeatureRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/features/{code}": { "get": { "tags": [ "Features" ], "summary": "Retrieve a feature", "operationId": "getFeature", "parameters": [ { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Features" ], "summary": "Archive a feature", "description": "Archives the feature: the code is freed for reuse and existing grants stop resolving.", "operationId": "archiveFeature", "parameters": [ { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Features" ], "summary": "Update a feature", "description": "Mutable fields only — code, kind, and value_type are immutable so existing grants keep their meaning.", "operationId": "updateFeature", "parameters": [ { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeatureRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "operationId": "listInvoices", "parameters": [ { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "draft", "pending", "open", "past_due", "paid", "voided", "written_off" ], "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Only invoices for this customer.", "schema": { "description": "Only invoices for this customer.", "format": "uuid", "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Create a draft invoice", "description": "Composes a manual invoice in `draft` status. Each line is either catalog (`price_id` set — the catalog price's calculator drives the amount) or ad-hoc (`description`, `quantity`, and `unit_amount_minor` supplied). Drafts carry no issued_at until finalized.", "operationId": "createDraftInvoice", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftInvoiceRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Retrieve an invoice", "operationId": "getInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/comments": { "get": { "tags": [ "Invoices" ], "summary": "List an invoice's comments", "operationId": "listInvoiceComments", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } }, { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentSharedResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Add a comment to an invoice", "operationId": "addInvoiceComment", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCommentRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentSharedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/comments/{commentId}": { "delete": { "tags": [ "Invoices" ], "summary": "Delete an invoice comment", "operationId": "deleteInvoiceComment", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment id.", "required": true, "schema": { "description": "Comment id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/custom-fields": { "patch": { "tags": [ "Invoices" ], "summary": "Update an invoice's custom fields", "description": "Partial update: only provided keys change; a null value clears the field. Returns the refreshed invoice.", "operationId": "updateInvoiceCustomFields", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomFieldsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/finalize": { "post": { "tags": [ "Invoices" ], "summary": "Finalize a draft invoice", "description": "Transitions a draft to `open`, stamping issued_at and the due date from the customer's net payment term. Only a draft can be finalized; any other status returns 409.", "operationId": "finalizeInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/pay": { "post": { "tags": [ "Invoices" ], "summary": "Record a payment on an invoice", "description": "Records money already received outside yRecurring (the offline, gateway-free path) against an `open`/`past_due` invoice. Partial payments leave the invoice open; covering the remaining balance flips it to `paid`. Overpayment is rejected with 422; an invoice that isn't payable returns 409.", "operationId": "payInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayInvoiceRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/rotate_link": { "post": { "tags": [ "Invoices" ], "summary": "Replace an invoice's public pay-page link", "description": "Mints a fresh hosted-page token and deletes the old link's view history: every previously shared URL stops working immediately, and the replacement starts with zero opens. Use when a pay link reached the wrong hands. The response's `hosted_link_url` is the only place the API surfaces the live link — send it to the customer if they still need to pay.", "operationId": "rotateInvoiceLink", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/void": { "post": { "tags": [ "Invoices" ], "summary": "Void an invoice", "description": "Retracts an invoice issued in error (`open`/`past_due` → `voided`). Terminal. Voiding doesn't refund money already collected — that's a credit note. An invalid transition returns 409.", "operationId": "voidInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceNoteBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/write-off": { "post": { "tags": [ "Invoices" ], "summary": "Write off an invoice", "description": "Marks an uncollectible invoice written off (`open`/`past_due` → `written_off`) — an accounting acknowledgement that the balance won't be collected, distinct from voiding an invoice issued in error. Terminal. An invalid transition returns 409.", "operationId": "writeOffInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice id.", "required": true, "schema": { "description": "Invoice id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceNoteBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/meters": { "get": { "tags": [ "Meters" ], "summary": "List meters", "operationId": "listMeters", "parameters": [ { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "active", "archived" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Meters" ], "summary": "Create a meter", "description": "Slug and aggregation are immutable after creation — changing either would silently re-interpret usage history already ingested against the meter.", "operationId": "createMeter", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMeterRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/meters/{id}": { "get": { "tags": [ "Meters" ], "summary": "Retrieve a meter", "operationId": "getMeter", "parameters": [ { "name": "id", "in": "path", "description": "Meter id.", "required": true, "schema": { "description": "Meter id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Meters" ], "summary": "Update a meter", "description": "Only the provided fields are changed. Slug and aggregation are immutable and cannot be patched.", "operationId": "updateMeter", "parameters": [ { "name": "id", "in": "path", "description": "Meter id.", "required": true, "schema": { "description": "Meter id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeterRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/meters/{id}/archive": { "post": { "tags": [ "Meters" ], "summary": "Archive a meter", "description": "An archived meter still accepts late-arriving usage, but new prices should not reference it. Idempotent — archiving an archived meter is a no-op.", "operationId": "archiveMeter", "parameters": [ { "name": "id", "in": "path", "description": "Meter id.", "required": true, "schema": { "description": "Meter id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/meters/{id}/unarchive": { "post": { "tags": [ "Meters" ], "summary": "Unarchive a meter", "operationId": "unarchiveMeter", "parameters": [ { "name": "id", "in": "path", "description": "Meter id.", "required": true, "schema": { "description": "Meter id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/payments/{id}/refund": { "post": { "tags": [ "Payments" ], "summary": "Refund a payment", "description": "Records money returned to the customer against a succeeded payment. Partial and multiple refunds are allowed up to the payment amount; the original invoice is not un-paid (the customer ledger nets the refund). Offline by default; `online: true` refunds through the gateway to the original payment method, and then REQUIRES the Idempotency-Key header (400 without it) so a retry can't double-refund. A payment that isn't refundable returns 409; a gateway decline returns 502 (the failed refund row is recorded).", "operationId": "refundPayment", "parameters": [ { "name": "id", "in": "path", "description": "Payment id.", "required": true, "schema": { "description": "Payment id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/portal_sessions": { "post": { "tags": [ "Customer Portal" ], "summary": "Create a portal session", "description": "Mints a single-use access_url that signs one of your customers into their self-serve billing portal. Optionally drop them into a single-purpose flow, return them to your app afterwards, or request an embeddable session for the popup widget. The session cookie is minted only when the access_url is opened; it never appears in this response. Requires the Grow plan or higher (402 otherwise); the hosted portal link is available on every plan.", "operationId": "createPortalSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePortalSessionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/portal_sessions/{id}": { "delete": { "tags": [ "Customer Portal" ], "summary": "Revoke a portal session", "description": "Ends a portal session server-side (logout). Idempotent: revoking an unknown or already-revoked session still returns 204.", "operationId": "revokePortalSession", "parameters": [ { "name": "id", "in": "path", "description": "The portal session id returned when it was created.", "required": true, "schema": { "description": "The portal session id returned when it was created.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prices": { "post": { "tags": [ "Prices" ], "summary": "Create a price", "operationId": "createPrice", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePriceRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prices/{id}": { "get": { "tags": [ "Prices" ], "summary": "Retrieve a price", "description": "If the price has been replaced by a newer version, superseded_by_price_id names it — so a client holding a grandfathered subscription's price id can discover the current price.", "operationId": "getPrice", "parameters": [ { "name": "id", "in": "path", "description": "Price id.", "required": true, "schema": { "description": "Price id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Prices" ], "summary": "Update a price", "description": "Only the display-ish fields (nickname, variant_label, is_taxable, trial_days, portal_eligible) are patchable. pricing_model, pricing_config, currency, and billing period are immutable — use replace to change them.", "operationId": "patchPrice", "parameters": [ { "name": "id", "in": "path", "description": "Price id.", "required": true, "schema": { "description": "Price id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePriceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prices/{id}/archive": { "post": { "tags": [ "Prices" ], "summary": "Archive a price", "description": "New subscriptions can no longer pick the price; existing subscribers stay pinned to it and keep billing it. Idempotent.", "operationId": "archivePrice", "parameters": [ { "name": "id", "in": "path", "description": "Price id.", "required": true, "schema": { "description": "Price id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prices/{id}/migrate": { "post": { "tags": [ "Prices" ], "summary": "Migrate subscribers to another price", "description": "Moves the grandfathered cohort pinned to this price ({id} is the source) onto to_price_id, one subscription item at a time — each move gets the same validation, proration, and audit trail as a hand-made price change. Per-item isolation: one failure never aborts the rest. With `\"dry_run\": true` it instead returns a preview (from_price_id, to_price_id, currency, count, upgrades, downgrades, unchanged, incompatible, immediate_net) without changing anything.", "operationId": "migratePrice", "parameters": [ { "name": "id", "in": "path", "description": "Price id.", "required": true, "schema": { "description": "Price id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigratePriceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigratePriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prices/{id}/replace": { "post": { "tags": [ "Prices" ], "summary": "Replace a price with a new version", "description": "Atomically creates a new price from the supplied spec (linked via supersedes_price_id) and archives this one so new subscriptions can't pick it. Existing subscribers are NOT moved — they stay pinned to the old price (grandfathered); use migrate to move them. Returns the new price.", "operationId": "replacePrice", "parameters": [ { "name": "id", "in": "path", "description": "Price id.", "required": true, "schema": { "description": "Price id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePriceRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pricing-units": { "get": { "tags": [ "Pricing Units" ], "summary": "List pricing units", "description": "Returns the org's full catalog (active first, then archived); not paginated.", "operationId": "listPricingUnits", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Pricing Units" ], "summary": "Create a pricing unit", "description": "A pricing unit is a unit of account a price can be denominated in (credits, tokens) for AI/usage billing where customers think in credits rather than dollars. code and decimals are immutable after creation.", "operationId": "createPricingUnit", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePricingUnitRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pricing-units/{id}": { "get": { "tags": [ "Pricing Units" ], "summary": "Retrieve a pricing unit", "operationId": "getPricingUnit", "parameters": [ { "name": "id", "in": "path", "description": "Pricing unit id.", "required": true, "schema": { "description": "Pricing unit id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Pricing Units" ], "summary": "Update a pricing unit", "description": "Only name and symbol are editable; code and decimals are immutable — they're load-bearing for amounts stored against the unit.", "operationId": "patchPricingUnit", "parameters": [ { "name": "id", "in": "path", "description": "Pricing unit id.", "required": true, "schema": { "description": "Pricing unit id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePricingUnitRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pricing-units/{id}/archive": { "post": { "tags": [ "Pricing Units" ], "summary": "Archive a pricing unit", "description": "An archived unit can't be attached to new prices; existing denominated prices keep billing (they snapshot the unit's precision).", "operationId": "archivePricingUnit", "parameters": [ { "name": "id", "in": "path", "description": "Pricing unit id.", "required": true, "schema": { "description": "Pricing unit id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pricing-units/{id}/unarchive": { "post": { "tags": [ "Pricing Units" ], "summary": "Unarchive a pricing unit", "operationId": "unarchivePricingUnit", "parameters": [ { "name": "id", "in": "path", "description": "Pricing unit id.", "required": true, "schema": { "description": "Pricing unit id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingUnitResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "operationId": "listProducts", "parameters": [ { "name": "kind", "in": "query", "description": "Filter by product kind.", "schema": { "description": "Filter by product kind.", "enum": [ "plan", "addon", "one_off" ], "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "active", "archived" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create a product", "operationId": "createProduct", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a product", "operationId": "getProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "description": "Only provided fields are changed. kind, is_metered, and external_id are immutable — they are set at creation.", "operationId": "patchProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/archive": { "post": { "tags": [ "Products" ], "summary": "Archive a product", "description": "Archiving hides the product from the active catalog so new subscriptions can't pick it; existing subscriptions keep billing it. Idempotent, and reversible via unarchive.", "operationId": "archiveProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/compatibility": { "get": { "tags": [ "Products" ], "summary": "List a product's compatibility rules", "description": "Returns the explicit allow-list for the product: compatible_addons for a plan, compatible_plans for an add-on. An empty list means permissive — every counterpart is allowed until the first rule is recorded.", "operationId": "listProductCompatibility", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Allow an add-on on a plan", "description": "Records that the add-on may attach to subscriptions on this plan ({id} is the plan-kind product). Idempotent — re-adding an existing pair succeeds without effect.", "operationId": "addProductCompatibility", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProductCompatibilityRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/compatibility/{addonId}": { "delete": { "tags": [ "Products" ], "summary": "Remove an add-on/plan compatibility rule", "description": "Idempotent — removing a pair that doesn't exist still returns 204.", "operationId": "removeProductCompatibility", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "addonId", "in": "path", "description": "Addon product id.", "required": true, "schema": { "description": "Addon product id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/entitlements": { "get": { "tags": [ "Entitlements" ], "summary": "List a product's entitlements", "description": "The plan defaults attached to the product — the feature values every subscription on this plan inherits unless overridden.", "operationId": "listProductEntitlements", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/entitlements/{code}": { "put": { "tags": [ "Entitlements" ], "summary": "Set a product entitlement", "description": "Sets (or replaces) a feature's plan-default value on the product. Send the value field matching the feature's kind: `enabled` for switch, `limit` or `unlimited` for limit/quota, `text` for enum.", "operationId": "putProductEntitlement", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutProductEntitlementRequest" } } } }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Entitlements" ], "summary": "Remove a product entitlement", "description": "Removes the feature's plan default from the product. A no-op when no default is attached.", "operationId": "deleteProductEntitlement", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/prices": { "get": { "tags": [ "Prices" ], "summary": "List a product's prices", "operationId": "listProductPrices", "parameters": [ { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "active", "archived" ], "type": "string" } }, { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products/{id}/unarchive": { "post": { "tags": [ "Products" ], "summary": "Unarchive a product", "operationId": "unarchiveProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product id.", "required": true, "schema": { "description": "Product id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports": { "get": { "tags": [ "Reports" ], "summary": "List reports", "description": "Returns the seeded report library plus the org's own custom reports.", "operationId": "listReports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Reports" ], "summary": "Create a custom report", "description": "Saves a report definition (a validated spec, never SQL). Gated by the plan's custom-report limit (402 when reached) and rejected with 422 if the spec is invalid or 409 if the name is taken.", "operationId": "createReport", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports/{id}": { "get": { "tags": [ "Reports" ], "summary": "Retrieve a report", "operationId": "getReport", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "tags": [ "Reports" ], "summary": "Update a custom report", "description": "Rewrites a custom report's name, description, category, and spec. System reports are read-only (404). 422 on an invalid spec, 409 on a name clash.", "operationId": "updateReport", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Reports" ], "summary": "Delete a custom report", "description": "Archives a custom report (soft-delete). System reports cannot be deleted (404).", "operationId": "deleteReport", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports/{id}/exports": { "post": { "tags": [ "Exports" ], "summary": "Export a report", "description": "Queues a CSV export of a report (system key or custom UUID) and returns the pending run. Poll the run until its status is completed, then fetch download_url. Unlike the dashboard, the API always queues (no inline streaming).", "operationId": "startReportExport", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports/{id}/run": { "post": { "tags": [ "Reports" ], "summary": "Run a report", "description": "Executes a report (system or custom) and returns its typed result: column metadata plus rows (money in integer minor units). Optionally overrides the date range, currency, or adds a filter for this run.", "operationId": "runReport", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReportRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports/{id}/schedules": { "post": { "tags": [ "Exports" ], "summary": "Schedule a report", "description": "Creates a recurring delivery of a report (system key or custom UUID) to org members. Gated by the plan's scheduled-exports feature (402); recipients must be org members (422).", "operationId": "createReportSchedule", "parameters": [ { "name": "id", "in": "path", "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "required": true, "schema": { "description": "The report id: a UUID for a custom report, or the key for a seeded report.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/schedules": { "get": { "tags": [ "Exports" ], "summary": "List schedules", "operationId": "listSchedules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/schedules/{id}": { "get": { "tags": [ "Exports" ], "summary": "Retrieve a schedule", "operationId": "getSchedule", "parameters": [ { "name": "id", "in": "path", "description": "The schedule id.", "required": true, "schema": { "description": "The schedule id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "tags": [ "Exports" ], "summary": "Update a schedule", "operationId": "updateSchedule", "parameters": [ { "name": "id", "in": "path", "description": "The schedule id.", "required": true, "schema": { "description": "The schedule id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Exports" ], "summary": "Delete a schedule", "operationId": "deleteSchedule", "parameters": [ { "name": "id", "in": "path", "description": "The schedule id.", "required": true, "schema": { "description": "The schedule id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions", "description": "Returns a page of subscriptions, newest first. List rows do not include items; retrieve a single subscription for its items.", "operationId": "listSubscriptions", "parameters": [ { "name": "customer_id", "in": "query", "description": "Only subscriptions belonging to this customer.", "schema": { "description": "Only subscriptions belonging to this customer.", "format": "uuid", "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by lifecycle status.", "schema": { "description": "Filter by lifecycle status.", "enum": [ "scheduled", "trialing", "active", "cancelling", "paused", "cancelled" ], "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Subscriptions" ], "summary": "Create a subscription", "description": "Creates a recurring subscription from catalog prices. Exactly one item must reference a plan price; add-ons ride along on the plan's cadence. Omitting `starts_at` starts (and bills) the subscription now; a future `starts_at` creates it in the `scheduled` state, and a plan with a trial starts it `trialing`.", "operationId": "createSubscription", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/preview": { "post": { "tags": [ "Subscriptions" ], "summary": "Preview a subscription create", "description": "Forecasts exactly what POST /subscriptions would produce for the same body — term boundaries, per-line amounts, MRR, and any immediate charge — without persisting anything. Same validation, same computation: what you preview is what you commit.", "operationId": "previewCreateSubscription", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePreviewResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Retrieve a subscription", "operationId": "getSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/activate": { "post": { "tags": [ "Subscriptions" ], "summary": "Activate a subscription", "description": "Moves a `scheduled` or `trialing` subscription to `active` without waiting for its start date or trial end.", "operationId": "activateSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/billing-day": { "post": { "tags": [ "Subscriptions" ], "summary": "Re-align a subscription's billing day", "description": "Moves an active monthly subscription's billing anchor to a new day-of-month. Requires calendar billing to be enabled for the org. In the default `next_renewal` mode the next renewal shapes the cycle onto the new day with no mid-cycle money movement; `immediate_prorated` re-cuts the current term now and prorates the difference.", "operationId": "setSubscriptionBillingDay", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSubscriptionBillingDayRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/cancel": { "post": { "tags": [ "Subscriptions" ], "summary": "Cancel a subscription", "description": "With `immediate: true`, settles what's owed and cancels now (terminal). Otherwise schedules the cancellation — the subscription moves to `cancelling` and keeps serving until `cancel_at` (default: the current term end). The body is optional; an empty body schedules a cancellation at the term end.", "operationId": "cancelSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/changes": { "post": { "tags": [ "Subscriptions" ], "summary": "Apply or schedule a subscription change", "description": "The unified change endpoint: one item change (`op`) plus a timing (`when`). `now` applies immediately; `end_of_term` queues the change at the current term end; `specific_date` queues it at `scheduled_for`. Omit `when` for the amount-based default — upgrades apply now, downgrades defer to end of term. The result carries the preview plus either the updated subscription (applied) or the queued scheduled change. With `?dry_run=true` the response is the preview alone.", "operationId": "changeSubscription", "parameters": [ { "name": "dry_run", "in": "query", "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "schema": { "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "type": "boolean" } }, { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSubscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeResultResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/comments": { "get": { "tags": [ "Subscriptions" ], "summary": "List a subscription's comments", "operationId": "listSubscriptionComments", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } }, { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentSharedResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Subscriptions" ], "summary": "Add a comment to a subscription", "operationId": "addSubscriptionComment", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCommentRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentSharedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/comments/{commentId}": { "delete": { "tags": [ "Subscriptions" ], "summary": "Delete a subscription comment", "operationId": "deleteSubscriptionComment", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment id.", "required": true, "schema": { "description": "Comment id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/coupon": { "get": { "tags": [ "Subscriptions" ], "summary": "Retrieve a subscription's active coupon", "description": "404 when the subscription has no active coupon application.", "operationId": "getActiveSubscriptionCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponApplicationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Subscriptions" ], "summary": "Apply a coupon to a subscription", "description": "Attaches a coupon and atomically consumes one redemption. A subscription holds at most one active coupon — applying while one is attached fails with 409. A coupon that is expired, exhausted, archived, over its per-customer cap, or in a different currency than the subscription fails with 422.", "operationId": "applySubscriptionCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplySubscriptionCouponRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponApplicationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "summary": "Remove the active coupon from a subscription", "description": "Marks the active coupon application as removed. The coupon's redemption count is not given back. 404 when the subscription has no active coupon.", "operationId": "removeSubscriptionCoupon", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponApplicationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/custom-fields": { "patch": { "tags": [ "Subscriptions" ], "summary": "Update a subscription's custom fields", "description": "Partial update: only provided keys change; a null value clears the field. Returns the refreshed subscription.", "operationId": "updateSubscriptionCustomFields", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomFieldsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/entitlements": { "get": { "tags": [ "Entitlements" ], "summary": "Retrieve a subscription's entitlements", "description": "The RESOLVED effective set for the subscription: its active plan's defaults overlaid with per-subscription overrides. This is the endpoint your app calls to gate features for one of your customers.", "operationId": "getSubscriptionEntitlements", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/entitlements/{code}": { "put": { "tags": [ "Entitlements" ], "summary": "Override a subscription entitlement", "description": "Overrides a feature for this subscription only, superseding the plan default. Send the value field matching the feature's kind: `enabled` for switch, `limit` or `unlimited` for limit/quota, `text` for enum.", "operationId": "putSubscriptionEntitlement", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSubscriptionEntitlementRequest" } } } }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Entitlements" ], "summary": "Reset a subscription entitlement", "description": "Drops the subscription's override so the feature resolves from the plan default again.", "operationId": "deleteSubscriptionEntitlement", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "code", "in": "path", "description": "Feature code.", "required": true, "schema": { "description": "Feature code.", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/invoices": { "post": { "tags": [ "Invoices" ], "summary": "Generate a subscription's invoice now", "description": "Builds an `open` invoice from the subscription's active items plus its pending unbilled charges, marking those charges invoiced. A subscription that isn't in a billable state, or has nothing to bill, returns 422.", "operationId": "generateInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/items": { "post": { "tags": [ "Subscriptions" ], "summary": "Add an item to a subscription", "description": "Adds a price to an active subscription mid-cycle. The remainder of the current term is prorated per the subscription's `proration_behavior`, landing as an unbilled charge on the next invoice. With `?dry_run=true` the response is the change preview instead.", "operationId": "addSubscriptionItem", "parameters": [ { "name": "dry_run", "in": "query", "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "schema": { "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "type": "boolean" } }, { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSubscriptionItemRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/items/{item_id}": { "delete": { "tags": [ "Subscriptions" ], "summary": "Remove a subscription item", "description": "Removes an item mid-cycle, crediting the unused remainder of the term per the subscription's `proration_behavior`. The last plan item cannot be removed — cancel the subscription instead. With `?dry_run=true` the response is the change preview instead. Returns the updated subscription.", "operationId": "removeSubscriptionItem", "parameters": [ { "name": "dry_run", "in": "query", "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "schema": { "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "type": "boolean" } }, { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "item_id", "in": "path", "description": "Subscription item id.", "required": true, "schema": { "description": "Subscription item id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Subscriptions" ], "summary": "Change a subscription item", "description": "Changes an item's quantity, or swaps its price when `price_id` is present (the swap must keep the same product kind). Applied immediately with proration per the subscription's `proration_behavior`. With `?dry_run=true` the response is the change preview instead.", "operationId": "changeSubscriptionItem", "parameters": [ { "name": "dry_run", "in": "query", "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "schema": { "description": "When true, previews the change — the prorated credit/charge and up/downgrade direction — without committing anything, and the response is the preview instead of the subscription.", "type": "boolean" } }, { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "item_id", "in": "path", "description": "Subscription item id.", "required": true, "schema": { "description": "Subscription item id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSubscriptionItemRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/next_renewal": { "get": { "tags": [ "Invoices" ], "summary": "Preview a subscription's next renewal", "description": "Forecasts the invoice the NEXT renewal will produce: recurring lines for the period after the current term ends, without pending unbilled charges (those settle on the current term's bill). Only `active` subscriptions are renewable; others return 422.", "operationId": "nextRenewal", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePreviewResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/pause": { "post": { "tags": [ "Subscriptions" ], "summary": "Pause a subscription", "description": "Suspends an active subscription (`active` → `paused`); no invoicing happens while paused. Pass `until` to schedule the automatic resume, or omit it (and the body) to pause indefinitely.", "operationId": "pauseSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseSubscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/po-number": { "post": { "tags": [ "Subscriptions" ], "summary": "Set a subscription's PO number", "description": "Updates the customer's procurement reference. Invoices snapshot the PO at generation time, so past invoices keep the prior value; only invoices generated from this point on carry the new one.", "operationId": "setSubscriptionPoNumber", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSubscriptionPoNumberRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/resume": { "post": { "tags": [ "Subscriptions" ], "summary": "Resume a paused subscription", "description": "Reactivates a paused subscription (`paused` → `active`). Under the org's default `slide` billing model the billing window slides forward past the pause so paused time is never billed; under the `invoice` model a resume past the old term re-anchors to a fresh term and bills it immediately.", "operationId": "resumeSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/scheduled_changes": { "get": { "tags": [ "Subscriptions" ], "summary": "List a subscription's scheduled changes", "description": "Every queued mid-cycle change for the subscription, in any status (pending, applied, cancelled, failed).", "operationId": "listScheduledChanges", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledChangeListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/scheduled_changes/{change_id}": { "delete": { "tags": [ "Subscriptions" ], "summary": "Cancel a scheduled change", "description": "Cancels a still-pending scheduled change so it never applies. Changes that already applied, failed, or were cancelled are refused with 409. Returns the cancelled change.", "operationId": "cancelScheduledChange", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "change_id", "in": "path", "description": "Scheduled change id.", "required": true, "schema": { "description": "Scheduled change id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledChangeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/unbilled_charges": { "get": { "tags": [ "Unbilled Charges" ], "summary": "List a subscription's unbilled charges", "description": "The subscription's queued charges (mid-cycle proration legs, etc.), newest first — pending charges land on the next invoice; settled and voided ones stay for the audit trail. Returns the complete set, unpaginated.", "operationId": "listSubscriptionUnbilledCharges", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnbilledChargeListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/uncancel": { "post": { "tags": [ "Subscriptions" ], "summary": "Uncancel a subscription", "description": "Reverses a scheduled cancellation, moving a `cancelling` subscription back to `active` and clearing the cancel timestamp, reason, and note. An already-cancelled subscription cannot be uncancelled.", "operationId": "uncancelSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/subscriptions/{id}/upcoming_invoice": { "get": { "tags": [ "Invoices" ], "summary": "Preview a subscription's upcoming invoice", "description": "Forecasts the invoice the current term's close would produce: recurring lines plus currently pending unbilled charges. Nothing is persisted.", "operationId": "upcomingInvoice", "parameters": [ { "name": "id", "in": "path", "description": "Subscription id.", "required": true, "schema": { "description": "Subscription id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePreviewResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/tax-rates": { "get": { "tags": [ "Tax Rates" ], "summary": "List tax rates", "operationId": "listTaxRates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Tax Rates" ], "summary": "Create a tax rate", "description": "Adds a manual tax rate for a (country, region). Invoice generation applies every active rate at the most specific scope matching the customer's billing address — several rates at one scope stack (GST + PST). A same-named active rate at the same country and region fails with 409.", "operationId": "createTaxRate", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxRateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/tax-rates/{id}/archive": { "post": { "tags": [ "Tax Rates" ], "summary": "Archive a tax rate", "description": "An archived rate stops applying to new invoices. Archiving an already-archived rate fails with 409.", "operationId": "archiveTaxRate", "parameters": [ { "name": "id", "in": "path", "description": "Tax rate id.", "required": true, "schema": { "description": "Tax rate id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/unbilled_charges/{id}/void": { "post": { "tags": [ "Unbilled Charges" ], "summary": "Void an unbilled charge", "description": "Cancels a still-pending charge before it's invoiced (e.g. a change was reverted). Only a pending charge can be voided; an already-invoiced or voided one returns 409.", "operationId": "voidUnbilledCharge", "parameters": [ { "name": "id", "in": "path", "description": "Unbilled charge id.", "required": true, "schema": { "description": "Unbilled charge id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidUnbilledChargeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnbilledChargeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/usage-records": { "post": { "tags": [ "Usage" ], "summary": "Record a usage event", "description": "Ingests one usage event against a metered subscription item. This endpoint does its own idempotency: `idempotency_key` (or the Idempotency-Key header) is a business key deduplicating the event per subscription item — a fresh write returns 201, a replay returns 200 with the original record and writes nothing. 404 when the subscription item does not exist; 422 when the item's price is not metered or occurred_at is missing or too far in the future.", "operationId": "recordUsage", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordUsageRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/usage-records/batch": { "post": { "tags": [ "Usage" ], "summary": "Record usage events in bulk", "description": "Ingests up to 1000 events in one call. Always returns 200 with a per-record results array in input order plus recorded/replayed/failed counts: each event succeeds or fails independently (its own idempotency key and dedup), and error results carry a stable machine-readable code. A structurally invalid batch (empty, or over the cap) fails whole with 422; a malformed record (bad UUID or amount) fails whole with 400.", "operationId": "recordUsageBatch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordUsageBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBatchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/usage-records/{id}": { "get": { "tags": [ "Usage" ], "summary": "Retrieve a usage record", "operationId": "getUsageRecord", "parameters": [ { "name": "id", "in": "path", "description": "Usage record id.", "required": true, "schema": { "description": "Usage record id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/wallets": { "post": { "tags": [ "Wallets" ], "summary": "Open a wallet", "description": "Opens a prepaid wallet for a customer, denominated in a currency (fiat) or a pricing unit. A customer may hold at most one active wallet per currency / per pricing unit — a duplicate fails with 409; an unknown customer fails with 404. Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "createWallet", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/wallets/{id}": { "get": { "tags": [ "Wallets" ], "summary": "Retrieve a wallet", "description": "Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "getWallet", "parameters": [ { "name": "id", "in": "path", "description": "Wallet id.", "required": true, "schema": { "description": "Wallet id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/wallets/{id}/archive": { "post": { "tags": [ "Wallets" ], "summary": "Archive a wallet", "description": "An archived wallet stops accepting transactions; the balance and history are kept. Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "archiveWallet", "parameters": [ { "name": "id", "in": "path", "description": "Wallet id.", "required": true, "schema": { "description": "Wallet id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/wallets/{id}/transactions": { "get": { "tags": [ "Wallets" ], "summary": "List a wallet's transactions", "description": "Returns a page of the wallet's ledger, newest first. Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "listWalletTransactions", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } }, { "name": "id", "in": "path", "description": "Wallet id.", "required": true, "schema": { "description": "Wallet id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTxListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Post a wallet transaction", "description": "Appends a signed entry to the wallet's ledger and updates the balance. This endpoint does its own idempotency: `idempotency_key` (or the Idempotency-Key header) deduplicates the entry per wallet — a fresh write returns 201, a replay returns 200 with the original transaction. A debit past the balance fails with 422 (insufficient balance), as does posting to an archived wallet. Requires the prepaid-wallets feature: the org's plan must include it (402 with an upgrade URL otherwise) and the org must have wallets enabled in Settings (403 otherwise).", "operationId": "postWalletTransaction", "parameters": [ { "name": "id", "in": "path", "description": "Wallet id.", "required": true, "schema": { "description": "Wallet id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostWalletTransactionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTxResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Registers an HTTPS endpoint and returns its signing secret ONCE. Persist the secret now — it is never retrievable again; rotate it if lost.", "operationId": "createWebhook", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "webhook_id", "in": "query", "description": "Filter to one endpoint.", "schema": { "description": "Filter to one endpoint.", "format": "uuid", "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by delivery status.", "schema": { "description": "Filter by delivery status.", "enum": [ "pending", "delivered", "failed", "gave_up" ], "type": "string" } }, { "name": "event_type", "in": "query", "description": "Filter by event type.", "schema": { "description": "Filter by event type.", "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Omit for the server default.", "schema": { "description": "Maximum number of records to return. Omit for the server default.", "minimum": 0, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of records to skip; use with limit to page through results.", "schema": { "description": "Number of records to skip; use with limit to page through results.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponseList" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/deliveries/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook delivery", "operationId": "getWebhookDelivery", "parameters": [ { "name": "id", "in": "path", "description": "Webhook delivery id.", "required": true, "schema": { "description": "Webhook delivery id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/deliveries/{id}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a webhook delivery", "description": "Re-delivers the event to its endpoint as a new delivery carrying the same Idempotency-Key. The original delivery is untouched. 409 if the endpoint was removed.", "operationId": "replayWebhookDelivery", "parameters": [ { "name": "id", "in": "path", "description": "Webhook delivery id.", "required": true, "schema": { "description": "Webhook delivery id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook endpoint", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "description": "Webhook endpoint id.", "required": true, "schema": { "description": "Webhook endpoint id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Removes the endpoint; its delivery history cascades. 204 on success.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "description": "Webhook endpoint id.", "required": true, "schema": { "description": "Webhook endpoint id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "description": "Webhook endpoint id.", "required": true, "schema": { "description": "Webhook endpoint id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/rotate_secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook's signing secret", "description": "Mints a new secret and returns it ONCE. The previous secret keeps verifying deliveries for a 24h grace window so in-flight deliveries aren't rejected mid-rotation.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "description": "Webhook endpoint id.", "required": true, "schema": { "description": "Webhook endpoint id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/send_test_event": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Fires a synthetic webhook.test event to this endpoint regardless of its subscriptions. Returns the queued delivery (202).", "operationId": "sendWebhookTestEvent", "parameters": [ { "name": "id", "in": "path", "description": "Webhook endpoint id.", "required": true, "schema": { "description": "Webhook endpoint id.", "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "schema": { "description": "A unique key (any string up to 255 chars, e.g. a UUID) making this request safe to retry: the first request executes, and replays with the same key return the original response with the Idempotent-Replayed header set. Replaying a key with a different request body fails with 422.", "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": { "coupon.archived": { "post": { "tags": [ "Webhook Events" ], "summary": "coupon.archived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `coupon.archived` (or `*`).", "operationId": "webhookEvent_coupon_archived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "coupon.created": { "post": { "tags": [ "Webhook Events" ], "summary": "coupon.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `coupon.created` (or `*`).", "operationId": "webhookEvent_coupon_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "coupon.redeemed": { "post": { "tags": [ "Webhook Events" ], "summary": "coupon.redeemed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `coupon.redeemed` (or `*`).", "operationId": "webhookEvent_coupon_redeemed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "coupon.unarchived": { "post": { "tags": [ "Webhook Events" ], "summary": "coupon.unarchived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `coupon.unarchived` (or `*`).", "operationId": "webhookEvent_coupon_unarchived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "coupon.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "coupon.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `coupon.updated` (or `*`).", "operationId": "webhookEvent_coupon_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "credit_note.created": { "post": { "tags": [ "Webhook Events" ], "summary": "credit_note.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `credit_note.created` (or `*`).", "operationId": "webhookEvent_credit_note_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "credit_note.voided": { "post": { "tags": [ "Webhook Events" ], "summary": "credit_note.voided", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `credit_note.voided` (or `*`).", "operationId": "webhookEvent_credit_note_voided", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_field.created": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_field.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_field.created` (or `*`).", "operationId": "webhookEvent_custom_field_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_field.deleted": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_field.deleted", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_field.deleted` (or `*`).", "operationId": "webhookEvent_custom_field_deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_field.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_field.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_field.updated` (or `*`).", "operationId": "webhookEvent_custom_field_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_record.created": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_record.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_record.created` (or `*`).", "operationId": "webhookEvent_custom_record_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_record.deleted": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_record.deleted", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_record.deleted` (or `*`).", "operationId": "webhookEvent_custom_record_deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "custom_record.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "custom_record.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `custom_record.updated` (or `*`).", "operationId": "webhookEvent_custom_record_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.archived": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.archived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.archived` (or `*`).", "operationId": "webhookEvent_customer_archived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.contact_added": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.contact_added", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.contact_added` (or `*`).", "operationId": "webhookEvent_customer_contact_added", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.contact_removed": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.contact_removed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.contact_removed` (or `*`).", "operationId": "webhookEvent_customer_contact_removed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.contact_updated": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.contact_updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.contact_updated` (or `*`).", "operationId": "webhookEvent_customer_contact_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.created": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.created` (or `*`).", "operationId": "webhookEvent_customer_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.hard_deleted": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.hard_deleted", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.hard_deleted` (or `*`).", "operationId": "webhookEvent_customer_hard_deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.unarchived": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.unarchived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.unarchived` (or `*`).", "operationId": "webhookEvent_customer_unarchived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "customer.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "customer.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `customer.updated` (or `*`).", "operationId": "webhookEvent_customer_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.awaiting_auth": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.awaiting_auth", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.awaiting_auth` (or `*`).", "operationId": "webhookEvent_dunning_awaiting_auth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.awaiting_card": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.awaiting_card", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.awaiting_card` (or `*`).", "operationId": "webhookEvent_dunning_awaiting_card", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.exhausted": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.exhausted", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.exhausted` (or `*`).", "operationId": "webhookEvent_dunning_exhausted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.paused": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.paused", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.paused` (or `*`).", "operationId": "webhookEvent_dunning_paused", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.recovered": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.recovered", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.recovered` (or `*`).", "operationId": "webhookEvent_dunning_recovered", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.resumed": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.resumed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.resumed` (or `*`).", "operationId": "webhookEvent_dunning_resumed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.retry_requested": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.retry_requested", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.retry_requested` (or `*`).", "operationId": "webhookEvent_dunning_retry_requested", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.retry_scheduled": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.retry_scheduled", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.retry_scheduled` (or `*`).", "operationId": "webhookEvent_dunning_retry_scheduled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "dunning.started": { "post": { "tags": [ "Webhook Events" ], "summary": "dunning.started", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `dunning.started` (or `*`).", "operationId": "webhookEvent_dunning_started", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "import.commit_failed": { "post": { "tags": [ "Webhook Events" ], "summary": "import.commit_failed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `import.commit_failed` (or `*`).", "operationId": "webhookEvent_import_commit_failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "import.committed": { "post": { "tags": [ "Webhook Events" ], "summary": "import.committed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `import.committed` (or `*`).", "operationId": "webhookEvent_import_committed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "import.dry_run": { "post": { "tags": [ "Webhook Events" ], "summary": "import.dry_run", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `import.dry_run` (or `*`).", "operationId": "webhookEvent_import_dry_run", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.created": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.created` (or `*`).", "operationId": "webhookEvent_invoice_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.credit_applied": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.credit_applied", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.credit_applied` (or `*`).", "operationId": "webhookEvent_invoice_credit_applied", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.finalized": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.finalized", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.finalized` (or `*`).", "operationId": "webhookEvent_invoice_finalized", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.paid": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.paid", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.paid` (or `*`).", "operationId": "webhookEvent_invoice_paid", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.payment_requested": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.payment_requested", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.payment_requested` (or `*`).", "operationId": "webhookEvent_invoice_payment_requested", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.updated` (or `*`).", "operationId": "webhookEvent_invoice_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.voided": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.voided", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.voided` (or `*`).", "operationId": "webhookEvent_invoice_voided", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "invoice.written_off": { "post": { "tags": [ "Webhook Events" ], "summary": "invoice.written_off", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `invoice.written_off` (or `*`).", "operationId": "webhookEvent_invoice_written_off", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.attempt_amount_mismatch": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.attempt_amount_mismatch", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.attempt_amount_mismatch` (or `*`).", "operationId": "webhookEvent_payment_attempt_amount_mismatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.attempt_failed": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.attempt_failed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.attempt_failed` (or `*`).", "operationId": "webhookEvent_payment_attempt_failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.attempt_recovered": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.attempt_recovered", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.attempt_recovered` (or `*`).", "operationId": "webhookEvent_payment_attempt_recovered", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.attempt_succeeded": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.attempt_succeeded", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.attempt_succeeded` (or `*`).", "operationId": "webhookEvent_payment_attempt_succeeded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.attempt_unbookable_charge": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.attempt_unbookable_charge", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.attempt_unbookable_charge` (or `*`).", "operationId": "webhookEvent_payment_attempt_unbookable_charge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.recorded": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.recorded", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.recorded` (or `*`).", "operationId": "webhookEvent_payment_recorded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment.refunded": { "post": { "tags": [ "Webhook Events" ], "summary": "payment.refunded", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment.refunded` (or `*`).", "operationId": "webhookEvent_payment_refunded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment_method.removed": { "post": { "tags": [ "Webhook Events" ], "summary": "payment_method.removed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment_method.removed` (or `*`).", "operationId": "webhookEvent_payment_method_removed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "payment_method.saved": { "post": { "tags": [ "Webhook Events" ], "summary": "payment_method.saved", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `payment_method.saved` (or `*`).", "operationId": "webhookEvent_payment_method_saved", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "price.archived": { "post": { "tags": [ "Webhook Events" ], "summary": "price.archived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `price.archived` (or `*`).", "operationId": "webhookEvent_price_archived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "price.created": { "post": { "tags": [ "Webhook Events" ], "summary": "price.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `price.created` (or `*`).", "operationId": "webhookEvent_price_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "price.superseded": { "post": { "tags": [ "Webhook Events" ], "summary": "price.superseded", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `price.superseded` (or `*`).", "operationId": "webhookEvent_price_superseded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "price.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "price.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `price.updated` (or `*`).", "operationId": "webhookEvent_price_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "product.archived": { "post": { "tags": [ "Webhook Events" ], "summary": "product.archived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `product.archived` (or `*`).", "operationId": "webhookEvent_product_archived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "product.created": { "post": { "tags": [ "Webhook Events" ], "summary": "product.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `product.created` (or `*`).", "operationId": "webhookEvent_product_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "product.unarchived": { "post": { "tags": [ "Webhook Events" ], "summary": "product.unarchived", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `product.unarchived` (or `*`).", "operationId": "webhookEvent_product_unarchived", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "product.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "product.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `product.updated` (or `*`).", "operationId": "webhookEvent_product_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.activated": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.activated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.activated` (or `*`).", "operationId": "webhookEvent_subscription_activated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.cancellation_scheduled": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.cancellation_scheduled", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.cancellation_scheduled` (or `*`).", "operationId": "webhookEvent_subscription_cancellation_scheduled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.cancelled": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.cancelled", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.cancelled` (or `*`).", "operationId": "webhookEvent_subscription_cancelled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.coupon_redeemed": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.coupon_redeemed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.coupon_redeemed` (or `*`).", "operationId": "webhookEvent_subscription_coupon_redeemed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.created": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.created", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.created` (or `*`).", "operationId": "webhookEvent_subscription_created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.paid": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.paid", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.paid` (or `*`).", "operationId": "webhookEvent_subscription_paid", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.paused": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.paused", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.paused` (or `*`).", "operationId": "webhookEvent_subscription_paused", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.resumed": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.resumed", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.resumed` (or `*`).", "operationId": "webhookEvent_subscription_resumed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.trial_ended": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.trial_ended", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.trial_ended` (or `*`).", "operationId": "webhookEvent_subscription_trial_ended", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.trial_started": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.trial_started", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.trial_started` (or `*`).", "operationId": "webhookEvent_subscription_trial_started", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } }, "subscription.updated": { "post": { "tags": [ "Webhook Events" ], "summary": "subscription.updated", "description": "Sent to your endpoint when this event occurs, if the endpoint subscribes to `subscription.updated` (or `*`).", "operationId": "webhookEvent_subscription_updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } } }, "components": { "schemas": { "AddCommentRequest": { "properties": { "body": { "description": "Comment text.", "type": "string" } }, "required": [ "body" ], "type": "object" }, "AddContactRequest": { "properties": { "email": { "description": "Contact's email address; validated and stored lower-cased.", "type": [ "null", "string" ] }, "first_name": { "description": "Contact's given name. At least one of first_name, last_name, or email is required.", "type": "string" }, "is_primary": { "description": "Marks this contact as the customer's canonical point of contact. At most one active primary per customer; promoting a new one auto-demotes the previous.", "type": "boolean" }, "last_name": { "description": "Contact's family name.", "type": "string" }, "phone": { "type": [ "null", "string" ] }, "role": { "description": "Free-text label (e.g. \"billing\", \"technical\", \"procurement\").", "type": "string" } }, "type": "object" }, "AddCustomerCommentRequest": { "properties": { "body": { "description": "Comment text.", "type": "string" } }, "required": [ "body" ], "type": "object" }, "AddProductCompatibilityRequest": { "properties": { "addon_product_id": { "description": "Id of the addon-kind product to allow alongside the plan.", "format": "uuid", "type": "string" } }, "required": [ "addon_product_id" ], "type": "object" }, "AddSubscriptionItemRequest": { "properties": { "price_id": { "description": "Catalog price to add; must be active and match the subscription's currency.", "format": "uuid", "type": "string" }, "quantity": { "description": "Units of the price. Omitted (or 0) defaults to 1.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "price_id" ], "type": "object" }, "ApplySubscriptionCouponRequest": { "properties": { "coupon_id": { "description": "Internal id (UUID) of the coupon to attach — not the customer-facing code.", "format": "uuid", "type": "string" } }, "required": [ "coupon_id" ], "type": "object" }, "AskCopilotRequest": { "properties": { "question": { "description": "The question, plain language, up to 500 characters.", "type": "string" }, "thread_id": { "description": "Continue an existing thread; omit to start a new one.", "type": "string" } }, "required": [ "question" ], "type": "object" }, "AskCopilotResponse": { "properties": { "answer_id": { "type": "string" }, "question_id": { "type": "string" }, "replayed": { "type": "boolean" }, "status": { "type": "string" }, "thread_id": { "type": "string" } }, "type": "object" }, "BillingRunError": { "properties": { "error": { "type": "string" }, "subscription_id": { "type": "string" } }, "type": "object" }, "BillingRunResponse": { "properties": { "as_of": { "type": "string" }, "due": { "type": "integer" }, "errors": { "items": { "$ref": "#/components/schemas/BillingRunError" }, "type": "array" }, "generated": { "type": "integer" }, "invoice_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "CancelSubscriptionRequest": { "properties": { "cancel_at": { "description": "When a scheduled cancellation takes effect. Must be in the future; defaults to the current term end. Ignored when immediate is true.", "format": "date-time", "type": [ "null", "string" ] }, "immediate": { "description": "true cancels now (settling what's owed first); false schedules the cancellation and keeps the subscription serving until it takes effect.", "type": "boolean" }, "note": { "description": "Free-form cancellation note.", "type": [ "null", "string" ] }, "reason": { "description": "Cancellation reason, stored on the subscription.", "type": [ "null", "string" ] } }, "type": "object" }, "CascadedCounts": { "properties": { "comments": { "format": "int64", "type": "integer" }, "contacts": { "format": "int64", "type": "integer" } }, "type": "object" }, "ChangeResultResponse": { "properties": { "effective_when": { "description": "The resolved timing (after the automatic upgrade-now / downgrade-at-term default).", "enum": [ "now", "end_of_term", "specific_date" ], "type": "string" }, "outcome": { "description": "Whether the change was applied immediately or queued as a scheduled change.", "enum": [ "applied", "scheduled" ], "type": "string" }, "preview": { "$ref": "#/components/schemas/PreviewResponse", "description": "The would-be effect the orchestrator computed before applying or scheduling." }, "scheduled_change": { "$ref": "#/components/schemas/ScheduledChangeResponse", "description": "The queued change; set when outcome is scheduled." }, "subscription": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The updated subscription; set when outcome is applied." } }, "type": "object" }, "ChangeSubscriptionItemRequest": { "properties": { "price_id": { "description": "New price to swap the item to; the swap must keep the same product kind (plan to plan, addon to addon).", "format": "uuid", "type": [ "null", "string" ] }, "quantity": { "description": "New quantity for the item. When price_id is also set, 0 (or omitted) keeps the current quantity.", "minimum": 0, "type": [ "null", "integer" ] } }, "type": "object" }, "ChangeSubscriptionRequest": { "properties": { "item_id": { "description": "Target subscription item. Required for update_quantity, change_price, and remove_item.", "format": "uuid", "type": [ "null", "string" ] }, "op": { "description": "The change to make.", "enum": [ "update_quantity", "change_price", "add_item", "remove_item" ], "type": "string" }, "price_id": { "description": "Catalog price involved. Required for change_price and add_item.", "format": "uuid", "type": [ "null", "string" ] }, "quantity": { "description": "Quantity for update_quantity / add_item; for change_price, 0 (or omitted) keeps the current quantity.", "minimum": 0, "type": [ "null", "integer" ] }, "scheduled_for": { "description": "Future instant the change applies at. Required when when is specific_date.", "format": "date-time", "type": [ "null", "string" ] }, "when": { "description": "When the change takes effect. Omit for the amount-based default: upgrades apply now, downgrades defer to end_of_term.", "enum": [ "now", "end_of_term", "specific_date" ], "type": "string" } }, "required": [ "op" ], "type": "object" }, "CheckoutAddonRequest": { "properties": { "default_qty": { "description": "Quantity the page opens with. 0 leaves the add-on unselected.", "minimum": 0, "type": "integer" }, "max_qty": { "description": "Largest quantity a buyer may choose. Omit for no cap.", "minimum": 1, "type": [ "null", "integer" ] }, "min_qty": { "description": "Smallest quantity a buyer may choose. Defaults to 1.", "minimum": 0, "type": "integer" }, "preselected": { "description": "Whether the add-on starts ticked.", "type": "boolean" }, "price_id": { "description": "Add-on price id (UUID). Must be an active add-on price in this organization, in the same currency as the plan.", "type": "string" } }, "required": [ "price_id" ], "type": "object" }, "CheckoutAddonResponse": { "properties": { "default_qty": { "type": "integer" }, "max_qty": { "type": [ "null", "integer" ] }, "min_qty": { "type": "integer" }, "preselected": { "type": "boolean" }, "price_id": { "type": "string" } }, "type": "object" }, "CheckoutCFResponse": { "properties": { "key": { "type": "string" }, "rule": { "type": "string" } }, "type": "object" }, "CheckoutCompletionRequest": { "properties": { "copy": { "additionalProperties": { "type": "string" }, "description": "Operator copy overrides: page_headline, page_subtitle, headline, thanks_message. Values may contain the merge tags {{ org_name }} and {{ plan_name }}.", "type": [ "object", "null" ] }, "mode": { "description": "Where buyers land after a successful signup: our branded thank-you page, or your success_url. Defaults to hosted.", "enum": [ "hosted", "redirect" ], "type": "string" }, "success_url": { "description": "Absolute http(s) URL to send buyers to. Required when mode is redirect. Only used for genuinely successful outcomes — a declined or pending order always lands on the hosted page.", "type": "string" } }, "type": "object" }, "CheckoutCompletionResp": { "properties": { "copy": { "additionalProperties": { "type": "string" }, "type": "object" }, "mode": { "type": "string" }, "success_url": { "type": "string" } }, "type": "object" }, "CheckoutOptionsRequest": { "properties": { "adjustable_quantity": { "$ref": "#/components/schemas/CheckoutQtyRequest", "description": "Buyer-adjustable plan quantity." }, "allow_coupon": { "description": "Show a coupon-code field.", "type": "boolean" }, "billing_address": { "description": "Whether to collect a billing address. Recommended for tax.", "enum": [ "", "optional", "required" ], "type": "string" }, "company": { "description": "Whether to collect a company name.", "enum": [ "", "optional", "required" ], "type": "string" }, "custom_fields": { "description": "Customer custom fields to ask on the page, by api_name, each optional or required.", "items": { "$ref": "#/components/schemas/CheckoutCFResponse" }, "type": [ "array", "null" ] }, "future_start_allowed": { "description": "Let buyers pick a later start date.", "type": "boolean" }, "payment": { "$ref": "#/components/schemas/CheckoutPayOptions", "description": "Per-checkout payment-method overrides." }, "phone": { "description": "Whether to collect a phone number, and whether it is mandatory. Omit or send \"\" to not collect it.", "enum": [ "", "optional", "required" ], "type": "string" }, "require_tos": { "description": "Require buyers to accept your terms before subscribing.", "type": "boolean" }, "shipping": { "description": "Whether to collect a shipping address.", "enum": [ "", "optional", "required" ], "type": "string" }, "tax_id": { "description": "Whether to collect the buyer's business tax identifier (VAT number, ABN, GSTIN). Required for EU B2B reverse charge: the number is format-checked at entry, then verified against the registry, and a confirmed number is zero-rated on later invoices.", "enum": [ "", "optional", "required" ], "type": "string" }, "tos_url": { "description": "Absolute http(s) link to your terms, shown beside the acceptance box.", "type": "string" } }, "type": "object" }, "CheckoutOptionsResponse": { "properties": { "adjustable_quantity": { "$ref": "#/components/schemas/CheckoutQtyResponse" }, "allow_coupon": { "type": "boolean" }, "billing_address": { "type": "string" }, "company": { "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/CheckoutCFResponse" }, "type": "array" }, "future_start_allowed": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/CheckoutPayOptionsRes" }, "phone": { "type": "string" }, "require_tos": { "type": "boolean" }, "shipping": { "type": "string" }, "tax_id": { "type": "string" }, "tos_url": { "type": "string" } }, "type": "object" }, "CheckoutPayOptions": { "properties": { "hidden": { "description": "Payment kinds this checkout does not offer (card, wallet, bank_debit).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "order": { "description": "Preferred display order of payment kinds; unlisted kinds follow in the default order.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "show_offline": { "description": "Force your offline payment instructions on (true) or off (false). Omit for automatic — shown only when no gateway applies.", "type": [ "null", "boolean" ] } }, "type": "object" }, "CheckoutPayOptionsRes": { "properties": { "hidden": { "items": { "type": "string" }, "type": "array" }, "order": { "items": { "type": "string" }, "type": "array" }, "show_offline": { "type": [ "null", "boolean" ] } }, "type": "object" }, "CheckoutQtyRequest": { "properties": { "enabled": { "description": "Show a quantity stepper beside the plan, so buyers choose how many (seats, licences, users). Only has an effect when the plan's price varies with quantity.", "type": "boolean" }, "max": { "description": "Largest quantity a buyer may choose. Defaults to 99; hard ceiling 999999.", "minimum": 0, "type": "integer" }, "min": { "description": "Smallest quantity a buyer may choose. Defaults to 1.", "minimum": 0, "type": "integer" } }, "type": "object" }, "CheckoutQtyResponse": { "properties": { "enabled": { "type": "boolean" }, "max": { "format": "int64", "type": "integer" }, "min": { "format": "int64", "type": "integer" } }, "type": "object" }, "CheckoutResponse": { "properties": { "addons": { "items": { "$ref": "#/components/schemas/CheckoutAddonResponse" }, "type": "array" }, "completion": { "$ref": "#/components/schemas/CheckoutCompletionResp" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "name": { "type": "string" }, "options": { "$ref": "#/components/schemas/CheckoutOptionsResponse" }, "price_choice": { "items": { "type": "string" }, "type": "array" }, "price_id": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "CheckoutResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CheckoutResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CheckoutSessionLinkActivity": { "properties": { "first_opened_at": { "format": "date-time", "type": "string" }, "last_opened_at": { "format": "date-time", "type": "string" }, "views": { "format": "int64", "type": "integer" } }, "type": "object" }, "CheckoutSessionPrefill": { "properties": { "company": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "CheckoutSessionResponse": { "properties": { "checkout_id": { "type": "string" }, "client_reference_id": { "type": "string" }, "completed_at": { "format": "date-time", "type": [ "null", "string" ] }, "created_at": { "format": "date-time", "type": "string" }, "customer_id": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "link_activity": { "$ref": "#/components/schemas/CheckoutSessionLinkActivity" }, "metadata": { "additionalProperties": {}, "type": "object" }, "plan_price_id": { "type": "string" }, "plan_quantity": { "type": [ "null", "integer" ] }, "prefill": { "$ref": "#/components/schemas/CheckoutSessionPrefill" }, "resulting_customer_id": { "type": "string" }, "resulting_invoice_id": { "type": "string" }, "resulting_subscription_id": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "CheckoutSessionResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CheckoutSessionResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CommentResponse": { "properties": { "actor_id": { "type": [ "null", "string" ] }, "actor_type": { "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "customer_id": { "type": "string" }, "id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "CommentResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CommentResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CommentSharedResponse": { "properties": { "actor_id": { "type": [ "null", "string" ] }, "actor_type": { "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "target_id": { "type": "string" }, "target_type": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "CommentSharedResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CommentSharedResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CompatibilityResponse": { "properties": { "addon_product_id": { "type": "string" }, "compatible_addons": { "items": { "type": "string" }, "type": "array" }, "compatible_plans": { "items": { "type": "string" }, "type": "array" }, "plan_product_id": { "type": "string" } }, "type": "object" }, "ContactListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ContactResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "ContactResponse": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "customer_id": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "first_name": { "type": "string" }, "id": { "type": "string" }, "is_primary": { "type": "boolean" }, "last_name": { "type": "string" }, "phone": { "type": [ "null", "string" ] }, "role": { "type": "string" }, "status": { "description": "Lifecycle status; removal is a soft delete.", "enum": [ "active", "removed" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "CopilotConversationResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/CopilotMessageResponse" }, "type": [ "array", "null" ] }, "thread": { "$ref": "#/components/schemas/CopilotThreadResponse" } }, "type": "object" }, "CopilotMessageResponse": { "properties": { "content": {}, "created_at": { "format": "date-time", "type": "string" }, "error_kind": { "type": "string" }, "id": { "type": "string" }, "progress": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "CopilotThreadResponse": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "last_active_at": { "format": "date-time", "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "CopilotThreadResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CopilotThreadResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CouponApplicationResponse": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "coupon_id": { "type": "string" }, "expires_at": { "format": "date-time", "type": [ "null", "string" ] }, "id": { "type": "string" }, "redemptions_used": { "type": "integer" }, "removed_at": { "format": "date-time", "type": [ "null", "string" ] }, "status": { "type": "string" }, "subscription_id": { "type": "string" } }, "type": "object" }, "CouponResponse": { "properties": { "applicable_product_ids": { "items": { "type": "string" }, "type": "array" }, "apply_on": { "type": "string" }, "coupon_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "discount_type": { "type": "string" }, "duration_count": { "type": "integer" }, "duration_type": { "type": "string" }, "duration_unit": { "type": "string" }, "effective_status": { "type": "string" }, "id": { "type": "string" }, "invoice_name": { "type": "string" }, "max_redemptions": { "type": [ "null", "integer" ] }, "max_redemptions_per_customer": { "type": [ "null", "integer" ] }, "name": { "type": "string" }, "redemptions_count": { "type": "integer" }, "status": { "type": "string" }, "valid_from": { "format": "date-time", "type": [ "null", "string" ] }, "valid_till": { "format": "date-time", "type": [ "null", "string" ] }, "value": { "format": "int64", "type": "integer" } }, "type": "object" }, "CouponResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CouponResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CreateCheckoutRequest": { "properties": { "addons": { "description": "Optional extras a buyer may add during signup.", "items": { "$ref": "#/components/schemas/CheckoutAddonRequest" }, "type": [ "array", "null" ] }, "completion": { "$ref": "#/components/schemas/CheckoutCompletionRequest", "description": "What happens after a successful signup." }, "metadata": { "additionalProperties": {}, "description": "Arbitrary key/value data stored with the checkout and returned on reads.", "type": [ "object", "null" ] }, "name": { "description": "Internal name for this checkout page.", "type": "string" }, "options": { "$ref": "#/components/schemas/CheckoutOptionsRequest", "description": "What the page collects and offers." }, "price_choice": { "description": "Alternative plan prices a buyer may pick instead (e.g. an annual term). All must share the plan's currency.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "price_id": { "description": "The plan price this page sells (UUID). Must be an active plan price in this organization.", "type": "string" }, "slug": { "description": "Custom URL slug for the public page. Lowercase letters, digits and dashes; anything else is collapsed to dashes. Omit it and one is generated from the name. A slug already in use is REJECTED rather than silently changed, because a caller that asked for a URL and got a different one would publish the wrong link.", "type": "string" } }, "required": [ "name", "price_id" ], "type": "object" }, "CreateCheckoutSessionRequest": { "properties": { "checkout_id": { "description": "The checkout page this session opens (UUID). Must be ACTIVE — a link to a draft or archived page would be a dead end handed to a buyer.", "type": "string" }, "client_reference_id": { "description": "Your own identifier for this signup (a user id, a quote number). Returned on reads so you can tie the resulting subscription back to your records.", "type": "string" }, "company": { "description": "Prefill the buyer's company name.", "type": "string" }, "customer_id": { "description": "Attach the signup to an EXISTING customer (UUID) instead of creating one — for upgrades and expansions. Their currency must match the plan's.", "type": "string" }, "email": { "description": "Prefill the buyer's email. They can change it; it is re-validated on submit.", "type": "string" }, "expires_in_seconds": { "description": "How long the link lives. Defaults to 86400 (24 hours); the maximum is 2592000 (30 days).", "minimum": 1, "type": "integer" }, "first_name": { "description": "Prefill the buyer's first name.", "type": "string" }, "last_name": { "description": "Prefill the buyer's last name.", "type": "string" }, "metadata": { "additionalProperties": {}, "description": "Arbitrary key/value data stored with the session and returned on reads.", "type": [ "object", "null" ] }, "phone": { "description": "Prefill the buyer's phone number.", "type": "string" }, "plan_price_id": { "description": "Pin which of the checkout's offered prices is billed (UUID). Must be a price this checkout offers. The buyer is not shown a chooser.", "type": "string" }, "plan_quantity": { "description": "Pin the quantity (seats, licences). Applied server-side and NOT subject to the page's buyer-facing range, so you can sell a figure agreed off-page.", "minimum": 1, "type": [ "null", "integer" ] } }, "required": [ "checkout_id" ], "type": "object" }, "CreateCouponRequest": { "properties": { "applicable_product_ids": { "description": "Product ids (UUIDs) the discount is scoped to. Required (non-empty) when apply_on is specific_items; must be omitted for invoice_amount.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "apply_on": { "description": "Whether the discount applies to the whole invoice subtotal or only to specific products' lines. Defaults to invoice_amount.", "enum": [ "invoice_amount", "specific_items" ], "type": "string" }, "coupon_id": { "description": "Customer-facing coupon code, unique per organization (e.g. \"WELCOME20\").", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code. Required when discount_type is fixed_amount; omit for percentage.", "type": "string" }, "discount_type": { "description": "How value is interpreted: a percentage of the discounted base, or a fixed amount in minor units.", "enum": [ "percentage", "fixed_amount" ], "type": "string" }, "duration_count": { "description": "Number of billing cycles the discount lasts. Required when duration_type is limited_period.", "minimum": 1, "type": "integer" }, "duration_type": { "description": "How long the discount applies once redeemed on a subscription.", "enum": [ "one_time", "forever", "limited_period" ], "type": "string" }, "duration_unit": { "description": "Unit of the limited period. Required when duration_type is limited_period.", "enum": [ "month", "year" ], "type": "string" }, "invoice_name": { "description": "Name printed on invoice lines; falls back to the coupon name when empty.", "type": "string" }, "max_redemptions": { "description": "Total redemption cap across all customers. Omit for unlimited.", "minimum": 1, "type": [ "null", "integer" ] }, "max_redemptions_per_customer": { "description": "Redemption cap per customer. Omit for unlimited.", "minimum": 1, "type": [ "null", "integer" ] }, "name": { "description": "Internal display name shown in the dashboard.", "type": "string" }, "valid_from": { "description": "Start of the redemption window; the coupon is not redeemable before this instant.", "format": "date-time", "type": [ "null", "string" ] }, "valid_till": { "description": "End of the redemption window; must be after valid_from when both are set.", "format": "date-time", "type": [ "null", "string" ] }, "value": { "description": "Percentage (1–100) for percentage coupons, or the amount in minor units for fixed_amount coupons.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "coupon_id", "name", "discount_type", "value", "duration_type" ], "type": "object" }, "CreateCreditNoteRequest": { "properties": { "currency": { "description": "Three-letter ISO 4217 code; must match the customer's currency. Omitted = the customer's currency.", "type": "string" }, "customer_id": { "description": "Customer the credit belongs to.", "format": "uuid", "type": "string" }, "external_id": { "description": "Your identifier for this credit note; unique per organization.", "type": [ "null", "string" ] }, "lines": { "description": "Lines being credited; at least one.", "items": { "$ref": "#/components/schemas/CreditNoteCreateLine" }, "type": [ "array", "null" ] }, "notes": { "description": "Operator-facing free-text notes.", "type": "string" }, "origin": { "description": "Provenance channel this note came from. Defaults to api.", "type": "string" }, "reason": { "description": "Why the credit exists.", "enum": [ "duplicate", "fraudulent", "order_change", "product_unsatisfactory", "write_off", "subscription_change", "goodwill", "other" ], "type": "string" }, "source_invoice_id": { "description": "Past invoice this note credits; must exist in the org and share the customer's currency. Omit for a standalone credit.", "format": "uuid", "type": [ "null", "string" ] }, "type": { "description": "Credit kind. Defaults to adjustment.", "enum": [ "adjustment", "refundable", "promotional" ], "type": "string" } }, "required": [ "customer_id", "reason", "lines" ], "type": "object" }, "CreateCustomRecordRequest": { "properties": { "fields": { "additionalProperties": {}, "description": "Values for the module's fields, keyed by field api_name; validated against the field definitions on write.", "type": [ "object", "null" ] }, "name": { "description": "The record's display name.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateCustomerRequest": { "properties": { "auto_collection": { "description": "Charge the stored payment method automatically when an invoice finalizes. Defaults to true.", "type": [ "null", "boolean" ] }, "billing_address": { "$ref": "#/components/schemas/CustomerAddress" }, "company": { "type": [ "null", "string" ] }, "consolidated_invoicing": { "description": "Consolidated invoicing mode; omit to inherit the organization default.", "type": [ "null", "string" ] }, "currency": { "description": "Three-letter ISO 4217 code (e.g. \"USD\"). All of the customer's subscriptions and invoices are denominated in this currency.", "type": "string" }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "display_name": { "description": "Name shown on invoices and in the dashboard.", "type": "string" }, "email": { "description": "Billing email; invoices and receipts are sent here.", "type": "string" }, "external_id": { "description": "Your identifier for this customer; unique per organization.", "type": [ "null", "string" ] }, "first_name": { "type": [ "null", "string" ] }, "invoice_note": { "description": "Note printed on every invoice for this customer.", "type": [ "null", "string" ] }, "is_tax_exempt": { "description": "When true, no tax is applied to this customer's invoices.", "type": "boolean" }, "last_name": { "type": [ "null", "string" ] }, "locale": { "description": "Locale used to format invoices (e.g. \"en-US\").", "type": "string" }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "net_terms_days": { "description": "Days until a finalized invoice is due. 0 means due on receipt.", "minimum": 0, "type": "integer" }, "phone": { "type": [ "null", "string" ] }, "price_type": { "description": "Whether catalog prices include tax for this customer. Defaults to tax_exclusive.", "enum": [ "tax_exclusive", "tax_inclusive" ], "type": "string" }, "shipping_address": { "$ref": "#/components/schemas/CustomerAddress" }, "tax_exemption_number": { "type": [ "null", "string" ] }, "tax_exemption_reason": { "type": [ "null", "string" ] }, "tax_id": { "description": "Tax/VAT identifier printed on invoices.", "type": [ "null", "string" ] }, "timezone": { "description": "IANA timezone (e.g. \"America/New_York\") used for billing-day math. Defaults to UTC.", "type": "string" } }, "required": [ "display_name", "email", "currency" ], "type": "object" }, "CreateDraftInvoiceRequest": { "properties": { "currency": { "description": "Three-letter ISO 4217 code (e.g. \"USD\"); must match the customer's currency.", "type": "string" }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "customer_id": { "description": "Customer to invoice.", "format": "uuid", "type": "string" }, "lines": { "description": "Invoice lines; at least one.", "items": { "$ref": "#/components/schemas/DraftInvoiceLine" }, "type": [ "array", "null" ] } }, "required": [ "customer_id", "currency", "lines" ], "type": "object" }, "CreateFeatureRequest": { "properties": { "code": { "description": "Stable, dot-namespaced key your app gates on (e.g. \"seats\", \"ai.copilot\"). Unique per organization; immutable after creation.", "type": "string" }, "config": { "$ref": "#/components/schemas/FeatureConfig", "description": "Kind-specific settings: options for enum-valued features, reset_period/reset_anchor for quotas." }, "description": { "type": "string" }, "kind": { "description": "How the feature is enforced: switch is on/off, limit caps concurrently-held resources, quota is a per-period allowance. Immutable after creation.", "enum": [ "switch", "limit", "quota" ], "type": "string" }, "name": { "description": "Human name shown in the dashboard.", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "CreateMeterRequest": { "properties": { "aggregation": { "description": "How per-period usage records roll up into a billable quantity. sum_amount sums the per-event amount (cost) instead of the quantity, for event-priced billing. Immutable after creation.", "enum": [ "sum", "count", "max", "last", "sum_amount" ], "type": "string" }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "name": { "description": "Human-readable label shown in the dashboard.", "type": "string" }, "slug": { "description": "Operator-facing machine id quoted in ingestion APIs: lowercase letters, digits, dashes, underscores, starting with a letter. Immutable after creation.", "type": "string" }, "unit_of_measure": { "description": "Display unit for quantities (e.g. \"requests\", \"GB\").", "type": [ "null", "string" ] } }, "required": [ "name", "slug", "aggregation" ], "type": "object" }, "CreatePortalSessionRequest": { "properties": { "customer_id": { "description": "The customer to sign in. Must be one of your own customers.", "type": "string" }, "embed": { "description": "Mint an embeddable session for the popup widget (door 3) rather than a full-page portal.", "type": "boolean" }, "flow": { "description": "Optional single-purpose flow to drop the customer directly into; omit for the full portal.", "enum": [ "pay_invoice", "update_payment_method", "cancel_subscription", "change_plan" ], "type": "string" }, "flow_target_id": { "description": "The id the flow acts on (e.g. the invoice for pay_invoice), when the flow needs one.", "type": "string" }, "return_url": { "description": "Where to send the customer after they finish, if you want them returned to your app.", "type": "string" } }, "required": [ "customer_id" ], "type": "object" }, "CreatePreviewLineResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "price_id": { "type": "string" }, "price_label": { "type": "string" }, "product_kind": { "type": "string" }, "quantity": { "format": "int64", "type": "integer" } }, "type": "object" }, "CreatePreviewResponse": { "properties": { "auto_collection": { "type": [ "null", "boolean" ] }, "billing_period_count": { "type": "integer" }, "billing_period_unit": { "type": "string" }, "coupon_label": { "type": "string" }, "currency": { "type": "string" }, "current_term_end": { "format": "date-time", "type": "string" }, "current_term_start": { "format": "date-time", "type": "string" }, "immediate_charge_minor": { "format": "int64", "type": "integer" }, "immediate_discount_minor": { "format": "int64", "type": "integer" }, "lines": { "items": { "$ref": "#/components/schemas/CreatePreviewLineResponse" }, "type": [ "array", "null" ] }, "mrr_minor": { "format": "int64", "type": "integer" }, "next_billing_at": { "format": "date-time", "type": "string" }, "po_number": { "type": [ "null", "string" ] }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "subtotal_minor": { "format": "int64", "type": "integer" }, "total_billing_cycles": { "type": [ "null", "integer" ] }, "trial_end": { "format": "date-time", "type": [ "null", "string" ] }, "trial_start": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "CreatePriceRequest": { "properties": { "billing_period_count": { "description": "Number of units per billing period (e.g. 3 with unit month bills quarterly).", "type": [ "null", "integer" ] }, "billing_period_unit": { "description": "Recurrence unit. Required for plan/addon prices; must be omitted for a one_off product's price.", "enum": [ "day", "week", "month", "year" ], "type": [ "null", "string" ] }, "billing_timing": { "description": "When in the period the charge bills. Defaults to in_advance; metered prices are always billed in_arrears.", "enum": [ "in_advance", "in_arrears" ], "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code (e.g. \"USD\").", "type": "string" }, "external_id": { "description": "Your identifier for this price; unique per organization.", "type": [ "null", "string" ] }, "included_quantity": { "description": "Quantity included before usage charges accrue.", "format": "int64", "type": "integer" }, "is_taxable": { "description": "Whether tax applies to this price's charges. Defaults to true.", "type": [ "null", "boolean" ] }, "meter_id": { "description": "Meter whose recorded usage rolls up into the billable quantity. Required when the product is metered; forbidden otherwise. Immutable after creation.", "format": "uuid", "type": [ "null", "string" ] }, "nickname": { "description": "Internal display name for this price (e.g. \"Pro monthly\").", "type": "string" }, "pricing_config": { "additionalProperties": {}, "description": "Model-specific configuration, amounts in minor units: unit_amount (and optional per_units) for flat/per_unit, package_size + flat_amount for package, percentage for percentage, a non-empty tiers array for tiered/volume/step, optional markup_pct for dynamic.", "type": [ "object", "null" ] }, "pricing_model": { "description": "How the price computes a charge; pricing_config is interpreted per model.", "enum": [ "flat", "per_unit", "tiered", "volume", "step", "package", "percentage", "dynamic" ], "type": "string" }, "product_id": { "description": "Id of the product this price belongs to.", "format": "uuid", "type": "string" }, "trial_days": { "description": "Free trial length in days before the first charge.", "type": "integer" }, "variant_label": { "description": "Label distinguishing this variant of the product (e.g. \"Monthly\", \"Annual\").", "type": [ "null", "string" ] } }, "required": [ "product_id", "nickname", "currency", "pricing_model" ], "type": "object" }, "CreatePricingUnitRequest": { "properties": { "code": { "description": "Stable machine id prices reference (lowercase letter, then lowercase letters/digits/dash/underscore). Normalized to lowercase. Immutable after creation.", "type": "string" }, "decimals": { "description": "The unit's precision (0-6). Immutable after creation — changing it would re-interpret stored amounts.", "maximum": 6, "minimum": 0, "type": "integer" }, "name": { "description": "Human label (e.g. \"Credits\").", "type": "string" }, "symbol": { "description": "Short display token used on invoices (max 8 characters, e.g. \"cr\"). Falls back to the code when empty.", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "CreateProductRequest": { "properties": { "category": { "description": "Free-form grouping label used to organize the catalog.", "type": [ "null", "string" ] }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "description": { "type": "string" }, "external_id": { "description": "Your identifier for this product; unique per organization.", "type": [ "null", "string" ] }, "external_name": { "description": "Customer-facing name on invoices and the portal. Defaults to name.", "type": "string" }, "is_giftable": { "description": "Whether this product can be gifted.", "type": "boolean" }, "is_metered": { "description": "When true, every price of this product bills from recorded usage events and must reference a meter. Immutable; a one_off product cannot be metered.", "type": "boolean" }, "kind": { "description": "How the product is sold: plan (the recurring subscription foundation), addon (a recurring add-on attached to a subscription), or one_off (a non-recurring charge). Immutable after creation.", "enum": [ "plan", "addon", "one_off" ], "type": "string" }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "name": { "description": "Internal name shown in the dashboard.", "type": "string" }, "tax_code": { "description": "Tax code applied to this product's charges.", "type": [ "null", "string" ] }, "unit_of_measure": { "description": "Label for what one unit represents (e.g. \"seat\", \"GB\").", "type": [ "null", "string" ] } }, "required": [ "kind", "name" ], "type": "object" }, "CreateReportRequest": { "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" }, "spec": { "$ref": "#/components/schemas/ReportReportSpec" } }, "required": [ "name", "spec" ], "type": "object" }, "CreateScheduleRequest": { "properties": { "cadence": { "description": "How often to deliver.", "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "format": { "description": "Export format; defaults to csv.", "enum": [ "csv" ], "type": "string" }, "hour": { "description": "Local hour (org timezone) to deliver at.", "maximum": 23, "minimum": 0, "type": "integer" }, "month_day": { "description": "Day of month for monthly cadence (clamped to month-end).", "maximum": 31, "minimum": 1, "type": "integer" }, "recipients": { "description": "Org-member email addresses to deliver to.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "weekday": { "description": "Day of week for weekly cadence (0=Sunday..6).", "maximum": 6, "minimum": 0, "type": "integer" } }, "required": [ "cadence", "recipients" ], "type": "object" }, "CreateSubscriptionItemRequest": { "properties": { "price_id": { "description": "Catalog price this line subscribes to.", "format": "uuid", "type": "string" }, "quantity": { "description": "Units of the price. Omitted (or \u003c= 0) defaults to 1.", "format": "int64", "type": "integer" } }, "required": [ "price_id" ], "type": "object" }, "CreateSubscriptionRequest": { "properties": { "auto_collection": { "description": "Per-subscription override of the customer's auto-collection setting. Omit to inherit.", "type": [ "null", "boolean" ] }, "billing_day": { "description": "Day-of-month (1-31) this subscription's billing aligns to, overriding the customer/org calendar policy. Requires calendar billing and a monthly plan. Omit to inherit the policy (or bill on the anniversary).", "maximum": 31, "minimum": 1, "type": [ "null", "integer" ] }, "collection_method": { "description": "How invoices are collected. Defaults to charge_automatically.", "enum": [ "charge_automatically", "send_invoice" ], "type": "string" }, "coupon_id": { "description": "Coupon to attach at creation. If it cannot be applied (not redeemable, currency mismatch, …) the whole create fails.", "format": "uuid", "type": [ "null", "string" ] }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "customer_id": { "description": "Customer the subscription bills.", "format": "uuid", "type": "string" }, "external_id": { "description": "Your identifier for this subscription; unique per organization.", "type": [ "null", "string" ] }, "items": { "description": "Subscription lines. Exactly one item must reference a plan price; add-ons must share the plan's currency.", "items": { "$ref": "#/components/schemas/CreateSubscriptionItemRequest" }, "type": [ "array", "null" ] }, "net_terms_days": { "description": "Days until a finalized invoice is due. 0 means due on receipt.", "minimum": 0, "type": "integer" }, "po_number": { "description": "Customer procurement reference; every invoice this subscription generates snapshots the value current at generation time.", "type": [ "null", "string" ] }, "proration_behavior": { "description": "How mid-cycle changes are prorated. Defaults to the organization's setting (create_prorations, or always_invoice when the org invoices upgrades immediately).", "enum": [ "create_prorations", "none", "always_invoice" ], "type": "string" }, "starts_at": { "description": "When the subscription starts. Omit to start now; a future instant creates it in the scheduled state. Must not be in the past (yRecurring is forward-effective only).", "format": "date-time", "type": [ "null", "string" ] }, "total_billing_cycles": { "description": "Cap on how many cycles the subscription bills before auto-cancelling. Omit to bill forever.", "minimum": 1, "type": [ "null", "integer" ] } }, "required": [ "customer_id", "items" ], "type": "object" }, "CreateTaxRateRequest": { "properties": { "country": { "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g. \"US\").", "type": "string" }, "effective_from": { "description": "When the rate starts applying (RFC 3339). Omit for immediately.", "format": "date-time", "type": [ "null", "string" ] }, "effective_to": { "description": "When the rate stops applying (RFC 3339). Omit for no end.", "format": "date-time", "type": [ "null", "string" ] }, "name": { "description": "Label shown on invoices (e.g. \"CA Sales Tax\").", "type": "string" }, "rate": { "description": "Percent as a decimal string between 0 and 100 (e.g. \"8.25\").", "type": "string" }, "region": { "description": "State/province/region code the rate is scoped to (e.g. \"CA\"). Omit for a country-wide rate.", "type": "string" } }, "required": [ "name", "country", "rate" ], "type": "object" }, "CreateWalletRequest": { "properties": { "currency": { "description": "Three-letter ISO 4217 code. Required for a fiat wallet; must be omitted for a unit wallet.", "type": "string" }, "customer_id": { "description": "The customer this wallet belongs to.", "format": "uuid", "type": "string" }, "denomination": { "description": "What the balance is counted in: fiat (a currency, account credit) or unit (a pricing unit — credits/tokens).", "enum": [ "fiat", "unit" ], "type": "string" }, "pricing_unit_id": { "description": "Pricing unit the balance is denominated in. Required for a unit wallet; must be omitted for a fiat wallet.", "format": "uuid", "type": "string" } }, "required": [ "customer_id", "denomination" ], "type": "object" }, "CreateWebhookRequest": { "properties": { "description": { "description": "Optional human label shown in the dashboard.", "type": "string" }, "event_types": { "description": "Event types to receive, or the single wildcard \"*\" for all. Each must be a name from the event catalog.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "is_active": { "description": "Whether the endpoint receives deliveries. Defaults to true.", "type": [ "null", "boolean" ] }, "url": { "description": "HTTPS endpoint the signed events are POSTed to. Plain http is allowed only for localhost.", "format": "uri", "type": "string" } }, "required": [ "url", "event_types" ], "type": "object" }, "CreditNoteCreateLine": { "properties": { "description": { "description": "Line description.", "type": "string" }, "quantity": { "description": "Units credited; must be positive.", "format": "int64", "minimum": 1, "type": "integer" }, "source_invoice_item_id": { "description": "Invoice line this credit line credits.", "format": "uuid", "type": [ "null", "string" ] }, "unit_amount_minor": { "description": "Per-unit amount in minor units (cents).", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "description", "quantity" ], "type": "object" }, "CreditNoteItemResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "description": { "type": "string" }, "id": { "type": "string" }, "quantity": { "format": "int64", "type": "integer" }, "source_invoice_item_id": { "type": [ "null", "string" ] }, "tax_minor": { "format": "int64", "type": "integer" }, "trace_id": { "type": [ "null", "string" ] }, "unit_amount_minor": { "format": "int64", "type": "integer" } }, "type": "object" }, "CreditNoteResponse": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_id": { "type": "string" }, "external_id": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "issued_at": { "format": "date-time", "type": [ "null", "string" ] }, "items": { "items": { "$ref": "#/components/schemas/CreditNoteItemResponse" }, "type": "array" }, "notes": { "type": "string" }, "number": { "type": "string" }, "origin": { "type": "string" }, "reason": { "type": "string" }, "source_invoice_id": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "subtotal_minor": { "format": "int64", "type": "integer" }, "tax_total_minor": { "format": "int64", "type": "integer" }, "total_minor": { "format": "int64", "type": "integer" }, "type": { "type": "string" }, "voided_at": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "CreditNoteResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CreditNoteResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CustomRecordResponse": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "id": { "type": "string" }, "module": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "CustomRecordResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CustomRecordResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CustomerAddress": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "state": { "type": "string" } }, "type": "object" }, "CustomerBalanceResponse": { "properties": { "balance_minor": { "description": "Net account balance in minor units. Positive = the customer owes you; negative = the customer is in credit.", "format": "int64", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 code the balance is computed in.", "type": "string" }, "customer_id": { "format": "uuid", "type": "string" } }, "type": "object" }, "CustomerResponse": { "properties": { "auto_collection": { "type": "boolean" }, "billing_address": { "$ref": "#/components/schemas/CustomerAddress" }, "company": { "type": [ "null", "string" ] }, "consolidated_invoicing": { "type": [ "null", "string" ] }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "display_name": { "type": "string" }, "email": { "type": "string" }, "external_id": { "type": [ "null", "string" ] }, "first_name": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "invoice_note": { "type": [ "null", "string" ] }, "is_tax_exempt": { "type": "boolean" }, "last_name": { "type": [ "null", "string" ] }, "locale": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": [ "object", "null" ] }, "net_terms_days": { "type": "integer" }, "origin": { "type": "string" }, "origin_detail": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "price_type": { "type": "string" }, "shipping_address": { "$ref": "#/components/schemas/CustomerAddress" }, "status": { "type": "string" }, "tax_exemption_number": { "type": [ "null", "string" ] }, "tax_exemption_reason": { "type": [ "null", "string" ] }, "tax_id": { "type": [ "null", "string" ] }, "tax_id_status": { "type": "string" }, "timezone": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "CustomerResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CustomerResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "CustomerStatementResponse": { "properties": { "closing_balance_minor": { "description": "Balance at the end of the window (minor units).", "format": "int64", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 code the statement is computed in.", "type": "string" }, "customer_id": { "format": "uuid", "type": "string" }, "entries": { "description": "Ledger lines inside the window, oldest first.", "items": { "$ref": "#/components/schemas/StatementEntryResponse" }, "type": [ "array", "null" ] }, "from": { "format": "date-time", "type": "string" }, "opening_balance_minor": { "description": "Balance carried into the window (minor units).", "format": "int64", "type": "integer" }, "to": { "format": "date-time", "type": "string" } }, "type": "object" }, "DeliveryResponse": { "properties": { "attempts": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "type": [ "null", "string" ] }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "is_replay": { "type": "boolean" }, "last_attempted_at": { "format": "date-time", "type": [ "null", "string" ] }, "last_error": { "type": "string" }, "last_response_status": { "type": [ "null", "integer" ] }, "max_attempts": { "type": "integer" }, "next_attempt_at": { "format": "date-time", "type": [ "null", "string" ] }, "status": { "type": "string" }, "webhook_id": { "type": "string" } }, "type": "object" }, "DeliveryResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DeliveryResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "DraftInvoiceLine": { "properties": { "description": { "description": "Line description. Required for ad-hoc lines; for catalog lines it defaults to the price's nickname.", "type": "string" }, "price_id": { "description": "Catalog price to bill (#41). When set, the price's calculator drives the amount and unit_amount_minor is ignored.", "format": "uuid", "type": [ "null", "string" ] }, "quantity": { "description": "Units billed; must be positive.", "format": "int64", "minimum": 1, "type": "integer" }, "unit_amount_minor": { "description": "Per-unit amount in minor units (cents). Required for ad-hoc lines; ignored for catalog lines.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "quantity" ], "type": "object" }, "DunningAttemptResponse": { "properties": { "attempt_no": { "type": "integer" }, "classification": { "type": "string" }, "decision": { "$ref": "#/components/schemas/DunningDecisionResponse" }, "error_code": { "type": "string" }, "next_attempt_at": { "format": "date-time", "type": [ "null", "string" ] }, "occurred_at": { "format": "date-time", "type": "string" }, "outcome": { "enum": [ "paid", "declined", "no_method", "requires_auth" ], "type": "string" }, "resulting_status": { "type": "string" } }, "type": "object" }, "DunningDecisionResponse": { "properties": { "classification": { "description": "Decline class the rule keyed on: soft, soft_funds, soft_transient, ambiguous, hard.", "type": "string" }, "detail": { "description": "Human-readable summary of the decision.", "type": "string" }, "gap_hours": { "description": "Wait applied before the next attempt.", "format": "double", "type": "number" }, "max_retries": { "type": "integer" }, "policy_step": { "description": "1-based retry ordinal consumed from the schedule.", "type": "integer" }, "rule": { "description": "Machine-readable rule id: policy_step, hard_decline_park, retry_hard_declines, no_method_park, requires_auth_park, schedule_exhausted, charge_succeeded, settled_out_of_band.", "type": "string" } }, "type": "object" }, "DunningRunDetailResponse": { "properties": { "attempts": { "items": { "$ref": "#/components/schemas/DunningAttemptResponse" }, "type": [ "array", "null" ] }, "attempts_made": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "customer_id": { "type": "string" }, "exhausted_at": { "format": "date-time", "type": [ "null", "string" ] }, "id": { "type": "string" }, "invoice_id": { "type": "string" }, "last_error_code": { "description": "The most recent gateway decline code.", "type": "string" }, "next_attempt_at": { "description": "When the next automatic retry fires; absent when parked or terminal.", "format": "date-time", "type": [ "null", "string" ] }, "recovered_at": { "format": "date-time", "type": [ "null", "string" ] }, "started_at": { "format": "date-time", "type": "string" }, "status": { "description": "Campaign lifecycle state.", "enum": [ "active", "awaiting_card", "awaiting_auth", "recovered", "exhausted", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "DunningRunResponse": { "properties": { "attempts_made": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "customer_id": { "type": "string" }, "exhausted_at": { "format": "date-time", "type": [ "null", "string" ] }, "id": { "type": "string" }, "invoice_id": { "type": "string" }, "last_error_code": { "description": "The most recent gateway decline code.", "type": "string" }, "next_attempt_at": { "description": "When the next automatic retry fires; absent when parked or terminal.", "format": "date-time", "type": [ "null", "string" ] }, "recovered_at": { "format": "date-time", "type": [ "null", "string" ] }, "started_at": { "format": "date-time", "type": "string" }, "status": { "description": "Campaign lifecycle state.", "enum": [ "active", "awaiting_card", "awaiting_auth", "recovered", "exhausted", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "DunningRunResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DunningRunResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "EntitlementEntry": { "properties": { "enabled": { "description": "Whether the feature is on. Present for switch features.", "type": [ "null", "boolean" ] }, "feature": { "description": "The feature code the value applies to.", "type": "string" }, "kind": { "description": "How the feature is enforced: switch is on/off, limit caps concurrently-held resources, quota is a per-period allowance.", "enum": [ "switch", "limit", "quota" ], "type": "string" }, "limit": { "description": "The cap or allowance. Present for limit/quota features unless unlimited.", "type": [ "null", "integer" ] }, "source": { "description": "Where the resolved value came from.", "enum": [ "plan", "override", "trial", "floor", "hq", "fallback" ], "type": "string" }, "unlimited": { "description": "true when a limit/quota feature has no cap.", "type": "boolean" } }, "type": "object" }, "EntitlementsResponse": { "properties": { "all_access": { "description": "true when everything is granted unconditionally.", "type": "boolean" }, "entitlements": { "description": "The full resolved set, sorted by feature code.", "items": { "$ref": "#/components/schemas/EntitlementEntry" }, "type": [ "array", "null" ] }, "plan": { "description": "Plan key the entitlements resolve from.", "type": "string" }, "trial": { "description": "true when the set is resolved from an active trial.", "type": "boolean" } }, "type": "object" }, "ExportRunResponse": { "properties": { "byte_size": { "format": "int64", "type": "integer" }, "completed_at": { "format": "date-time", "type": [ "null", "string" ] }, "created_at": { "format": "date-time", "type": "string" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "expires_at": { "format": "date-time", "type": [ "null", "string" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "report_id": { "type": "string" }, "report_key": { "type": "string" }, "row_count": { "format": "int64", "type": "integer" }, "started_at": { "format": "date-time", "type": [ "null", "string" ] }, "status": { "type": "string" } }, "type": "object" }, "ExportRunResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExportRunResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "FeatureConfig": { "properties": { "options": { "description": "Allowed values, for enum-valued features.", "items": { "type": "string" }, "type": "array" }, "reset_anchor": { "description": "What a quota's reset period aligns to.", "enum": [ "billing_anniversary", "calendar" ], "type": "string" }, "reset_period": { "description": "How often a quota's usage resets. Quota features only; omit for no reset.", "enum": [ "day", "week", "month", "year" ], "type": "string" } }, "type": "object" }, "FeatureListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FeatureResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "FeatureResponse": { "properties": { "code": { "description": "Stable, dot-namespaced key your app gates on (e.g. \"seats\", \"ai.copilot\").", "type": "string" }, "config": { "$ref": "#/components/schemas/FeatureConfig" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "kind": { "description": "How the feature is enforced: switch is on/off, limit caps concurrently-held resources, quota is a per-period allowance.", "enum": [ "switch", "limit", "quota" ], "type": "string" }, "name": { "type": "string" }, "value_type": { "description": "Storage type of the feature's value; derived from kind.", "enum": [ "bool", "int", "enum" ], "type": "string" } }, "type": "object" }, "FilterCondition": { "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": {} }, "type": "object" }, "FilterGroup": { "properties": { "conditions": { "items": { "$ref": "#/components/schemas/FilterCondition" }, "type": "array" }, "groups": { "items": { "$ref": "#/components/schemas/FilterSubGroup" }, "type": "array" }, "op": { "type": "string" } }, "type": "object" }, "FilterSubGroup": { "properties": { "conditions": { "items": { "$ref": "#/components/schemas/FilterCondition" }, "type": "array" }, "op": { "type": "string" } }, "type": "object" }, "HardDeleteCustomerResponse": { "properties": { "cascaded": { "$ref": "#/components/schemas/CascadedCounts", "description": "Dependent records wiped along with the customer." }, "deleted": { "$ref": "#/components/schemas/CustomerResponse", "description": "Final snapshot of the customer at the moment of deletion." } }, "type": "object" }, "InvoiceItemResponse": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "position": { "type": "integer" }, "price_id": { "type": [ "null", "string" ] }, "quantity": { "format": "int64", "type": "integer" }, "subtotal": { "format": "int64", "type": "integer" }, "tax_amount": { "format": "int64", "type": "integer" }, "taxable": { "type": "boolean" }, "total": { "format": "int64", "type": "integer" }, "trace_id": { "type": "string" } }, "type": "object" }, "InvoiceLinkResponse": { "properties": { "amount_paid": { "format": "int64", "type": "integer" }, "amount_remaining": { "format": "int64", "type": "integer" }, "billing_reason": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "customer_id": { "type": "string" }, "customer_note": { "type": [ "null", "string" ] }, "discount_total": { "format": "int64", "type": "integer" }, "discount_trace_id": { "type": [ "null", "string" ] }, "due_at": { "format": "date-time", "type": [ "null", "string" ] }, "hosted_link_url": { "type": "string" }, "id": { "type": "string" }, "issued_at": { "format": "date-time", "type": [ "null", "string" ] }, "items": { "items": { "$ref": "#/components/schemas/InvoiceItemResponse" }, "type": "array" }, "number": { "type": "string" }, "origin": { "type": "string" }, "origin_detail": { "type": [ "null", "string" ] }, "paid_at": { "format": "date-time", "type": [ "null", "string" ] }, "period_end": { "format": "date-time", "type": [ "null", "string" ] }, "period_start": { "format": "date-time", "type": [ "null", "string" ] }, "po_number": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "status_reason": { "type": "string" }, "subscription_id": { "type": [ "null", "string" ] }, "subtotal": { "format": "int64", "type": "integer" }, "tax_breakdown": { "items": { "$ref": "#/components/schemas/TaxationItemResponse" }, "type": "array" }, "tax_inclusive": { "type": "boolean" }, "tax_total": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" }, "untaxed_reason": { "type": "string" }, "voided_at": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "InvoiceNoteBody": { "properties": { "note": { "description": "Free-text reason recorded on the invoice's status_reason.", "type": "string" }, "reason": { "description": "Alias for note; used when note is empty.", "type": "string" } }, "type": "object" }, "InvoicePreviewLineResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "description": { "type": "string" }, "quantity": { "format": "int64", "type": "integer" }, "source": { "type": "string" }, "trace_id": { "type": [ "null", "string" ] } }, "type": "object" }, "InvoicePreviewResponse": { "properties": { "coupon_label": { "type": "string" }, "currency": { "type": "string" }, "discount_minor": { "format": "int64", "type": "integer" }, "lines": { "items": { "$ref": "#/components/schemas/InvoicePreviewLineResponse" }, "type": [ "array", "null" ] }, "next_billing_at": { "format": "date-time", "type": "string" }, "period_end": { "format": "date-time", "type": "string" }, "period_start": { "format": "date-time", "type": "string" }, "subtotal_minor": { "format": "int64", "type": "integer" }, "tax_minor": { "format": "int64", "type": "integer" }, "total_minor": { "format": "int64", "type": "integer" }, "untaxed_reason": { "type": "string" } }, "type": "object" }, "InvoiceResponse": { "properties": { "amount_paid": { "format": "int64", "type": "integer" }, "amount_remaining": { "format": "int64", "type": "integer" }, "billing_reason": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "customer_id": { "type": "string" }, "customer_note": { "type": [ "null", "string" ] }, "discount_total": { "format": "int64", "type": "integer" }, "discount_trace_id": { "type": [ "null", "string" ] }, "due_at": { "format": "date-time", "type": [ "null", "string" ] }, "id": { "type": "string" }, "issued_at": { "format": "date-time", "type": [ "null", "string" ] }, "items": { "items": { "$ref": "#/components/schemas/InvoiceItemResponse" }, "type": "array" }, "number": { "type": "string" }, "origin": { "type": "string" }, "origin_detail": { "type": [ "null", "string" ] }, "paid_at": { "format": "date-time", "type": [ "null", "string" ] }, "period_end": { "format": "date-time", "type": [ "null", "string" ] }, "period_start": { "format": "date-time", "type": [ "null", "string" ] }, "po_number": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "status_reason": { "type": "string" }, "subscription_id": { "type": [ "null", "string" ] }, "subtotal": { "format": "int64", "type": "integer" }, "tax_breakdown": { "items": { "$ref": "#/components/schemas/TaxationItemResponse" }, "type": "array" }, "tax_inclusive": { "type": "boolean" }, "tax_total": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" }, "untaxed_reason": { "type": "string" }, "voided_at": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "InvoiceResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/InvoiceResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "MeterResponse": { "properties": { "aggregation": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "id": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": [ "object", "null" ] }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "unit_of_measure": { "type": [ "null", "string" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "MeterResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MeterResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "MigratePriceRequest": { "properties": { "dry_run": { "description": "When true, returns a preview (cohort size, upgrade/downgrade breakdown, immediate net proration) without changing anything.", "type": "boolean" }, "to_price_id": { "description": "The active price to move the cohort onto.", "format": "uuid", "type": "string" }, "when": { "description": "When each moved item takes effect. Defaults to end_of_term — forward-effective at renewal, with no mid-cycle proration.", "enum": [ "now", "end_of_term" ], "type": "string" } }, "required": [ "to_price_id" ], "type": "object" }, "MigratePriceResponse": { "properties": { "applied": { "description": "Items moved immediately.", "type": "integer" }, "failed": { "description": "Items whose per-subscription change failed; the rest proceeded.", "type": "integer" }, "from_price_id": { "type": "string" }, "pending": { "description": "Cohort size found on the source price.", "type": "integer" }, "scheduled": { "description": "Items scheduled to move at end of term.", "type": "integer" }, "to_price_id": { "type": "string" }, "when": { "type": "string" } }, "type": "object" }, "PatchCustomFieldsRequest": { "properties": { "custom_fields": { "additionalProperties": {}, "description": "Partial update of the entity's org-defined custom fields: only provided keys change, and a null value clears the field. Values are validated against the field definitions.", "type": [ "object", "null" ] } }, "required": [ "custom_fields" ], "type": "object" }, "PauseSubscriptionRequest": { "properties": { "until": { "description": "When the pause should end. Omit or null to pause indefinitely (resume manually).", "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "PayInvoiceRequest": { "properties": { "amount_minor": { "description": "Amount received, in minor units (cents). Must be positive and at most the invoice's amount_remaining; a partial amount leaves the invoice open.", "format": "int64", "minimum": 1, "type": "integer" }, "method": { "description": "How the funds were tendered.", "enum": [ "cash", "cheque", "bank_transfer", "wire", "card", "ach", "sepa_debit", "bacs_debit", "other" ], "type": "string" }, "note": { "description": "Free-text note.", "type": "string" }, "received_at": { "description": "Value date the funds were received, RFC 3339 or YYYY-MM-DD. Omitted = now.", "type": "string" }, "reference": { "description": "Operator note, e.g. \"Cheque #1234\" or \"Wire ref 99\".", "type": "string" } }, "required": [ "amount_minor", "method" ], "type": "object" }, "PaymentResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "customer_id": { "type": "string" }, "fully_paid": { "type": "boolean" }, "id": { "type": "string" }, "invoice_amount_remaining": { "format": "int64", "type": "integer" }, "invoice_id": { "type": "string" }, "invoice_status": { "type": "string" }, "method": { "type": "string" }, "received_at": { "format": "date-time", "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "PortalSessionResponse": { "properties": { "access_url": { "type": "string" }, "embedded": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" } }, "type": "object" }, "PostWalletTransactionRequest": { "properties": { "amount_minor": { "description": "Amount in minor units of the wallet's denomination. Positive magnitude for every kind except adjustment, which is signed. Zero is rejected.", "format": "int64", "type": "integer" }, "idempotency_key": { "description": "Business key deduplicating this entry per wallet. Also read from the Idempotency-Key header when absent from the body. Replays return the original transaction with 200.", "type": "string" }, "kind": { "description": "What the entry represents. top_up/credit/refund add funds, debit/expiry remove funds (amount_minor is a positive magnitude for all five); adjustment is an operator correction with a signed amount.", "enum": [ "top_up", "credit", "refund", "debit", "expiry", "adjustment" ], "type": "string" }, "reason": { "description": "Free-text note recorded on the ledger entry.", "type": "string" } }, "required": [ "kind", "amount_minor" ], "type": "object" }, "PreviewResponse": { "properties": { "charge_minor": { "description": "Prorated charge for the new configuration (minor units, \u003e= 0).", "format": "int64", "type": "integer" }, "credit_minor": { "description": "Prorated credit for the unused old configuration (minor units, \u003c= 0).", "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "direction": { "description": "Amount-based direction of the change.", "enum": [ "upgrade", "downgrade", "none" ], "type": "string" }, "net_minor": { "description": "charge_minor + credit_minor.", "format": "int64", "type": "integer" }, "prorated": { "description": "false when proration_behavior is none or the amount is unchanged — no money moves now.", "type": "boolean" }, "recurring_after_minor": { "description": "The item's recurring per-period amount after the change (minor units).", "format": "int64", "type": "integer" }, "recurring_before_minor": { "description": "The item's recurring per-period amount before the change (minor units).", "format": "int64", "type": "integer" } }, "type": "object" }, "PriceResponse": { "properties": { "billing_period_count": { "type": [ "null", "integer" ] }, "billing_period_unit": { "type": [ "null", "string" ] }, "billing_timing": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "external_id": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "included_quantity": { "format": "int64", "type": "integer" }, "is_taxable": { "type": "boolean" }, "meter_id": { "type": [ "null", "string" ] }, "nickname": { "type": "string" }, "portal_eligible": { "type": "boolean" }, "pricing_config": { "additionalProperties": {}, "type": [ "object", "null" ] }, "pricing_model": { "type": "string" }, "product_id": { "type": "string" }, "status": { "type": "string" }, "superseded_by_price_id": { "type": [ "null", "string" ] }, "supersedes_price_id": { "type": [ "null", "string" ] }, "trial_days": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "variant_label": { "type": [ "null", "string" ] } }, "type": "object" }, "PriceResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PriceResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "PricingUnitResponse": { "properties": { "code": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "decimals": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "symbol": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "PricingUnitResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PricingUnitResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "Problem": { "properties": { "detail": { "type": "string" }, "instance": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "ProductEntitlementListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductEntitlementResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "ProductEntitlementResponse": { "properties": { "enabled": { "description": "Whether the feature is on. Present for switch features.", "type": [ "null", "boolean" ] }, "feature": { "description": "The feature code the default applies to.", "type": "string" }, "kind": { "description": "The feature's kind.", "enum": [ "switch", "limit", "quota" ], "type": "string" }, "limit": { "description": "The cap or allowance. Present for limit/quota features unless unlimited.", "type": [ "null", "integer" ] }, "text": { "description": "The selected option, for enum features.", "type": "string" }, "unlimited": { "description": "true when a limit/quota feature has no cap.", "type": "boolean" } }, "type": "object" }, "ProductResponse": { "properties": { "category": { "type": [ "null", "string" ] }, "created_at": { "format": "date-time", "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "description": { "type": "string" }, "external_id": { "type": [ "null", "string" ] }, "external_name": { "type": "string" }, "id": { "type": "string" }, "is_giftable": { "type": "boolean" }, "is_metered": { "type": "boolean" }, "kind": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": [ "object", "null" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "tax_code": { "type": [ "null", "string" ] }, "unit_of_measure": { "type": [ "null", "string" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "ProductResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "PutProductEntitlementRequest": { "properties": { "enabled": { "description": "Value for a switch feature: whether it is on.", "type": [ "null", "boolean" ] }, "limit": { "description": "Value for a limit/quota feature: the cap or per-period allowance. Must not be negative.", "minimum": 0, "type": [ "null", "integer" ] }, "text": { "description": "Value for an enum feature; must be one of the feature's configured options.", "type": "string" }, "unlimited": { "description": "true grants a limit/quota feature without a cap (limit is ignored).", "type": "boolean" } }, "type": "object" }, "PutSubscriptionEntitlementRequest": { "properties": { "enabled": { "description": "Value for a switch feature: whether it is on.", "type": [ "null", "boolean" ] }, "expires_at": { "description": "When the override lapses and the subscription falls back to the plan default. Must be in the future; omit for no expiry.", "format": "date-time", "type": [ "null", "string" ] }, "limit": { "description": "Value for a limit/quota feature: the cap or per-period allowance. Must not be negative.", "minimum": 0, "type": [ "null", "integer" ] }, "reason": { "description": "Why the override exists, recorded for auditability. Defaults to \"set via API\".", "type": "string" }, "text": { "description": "Value for an enum feature; must be one of the feature's configured options.", "type": "string" }, "unlimited": { "description": "true grants a limit/quota feature without a cap (limit is ignored).", "type": "boolean" } }, "type": "object" }, "RecordUsageBatchRequest": { "properties": { "records": { "description": "Up to 1000 events. Parsing is strict: one malformed record rejects the whole request with 400. Ingestion is per record: an event failing a business rule fails only itself.", "items": { "$ref": "#/components/schemas/UsageBatchRecordRequest" }, "type": [ "array", "null" ] } }, "required": [ "records" ], "type": "object" }, "RecordUsageRequest": { "properties": { "amount": { "description": "Caller-computed event cost in minor units, as a decimal string (e.g. \"0.0025\"), for event-priced (dynamic) billing. Omit for quantity-priced events.", "type": "string" }, "idempotency_key": { "description": "Business key deduplicating this event per subscription item. Also read from the Idempotency-Key header when absent from the body. Replays return the original record with 200.", "type": "string" }, "occurred_at": { "description": "When the usage happened (RFC 3339). May not be more than 5 minutes in the future.", "format": "date-time", "type": "string" }, "quantity": { "description": "Event quantity, rolled up by the meter's aggregation. Ignored by count meters.", "format": "int64", "type": "integer" }, "subscription_item_id": { "description": "The metered subscription item this event bills against.", "format": "uuid", "type": "string" } }, "required": [ "subscription_item_id", "occurred_at" ], "type": "object" }, "RefundRequest": { "properties": { "amount_minor": { "description": "Amount returned, in minor units (cents). Must be positive; this plus prior refunds may not exceed the payment amount.", "format": "int64", "minimum": 1, "type": "integer" }, "method": { "description": "How the money was returned. Required for offline refunds (online=false); ignored for online refunds, where the gateway returns funds to the original payment method.", "enum": [ "cash", "cheque", "bank_transfer", "wire", "card", "ach", "sepa_debit", "bacs_debit", "other" ], "type": "string" }, "mode": { "description": "How the refund settles against the customer's receivable: reverse re-opens the balance, goodwill forgives it. Defaults to reverse.", "enum": [ "reverse", "goodwill" ], "type": "string" }, "note": { "description": "Free-text note.", "type": "string" }, "online": { "description": "When true, sends the money back to the payment method the charge was made with, via the gateway — instead of just recording an offline refund. The Idempotency-Key header is then required (400 without it).", "type": "boolean" }, "reason": { "description": "Why the money was returned. Defaults to other. chargeback records money the customer's bank took back after a lost dispute — the dispute pipeline records these automatically for gateways that report disputes; use it by hand only for gateways that do not (Authorize.Net) or charges the ledger never tracked. A chargeback defaults to goodwill mode and is refused for an online refund (nothing is sent to the gateway for a chargeback).", "enum": [ "requested_by_customer", "duplicate", "fraudulent", "other", "chargeback" ], "type": "string" }, "reference": { "description": "Operator note, e.g. \"Cheque #1234\". Offline refunds only.", "type": "string" }, "refunded_at": { "description": "Value date of the refund, RFC 3339 or YYYY-MM-DD. Omitted = now. Offline refunds only.", "type": "string" } }, "required": [ "amount_minor" ], "type": "object" }, "RefundResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "customer_id": { "type": "string" }, "id": { "type": "string" }, "method": { "type": "string" }, "mode": { "type": "string" }, "payment_id": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "refunded_at": { "format": "date-time", "type": "string" }, "status": { "description": "reversed: the issuer later reversed the lost dispute this chargeback recorded and the money came back; the row stays for history and no longer counts as refunded.", "enum": [ "pending", "processing", "succeeded", "failed", "reversed" ], "type": "string" } }, "type": "object" }, "ReplacePriceRequest": { "properties": { "billing_period_count": { "description": "Number of units per billing period (e.g. 3 with unit month bills quarterly).", "type": [ "null", "integer" ] }, "billing_period_unit": { "description": "Recurrence unit. Required for plan/addon prices; must be omitted for a one_off product's price.", "enum": [ "day", "week", "month", "year" ], "type": [ "null", "string" ] }, "billing_timing": { "description": "When in the period the charge bills. Defaults to in_advance; metered prices are always billed in_arrears.", "enum": [ "in_advance", "in_arrears" ], "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code (e.g. \"USD\").", "type": "string" }, "included_quantity": { "description": "Quantity included before usage charges accrue.", "format": "int64", "type": "integer" }, "is_taxable": { "description": "Whether tax applies to this price's charges. Defaults to true.", "type": [ "null", "boolean" ] }, "meter_id": { "description": "Meter whose recorded usage rolls up into the billable quantity. Required when the product is metered; forbidden otherwise.", "format": "uuid", "type": [ "null", "string" ] }, "nickname": { "description": "Internal display name for the new price version.", "type": "string" }, "pricing_config": { "additionalProperties": {}, "description": "Model-specific configuration, amounts in minor units: unit_amount (and optional per_units) for flat/per_unit, package_size + flat_amount for package, percentage for percentage, a non-empty tiers array for tiered/volume/step, optional markup_pct for dynamic.", "type": [ "object", "null" ] }, "pricing_model": { "description": "How the price computes a charge; pricing_config is interpreted per model.", "enum": [ "flat", "per_unit", "tiered", "volume", "step", "package", "percentage", "dynamic" ], "type": "string" }, "trial_days": { "description": "Free trial length in days before the first charge.", "type": "integer" }, "variant_label": { "description": "Label distinguishing this variant of the product.", "type": [ "null", "string" ] } }, "required": [ "nickname", "currency", "pricing_model" ], "type": "object" }, "ReportDimension": { "properties": { "column": { "type": "string" }, "granularity": { "type": "string" }, "label": { "type": "string" } }, "type": "object" }, "ReportMeasure": { "properties": { "column": { "type": "string" }, "fn": { "type": "string" }, "label": { "type": "string" } }, "type": "object" }, "ReportRelativeWindow": { "properties": { "column": { "type": "string" }, "from": { "type": "string" }, "preset": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "ReportReportSpec": { "properties": { "columns": { "items": { "type": "string" }, "type": "array" }, "compare": { "type": "string" }, "dataset": { "type": "string" }, "dimensions": { "items": { "$ref": "#/components/schemas/ReportDimension" }, "type": "array" }, "filter": { "$ref": "#/components/schemas/FilterGroup" }, "kind": { "type": "string" }, "limit": { "type": "integer" }, "measures": { "items": { "$ref": "#/components/schemas/ReportMeasure" }, "type": "array" }, "sort": { "items": { "$ref": "#/components/schemas/ReportSortKey" }, "type": "array" }, "version": { "type": "integer" }, "viz": { "$ref": "#/components/schemas/ReportVizSpec" }, "window": { "$ref": "#/components/schemas/ReportRelativeWindow" } }, "type": "object" }, "ReportResponse": { "properties": { "category": { "type": "string" }, "cloned_from": { "type": "string" }, "created_at": { "format": "date-time", "type": [ "null", "string" ] }, "dataset": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "spec": { "$ref": "#/components/schemas/ReportReportSpec" }, "system": { "type": "boolean" } }, "type": "object" }, "ReportResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ReportResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "ReportRow": { "additionalProperties": {}, "type": "object" }, "ReportSortKey": { "properties": { "desc": { "type": "boolean" }, "key": { "type": "string" } }, "type": "object" }, "ReportVizSpec": { "properties": { "kind": { "type": "string" }, "options": { "additionalProperties": { "type": "string" }, "type": "object" } }, "type": "object" }, "RunColumn": { "properties": { "currency": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "measure": { "type": "boolean" }, "type": { "type": "string" } }, "type": "object" }, "RunReportRequest": { "properties": { "currency": { "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterGroup" }, "window": { "$ref": "#/components/schemas/ReportRelativeWindow" } }, "type": "object" }, "RunReportResponse": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "columns": { "items": { "$ref": "#/components/schemas/RunColumn" }, "type": [ "array", "null" ] }, "rows": { "items": { "$ref": "#/components/schemas/ReportRow" }, "type": [ "array", "null" ] } }, "type": "object" }, "ScheduleResponse": { "properties": { "cadence": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "enabled": { "type": "boolean" }, "format": { "type": "string" }, "hour": { "type": "integer" }, "id": { "type": "string" }, "last_run_at": { "format": "date-time", "type": [ "null", "string" ] }, "month_day": { "type": "integer" }, "next_run_at": { "format": "date-time", "type": "string" }, "recipients": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "report_id": { "type": "string" }, "report_key": { "type": "string" }, "weekday": { "type": "integer" } }, "type": "object" }, "ScheduleResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ScheduleResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "ScheduledChangeListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ScheduledChangeResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "ScheduledChangeResponse": { "properties": { "applied_at": { "format": "date-time", "type": [ "null", "string" ] }, "cancelled_at": { "format": "date-time", "type": [ "null", "string" ] }, "change_type": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "failure_reason": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "item_id": { "type": [ "null", "string" ] }, "price_id": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "integer" ] }, "scheduled_for": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "subscription_id": { "type": "string" } }, "type": "object" }, "SetSubscriptionBillingDayRequest": { "properties": { "billing_day": { "description": "Day-of-month (1-31) to re-anchor billing to.", "maximum": 31, "minimum": 1, "type": "integer" }, "mode": { "description": "When the re-alignment takes effect. Defaults to next_renewal: the stored billing day is re-anchored and the next renewal shapes the cycle onto the new day, with no mid-cycle money movement. immediate_prorated re-cuts the current term now and prorates the difference.", "enum": [ "next_renewal", "immediate_prorated" ], "type": "string" } }, "required": [ "billing_day" ], "type": "object" }, "SetSubscriptionPoNumberRequest": { "properties": { "po_number": { "description": "New procurement reference; null (or empty) clears it. Past invoices keep their snapshot of the prior value.", "type": [ "null", "string" ] } }, "type": "object" }, "StatementEntryResponse": { "properties": { "balance_minor": { "description": "Running balance after this entry (minor units).", "format": "int64", "type": "integer" }, "credit_minor": { "description": "Amount credited to the customer (minor units).", "format": "int64", "type": "integer" }, "date": { "format": "date-time", "type": "string" }, "debit_minor": { "description": "Amount charged to the customer (minor units).", "format": "int64", "type": "integer" }, "description": { "type": "string" }, "kind": { "description": "The document that produced the line.", "enum": [ "invoice", "payment", "write_off", "credit_note", "refund", "goodwill_adjustment", "chargeback", "chargeback_write_off", "refund_reversed", "goodwill_adjustment_reversed", "chargeback_reversed", "chargeback_write_off_reversed" ], "type": "string" }, "reference": { "description": "Human reference of the source document (e.g. the invoice number).", "type": "string" } }, "type": "object" }, "SubscriptionItemResponse": { "properties": { "id": { "type": "string" }, "price_id": { "type": "string" }, "product_kind": { "enum": [ "plan", "addon", "one_off" ], "type": "string" }, "quantity": { "format": "int64", "type": "integer" }, "status": { "description": "active bills every cycle; removed was taken off mid-cycle with its unused period credited; settled is a one_off item whose one-time charge was queued the moment it was added — it bills once, on the next invoice, and never recurs.", "enum": [ "active", "removed", "settled" ], "type": "string" } }, "type": "object" }, "SubscriptionResponse": { "properties": { "auto_collection": { "type": [ "null", "boolean" ] }, "billing_cycles_completed": { "type": "integer" }, "billing_day": { "type": [ "null", "integer" ] }, "billing_period_count": { "type": "integer" }, "billing_period_unit": { "type": "string" }, "cancel_at": { "format": "date-time", "type": [ "null", "string" ] }, "cancelled_at": { "format": "date-time", "type": [ "null", "string" ] }, "collection_method": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "current_term_end": { "format": "date-time", "type": "string" }, "current_term_start": { "format": "date-time", "type": "string" }, "custom_fields": { "additionalProperties": {}, "type": [ "object", "null" ] }, "customer_id": { "type": "string" }, "external_id": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/SubscriptionItemResponse" }, "type": "array" }, "mrr_minor": { "format": "int64", "type": "integer" }, "next_billing_at": { "format": "date-time", "type": "string" }, "origin": { "type": "string" }, "origin_detail": { "type": [ "null", "string" ] }, "paused_until": { "format": "date-time", "type": [ "null", "string" ] }, "po_number": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "total_billing_cycles": { "type": [ "null", "integer" ] }, "trial_end": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "SubscriptionResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SubscriptionResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "TaxRateListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TaxRateResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "TaxRateResponse": { "properties": { "country": { "type": "string" }, "effective_from": { "format": "date-time", "type": [ "null", "string" ] }, "effective_to": { "format": "date-time", "type": [ "null", "string" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "rate_percent": { "type": "string" }, "region": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "TaxationItemResponse": { "properties": { "country": { "type": "string" }, "invoice_item_id": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "provider_ref": { "type": "string" }, "rate_percent": { "type": "string" }, "region": { "type": "string" }, "tax_minor": { "format": "int64", "type": "integer" }, "tax_rate_id": { "type": [ "null", "string" ] }, "taxable_minor": { "format": "int64", "type": "integer" } }, "type": "object" }, "UnbilledChargeListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UnbilledChargeResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "UnbilledChargeResponse": { "properties": { "amount": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "invoiced_at": { "format": "date-time", "type": [ "null", "string" ] }, "price_id": { "format": "uuid", "type": [ "null", "string" ] }, "quantity": { "format": "int64", "type": "integer" }, "service_period_end": { "format": "date-time", "type": [ "null", "string" ] }, "service_period_start": { "format": "date-time", "type": [ "null", "string" ] }, "source": { "description": "What produced the charge. setup_fee is a one-time (one_off) item, queued in full when it was added to the subscription and billed once on the next invoice.", "enum": [ "proration_credit", "proration_charge", "mid_cycle_change", "usage", "manual", "addon_trial_end", "setup_fee", "coupon_carryover", "renewal_credit" ], "type": "string" }, "status": { "type": "string" }, "subscription_id": { "type": [ "null", "string" ] }, "subscription_item_id": { "type": [ "null", "string" ] }, "taxable": { "type": "boolean" }, "trace_id": { "type": "string" }, "voided_at": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateCheckoutRequest": { "properties": { "addons": { "description": "Offered add-ons. Replaces the existing list.", "items": { "$ref": "#/components/schemas/CheckoutAddonRequest" }, "type": [ "array", "null" ] }, "completion": { "$ref": "#/components/schemas/CheckoutCompletionRequest", "description": "What happens after a successful signup. Replaces the existing completion." }, "metadata": { "additionalProperties": {}, "description": "Arbitrary key/value data.", "type": [ "object", "null" ] }, "name": { "description": "Internal name for this checkout page.", "type": "string" }, "options": { "$ref": "#/components/schemas/CheckoutOptionsRequest", "description": "What the page collects and offers. Replaces the existing options." }, "price_choice": { "description": "Alternative plan prices a buyer may pick instead. Replaces the existing list.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "price_id": { "description": "The plan price this page sells (UUID).", "type": "string" } }, "required": [ "name", "price_id" ], "type": "object" }, "UpdateContactRequest": { "properties": { "email": { "description": "New email address; validated and stored lower-cased.", "type": [ "null", "string" ] }, "first_name": { "type": [ "null", "string" ] }, "is_primary": { "description": "true promotes this contact to primary (auto-demoting the previous one); false demotes it. Omit to leave unchanged.", "type": [ "null", "boolean" ] }, "last_name": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "role": { "description": "Free-text label (e.g. \"billing\", \"technical\", \"procurement\").", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateCustomRecordRequest": { "properties": { "fields": { "additionalProperties": {}, "description": "Partial update: only provided fields change; a null or empty value clears the field.", "type": [ "object", "null" ] }, "name": { "description": "New display name; omit to keep the current one.", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateCustomerRequest": { "properties": { "auto_collection": { "description": "Charge the stored payment method automatically when an invoice finalizes.", "type": [ "null", "boolean" ] }, "billing_address": { "$ref": "#/components/schemas/CustomerAddress" }, "company": { "type": [ "null", "string" ] }, "consolidated_invoicing": { "description": "Consolidated invoicing mode.", "type": [ "null", "string" ] }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "display_name": { "description": "Name shown on invoices and in the dashboard.", "type": [ "null", "string" ] }, "email": { "description": "Billing email; invoices and receipts are sent here.", "type": [ "null", "string" ] }, "first_name": { "type": [ "null", "string" ] }, "invoice_note": { "description": "Note printed on every invoice for this customer.", "type": [ "null", "string" ] }, "is_tax_exempt": { "description": "When true, no tax is applied to this customer's invoices.", "type": [ "null", "boolean" ] }, "last_name": { "type": [ "null", "string" ] }, "locale": { "description": "Locale used to format invoices (e.g. \"en-US\").", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "net_terms_days": { "description": "Days until a finalized invoice is due. 0 means due on receipt.", "minimum": 0, "type": [ "null", "integer" ] }, "phone": { "type": [ "null", "string" ] }, "price_type": { "description": "Whether catalog prices include tax for this customer.", "enum": [ "tax_exclusive", "tax_inclusive" ], "type": [ "null", "string" ] }, "shipping_address": { "$ref": "#/components/schemas/CustomerAddress" }, "tax_exemption_number": { "type": [ "null", "string" ] }, "tax_exemption_reason": { "type": [ "null", "string" ] }, "tax_id": { "description": "Tax/VAT identifier printed on invoices.", "type": [ "null", "string" ] }, "timezone": { "description": "IANA timezone (e.g. \"America/New_York\") used for billing-day math.", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateFeatureRequest": { "properties": { "config": { "$ref": "#/components/schemas/FeatureConfig", "description": "Replaces the whole config object when provided." }, "description": { "type": [ "null", "string" ] }, "name": { "description": "Human name shown in the dashboard. Must not be empty when provided.", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateMeterRequest": { "properties": { "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "name": { "description": "Human-readable label shown in the dashboard.", "type": [ "null", "string" ] }, "unit_of_measure": { "description": "Display unit for quantities (e.g. \"requests\", \"GB\").", "type": [ "null", "string" ] } }, "type": "object" }, "UpdatePriceRequest": { "properties": { "is_taxable": { "description": "Whether tax applies to this price's charges.", "type": [ "null", "boolean" ] }, "nickname": { "description": "Internal display name for this price.", "type": [ "null", "string" ] }, "portal_eligible": { "description": "Whether customers may self-serve switch to this price in the customer portal (same product, currency and billing period only).", "type": [ "null", "boolean" ] }, "trial_days": { "description": "Free trial length in days before the first charge.", "type": [ "null", "integer" ] }, "variant_label": { "description": "Label distinguishing this variant of the product.", "type": [ "null", "string" ] } }, "type": "object" }, "UpdatePricingUnitRequest": { "properties": { "name": { "description": "Human label (e.g. \"Credits\").", "type": [ "null", "string" ] }, "symbol": { "description": "Short display token used on invoices (max 8 characters). Falls back to the code when empty.", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateProductRequest": { "properties": { "category": { "description": "Free-form grouping label used to organize the catalog.", "type": [ "null", "string" ] }, "custom_fields": { "additionalProperties": {}, "description": "Values for the org-defined custom fields; validated against their definitions on write.", "type": [ "object", "null" ] }, "description": { "type": [ "null", "string" ] }, "external_name": { "description": "Customer-facing name on invoices and the portal.", "type": [ "null", "string" ] }, "metadata": { "additionalProperties": {}, "description": "Free-form key-value store, opaque to yRecurring.", "type": [ "object", "null" ] }, "name": { "description": "Internal name shown in the dashboard.", "type": [ "null", "string" ] }, "tax_code": { "description": "Tax code applied to this product's charges.", "type": [ "null", "string" ] }, "unit_of_measure": { "description": "Label for what one unit represents (e.g. \"seat\", \"GB\").", "type": [ "null", "string" ] } }, "type": "object" }, "UpdateWebhookRequest": { "properties": { "description": { "description": "Replace the description.", "type": [ "null", "string" ] }, "event_types": { "description": "Replace the subscribed event types (non-empty, or \"*\").", "items": { "type": "string" }, "type": [ "null", "array" ] }, "is_active": { "description": "Enable or disable deliveries.", "type": [ "null", "boolean" ] }, "url": { "description": "Replace the endpoint URL (HTTPS, or http for localhost).", "format": "uri", "type": [ "null", "string" ] } }, "type": "object" }, "UsageBatchRecordRequest": { "properties": { "amount": { "description": "Caller-computed event cost in minor units, as a decimal string, for event-priced (dynamic) billing. Omit for quantity-priced events.", "type": "string" }, "idempotency_key": { "description": "Per-record business key deduplicating the event. Required on every record — the request-level Idempotency-Key header is ignored on this endpoint.", "type": "string" }, "occurred_at": { "description": "When the usage happened (RFC 3339).", "format": "date-time", "type": "string" }, "quantity": { "description": "Event quantity, rolled up by the meter's aggregation. Ignored by count meters.", "format": "int64", "type": "integer" }, "subscription_item_id": { "description": "Metered subscription item this event bills against.", "format": "uuid", "type": "string" } }, "required": [ "subscription_item_id", "occurred_at", "idempotency_key" ], "type": "object" }, "UsageBatchResponse": { "properties": { "failed": { "type": "integer" }, "recorded": { "type": "integer" }, "replayed": { "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/UsageBatchResult" }, "type": [ "array", "null" ] } }, "type": "object" }, "UsageBatchResult": { "properties": { "code": { "type": "string" }, "deduplicated": { "type": "boolean" }, "error": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "UsageRecordResponse": { "properties": { "amount": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "idempotency_key": { "type": [ "null", "string" ] }, "meter_id": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "quantity": { "format": "int64", "type": "integer" }, "recorded_at": { "format": "date-time", "type": "string" }, "subscription_item_id": { "type": "string" } }, "type": "object" }, "VoidUnbilledChargeRequest": { "properties": { "reason": { "description": "Free-text reason recorded on the void audit event.", "type": "string" } }, "type": "object" }, "WalletListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WalletResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "WalletResponse": { "properties": { "balance_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "customer_id": { "type": "string" }, "decimals": { "type": "integer" }, "denomination": { "type": "string" }, "id": { "type": "string" }, "pricing_unit_id": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "WalletTxListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WalletTxResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "WalletTxResponse": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "balance_after_minor": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "kind": { "type": "string" }, "reason": { "type": "string" }, "wallet_id": { "type": "string" } }, "type": "object" }, "WebhookActor": { "properties": { "id": { "description": "The actor's id, when the actor is an identifiable principal (omitted for system actors).", "type": "string" }, "type": { "description": "The kind of actor that caused the event: user, api_key, system, workflow, or import.", "type": "string" } }, "type": "object" }, "WebhookPayload": { "properties": { "actor": { "$ref": "#/components/schemas/WebhookActor", "description": "Who or what caused the event." }, "api_version": { "description": "The API version pinned on the endpoint when it was created. The payload shape follows this version.", "type": "string" }, "data": { "additionalProperties": {}, "description": "The affected resource. Always carries object (the resource type, e.g. customer) and id. When available it also carries record — the resource's full current state — and changes, the fields that changed. On a delete, record is omitted.", "type": [ "object", "null" ] }, "id": { "description": "The event's unique id. Stable across the original delivery and any retries or replays of the same event.", "type": "string" }, "occurred_at": { "description": "When the event occurred (RFC 3339). Preserved across replays so it reflects the original occurrence, not the redelivery.", "format": "date-time", "type": "string" }, "org_id": { "description": "The id of the organization the event belongs to.", "type": "string" }, "type": { "description": "The event type, e.g. invoice.paid. Always one of the subscribable event types in the catalog.", "type": "string" } }, "type": "object" }, "WebhookResponse": { "properties": { "api_version": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "event_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "WebhookResponseList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookResponse" }, "type": [ "array", "null" ] }, "total": { "format": "int64", "type": "integer" } }, "type": "object" }, "WebhookSecretResponse": { "properties": { "api_version": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "event_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "secret": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "securitySchemes": { "apiKey": { "description": "An API key (`yr_…`) passed as a bearer token. Create and revoke keys on the dashboard's API keys page.", "type": "http", "scheme": "bearer" } } }, "security": [ { "apiKey": [] } ] }