{ "openapi": "3.1.0", "info": { "title": "Commet API", "version": "2026-08-27", "description": "Billing and payments API for SaaS and AI products." }, "servers": [ { "url": "https://commet.co/api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Test Clock", "description": "Simulate the passage of time in sandbox to test billing flows. Mirrors Stripe test clocks: forward-only and sandbox-only." }, { "name": "Customers" }, { "name": "Subscriptions" }, { "name": "Plans" }, { "name": "Markets", "description": "Reusable country groups for market-specific prices and selectable price variants." }, { "name": "Offers" }, { "name": "Promo Codes" }, { "name": "Features" }, { "name": "Usage" }, { "name": "Seats" }, { "name": "Quota" }, { "name": "Add-ons" }, { "name": "Portal" }, { "name": "Credit Packs" }, { "name": "Plan Groups" }, { "name": "Invoices" }, { "name": "Payments", "description": "One-time payments with no subscription or plan. Charge a customer's saved payment method off-session, or create a payment link the customer opens to pay. Tax, invoice, and receipt are handled automatically." }, { "name": "Transactions" }, { "name": "Webhooks" }, { "name": "API Keys" }, { "name": "Payouts", "description": "Withdraw available balance to your bank and manage the payout account (verification + destination bank accounts)." }, { "name": "Provisioning", "description": "Take ownership of an organization an agent provisioned headlessly. The agent holds the API keys from the start; a human claims the account through a claim link." } ], "paths": { "/active-addons": { "get": { "operationId": "list-active-addons", "summary": "List active add-ons", "tags": ["Add-ons"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActiveAddon" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "slug": "extra-api-calls", "name": "Extra API calls", "basePrice": 1000, "featureCode": "api_calls", "featureName": "API Calls", "featureType": "usage", "consumptionModel": "metered", "activatedAt": "2026-09-07T12:00:00.000Z", "object": "subscription_addon", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List all active add-ons for a customer's subscription.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/addons/{id}": { "get": { "operationId": "get-addon", "summary": "Get add-on", "tags": ["Add-ons"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" }, "example": { "id": "addon_1a2b3c4d", "name": "Extra API calls", "slug": "extra-api-calls", "description": "An additional 1,000 API calls per billing period", "basePrice": 1000, "featureCode": "api_calls", "featureName": "API Calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "consumptionModel": "metered", "includedUnits": 1000, "overageRate": null, "creditCost": null, "object": "addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve an add-on by its public ID or slug.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-addon", "summary": "Update add-on", "tags": ["Add-ons"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" }, "example": { "id": "addon_1a2b3c4d", "name": "Extra API calls", "slug": "extra-api-calls", "description": "An additional 1,000 API calls per billing period", "basePrice": 1000, "featureCode": "api_calls", "featureName": "API Calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "consumptionModel": "metered", "includedUnits": 1000, "overageRate": null, "creditCost": null, "object": "addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update an add-on's name, description, or pricing.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "basePrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "includedUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "overageRate": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } } }, "delete": { "operationId": "delete-addon", "summary": "Delete add-on", "tags": ["Add-ons"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "addon_1a2b3c4d", "deleted": true, "object": "addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Soft-delete an add-on. Fails if the add-on has active subscriptions.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/addons": { "get": { "operationId": "list-addons", "summary": "List add-ons", "tags": ["Add-ons"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Addon" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "addon_1a2b3c4d", "name": "Extra API calls", "slug": "extra-api-calls", "description": "An additional 1,000 API calls per billing period", "basePrice": 1000, "featureCode": "api_calls", "featureName": "API Calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "consumptionModel": "metered", "includedUnits": 1000, "overageRate": null, "creditCost": null, "object": "addon", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List all add-ons with cursor-based pagination.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "create-addon", "summary": "Create add-on", "tags": ["Add-ons"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" }, "example": { "id": "addon_1a2b3c4d", "name": "Extra API calls", "slug": "extra-api-calls", "description": "An additional 1,000 API calls per billing period", "basePrice": 1000, "featureCode": "api_calls", "featureName": "API Calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "consumptionModel": "metered", "includedUnits": 1000, "overageRate": null, "creditCost": null, "object": "addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new add-on linked to a feature. Each feature can only be assigned to one add-on.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "basePrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "featureId": { "type": "string", "minLength": 1 }, "consumptionModel": { "type": "string", "const": "boolean" } }, "required": [ "name", "basePrice", "featureId", "consumptionModel" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "basePrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "featureId": { "type": "string", "minLength": 1 }, "consumptionModel": { "type": "string", "const": "metered" }, "includedUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "overageRate": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "basePrice", "featureId", "consumptionModel", "includedUnits", "overageRate" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "basePrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "featureId": { "type": "string", "minLength": 1 }, "consumptionModel": { "type": "string", "const": "credits" }, "creditCost": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "basePrice", "featureId", "consumptionModel", "creditCost" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "basePrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "featureId": { "type": "string", "minLength": 1 }, "consumptionModel": { "type": "string", "const": "balance" }, "overageRate": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "basePrice", "featureId", "consumptionModel", "overageRate" ], "additionalProperties": false } ] } } } } } }, "/api-keys/{id}": { "delete": { "operationId": "delete-api-key", "summary": "Delete API key", "tags": ["API Keys"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "key_1a2b3c4d", "deleted": true, "object": "api_key", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Permanently revoke and delete an API key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api-keys": { "get": { "operationId": "list-api-keys", "summary": "List API keys", "tags": ["API Keys"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "key_1a2b3c4d", "name": "Local development", "prefix": "ck_example", "expiresAt": "2027-09-07T12:00:00.000Z", "lastUsedAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "object": "api_key", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List API keys with cursor-based pagination. Keys are returned without the full secret.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "create-api-key", "summary": "Create API key", "tags": ["API Keys"], "x-commet-representation": "result", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" }, "example": { "id": "key_1a2b3c4d", "name": "Local development", "apiKey": "ck_example_not_a_real_api_key", "prefix": "ck_example", "expiresAt": "2027-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "api_key", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new API key. The full key is only returned once in the response.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "expiresInDays": { "default": 365, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["name"] } } } } } }, "/claim-link": { "post": { "operationId": "create-claim-link", "summary": "Create claim link", "tags": ["Provisioning"], "x-commet-representation": "result", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimLink" }, "example": { "url": "https://commet.co/claim/example_claim_token", "expiresAt": "2026-09-07T13:00:00.000Z", "object": "claim_link", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Issue a fresh claim link for an organization that was provisioned headlessly and has not been claimed yet. Any previously issued link stops working.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ] } }, "/credit-packs/{id}": { "patch": { "operationId": "update-credit-pack", "summary": "Update credit pack", "tags": ["Credit Packs"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPack" }, "example": { "id": "cp_1a2b3c4d", "name": "1,000 credits", "description": "Additional credits for your subscription", "credits": 1000, "price": 1000, "isActive": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "credit_pack", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a credit pack's name, description, credits, price, or active status.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "credits": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } } } } } } }, "delete": { "operationId": "delete-credit-pack", "summary": "Delete credit pack", "tags": ["Credit Packs"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "cp_1a2b3c4d", "deleted": true, "object": "credit_pack", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Soft-delete a credit pack.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/credit-packs": { "get": { "operationId": "list-credit-packs", "summary": "List credit packs", "tags": ["Credit Packs"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPackListItem" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "cp_1a2b3c4d", "name": "1,000 credits", "description": "Additional credits for your subscription", "credits": 1000, "price": 1000, "currency": "usd", "object": "credit_pack", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List all active credit packs." }, "post": { "operationId": "create-credit-pack", "summary": "Create credit pack", "tags": ["Credit Packs"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPack" }, "example": { "id": "cp_1a2b3c4d", "name": "1,000 credits", "description": "Additional credits for your subscription", "credits": 1000, "price": 1000, "isActive": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "credit_pack", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new credit pack.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 255 }, "credits": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } }, "required": ["name", "credits", "price"] } } } } } }, "/customers/{id}/credits/{creditId}/revoke": { "post": { "operationId": "revoke-customer-credit", "summary": "Revoke remaining customer credit", "tags": ["Customers"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditRevocation" }, "example": { "id": "cc_1a2b3c4d", "remainingAmount": 0, "revokedAmount": 500, "currency": "usd", "object": "customer_credit", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Revoke the unallocated remainder of a customer credit grant. Applied invoice history is unchanged.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "creditId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/customers/{id}/credits": { "get": { "operationId": "list-customer-credits", "summary": "List customer credits", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCredit" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "cc_1a2b3c4d", "amount": 500, "appliedAmount": 0, "reversedAmount": 0, "revokedAmount": 0, "remainingAmount": 500, "currency": "usd", "reason": "Service credit", "source": "api", "expiresAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "object": "customer_credit", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List currency-specific invoice credit grants and their remaining balances for a customer.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "create-customer-credit", "summary": "Grant customer credit", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCredit" }, "example": { "id": "cc_1a2b3c4d", "amount": 500, "appliedAmount": 0, "reversedAmount": 0, "revokedAmount": 0, "remainingAmount": 500, "currency": "usd", "reason": "Service credit", "source": "api", "expiresAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "object": "customer_credit", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Grant monetary credit in one currency. Credit is applied FIFO before tax to eligible recurring invoices.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's smallest unit." }, "currency": { "type": "string", "enum": [ "usd", "ars", "brl", "clp", "cop", "pen", "uyu", "pyg", "bob", "mxn", "cad", "eur", "gbp", "jpy", "cny", "krw", "hkd", "sgd", "twd", "inr", "thb" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["amount", "currency", "reason"] } } } } } }, "/customers/{id}/plan-grants/{grantId}/revoke": { "post": { "operationId": "revoke-plan-grant", "summary": "Revoke temporary plan access", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGrant" }, "example": { "id": "grant_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "basePlanId": "plan_1a2b3c4d", "planId": "plan_5e6f7a8b", "planReleaseId": "release_5e6f7a8b", "status": "revoked", "duration": "until_date", "durationCycles": null, "startsAt": "2026-09-07T12:00:00.000Z", "expiresAt": "2026-10-07T12:00:00.000Z", "reason": "Evaluate Business features", "source": "api", "revokedAt": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "events": [ { "id": "event_1a2b3c4d", "type": "created", "reason": "Evaluate Business features", "source": "api", "previousExpiresAt": null, "expiresAt": "2026-10-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-10-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" }, { "id": "event_5e6f7a8b", "type": "revoked", "reason": "Evaluation ended", "source": "api", "previousExpiresAt": "2026-10-07T12:00:00.000Z", "expiresAt": "2026-10-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-10-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" } ], "object": "plan_grant", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "End expanded access immediately and restore the base plan's limits. The subscription, billing cycle, invoices, and payment state remain unchanged.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": ["reason"] } } } } } }, "/customers/{id}/plan-grants/{grantId}": { "patch": { "operationId": "update-plan-grant", "summary": "Update temporary access expiration", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGrant" }, "example": { "id": "grant_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "basePlanId": "plan_1a2b3c4d", "planId": "plan_5e6f7a8b", "planReleaseId": "release_5e6f7a8b", "status": "active", "duration": "until_date", "durationCycles": null, "startsAt": "2026-09-07T12:00:00.000Z", "expiresAt": "2026-11-07T12:00:00.000Z", "reason": "Extended evaluation", "source": "api", "revokedAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "events": [ { "id": "event_1a2b3c4d", "type": "created", "reason": "Evaluate Business features", "source": "api", "previousExpiresAt": null, "expiresAt": "2026-10-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-10-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" }, { "id": "event_5e6f7a8b", "type": "updated", "reason": "Extended evaluation", "source": "api", "previousExpiresAt": "2026-10-07T12:00:00.000Z", "expiresAt": "2026-11-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-11-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" } ], "object": "plan_grant", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Keep the overlay for a number of the subscription's existing billing cycles, set an exact deadline, or leave it active until revoked. The billing anchor is never reset.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "cycles" }, "durationCycles": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["reason", "duration", "durationCycles"] }, { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "until_date" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["reason", "duration", "expiresAt"] }, { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "until_revoked" } }, "required": ["reason", "duration"] } ] } } } } } }, "/customers/{id}/plan-grants": { "get": { "operationId": "list-plan-grants", "summary": "List plan grants", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanGrant" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "grant_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "basePlanId": "plan_1a2b3c4d", "planId": "plan_5e6f7a8b", "planReleaseId": "release_5e6f7a8b", "status": "active", "duration": "until_date", "durationCycles": null, "startsAt": "2026-09-07T12:00:00.000Z", "expiresAt": "2026-10-07T12:00:00.000Z", "reason": "Evaluate Business features", "source": "api", "revokedAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "events": [ { "id": "event_1a2b3c4d", "type": "created", "reason": "Evaluate Business features", "source": "api", "previousExpiresAt": null, "expiresAt": "2026-10-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-10-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" } ], "object": "plan_grant", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List the independent audit timeline for paid-plan access granted without checkout or payment credentials.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "create-plan-grant", "summary": "Grant temporary plan access", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGrant" }, "example": { "id": "grant_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "basePlanId": "plan_1a2b3c4d", "planId": "plan_5e6f7a8b", "planReleaseId": "release_5e6f7a8b", "status": "active", "duration": "until_date", "durationCycles": null, "startsAt": "2026-09-07T12:00:00.000Z", "expiresAt": "2026-10-07T12:00:00.000Z", "reason": "Evaluate Business features", "source": "api", "revokedAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "events": [ { "id": "event_1a2b3c4d", "type": "created", "reason": "Evaluate Business features", "source": "api", "previousExpiresAt": null, "expiresAt": "2026-10-07T12:00:00.000Z", "duration": "until_date", "durationCycles": null, "requestedExpiresAt": "2026-10-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z" } ], "object": "plan_grant", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Temporarily expand an active subscription's feature access using a higher plan in the same plan group. Billing, prices, periods, invoices, and the base subscription remain unchanged.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "subscriptionId": { "type": "string", "minLength": 1 }, "planId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "cycles" }, "durationCycles": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "subscriptionId", "planId", "reason", "duration", "durationCycles" ] }, { "type": "object", "properties": { "subscriptionId": { "type": "string", "minLength": 1 }, "planId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "until_date" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "subscriptionId", "planId", "reason", "duration", "expiresAt" ] }, { "type": "object", "properties": { "subscriptionId": { "type": "string", "minLength": 1 }, "planId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "duration": { "type": "string", "const": "until_revoked" } }, "required": [ "subscriptionId", "planId", "reason", "duration" ] } ] } } } } } }, "/customers/{id}": { "get": { "operationId": "get-customer", "summary": "Get customer", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_1a2b3c4d", "externalId": null, "fullName": "user@example.com", "email": "user@example.com", "taxDocument": null, "documentType": null, "timezone": "UTC", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "customer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a customer by their public ID, including subscription status and metadata.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-customer", "summary": "Update customer", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_1a2b3c4d", "externalId": null, "fullName": "user@example.com", "email": "user@example.com", "taxDocument": null, "documentType": null, "timezone": "UTC", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "customer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a customer's name, external ID, or metadata.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fullName": { "type": "string", "maxLength": 200 }, "taxDocument": { "type": "string", "maxLength": 50 }, "externalId": { "type": "string", "maxLength": 200 }, "timezone": { "$ref": "#/components/schemas/Timezone" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1 }, "line2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "state": { "type": "string" }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "region": { "type": "string" } }, "required": ["line1", "city", "postalCode", "country"] } } } } } } } }, "/customers/batch": { "post": { "operationId": "batch-create-customers", "summary": "Batch create customers", "tags": ["Customers"], "x-commet-representation": "result", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBatch" }, "example": { "successful": [ { "id": "cus_1a2b3c4d", "externalId": null, "email": "user@example.com" } ], "failed": [], "object": "customer_batch", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create up to 100 customers in a single request.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "id": { "type": "string", "maxLength": 100 }, "externalId": { "type": "string", "maxLength": 100 }, "fullName": { "type": "string", "maxLength": 200 }, "taxDocument": { "type": "string", "maxLength": 50 }, "timezone": { "$ref": "#/components/schemas/Timezone" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1 }, "line2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "state": { "type": "string" }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "region": { "type": "string" } }, "required": ["line1", "city", "postalCode", "country"] } }, "required": ["email"] } } }, "required": ["customers"] } } } } } }, "/customers": { "get": { "operationId": "list-customers", "summary": "List customers", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "cus_1a2b3c4d", "externalId": null, "fullName": "user@example.com", "email": "user@example.com", "taxDocument": null, "documentType": null, "timezone": "UTC", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "customer", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List customers with cursor-based pagination.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "create-customer", "summary": "Create customer", "tags": ["Customers"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_1a2b3c4d", "externalId": null, "fullName": "user@example.com", "email": "user@example.com", "taxDocument": null, "documentType": null, "timezone": "UTC", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "customer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new customer. Idempotent when customerId is provided.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 100 }, "externalId": { "type": "string", "maxLength": 100 }, "fullName": { "type": "string", "maxLength": 200 }, "taxDocument": { "type": "string", "maxLength": 50 }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1 }, "line2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "state": { "type": "string" }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "region": { "type": "string" } }, "required": ["line1", "city", "postalCode", "country"] }, "addressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "timezone": { "$ref": "#/components/schemas/Timezone" }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["email"] } } } } } }, "/feature-access/{code}": { "get": { "operationId": "get-feature-access", "summary": "Get feature access", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureAccess" }, "example": { "code": "api_calls", "name": "API Calls", "unitName": "calls", "type": "usage", "allowed": true, "consumption": { "model": "metered", "period": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z" }, "unitsUsed": 250, "includedUnits": 1000, "remainingUnits": 750, "unlimited": false, "overage": { "enabled": false, "units": 0 } }, "object": "feature_access", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get one feature's access and current usage for a customer. To evaluate a prospective consumption, use POST /usage/check.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/feature-access": { "get": { "operationId": "list-feature-access", "summary": "List feature access", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureAccess" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "examples": { "balance": { "summary": "Balance usage feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "web_search", "name": "Web search", "unitName": "searches", "type": "usage", "allowed": true, "consumption": { "model": "balance", "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-08-01T00:00:00.000Z" }, "unitsUsed": 4, "spent": { "amount": 100, "currency": "usd" }, "availableUnits": 796, "unitPrice": { "amount": 2500, "currency": "usd", "scale": 10000 } }, "object": "feature_access", "livemode": true } ] } }, "credits": { "summary": "Credits usage feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "ai_generation", "name": "AI generation", "unitName": "generations", "type": "usage", "allowed": true, "consumption": { "model": "credits", "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-08-01T00:00:00.000Z" }, "unitsUsed": 4, "creditsPerUnit": 3, "creditsConsumed": 12, "availableUnits": 28 }, "object": "feature_access", "livemode": true } ] } }, "metered": { "summary": "Metered usage feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "api_calls", "name": "API calls", "unitName": "calls", "type": "usage", "allowed": true, "consumption": { "model": "metered", "period": { "start": "2026-07-10T00:00:00.000Z", "end": "2026-08-10T00:00:00.000Z" }, "unitsUsed": 120, "includedUnits": 100, "remainingUnits": 0, "unlimited": false, "overage": { "enabled": true, "units": 20, "unitPrice": { "amount": 500, "currency": "usd", "scale": 10000 } } }, "object": "feature_access", "livemode": true } ] } }, "seats": { "summary": "Seats feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "team_members", "name": "Team members", "unitName": "seats", "type": "seats", "allowed": true, "usage": { "period": { "start": "2026-07-10T00:00:00.000Z", "end": "2026-08-10T00:00:00.000Z" }, "unitsUsed": 8, "includedUnits": 5, "remainingUnits": 0, "unlimited": false, "overage": { "enabled": true, "units": 3, "unitPrice": { "amount": 50000, "currency": "usd", "scale": 10000 } } }, "object": "feature_access", "livemode": true } ] } }, "quota": { "summary": "Quota feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "active_projects", "name": "Active projects", "unitName": "projects", "type": "quota", "allowed": true, "usage": { "period": { "start": "2026-07-10T00:00:00.000Z", "end": "2026-08-10T00:00:00.000Z" }, "unitsUsed": 4, "includedUnits": 5, "remainingUnits": 1, "unlimited": false, "billedUnits": 8, "overage": { "enabled": false, "units": 0 } }, "object": "feature_access", "livemode": true } ] } }, "boolean": { "summary": "Boolean feature", "value": { "object": "list", "hasMore": false, "data": [ { "code": "advanced_reports", "name": "Advanced reports", "unitName": null, "type": "boolean", "allowed": true, "enabled": true, "object": "feature_access", "livemode": true } ] } } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List a customer's feature access and current usage.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/features/{code}": { "get": { "operationId": "get-feature", "summary": "Get feature", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_1a2b3c4d", "name": "API Calls", "code": "api_calls", "type": "usage", "description": "Requests made to the API", "unitName": "calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get a single feature definition by code from the organization's feature catalog.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-feature", "summary": "Update feature", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_1a2b3c4d", "name": "API Calls", "code": "api_calls", "type": "usage", "description": "Requests made to the API", "unitName": "calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a feature's name, description, or unit name. At least one field must be provided.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "delete": { "operationId": "delete-feature", "summary": "Delete feature", "tags": ["Features"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "feat_1a2b3c4d", "deleted": true, "object": "feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Delete a feature. Fails if the feature is attached to active plans or has an active add-on.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/features": { "get": { "operationId": "list-features", "summary": "List features", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Feature" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "feat_1a2b3c4d", "name": "API Calls", "code": "api_calls", "type": "usage", "description": "Requests made to the API", "unitName": "calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "feature", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List every feature defined in the organization. This is the organization's feature catalog (definitions), not a customer's feature access." }, "post": { "operationId": "create-feature", "summary": "Create feature", "tags": ["Features"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_1a2b3c4d", "name": "API Calls", "code": "api_calls", "type": "usage", "description": "Requests made to the API", "unitName": "calls", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new feature. Code must be lowercase alphanumeric with underscores.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }, "type": { "type": "string", "enum": ["boolean", "usage", "seats", "quota"] }, "description": { "type": "string" }, "unitName": { "type": "string" } }, "required": ["name", "code", "type"] } } } } } }, "/invoices/{id}/download-links": { "post": { "operationId": "download-invoice", "summary": "Download invoice PDF", "tags": ["Invoices"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDownload" }, "example": { "url": "https://example.com/invoices/INV-2026-0001.pdf", "expiresAt": "2026-09-07T13:00:00.000Z", "object": "invoice_download_link", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Generate a signed URL to download the invoice as a PDF. The URL expires after 7 days.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/invoices/{id}": { "get": { "operationId": "get-invoice", "summary": "Get invoice", "tags": ["Invoices"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "invoiceNumber": "INV-2026-0001", "status": "paid", "invoiceType": "recurring", "currency": "usd", "subtotal": 2000, "discountAmount": 0, "taxAmount": 0, "total": 2000, "periodStart": "2026-09-07T12:00:00.000Z", "periodEnd": "2026-10-07T12:00:00.000Z", "issueDate": "2026-09-07T12:00:00.000Z", "dueDate": "2026-09-07T12:00:00.000Z", "memo": null, "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "creditApplied": 0, "planName": "Pro", "poNumber": null, "reference": null, "lineItems": [ { "lineType": "plan_base", "featureName": null, "description": "Pro — monthly subscription", "quantity": 1, "unitAmount": 2000, "amount": 2000, "includedAmount": null, "usedAmount": null, "overageAmount": null, "discountType": null, "discountValue": null, "discountName": null, "chargeType": "standard" } ], "object": "invoice", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a single invoice by its public ID, including line items.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/invoices/{id}/send": { "post": { "operationId": "send-invoice", "summary": "Send invoice email", "tags": ["Invoices"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentInvoice" }, "example": { "sent": true, "sentAt": "2026-09-07T12:00:00.000Z", "object": "invoice_delivery", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Send the invoice to the customer via email.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/invoices/{id}/status": { "patch": { "operationId": "update-invoice-status", "summary": "Update invoice status", "tags": ["Invoices"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "invoiceNumber": "INV-2026-0001", "status": "paid", "invoiceType": "recurring", "currency": "usd", "subtotal": 2000, "discountAmount": 0, "taxAmount": 0, "total": 2000, "periodStart": "2026-09-07T12:00:00.000Z", "periodEnd": "2026-10-07T12:00:00.000Z", "issueDate": "2026-09-07T12:00:00.000Z", "dueDate": "2026-09-07T12:00:00.000Z", "memo": null, "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "creditApplied": 0, "planName": "Pro", "poNumber": null, "reference": null, "lineItems": [ { "lineType": "plan_base", "featureName": null, "description": "Pro — monthly subscription", "quantity": 1, "unitAmount": 2000, "amount": 2000, "includedAmount": null, "usedAmount": null, "overageAmount": null, "discountType": null, "discountValue": null, "discountName": null, "chargeType": "standard" } ], "object": "invoice", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Mark an outstanding invoice as \"paid\" or \"void\" and return the updated invoice. Cannot change the status of already paid or voided invoices.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["paid", "void"] } }, "required": ["status"] } } } } } }, "/invoices": { "get": { "operationId": "list-invoices", "summary": "List invoices", "tags": ["Invoices"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceListItem" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "inv_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": "sub_1a2b3c4d", "invoiceNumber": "INV-2026-0001", "status": "paid", "invoiceType": "recurring", "currency": "usd", "subtotal": 2000, "discountAmount": 0, "taxAmount": 0, "total": 2000, "periodStart": "2026-09-07T12:00:00.000Z", "periodEnd": "2026-10-07T12:00:00.000Z", "issueDate": "2026-09-07T12:00:00.000Z", "dueDate": "2026-09-07T12:00:00.000Z", "memo": null, "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "invoice", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List invoices with cursor-based pagination. Filter by customer, status, or subscription.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["draft", "outstanding", "paid", "void", "uncollectible"] } }, { "name": "subscriptionId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "create-adjustment-invoice", "summary": "Create adjustment invoice", "tags": ["Invoices"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_1a2b3c4d", "customerId": "cus_1a2b3c4d", "subscriptionId": null, "invoiceNumber": "INV-2026-0001", "status": "outstanding", "invoiceType": "adjustment", "currency": "usd", "subtotal": 500, "discountAmount": 0, "taxAmount": 0, "total": 500, "periodStart": "2026-09-07T12:00:00.000Z", "periodEnd": "2026-10-07T12:00:00.000Z", "issueDate": "2026-09-07T12:00:00.000Z", "dueDate": "2026-09-07T12:00:00.000Z", "memo": "Additional support session", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "creditApplied": 0, "planName": null, "poNumber": null, "reference": null, "lineItems": [ { "lineType": "one_time", "featureName": null, "description": "Additional support session", "quantity": 1, "unitAmount": 500, "amount": 500, "includedAmount": null, "usedAmount": null, "overageAmount": null, "discountType": null, "discountValue": null, "discountName": null, "chargeType": "standard" } ], "object": "invoice", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a one-off adjustment invoice and return the created invoice. Use a negative amount for a credit.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["customerId", "amount", "description"] } } } } } }, "/markets/{id}": { "get": { "operationId": "get-market", "summary": "Get market", "tags": ["Markets"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" }, "example": { "id": "market_1a2b3c4d", "name": "North America", "countryCodes": ["US", "CA"], "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "market", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get one reusable market.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-market", "summary": "Update market", "tags": ["Markets"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" }, "example": { "id": "market_1a2b3c4d", "name": "North America", "countryCodes": ["US", "CA"], "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "market", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Replace the name, countries, and metadata of a market.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "countryCodes": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "countryCodes"], "additionalProperties": false } } } } }, "delete": { "operationId": "delete-market", "summary": "Delete market", "tags": ["Markets"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "market_1a2b3c4d", "deleted": true, "object": "market", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Delete an unused market. Markets referenced by prices or subscriptions cannot be deleted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/markets": { "get": { "operationId": "list-markets", "summary": "List markets", "tags": ["Markets"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "market_1a2b3c4d", "name": "North America", "countryCodes": ["US", "CA"], "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "market", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List reusable country groups that resolve market-specific prices independently from currency." }, "post": { "operationId": "create-market", "summary": "Create market", "tags": ["Markets"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" }, "example": { "id": "market_1a2b3c4d", "name": "North America", "countryCodes": ["US", "CA"], "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "market", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a reusable market without attaching it to a plan or price. Countries can belong to only one active market.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "countryCodes": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "countryCodes"], "additionalProperties": false } } } } } }, "/offers/{id}": { "get": { "operationId": "get-offer", "summary": "Get offer", "tags": ["Offers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" }, "example": { "id": "offer_1a2b3c4d", "name": "Launch discount", "phases": [ { "type": "percentage", "durationCycles": 3, "durationInterval": "monthly", "percentage": 20 } ], "metadata": {}, "startsAt": null, "endsAt": null, "active": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "offer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve reusable offer terms by public ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-offer", "summary": "Update offer", "tags": ["Offers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" }, "example": { "id": "offer_1a2b3c4d", "name": "Launch discount", "phases": [ { "type": "percentage", "durationCycles": 3, "durationInterval": "monthly", "percentage": 20 } ], "metadata": {}, "startsAt": null, "endsAt": null, "active": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "offer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Replace reusable offer terms. Existing applications keep their immutable accepted terms.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phases": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["type", "durationDays"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "percentage": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "Discount in basis points. 5000 means 50%." } }, "required": ["type", "durationCycles", "percentage"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "amounts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"] } } }, "required": ["type", "durationCycles", "amounts"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "prices": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"] } } }, "required": ["type", "durationCycles", "prices"] } ] } }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "startsAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "default": true, "type": "boolean" } }, "required": ["name", "phases"] } } } } }, "delete": { "operationId": "delete-offer", "summary": "Delete offer", "tags": ["Offers"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedOffer" }, "example": { "deleted": true, "object": "offer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Soft-delete an Offer. Existing applications and their accepted terms remain available for billing and audit.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/offers": { "get": { "operationId": "list-offers", "summary": "List offers", "tags": ["Offers"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "offer_1a2b3c4d", "name": "Launch discount", "phases": [ { "type": "percentage", "durationCycles": 3, "durationInterval": "monthly", "percentage": 20 } ], "metadata": {}, "startsAt": null, "endsAt": null, "active": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "offer", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List reusable offer terms. Offers are independent from plans, prices, eligibility, and distribution channels.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" } } ] }, "post": { "operationId": "create-offer", "summary": "Create offer", "tags": ["Offers"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" }, "example": { "id": "offer_1a2b3c4d", "name": "Launch discount", "phases": [ { "type": "percentage", "durationCycles": 3, "durationInterval": "monthly", "percentage": 20 } ], "metadata": {}, "startsAt": null, "endsAt": null, "active": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "offer", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create reusable offer terms without assigning a plan, price, eligibility rule, or distribution channel.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phases": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["type", "durationDays"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "percentage": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "Discount in basis points. 5000 means 50%." } }, "required": ["type", "durationCycles", "percentage"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "amounts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"] } } }, "required": ["type", "durationCycles", "amounts"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "prices": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"] } } }, "required": ["type", "durationCycles", "prices"] } ] } }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "startsAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "default": null, "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "default": true, "type": "boolean" } }, "required": ["name", "phases"] } } } } } }, "/payments/{id}/cancel": { "post": { "operationId": "cancel-payment", "summary": "Cancel a payment link", "tags": ["Payments"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_1a2b3c4d", "customerId": "cus_1a2b3c4d", "kind": "link", "status": "canceled", "provider": "commet", "amountSubtotal": 2000, "taxAmount": 0, "amountTotal": 2000, "currency": "usd", "description": "Onboarding session", "metadata": {}, "url": null, "expiresAt": "2026-09-07T13:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "payment", "livemode": false, "paymentContext": { "reason": "one_time_payment", "paymentLinkId": "pay_1a2b3c4d", "recovery": null } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Cancel a pending payment link so it can no longer be paid. Only a link that has not been paid or started processing can be canceled; canceling an already canceled link is a no-op. Charges cannot be canceled.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/payments/{id}": { "get": { "operationId": "get-payment", "summary": "Get payment", "tags": ["Payments"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_1a2b3c4d", "customerId": "cus_1a2b3c4d", "kind": "link", "status": "pending", "provider": "commet", "amountSubtotal": 2000, "taxAmount": 0, "amountTotal": 2000, "currency": "usd", "description": "Onboarding session", "metadata": {}, "url": "https://commet.co/checkout/example_payment_token", "expiresAt": "2026-09-07T13:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "payment", "livemode": false, "paymentContext": { "reason": "one_time_payment", "paymentLinkId": "pay_1a2b3c4d", "recovery": null } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a payment by its public ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/payments/charge": { "post": { "operationId": "charge-payment", "summary": "Charge a customer", "tags": ["Payments"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_1a2b3c4d", "customerId": "cus_1a2b3c4d", "kind": "charge", "status": "succeeded", "provider": "commet", "amountSubtotal": 2000, "taxAmount": 0, "amountTotal": 2000, "currency": "usd", "description": "Onboarding session", "metadata": {}, "url": null, "expiresAt": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "payment", "livemode": false, "paymentContext": { "reason": "one_time_payment", "paymentLinkId": null, "recovery": null } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Charge a customer's vaulted payment method off-session. Calculates tax, generates an invoice, and sends a receipt. Requires the customer to have a subscription in active, trialing, or past_due state.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": ["customerId", "amount", "currency", "description"] } } } } } }, "/payments": { "get": { "operationId": "list-payments", "summary": "List payments", "tags": ["Payments"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "pay_1a2b3c4d", "customerId": "cus_1a2b3c4d", "kind": "link", "status": "pending", "provider": "commet", "amountSubtotal": 2000, "taxAmount": 0, "amountTotal": 2000, "currency": "usd", "description": "Onboarding session", "metadata": {}, "url": "https://commet.co/checkout/example_payment_token", "expiresAt": "2026-09-07T13:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "payment", "livemode": false, "paymentContext": { "reason": "one_time_payment", "paymentLinkId": "pay_1a2b3c4d", "recovery": null } } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List payments with cursor-based pagination. Filter by customer.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "create-payment", "summary": "Create a payment link", "tags": ["Payments"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_1a2b3c4d", "customerId": "cus_1a2b3c4d", "kind": "link", "status": "pending", "provider": "commet", "amountSubtotal": 2000, "taxAmount": 0, "amountTotal": 2000, "currency": "usd", "description": "Onboarding session", "metadata": {}, "url": "https://commet.co/checkout/example_payment_token", "expiresAt": "2026-09-07T13:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "payment", "livemode": false, "paymentContext": { "reason": "one_time_payment", "paymentLinkId": "pay_1a2b3c4d", "recovery": null } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a hosted payment link. Returns a url the customer opens to pay with any card. Calculates tax, generates an invoice, and vaults the payment method on confirmation. No subscription or plan required.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "customerId": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "successUrl": { "type": "string", "format": "uri" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": ["amount", "currency", "description"] } } } } } }, "/payouts/bank-accounts": { "post": { "operationId": "add-payout-bank-account", "summary": "Add a payout bank account", "tags": ["Payouts"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutBankAccount" }, "example": { "id": "bank_1a2b3c4d", "providerExternalAccountId": "ba_example", "holderName": "Example Software LLC", "last4": "6789", "bankName": "Example Bank", "country": "US", "currency": "usd", "accountType": "checking", "isDefault": true, "status": "active", "createdAt": "2026-09-07T12:00:00.000Z", "object": "payout_bank_account", "livemode": true } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Add an additional destination bank account to the organization's existing payout account. Country and currency are resolved from the organization. The full account number is never returned — only `last4`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "accountHolderName": { "type": "string", "minLength": 1 }, "routingNumber": { "type": "string" }, "accountType": { "type": "string", "enum": ["checking", "savings"] }, "setDefault": { "default": false, "type": "boolean" } }, "required": ["accountNumber", "accountHolderName"] } } } } } }, "/payouts": { "post": { "operationId": "request-payout", "summary": "Request a payout", "tags": ["Payouts"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "example": { "id": "payout_1a2b3c4d", "status": "pending", "amount": 10000, "fee": 0, "netAmount": 10000, "currency": "usd", "description": "September payout", "providerTransferId": "transfer_example", "createdAt": "2026-09-07T12:00:00.000Z", "object": "payout", "livemode": true } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Withdraw available balance to the organization's verified payout account. `amount` is in cents (USD, minimum 1000 = $10). The payout is created in `pending` and settles to `paid` asynchronously as provider webhooks arrive.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1000, "maximum": 9007199254740991 }, "description": { "type": "string", "maxLength": 500 } }, "required": ["amount"] } } } } } }, "/payouts/verification": { "post": { "operationId": "complete-payout-verification", "summary": "Deprecated payout verification", "tags": ["Payouts"], "x-commet-representation": "result", "responses": { "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "410": { "description": "Gone", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "endpoint_deprecated", "message": "This endpoint is no longer available. Use the replacement documented for this API version.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/endpoint_deprecated.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Deprecated. Complete business and identity verification in the Commet dashboard. This endpoint no longer accepts or processes KYC data.", "deprecated": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ] } }, "/plan-groups/{id}/plans/{planId}": { "delete": { "operationId": "remove-plan-from-group", "summary": "Remove plan from group", "tags": ["Plan Groups"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedPlanFromGroup" }, "example": { "id": "plan_1a2b3c4d", "removed": true, "object": "plan_group_membership", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Remove a plan from a plan group.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plan-groups/{id}/plans/reorder": { "put": { "operationId": "reorder-plans-in-group", "summary": "Reorder plans in group", "tags": ["Plan Groups"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderedPlans" }, "example": { "reordered": true, "object": "plan_group_order", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set the display order of plans within a group. All plan IDs in the group must be provided.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": ["planIds"] } } } } } }, "/plan-groups/{id}/plans": { "post": { "operationId": "add-plan-to-group", "summary": "Add plan to group", "tags": ["Plan Groups"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddedPlanToGroup" }, "example": { "success": true, "object": "plan_group_membership", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Add an existing plan to a plan group with optional sort order.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "minLength": 1 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["planId"] } } } } } }, "/plan-groups/{id}": { "get": { "operationId": "get-plan-group", "summary": "Get plan group", "tags": ["Plan Groups"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGroupDetail" }, "example": { "id": "group_1a2b3c4d", "name": "API plans", "description": "Plans for the API", "isPublic": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_group", "livemode": false, "plans": [ { "id": "plan_1a2b3c4d", "name": "Pro", "sortOrder": 0 } ] } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a plan group by ID, including its plans ordered by sortOrder.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-plan-group", "summary": "Update plan group", "tags": ["Plan Groups"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGroup" }, "example": { "id": "group_1a2b3c4d", "name": "API plans", "description": "Plans for the API", "isPublic": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_group", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a plan group's name, description, or visibility.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPublic": { "type": "boolean" } } } } } } }, "delete": { "operationId": "delete-plan-group", "summary": "Delete plan group", "tags": ["Plan Groups"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "group_1a2b3c4d", "deleted": true, "object": "plan_group", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Delete a plan group. Plans in the group are unlinked, not deleted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plan-groups": { "get": { "operationId": "list-plan-groups", "summary": "List plan groups", "tags": ["Plan Groups"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanGroup" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "group_1a2b3c4d", "name": "API plans", "description": "Plans for the API", "isPublic": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_group", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List plan groups with cursor-based pagination.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "create-plan-group", "summary": "Create plan group", "tags": ["Plan Groups"], "x-commet-representation": "summary", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGroup" }, "example": { "id": "group_1a2b3c4d", "name": "API plans", "description": "Plans for the API", "isPublic": true, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_group", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new plan group for organizing plans.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "isPublic": { "type": "boolean" } }, "required": ["name"] } } } } } }, "/plans/{id}/features/{featureId}": { "patch": { "operationId": "update-plan-feature", "summary": "Update plan feature", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanFeature" }, "example": { "planId": "plan_1a2b3c4d", "featureId": "feat_1a2b3c4d", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "unitPrice": 0 }, "creditsPerUnit": null, "pricingMode": "fixed", "margin": null, "object": "plan_feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update limits, overage, or enabled status of a feature on a plan.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "includedAmount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlimited": { "type": "boolean" }, "overage": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unitPrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "creditsPerUnit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } } } } } } }, "delete": { "operationId": "remove-plan-feature", "summary": "Remove feature from plan", "tags": ["Plans"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedPlanFeature" }, "example": { "id": "feat_1a2b3c4d", "removed": true, "object": "plan_feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Detach a feature from a plan.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plans/{id}/features": { "post": { "operationId": "add-plan-feature", "summary": "Add feature to plan", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanFeature" }, "example": { "planId": "plan_1a2b3c4d", "featureId": "feat_1a2b3c4d", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "unitPrice": 0 }, "creditsPerUnit": null, "pricingMode": "fixed", "margin": null, "object": "plan_feature", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Attach a feature to a plan with limits, overage, and credits configuration.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "featureId": { "type": "string", "minLength": 1 }, "enabled": { "default": true, "type": "boolean" }, "includedAmount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlimited": { "default": false, "type": "boolean" }, "overage": { "default": { "enabled": false, "unitPrice": 0 }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "unitPrice": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "creditsPerUnit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pricingMode": { "default": "fixed", "type": "string", "enum": ["fixed", "ai_model"] }, "margin": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["featureId"] } } } } } }, "/plans/{id}/prices/{priceId}/default": { "put": { "operationId": "set-default-plan-price", "summary": "Set default price", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPrice" }, "example": { "id": "price_1a2b3c4d", "planId": "plan_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_price", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set a specific price as the default and return the updated plan price.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plans/{id}/prices/{priceId}/regional": { "put": { "operationId": "upsert-regional-prices", "summary": "Upsert regional prices", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRegionalPricing" }, "example": { "priceId": "price_1a2b3c4d", "overrides": [ { "currency": "eur", "price": 1800 } ], "object": "plan_regional_pricing", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create or update regional currency price overrides for a plan price.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overrides": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 1 }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "includedBalance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["currency", "price"] } } }, "required": ["overrides"] } } } } }, "delete": { "operationId": "delete-regional-prices", "summary": "Delete regional prices", "tags": ["Plans"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedPlanRegionalPricing" }, "example": { "deleted": true, "object": "plan_regional_pricing", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Remove all regional currency overrides for a plan price. The request is rejected while billable subscriptions depend on an override.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plans/{id}/prices/{priceId}": { "patch": { "operationId": "update-plan-price", "summary": "Update plan price", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPrice" }, "example": { "id": "price_1a2b3c4d", "planId": "plan_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_price", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a base price or market price variant. Removing a base market override is rejected while a variant depends on it. Offer terms are managed through Offers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isDefault": { "type": "boolean" }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "includedBalance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedCredits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "description": "Metadata keys to merge into the existing price metadata.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "marketPrices": { "type": "array", "items": { "type": "object", "properties": { "marketGroupId": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "enum": [ "usd", "ars", "brl", "clp", "cop", "pen", "uyu", "pyg", "bob", "mxn", "cad", "eur", "gbp", "jpy", "cny", "krw", "hkd", "sgd", "twd", "inr", "thb" ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["marketGroupId", "currency", "price"], "additionalProperties": false } } }, "additionalProperties": false } } } } }, "delete": { "operationId": "delete-plan-price", "summary": "Archive plan price", "tags": ["Plans"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "price_1a2b3c4d", "deleted": true, "object": "plan_price", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Archive a price for new subscriptions. Existing subscriptions that selected it continue using its current catalog value.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plans/{id}/prices": { "post": { "operationId": "add-plan-price", "summary": "Add price to plan", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPrice" }, "example": { "id": "price_1a2b3c4d", "planId": "plan_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "plan_price", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Add a base price or a selectable market price variant. Variants inherit their base price outside the markets they override. Configure introductory and promotional benefits through Offers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "billingInterval": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isDefault": { "type": "boolean" }, "includedBalance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedCredits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "marketPrices": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "marketGroupId": { "type": "string", "minLength": 1, "description": "Public ID of a reusable pricing market group." }, "currency": { "type": "string", "enum": [ "usd", "ars", "brl", "clp", "cop", "pen", "uyu", "pyg", "bob", "mxn", "cad", "eur", "gbp", "jpy", "cny", "krw", "hkd", "sgd", "twd", "inr", "thb" ], "description": "Presentment currency configured for this plan and market." }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Market price in the currency's minor unit." } }, "required": ["marketGroupId", "currency", "price"], "additionalProperties": false } } }, "required": ["billingInterval", "price"], "additionalProperties": false, "description": "A base price. Market prices are optional overrides; currency pricing remains the fallback elsewhere." }, { "type": "object", "properties": { "billingInterval": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inheritsFromPriceId": { "type": "string", "minLength": 1 }, "marketPrices": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "marketGroupId": { "type": "string", "minLength": 1, "description": "Public ID of a reusable pricing market group." }, "currency": { "type": "string", "enum": [ "usd", "ars", "brl", "clp", "cop", "pen", "uyu", "pyg", "bob", "mxn", "cad", "eur", "gbp", "jpy", "cny", "krw", "hkd", "sgd", "twd", "inr", "thb" ], "description": "Presentment currency configured for this plan and market." }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Market price in the currency's minor unit." } }, "required": ["marketGroupId", "currency", "price"], "additionalProperties": false } } }, "required": [ "billingInterval", "inheritsFromPriceId", "marketPrices" ], "additionalProperties": false, "description": "A selectable market price variant. It inherits the base terms and must override at least one market already configured on the base price." } ] } } } } } }, "/plans/{id}/regional": { "put": { "operationId": "set-plan-regional-pricing", "summary": "Set plan regional pricing", "tags": ["Plans"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRegionalPricingResult" }, "example": { "planId": "plan_1a2b3c4d", "currency": "eur", "exchangeRate": 0.9, "pricesConfigured": 1, "featuresConfigured": 1, "object": "plan_regional_pricing", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Configure regional prices and feature overage values for one currency. Currency-specific offer terms are managed through Offers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "ars", "brl", "clp", "cop", "pen", "uyu", "pyg", "bob", "mxn", "cad", "eur", "gbp", "jpy", "cny", "krw", "hkd", "sgd", "twd", "inr", "thb" ] }, "exchangeRate": { "type": "number", "exclusiveMinimum": 0 }, "prices": { "type": "array", "items": { "type": "object", "properties": { "priceId": { "type": "string" }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "includedBalance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["priceId", "price"] } }, "features": { "type": "array", "items": { "type": "object", "properties": { "featureId": { "type": "string" }, "overageUnitPrice": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["featureId", "overageUnitPrice"] } } }, "required": ["currency", "exchangeRate"], "additionalProperties": false } } } } } }, "/plans/{id}": { "get": { "operationId": "get-plan", "summary": "Get plan", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_1a2b3c4d", "name": "Pro", "code": "pro", "description": "For growing API products", "consumptionModel": "metered", "isPublic": true, "isDefault": false, "isFree": false, "blockOnExhaustion": true, "sortOrder": 0, "planGroupId": "group_1a2b3c4d", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "unitName": "calls", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "model": null, "unitPrice": null }, "regionalPrices": [] } ], "prices": [ { "id": "price_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "regionalPrices": [] } ], "exchangeRates": [], "object": "plan", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get a plan with public price IDs and their automatic introductory offer IDs.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-plan", "summary": "Update plan", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_1a2b3c4d", "name": "Pro", "code": "pro", "description": "For growing API products", "consumptionModel": "metered", "isPublic": true, "isDefault": false, "isFree": false, "blockOnExhaustion": true, "sortOrder": 0, "planGroupId": "group_1a2b3c4d", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "unitName": "calls", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "model": null, "unitPrice": null }, "regionalPrices": [] } ], "prices": [ { "id": "price_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "regionalPrices": [] } ], "exchangeRates": [], "object": "plan", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a plan's name, description, visibility, or metadata.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "isPublic": { "type": "boolean" } } } } } } }, "delete": { "operationId": "delete-plan", "summary": "Delete plan", "tags": ["Plans"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "plan_1a2b3c4d", "deleted": true, "object": "plan", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Soft-delete a plan.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plans/{id}/visibility": { "put": { "operationId": "set-plan-visibility", "summary": "Set plan visibility", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_1a2b3c4d", "name": "Pro", "code": "pro", "description": "For growing API products", "consumptionModel": "metered", "isPublic": false, "isDefault": false, "isFree": false, "blockOnExhaustion": true, "sortOrder": 0, "planGroupId": "group_1a2b3c4d", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "unitName": "calls", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "model": null, "unitPrice": null }, "regionalPrices": [] } ], "prices": [ { "id": "price_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "regionalPrices": [] } ], "exchangeRates": [], "object": "plan", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set a plan's public visibility and return the updated plan.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "type": "boolean" } }, "required": ["isPublic"] } } } } } }, "/plans": { "get": { "operationId": "list-plans", "summary": "List plans", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "plan_1a2b3c4d", "name": "Pro", "code": "pro", "description": "For growing API products", "consumptionModel": "metered", "isPublic": true, "isDefault": false, "isFree": false, "blockOnExhaustion": true, "sortOrder": 0, "planGroupId": "group_1a2b3c4d", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "unitName": "calls", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "model": null, "unitPrice": null }, "regionalPrices": [] } ], "prices": [ { "id": "price_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "regionalPrices": [] } ], "exchangeRates": [], "object": "plan", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List plans with public price IDs and their automatic introductory offer IDs.", "parameters": [ { "name": "includePrivate", "in": "query", "required": false, "schema": { "type": "boolean" } } ] }, "post": { "operationId": "create-plan", "summary": "Create plan", "tags": ["Plans"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_1a2b3c4d", "name": "Pro", "code": "pro", "description": "For growing API products", "consumptionModel": "metered", "isPublic": true, "isDefault": false, "isFree": false, "blockOnExhaustion": true, "sortOrder": 0, "planGroupId": "group_1a2b3c4d", "metadata": {}, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "unitName": "calls", "enabled": true, "includedAmount": 1000, "unlimited": false, "overage": { "enabled": false, "model": null, "unitPrice": null }, "regionalPrices": [] } ], "prices": [ { "id": "price_1a2b3c4d", "billingInterval": "monthly", "price": 2000, "isDefault": true, "trialDays": 0, "includedBalance": null, "includedCredits": null, "offerId": null, "inheritsFromPriceId": null, "metadata": {}, "marketPrices": [], "regionalPrices": [] } ], "exchangeRates": [], "object": "plan", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new plan with optional consumption model, visibility, and plan group assignment.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }, "description": { "type": "string" }, "consumptionModel": { "type": "string", "enum": ["metered", "credits", "balance"] }, "isPublic": { "type": "boolean" }, "isFree": { "type": "boolean" }, "blockOnExhaustion": { "type": "boolean" }, "planGroupId": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "code"] } } } } } }, "/portal/sessions": { "post": { "operationId": "request-portal-access", "summary": "Request portal access", "tags": ["Portal"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalAccess" }, "example": { "portalUrl": "https://commet.co/portal/example_portal_token", "object": "portal_session", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Generate a customer portal URL. Exactly one identifier (email or customerId) is required.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "returnUrl": { "type": "string" } }, "required": ["email"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "returnUrl": { "type": "string" } }, "required": ["customerId"], "additionalProperties": false } ] } } } } } }, "/promo-codes/{id}": { "get": { "operationId": "get-promo-code", "summary": "Get promo code", "tags": ["Promo Codes"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" }, "example": { "id": "promo_1a2b3c4d", "code": "LAUNCH20", "offerId": "offer_1a2b3c4d", "billingInterval": "monthly", "maxRedemptions": 100, "expiresAt": null, "isActive": true, "redemptionCount": 0, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "promo_code", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a promo code by its public ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-promo-code", "summary": "Update promo code", "tags": ["Promo Codes"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" }, "example": { "id": "promo_1a2b3c4d", "code": "LAUNCH20", "offerId": "offer_1a2b3c4d", "billingInterval": "monthly", "maxRedemptions": 100, "expiresAt": null, "isActive": true, "redemptionCount": 0, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "promo_code", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a promo code's billing interval, redemption limits, expiration, active status, or plan restrictions.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "maxRedemptions": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "planIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } } } }, "/promo-codes": { "get": { "operationId": "list-promo-codes", "summary": "List promo codes", "tags": ["Promo Codes"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromoCode" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "promo_1a2b3c4d", "code": "LAUNCH20", "offerId": "offer_1a2b3c4d", "billingInterval": "monthly", "maxRedemptions": 100, "expiresAt": null, "isActive": true, "redemptionCount": 0, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "promo_code", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List promo codes with cursor-based pagination.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "create-promo-code", "summary": "Create promo code", "tags": ["Promo Codes"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" }, "example": { "id": "promo_1a2b3c4d", "code": "LAUNCH20", "offerId": "offer_1a2b3c4d", "billingInterval": "monthly", "maxRedemptions": 100, "expiresAt": null, "isActive": true, "redemptionCount": 0, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "promo_code", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a distribution code for an existing Offer. The referenced Offer owns the benefit and duration; the promo code owns redemption restrictions.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "offerId": { "type": "string", "minLength": 1 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "maxRedemptions": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "format": "date-time" }, "planIds": { "type": "array", "items": { "type": "string" } } }, "required": ["code", "offerId"], "additionalProperties": false } } } } } }, "/seats/balance": { "get": { "operationId": "get-seat-balance", "summary": "Get seat balance", "tags": ["Seats"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatBalance" }, "example": { "current": 3, "asOf": "2026-09-07T12:00:00.000Z", "object": "seat_balance", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get current balance for a specific seat type.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "featureCode", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/seats/balances": { "get": { "operationId": "get-all-seat-balances", "summary": "Get all seat balances", "tags": ["Seats"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatBalanceCollection" }, "example": { "balances": { "team_seats": { "current": 3, "asOf": "2026-09-07T12:00:00.000Z" } }, "object": "seat_balance_collection", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get the current balance for all seat types in a customer's subscription.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/seats/bulk": { "put": { "operationId": "bulk-set-seats", "summary": "Bulk set seats", "tags": ["Seats"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeatEvent" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "seat_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "team_seats", "previousBalance": 2, "newBalance": 3, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "seat_event", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set all seat types at once.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "seats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": ["customerId", "seats"] } } } } } }, "/seats/remove": { "post": { "operationId": "remove-seats", "summary": "Remove seats", "tags": ["Seats"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatEvent" }, "example": { "id": "seat_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "team_seats", "previousBalance": 3, "newBalance": 2, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "seat_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Remove seats from a customer's subscription. Takes effect at the end of the billing period.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["customerId", "featureCode", "count"] } } } } } }, "/seats": { "post": { "operationId": "add-seats", "summary": "Add seats", "tags": ["Seats"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatEvent" }, "example": { "id": "seat_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "team_seats", "previousBalance": 2, "newBalance": 3, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "seat_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Add seats to a customer's subscription. Prorates charges for the current billing period.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["customerId", "featureCode", "count"] } } } } }, "put": { "operationId": "set-seats", "summary": "Set seats", "tags": ["Seats"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatEvent" }, "example": { "id": "seat_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "team_seats", "previousBalance": 2, "newBalance": 3, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "seat_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set seats to an exact count.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["customerId", "featureCode", "count"] } } } } } }, "/subscriptions/{id}/addons/{addonId}": { "delete": { "operationId": "deactivate-addon", "summary": "Deactivate add-on", "tags": ["Add-ons"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedSubscriptionAddon" }, "example": { "id": "addon_1a2b3c4d", "status": "inactive", "deactivatedAt": "2026-09-07T12:00:00.000Z", "object": "subscription_addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Deactivate an add-on from a subscription.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "addonId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/addons": { "post": { "operationId": "activate-addon", "summary": "Activate add-on", "tags": ["Add-ons"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAddon" }, "example": { "addonId": "addon_1a2b3c4d", "status": "active", "proratedCharge": 1000, "object": "subscription_addon", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Activate an add-on on a subscription. Charges a prorated amount for the current billing period.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addonId": { "type": "string", "minLength": 1 } }, "required": ["addonId"] } } } } } }, "/subscriptions/{id}/balance/adjust": { "post": { "operationId": "adjust-balance", "summary": "Adjust balance", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceAdjustment" }, "example": { "amount": 500, "newBalance": 1500, "reason": "Service credit", "object": "balance_transaction", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Adjust a subscription's balance or credits by a signed amount. Positive adds, negative subtracts.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "type": { "default": "balance", "type": "string", "enum": ["credits", "balance"] } }, "required": ["amount"] } } } } } }, "/subscriptions/{id}/balance/topup": { "post": { "operationId": "topup-balance", "summary": "Top up balance", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopup" }, "example": { "amount": 2000, "object": "balance_topup", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Top up a subscription's balance. Charges the customer's payment method for the specified amount.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["amount"] } } } } } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "cancel-subscription", "summary": "Cancel subscription", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": { "scheduledAt": "2026-09-07T12:00:00.000Z", "reason": "Customer requested cancellation", "effectiveAt": "2026-10-07T12:00:00.000Z" }, "cancelAtPeriodEnd": true, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Cancel immediately or at period end and return the updated subscription.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "immediate": { "type": "boolean" } } } } } } } }, "/subscriptions/{id}/change-plan": { "post": { "operationId": "change-plan", "summary": "Change plan", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanChange" }, "example": { "outcome": "requires_checkout", "requiresCheckout": true, "checkoutUrl": "https://commet.co/checkout/example_plan_change_token", "object": "plan_change", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Upgrade or change billing interval immediately, optionally applying an Offer. Scheduled changes do not accept offers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newPlanId": { "type": "string", "minLength": 1 }, "newBillingInterval": { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "type": "string", "minLength": 1 } } } } } } } }, "/subscriptions/{id}/credits": { "post": { "operationId": "purchase-credits", "summary": "Purchase credits", "tags": ["Credit Packs"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditGrant" }, "example": { "credits": 1000, "object": "credit_grant", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Purchase a credit pack for a subscription. Charges the customer and adds credits to their balance.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditPackId": { "type": "string", "minLength": 1 } }, "required": ["creditPackId"] } } } } } }, "/subscriptions/{id}/offer": { "put": { "operationId": "apply-subscription-offer", "summary": "Apply an Offer to a subscription", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [ { "id": "application_1a2b3c4d", "name": "Launch discount", "appliesTo": { "type": "plan_price", "id": "price_1a2b3c4d" }, "offerId": "offer_1a2b3c4d", "source": "direct", "status": "applied", "currency": "usd", "subtotal": 2000, "discountAmount": 400, "total": 1600, "phases": [ { "type": "percentage", "durationCycles": 3, "durationInterval": "monthly", "percentage": 20, "startsAt": "2026-09-07T12:00:00.000Z", "endsAt": "2026-12-07T12:00:00.000Z" } ], "quotedAt": "2026-09-07T12:00:00.000Z", "expiresAt": null, "appliedAt": "2026-09-07T12:00:00.000Z" } ], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Apply a direct Offer to a subscription. On a pending payment checkout it quotes or replaces the checkout discount and the existing checkout URL remains unchanged. On an active subscription it applies the Offer immediately with its discount phases starting at the next billing cycle; the call is rejected while another applied Offer still has active or upcoming discount phases. Offers with a free trial phase cannot be applied after checkout creation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offerId": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["offerId"] } } } } }, "delete": { "operationId": "remove-subscription-offer", "summary": "Remove an Offer from a pending checkout", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Remove the quoted direct Offer from a subscription's pending payment checkout. The existing checkout URL remains unchanged and returns to its undiscounted price.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/pause": { "post": { "operationId": "pause-subscription", "summary": "Pause subscription", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "paused", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": null, "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": { "status": "active", "mode": "immediate", "requestedAt": "2026-09-07T12:00:00.000Z", "effectiveAt": "2026-09-07T12:00:00.000Z", "resumeAt": "2026-10-07T12:00:00.000Z" }, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Pause immediately or schedule a pause for the end of the current billing or trial period. Set durationDays to null for an indefinite pause.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["immediate", "period_end"] }, "durationDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["mode", "durationDays"], "additionalProperties": false } } } } }, "patch": { "operationId": "update-subscription-pause", "summary": "Update subscription pause", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "paused", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": null, "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": { "status": "active", "mode": "immediate", "requestedAt": "2026-09-07T12:00:00.000Z", "effectiveAt": "2026-09-07T12:00:00.000Z", "resumeAt": "2026-11-07T12:00:00.000Z" }, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Change the duration of a scheduled or active pause. Set durationDays to null to make it indefinite.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "durationDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["durationDays"], "additionalProperties": false } } } } }, "delete": { "operationId": "revoke-subscription-pause", "summary": "Revoke scheduled pause", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Revoke a pause before it becomes effective. Active pauses must be resumed instead.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/payment-method/update": { "post": { "operationId": "update-payment-method", "summary": "Update payment method", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodUpdateCheckout" }, "example": { "checkoutUrl": "https://commet.co/checkout/example_payment_method_token", "object": "checkout_session", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Creates a hosted checkout session for the customer to update the subscription's default payment method.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "successUrl": { "type": "string", "format": "uri" } } } } } } } }, "/subscriptions/{id}/preview-change": { "post": { "operationId": "preview-change-plan", "summary": "Preview plan change", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewChange" }, "example": { "currency": "usd", "currentPlanCredit": 2000, "newPlanCharge": 4000, "estimatedTotal": 2000, "effectiveDate": "2026-09-07T12:00:00.000Z", "daysRemaining": 30, "totalDays": 30, "isUpgrade": true, "object": "plan_change_preview", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "minLength": 1 }, "billingInterval": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, "offerId": { "type": "string", "minLength": 1 } }, "required": ["planId"] } } } } } }, "/subscriptions/{id}/reactivate": { "post": { "operationId": "reactivate-subscription", "summary": "Reactivate a past due or canceled subscription", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactivatedSubscription" }, "example": { "subscriptionId": "sub_1a2b3c4d", "invoiceId": "inv_1a2b3c4d", "status": "processing", "object": "subscription_reactivation", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Reactivates a subscription. A past_due subscription retries its outstanding renewal charge (recovering to active on success). A canceled subscription generates a fresh invoice, charges the saved card, and resets the billing period. On a successful charge the subscription becomes active; a declined charge returns an error with a recoveryUrl in the error details that can be sent to the customer to update their card. A canceled subscription may apply an Offer by offerId; past-due recovery cannot.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "offerId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } } } }, "/subscriptions/{id}/recovery-links": { "post": { "operationId": "create-subscription-recovery-link", "summary": "Create a recovery payment link for a past due subscription", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryLink" }, "example": { "url": "https://commet.co/recovery/example_recovery_token", "token": "example_recovery_token", "object": "recovery_link", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Generates a hosted, signed recovery link that lets the customer pay the outstanding renewal charge for a past_due subscription. Unlike reactivate, which charges server-to-server, this returns a link the merchant can deliver through their own email, SMS, or dashboard. The link carries a self-contained signed token and stays valid until the charge is paid or the subscription is no longer past due.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/resume": { "post": { "operationId": "resume-subscription", "summary": "Resume subscription", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResume" }, "example": { "subscriptionId": "sub_1a2b3c4d", "invoiceId": "inv_1a2b3c4d", "status": "processing", "object": "subscription_resume", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Resume a paused subscription. Immediate pauses continue the preserved period without a charge. Period-end pauses charge a new period before access is restored.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}": { "get": { "operationId": "get-subscription", "summary": "Get subscription by ID", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get a subscription by its public ID, regardless of status (including pending_payment and past_due).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/uncancel": { "post": { "operationId": "uncancel-subscription", "summary": "Revert scheduled cancellation", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Revert a scheduled cancellation and return the updated subscription. Only works before cancellation takes effect.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/active": { "get": { "operationId": "get-active-subscription", "summary": "Get active subscription", "tags": ["Subscriptions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "null" } ] }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get the active subscription for a customer. Returns null if none.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions": { "get": { "operationId": "list-subscriptions", "summary": "List subscriptions", "tags": ["Subscriptions"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionSummary" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro" }, "name": "Pro", "description": null, "status": "active", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": "2026-10-07T12:00:00.000Z", "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List all subscriptions. Filter by customer ID or status.", "parameters": [ { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SubscriptionStatus" } } ] }, "post": { "operationId": "create-subscription", "summary": "Create subscription", "tags": ["Subscriptions"], "x-commet-representation": "result", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedSubscription" }, "example": { "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro" }, "name": "Pro", "description": null, "status": "pending_payment", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": null, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": null, "nextBillingDate": null, "checkoutUrl": "https://commet.co/checkout/example_checkout_token", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": null, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "checkoutProvider": "commet" } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a subscription for a customer. Commet selects the default price when priceId is omitted and resolves its market from the customer's billing country. Without an offer override, Commet applies the price's automatic introductory Offer. Pass offerId to apply an active compatible Offer directly, or cardPromotionId to preselect a card-eligible Promotional Offer for the initial checkout when card promotions are enabled for the organization. For the initial checkout, provider accepts either a processor name or an exact payment connection ID.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "not": {} }, "promoCode": { "type": "string", "minLength": 1 }, "customTrialDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipTrial": { "default": false, "type": "boolean" }, "planId": { "type": "string", "minLength": 1 } }, "required": ["customerId", "planId"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "not": {} }, "promoCode": { "type": "string", "minLength": 1 }, "customTrialDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipTrial": { "default": false, "type": "boolean" }, "planCode": { "type": "string", "minLength": 1 } }, "required": ["customerId", "planCode"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "type": "string", "minLength": 1 }, "promoCode": { "not": {} }, "customTrialDays": { "not": {} }, "skipTrial": { "default": false, "type": "boolean", "const": false }, "planId": { "type": "string", "minLength": 1 } }, "required": ["customerId", "offerId", "planId"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "type": "string", "minLength": 1 }, "promoCode": { "not": {} }, "customTrialDays": { "not": {} }, "skipTrial": { "default": false, "type": "boolean", "const": false }, "planCode": { "type": "string", "minLength": 1 } }, "required": ["customerId", "offerId", "planCode"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "not": {} }, "cardPromotionId": { "type": "string", "minLength": 1, "description": "Public card promotion ID. The offer is shown immediately and remains conditional on card eligibility until checkout confirmation." }, "promoCode": { "not": {} }, "customTrialDays": { "not": {} }, "skipTrial": { "default": false, "type": "boolean", "const": false }, "planId": { "type": "string", "minLength": 1 } }, "required": ["customerId", "cardPromotionId", "planId"], "additionalProperties": false }, { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly", "one_time" ] }, { "type": "null" } ] }, "priceId": { "description": "Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.", "type": "string", "minLength": 1 }, "initialSeats": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "provider": { "anyOf": [ { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, { "type": "string", "pattern": "^pcon_.*" } ], "description": "Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present." }, "name": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "successUrl": { "type": "string", "format": "uri" }, "offerId": { "not": {} }, "cardPromotionId": { "type": "string", "minLength": 1, "description": "Public card promotion ID. The offer is shown immediately and remains conditional on card eligibility until checkout confirmation." }, "promoCode": { "not": {} }, "customTrialDays": { "not": {} }, "skipTrial": { "default": false, "type": "boolean", "const": false }, "planCode": { "type": "string", "minLength": 1 } }, "required": ["customerId", "cardPromotionId", "planCode"], "additionalProperties": false } ] } } } } } }, "/test-clock/process-billing": { "post": { "operationId": "process-test-clock-billing", "summary": "Deprecated manual billing processing", "tags": ["Test Clock"], "x-commet-representation": "result", "responses": { "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "410": { "description": "Gone", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "endpoint_deprecated", "message": "This endpoint is no longer available. Use the replacement documented for this API version.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/endpoint_deprecated.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Deprecated. POST /test-clock now advances time and processes every due billing deadline in one durable run.", "deprecated": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ] } }, "/test-clock": { "get": { "operationId": "get-test-clock", "summary": "Get test clock state", "tags": ["Test Clock"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClock" }, "example": { "simulatedTime": "2026-09-07T12:00:00.000Z", "isActive": true, "now": "2026-09-07T12:00:00.000Z", "latestRun": null, "object": "test_clock", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Returns the organization's current test clock state and latest durable run. Sandbox only." }, "post": { "operationId": "advance-test-clock", "summary": "Advance test clock", "tags": ["Test Clock"], "x-commet-representation": "resource", "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockRun" }, "example": { "id": "run_1a2b3c4d", "status": "pending", "startedAtTime": "2026-09-07T12:00:00.000Z", "targetTime": "2026-10-07T12:00:00.000Z", "estimatedDeadlineCount": 1, "completedDeadlineCount": 0, "failedDeadlineCount": 0, "error": null, "items": [], "object": "test_clock_run", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Starts a durable run that moves the test clock forward and processes every billing deadline due before the target time. Poll GET /test-clock for progress and terminal results. Sandbox only.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "advanceDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["advanceDays"], "additionalProperties": false }, { "type": "object", "properties": { "frozenTime": { "type": "string", "format": "date-time" } }, "required": ["frozenTime"], "additionalProperties": false } ] } } } } } }, "/transactions/{id}/refund": { "post": { "operationId": "refund-transaction", "summary": "Refund transaction", "tags": ["Transactions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "ref_1a2b3c4d", "transactionId": "txn_1a2b3c4d", "amount": 2000, "currency": "usd", "chargeId": "charge_1a2b3c4d", "status": "succeeded", "reason": "requested_by_customer", "object": "refund", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Issue a full refund and return the provider-neutral refund resource with its actual status.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/transactions/{id}/retry": { "post": { "operationId": "retry-transaction", "summary": "Retry transaction", "tags": ["Transactions"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRetry" }, "example": { "originalTransactionId": "txn_5e6f7a8b", "invoiceId": "inv_1a2b3c4d", "status": "processing", "object": "transaction_retry", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Retry a failed subscription renewal and return an honest retry result. The original failed transaction remains immutable.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/transactions/{id}": { "get": { "operationId": "get-transaction", "summary": "Get transaction", "tags": ["Transactions"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "example": { "id": "txn_1a2b3c4d", "invoiceId": "inv_1a2b3c4d", "grossAmount": 2000, "subtotal": 2000, "taxAmount": 0, "presentmentAmount": 2000, "currency": "usd", "provider": "commet", "status": "succeeded", "customerEmail": "user@example.com", "customerName": "user@example.com", "paidAt": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "availableAt": null, "object": "transaction", "livemode": false, "paymentContext": { "reason": "recurring_billing", "paymentLinkId": null, "recovery": null } } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a single payment transaction by its public ID, including provider details.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/transactions": { "get": { "operationId": "list-transactions", "summary": "List transactions", "tags": ["Transactions"], "x-commet-representation": "summary", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionListItem" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "txn_1a2b3c4d", "invoiceId": "inv_1a2b3c4d", "grossAmount": 2000, "subtotal": 2000, "taxAmount": 0, "presentmentAmount": 2000, "currency": "usd", "provider": "commet", "status": "succeeded", "customerEmail": "user@example.com", "customerName": "user@example.com", "paidAt": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "object": "transaction", "livemode": false, "paymentContext": { "reason": "recurring_billing", "paymentLinkId": null, "recovery": null } } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List payment transactions with cursor-based pagination. Filter by status or customer email.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "customerEmail", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/usage/check": { "post": { "operationId": "check-usage-availability", "summary": "Check usage availability", "tags": ["Usage"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageCheck" }, "example": { "allowed": true, "subscriptionStatus": "active", "featureCode": "api_calls", "quantity": 1, "consumptionModel": "metered", "current": 250, "remaining": 750, "unlimited": false, "included": 1000, "overageEnabled": false, "overageUnitPrice": null, "object": "usage_check", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Check if a customer can consume a feature before actual consumption. Returns availability and cost estimates based on the plan's consumption model.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "quantity": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["customerId", "featureCode"] } } } } } }, "/usage/events": { "post": { "operationId": "track-usage", "summary": "Track usage event", "tags": ["Usage"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEvent" }, "example": { "id": "usage_1a2b3c4d", "featureCode": "api_calls", "value": 1, "customerId": "cus_1a2b3c4d", "eventId": "request_123", "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "properties": [ { "property": "endpoint", "value": "/v1/search" } ], "object": "usage_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "402": { "description": "Payment required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "payment_failed", "message": "The payment could not be completed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/payment_failed.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Track a usage event for a metered feature. Deducts from balance/credits if applicable.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "timestamp": { "type": "string", "format": "date-time" }, "properties": { "default": [], "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["property", "value"] } }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "value": { "not": {} }, "cacheReadTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheWriteTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "featureCode", "customerId", "model", "inputTokens", "outputTokens" ], "additionalProperties": false }, { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "timestamp": { "type": "string", "format": "date-time" }, "properties": { "default": [], "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["property", "value"] } }, "value": { "default": 1, "type": "number", "minimum": 0 }, "model": { "not": {} }, "inputTokens": { "not": {} }, "outputTokens": { "not": {} }, "cacheReadTokens": { "not": {} }, "cacheWriteTokens": { "not": {} } }, "required": ["featureCode", "customerId"], "additionalProperties": false } ] } } } } } }, "/usage/quota/all": { "get": { "operationId": "get-all-quota-allowances", "summary": "List quota allowances", "tags": ["Quota"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageQuota" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "featureCode": "projects", "current": 3, "included": 10, "remaining": 7, "billedQuantity": 0, "unlimited": false, "overageEnabled": false, "asOf": "2026-09-07T12:00:00.000Z", "object": "usage_quota", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get all quota allowances for a customer across every quota feature in their plan.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/usage/quota/remove": { "post": { "operationId": "remove-quota", "summary": "Remove quota", "tags": ["Quota"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQuotaEvent" }, "example": { "id": "quota_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "projects", "previousBalance": 3, "newBalance": 2, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "usage_quota_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Remove from a customer's quota allowance for a feature. Defaults to 1 if count is omitted. Returns 400 insufficient_balance if the balance would go negative.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "customerId"], "additionalProperties": false }, { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "externalId"], "additionalProperties": false } ] } } } } } }, "/usage/quota": { "get": { "operationId": "get-quota-allowance", "summary": "Get quota allowance", "tags": ["Quota"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQuota" }, "example": { "featureCode": "projects", "current": 3, "included": 10, "remaining": 7, "billedQuantity": 0, "unlimited": false, "overageEnabled": false, "asOf": "2026-09-07T12:00:00.000Z", "object": "usage_quota", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Get the current quota allowance (used vs included) for a specific feature.", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "featureCode", "in": "query", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "add-quota", "summary": "Add quota", "tags": ["Quota"], "x-commet-representation": "resource", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQuotaEvent" }, "example": { "id": "quota_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "projects", "previousBalance": 2, "newBalance": 3, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "usage_quota_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Add to a customer's quota allowance for a feature. Defaults to 1 if count is omitted.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "customerId"], "additionalProperties": false }, { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "externalId"], "additionalProperties": false } ] } } } } }, "put": { "operationId": "set-quota", "summary": "Set quota", "tags": ["Quota"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQuotaEvent" }, "example": { "id": "quota_1a2b3c4d", "customerId": "cus_1a2b3c4d", "featureCode": "projects", "previousBalance": 2, "newBalance": 3, "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "object": "usage_quota_event", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set a customer's quota allowance for a feature to an exact value.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "count", "customerId"], "additionalProperties": false }, { "type": "object", "properties": { "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["featureCode", "count", "externalId"], "additionalProperties": false } ] } } } } } }, "/usage": { "put": { "operationId": "set-usage", "summary": "Set current usage", "tags": ["Usage"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdjustment" }, "example": { "id": "usage_5e6f7a8b", "value": 200, "previousValue": 250, "adjustment": -50, "customerId": "cus_1a2b3c4d", "reason": "Correct duplicate usage events", "ts": "2026-09-07T12:00:00.000Z", "createdAt": "2026-09-07T12:00:00.000Z", "featureCode": "api_calls", "object": "usage_adjustment", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "422": { "description": "Unprocessable entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Set a metered feature's usage to an exact value for the current period. Use the Idempotency-Key header to make retries safe.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "featureCode": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_]+$" }, "value": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": ["customerId", "featureCode", "value"] } } } } } }, "/webhooks/{id}": { "get": { "operationId": "get-webhook-endpoint", "summary": "Get webhook endpoint", "tags": ["Webhooks"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "example": { "id": "wh_1a2b3c4d", "url": "https://example.com/api/webhooks/commet", "events": [ "customer.created", "subscription.activated", "payment.received" ], "description": "Billing events", "isActive": true, "apiVersion": "2026-08-27", "createdAt": "2026-09-07T12:00:00.000Z", "object": "webhook", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Retrieve a webhook endpoint by its public ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "update-webhook-endpoint", "summary": "Update webhook endpoint", "tags": ["Webhooks"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "example": { "id": "wh_1a2b3c4d", "url": "https://example.com/api/webhooks/commet", "events": [ "customer.created", "subscription.activated", "payment.received" ], "description": "Billing events", "isActive": true, "apiVersion": "2026-08-27", "createdAt": "2026-09-07T12:00:00.000Z", "object": "webhook", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Update a webhook endpoint. Only the provided fields change.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "subscription.created", "subscription.activated", "subscription.reactivated", "subscription.pause_scheduled", "subscription.pause_updated", "subscription.pause_revoked", "subscription.paused", "subscription.resumed", "subscription.resume_failed", "subscription.canceled", "subscription.updated", "subscription.plan_changed", "subscription.cancellation_scheduled", "subscription.cancellation_revoked", "subscription.plan_change_scheduled", "subscription.plan_change_revoked", "subscription.past_due", "trial.started", "trial.converted", "trial.expired", "trial.will_end", "trial.checkout_ready", "checkout.ready", "payment.received", "payment.failed", "payment.recovered", "payment.retry_failed", "payment.refunded", "payment.disputed", "payment.dispute_resolved", "payment_link.created", "payment_link.completed", "payment_link.failed", "payment_link.canceled", "invoice.created", "invoice.voided", "invoice.overdue", "invoice.upcoming", "payment_method.attached", "payment_method.updated", "customer.created", "customer.updated", "customer.state_changed", "plan_grant.created", "plan_grant.updated", "plan_grant.expired", "plan_grant.revoked", "credits.granted", "credits.purchased", "credits.low", "credits.depleted", "credits.expired", "balance.topped_up", "balance.low", "balance.depleted", "quota.threshold_reached", "quota.exceeded", "seats.updated", "seats.limit_reached", "addon.activated", "addon.deactivated", "usage.recorded", "payout.available", "payout.created", "payout.paid", "payout.failed" ] } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "apiVersion": { "type": "string" } } } } } } }, "delete": { "operationId": "delete-webhook-endpoint", "summary": "Delete webhook endpoint", "tags": ["Webhooks"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "example": { "id": "wh_1a2b3c4d", "deleted": true, "object": "webhook", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "Permanently delete a webhook endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/webhooks/{id}/test": { "post": { "operationId": "test-webhook-endpoint", "summary": "Test webhook endpoint", "tags": ["Webhooks"], "x-commet-representation": "result", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" }, "example": { "success": true, "deliveryId": "delivery_1a2b3c4d", "deliveredAt": "2026-09-07T12:00:00.000Z", "object": "webhook_delivery", "livemode": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Send a test event to a webhook endpoint to verify connectivity.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/webhooks": { "get": { "operationId": "list-webhook-endpoints", "summary": "List webhook endpoints", "tags": ["Webhooks"], "x-commet-representation": "resource", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": ["object", "data", "hasMore"], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "wh_1a2b3c4d", "url": "https://example.com/api/webhooks/commet", "events": [ "customer.created", "subscription.activated", "payment.received" ], "description": "Billing events", "isActive": true, "apiVersion": "2026-08-27", "createdAt": "2026-09-07T12:00:00.000Z", "object": "webhook", "livemode": false } ], "hasMore": false } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } } }, "description": "List webhook endpoints with cursor-based pagination.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "create-webhook-endpoint", "summary": "Create webhook endpoint", "tags": ["Webhooks"], "x-commet-representation": "result", "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhook" }, "example": { "id": "wh_1a2b3c4d", "url": "https://example.com/api/webhooks/commet", "events": [ "customer.created", "subscription.activated", "payment.received" ], "description": "Billing events", "isActive": true, "apiVersion": "2026-08-27", "createdAt": "2026-09-07T12:00:00.000Z", "object": "webhook", "livemode": false, "secretKey": "whsec_example_not_a_real_signing_secret" } } } }, "400": { "description": "Bad request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" } } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" } } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" } } } } }, "429": { "description": "Too many requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" } } } } } }, "description": "Create a new webhook endpoint. The response includes the signing secret which is only returned once.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key used to safely retry this write for 24 hours without applying it twice.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "subscription.created", "subscription.activated", "subscription.reactivated", "subscription.pause_scheduled", "subscription.pause_updated", "subscription.pause_revoked", "subscription.paused", "subscription.resumed", "subscription.resume_failed", "subscription.canceled", "subscription.updated", "subscription.plan_changed", "subscription.cancellation_scheduled", "subscription.cancellation_revoked", "subscription.plan_change_scheduled", "subscription.plan_change_revoked", "subscription.past_due", "trial.started", "trial.converted", "trial.expired", "trial.will_end", "trial.checkout_ready", "checkout.ready", "payment.received", "payment.failed", "payment.recovered", "payment.retry_failed", "payment.refunded", "payment.disputed", "payment.dispute_resolved", "payment_link.created", "payment_link.completed", "payment_link.failed", "payment_link.canceled", "invoice.created", "invoice.voided", "invoice.overdue", "invoice.upcoming", "payment_method.attached", "payment_method.updated", "customer.created", "customer.updated", "customer.state_changed", "plan_grant.created", "plan_grant.updated", "plan_grant.expired", "plan_grant.revoked", "credits.granted", "credits.purchased", "credits.low", "credits.depleted", "credits.expired", "balance.topped_up", "balance.low", "balance.depleted", "quota.threshold_reached", "quota.exceeded", "seats.updated", "seats.limit_reached", "addon.activated", "addon.deactivated", "usage.recorded", "payout.available", "payout.created", "payout.paid", "payout.failed" ] } }, "description": { "type": "string" }, "apiVersion": { "type": "string" } }, "required": ["url", "events"] } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "headers": { "RequestId": { "description": "Server-generated identifier that correlates this response with Platform logs.", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "FeatureType": { "type": "string", "enum": ["boolean", "usage", "seats", "quota"] }, "ActiveAddon": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "basePrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "featureCode": { "type": "string" }, "featureName": { "type": "string" }, "featureType": { "$ref": "#/components/schemas/FeatureType" }, "consumptionModel": { "type": "string", "enum": ["boolean", "metered", "credits", "balance"] }, "activatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "subscription_addon" }, "livemode": { "type": "boolean" } }, "required": [ "slug", "name", "basePrice", "featureCode", "featureName", "featureType", "consumptionModel", "activatedAt", "object", "livemode" ], "additionalProperties": false }, "Addon": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "basePrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "featureCode": { "type": "string" }, "featureName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "consumptionModel": { "type": "string", "enum": ["boolean", "metered", "credits", "balance"] }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overageRate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "creditCost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "object": { "type": "string", "const": "addon" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "slug", "description", "basePrice", "featureCode", "featureName", "createdAt", "updatedAt", "consumptionModel", "includedUnits", "overageRate", "creditCost", "object", "livemode" ], "additionalProperties": false }, "DeletedObject": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "object": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": ["id", "deleted", "object", "livemode"], "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "api_key" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "prefix", "expiresAt", "lastUsedAt", "createdAt", "object", "livemode" ], "additionalProperties": false }, "CreatedApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "apiKey": { "type": "string" }, "prefix": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "api_key" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "apiKey", "prefix", "expiresAt", "createdAt", "object", "livemode" ], "additionalProperties": false }, "ClaimLink": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "claim_link" }, "livemode": { "type": "boolean" } }, "required": ["url", "expiresAt", "object", "livemode"], "additionalProperties": false }, "CreditPack": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "credit_pack" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "description", "credits", "price", "isActive", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "CreditPackListItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "object": { "type": "string", "const": "credit_pack" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "description", "credits", "price", "currency", "object", "livemode" ], "additionalProperties": false }, "CustomerCreditRevocation": { "type": "object", "properties": { "id": { "type": "string" }, "remainingAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "revokedAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "object": { "type": "string", "const": "customer_credit" }, "livemode": { "type": "boolean" } }, "required": [ "id", "remainingAmount", "revokedAmount", "currency", "object", "livemode" ], "additionalProperties": false }, "CustomerCredit": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Original grant amount in the currency's smallest unit." }, "appliedAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reversedAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "revokedAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remainingAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string", "enum": ["dashboard", "api", "plan_change", "migration"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "customer_credit" }, "livemode": { "type": "boolean" } }, "required": [ "id", "amount", "appliedAmount", "reversedAmount", "revokedAmount", "remainingAmount", "currency", "reason", "source", "expiresAt", "createdAt", "object", "livemode" ], "additionalProperties": false }, "PlanGrant": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "subscriptionId": { "type": "string" }, "basePlanId": { "type": "string" }, "planId": { "type": "string" }, "planReleaseId": { "type": "string" }, "status": { "type": "string", "enum": ["active", "expired", "revoked"] }, "duration": { "type": "string", "enum": ["cycles", "until_date", "until_revoked"] }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "startsAt": { "type": "string", "format": "date-time" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reason": { "type": "string" }, "source": { "type": "string", "enum": ["dashboard", "api"] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["created", "updated", "expired", "revoked"] }, "reason": { "type": "string" }, "source": { "type": "string", "enum": ["dashboard", "api", "system"] }, "previousExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "string", "enum": ["cycles", "until_date", "until_revoked"] }, { "type": "null" } ] }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "requestedExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "reason", "source", "previousExpiresAt", "expiresAt", "duration", "durationCycles", "requestedExpiresAt", "createdAt" ], "additionalProperties": false } }, "object": { "type": "string", "const": "plan_grant" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "subscriptionId", "basePlanId", "planId", "planReleaseId", "status", "duration", "durationCycles", "startsAt", "expiresAt", "reason", "source", "revokedAt", "createdAt", "updatedAt", "events", "object", "livemode" ], "additionalProperties": false }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "taxDocument": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "documentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "customer" }, "livemode": { "type": "boolean" } }, "required": [ "id", "externalId", "fullName", "email", "taxDocument", "documentType", "timezone", "metadata", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "Timezone": { "default": "UTC", "type": "string", "enum": [ "UTC", "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Sao_Paulo", "America/Mexico_City", "America/Buenos_Aires", "America/Santiago", "America/Bogota", "America/Lima", "America/Asuncion", "Europe/London", "Europe/Paris", "Europe/Berlin", "Europe/Madrid", "Asia/Tokyo", "Asia/Shanghai", "Asia/Singapore", "Asia/Dubai", "Australia/Sydney" ] }, "CustomerBatch": { "type": "object", "properties": { "successful": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" } }, "required": ["id", "externalId", "email"], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "error": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "email": { "type": "string" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxDocument": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" } }, "required": ["line1", "city", "postalCode", "country"], "additionalProperties": false } }, "required": ["email"], "additionalProperties": false } }, "required": ["index", "error", "data"], "additionalProperties": false } }, "object": { "type": "string", "const": "customer_batch" }, "livemode": { "type": "boolean" } }, "required": ["successful", "failed", "object", "livemode"], "additionalProperties": false }, "FeatureAccess": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Unique feature code." }, "name": { "type": "string", "description": "Display name of the feature." }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for one product unit, or null when not applicable." }, "allowed": { "type": "boolean", "description": "Whether the customer can currently access or consume the feature." }, "type": { "type": "string", "const": "boolean" }, "enabled": { "type": "boolean", "description": "Whether the feature is enabled." }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"], "additionalProperties": false }, { "type": "null" } ] }, "object": { "type": "string", "const": "feature_access" }, "livemode": { "type": "boolean" } }, "required": [ "code", "name", "unitName", "allowed", "type", "enabled", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string", "description": "Unique feature code." }, "name": { "type": "string", "description": "Display name of the feature." }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for one product unit, or null when not applicable." }, "allowed": { "type": "boolean", "description": "Whether the customer can currently access or consume the feature." }, "type": { "type": "string", "const": "usage" }, "consumption": { "oneOf": [ { "type": "object", "properties": { "model": { "type": "string", "const": "metered", "description": "Usage is measured against an included allowance and overage." }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive usage period start." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive usage period end." } }, "required": ["start", "end"], "additionalProperties": false, "description": "Time range used to calculate this feature's consumption." }, "unitsUsed": { "type": "number", "description": "Product units recorded during the period." }, "includedUnits": { "type": "number", "description": "Product units included in the subscription for the period." }, "remainingUnits": { "type": "number", "description": "Included units not yet consumed. Absent when usage is unlimited." }, "unlimited": { "type": "boolean", "description": "Whether the feature has no usage limit." }, "overage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether usage above the included amount is allowed and billed." }, "units": { "type": "number", "description": "Units consumed above the included amount." }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer rate amount. Divide by scale to obtain the price." }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." }, "scale": { "type": "number", "const": 10000, "description": "Divide amount by scale to obtain the major-unit price." } }, "required": ["amount", "currency", "scale"], "additionalProperties": false, "description": "Price for one additional product unit." } }, "required": ["enabled", "units"], "additionalProperties": false } }, "required": [ "model", "period", "unitsUsed", "includedUnits", "unlimited", "overage" ], "additionalProperties": false }, { "type": "object", "properties": { "model": { "type": "string", "const": "credits", "description": "Product usage consumes credits from a shared pool." }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive usage period start." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive usage period end." } }, "required": ["start", "end"], "additionalProperties": false, "description": "Time range used to calculate this feature's consumption." }, "unitsUsed": { "type": "number", "description": "Product units recorded during the period." }, "creditsPerUnit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Credits deducted for each product unit." }, "creditsConsumed": { "type": "number", "minimum": 0, "description": "Actual credits deducted by this feature during the period." }, "availableUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Additional product units available from the current shared credit pool at this feature's conversion rate." } }, "required": [ "model", "period", "unitsUsed", "creditsPerUnit", "creditsConsumed", "availableUnits" ], "additionalProperties": false }, { "type": "object", "properties": { "model": { "type": "string", "const": "balance", "description": "Product usage deducts money from a shared balance." }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive usage period start." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive usage period end." } }, "required": ["start", "end"], "additionalProperties": false, "description": "Time range used to calculate this feature's consumption." }, "unitsUsed": { "type": "number", "description": "Product units recorded during the period." }, "spent": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's smallest unit." }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Actual money deducted for this feature during the period." }, "availableUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Estimated additional units available from the current shared balance at this feature's fixed price. Absent for dynamic pricing." }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer rate amount. Divide by scale to obtain the price." }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." }, "scale": { "type": "number", "const": 10000, "description": "Divide amount by scale to obtain the major-unit price." } }, "required": ["amount", "currency", "scale"], "additionalProperties": false, "description": "Price for one additional product unit." } }, "required": ["model", "period", "unitsUsed", "spent"], "additionalProperties": false } ] }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "includedUnits": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["includedUnits", "unlimited"], "additionalProperties": false }, { "type": "null" } ] }, "object": { "type": "string", "const": "feature_access" }, "livemode": { "type": "boolean" } }, "required": [ "code", "name", "unitName", "allowed", "type", "consumption", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string", "description": "Unique feature code." }, "name": { "type": "string", "description": "Display name of the feature." }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for one product unit, or null when not applicable." }, "allowed": { "type": "boolean", "description": "Whether the customer can currently access or consume the feature." }, "type": { "type": "string", "const": "seats" }, "usage": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive usage period start." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive usage period end." } }, "required": ["start", "end"], "additionalProperties": false, "description": "Time range used to calculate this feature's consumption." }, "unitsUsed": { "type": "number", "description": "Current units assigned or in use." }, "includedUnits": { "type": "number", "description": "Units included in the subscription for the period." }, "remainingUnits": { "type": "number", "description": "Included units still available. Absent when usage is unlimited." }, "unlimited": { "type": "boolean", "description": "Whether the feature has no usage limit." }, "overage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether usage above the included amount is allowed and billed." }, "units": { "type": "number", "description": "Units consumed above the included amount." }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer rate amount. Divide by scale to obtain the price." }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." }, "scale": { "type": "number", "const": 10000, "description": "Divide amount by scale to obtain the major-unit price." } }, "required": ["amount", "currency", "scale"], "additionalProperties": false, "description": "Price for one additional product unit." } }, "required": ["enabled", "units"], "additionalProperties": false } }, "required": [ "period", "unitsUsed", "includedUnits", "unlimited", "overage" ], "additionalProperties": false }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "includedUnits": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["includedUnits", "unlimited"], "additionalProperties": false }, { "type": "null" } ] }, "object": { "type": "string", "const": "feature_access" }, "livemode": { "type": "boolean" } }, "required": [ "code", "name", "unitName", "allowed", "type", "usage", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string", "description": "Unique feature code." }, "name": { "type": "string", "description": "Display name of the feature." }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for one product unit, or null when not applicable." }, "allowed": { "type": "boolean", "description": "Whether the customer can currently access or consume the feature." }, "type": { "type": "string", "const": "quota" }, "usage": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive usage period start." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive usage period end." } }, "required": ["start", "end"], "additionalProperties": false, "description": "Time range used to calculate this feature's consumption." }, "unitsUsed": { "type": "number", "description": "Current units assigned or in use." }, "includedUnits": { "type": "number", "description": "Units included in the subscription for the period." }, "remainingUnits": { "type": "number", "description": "Included units still available. Absent when usage is unlimited." }, "unlimited": { "type": "boolean", "description": "Whether the feature has no usage limit." }, "overage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether usage above the included amount is allowed and billed." }, "units": { "type": "number", "description": "Units consumed above the included amount." }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer rate amount. Divide by scale to obtain the price." }, "currency": { "type": "string", "description": "Lowercase ISO 4217 currency code." }, "scale": { "type": "number", "const": 10000, "description": "Divide amount by scale to obtain the major-unit price." } }, "required": ["amount", "currency", "scale"], "additionalProperties": false, "description": "Price for one additional product unit." } }, "required": ["enabled", "units"], "additionalProperties": false }, "billedUnits": { "type": "number", "description": "Highest quota reached during the period and used for billing." } }, "required": [ "period", "unitsUsed", "includedUnits", "unlimited", "overage", "billedUnits" ], "additionalProperties": false }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "includedUnits": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["includedUnits", "unlimited"], "additionalProperties": false }, { "type": "null" } ] }, "object": { "type": "string", "const": "feature_access" }, "livemode": { "type": "boolean" } }, "required": [ "code", "name", "unitName", "allowed", "type", "usage", "object", "livemode" ], "additionalProperties": false } ] }, "Feature": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "type": { "$ref": "#/components/schemas/FeatureType" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "feature" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "code", "type", "description", "unitName", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "InvoiceDownload": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "invoice_download_link" }, "livemode": { "type": "boolean" } }, "required": ["url", "expiresAt", "object", "livemode"], "additionalProperties": false }, "InvoiceType": { "type": "string", "enum": [ "recurring", "overage", "plan_change", "adjustment", "credit_purchase", "balance_topup", "addon_activation", "one_time_payment", "reactivation", "resume" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "subscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "enum": ["draft", "outstanding", "paid", "void", "uncollectible"] }, "invoiceType": { "$ref": "#/components/schemas/InvoiceType" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "issueDate": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creditApplied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "planName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "poNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "lineType": { "type": "string", "enum": [ "plan_base", "feature_overage", "feature_seats", "feature_quota", "discount", "promo_code_discount", "credit", "balance_overage", "addon_base", "one_time" ] }, "featureName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "includedAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "usedAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overageAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountValue": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "chargeType": { "type": "string", "enum": ["standard", "advance", "true_up"] } }, "required": [ "lineType", "featureName", "description", "quantity", "unitAmount", "amount", "includedAmount", "usedAmount", "overageAmount", "discountType", "discountValue", "discountName", "chargeType" ], "additionalProperties": false } }, "object": { "type": "string", "const": "invoice" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "subscriptionId", "invoiceNumber", "status", "invoiceType", "currency", "subtotal", "discountAmount", "taxAmount", "total", "periodStart", "periodEnd", "issueDate", "dueDate", "memo", "metadata", "createdAt", "updatedAt", "creditApplied", "planName", "poNumber", "reference", "lineItems", "object", "livemode" ], "additionalProperties": false }, "SentInvoice": { "type": "object", "properties": { "sent": { "type": "boolean" }, "sentAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "invoice_delivery" }, "livemode": { "type": "boolean" } }, "required": ["sent", "sentAt", "object", "livemode"], "additionalProperties": false }, "InvoiceListItem": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "subscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "enum": ["draft", "outstanding", "paid", "void", "uncollectible"] }, "invoiceType": { "$ref": "#/components/schemas/InvoiceType" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "issueDate": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "invoice" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "subscriptionId", "invoiceNumber", "status", "invoiceType", "currency", "subtotal", "discountAmount", "taxAmount", "total", "periodStart", "periodEnd", "issueDate", "dueDate", "memo", "metadata", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "Market": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "countryCodes": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "market" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "countryCodes", "metadata", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "Offer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phases": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["type", "durationDays"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "percentage": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "Discount in basis points. 5000 means 50%." } }, "required": [ "type", "durationCycles", "durationInterval", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "amounts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"], "additionalProperties": false } } }, "required": [ "type", "durationCycles", "durationInterval", "amounts" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "default": null, "description": "Unit the phase duration is counted in. Only a fixed-price phase may set it, because its amount is declared rather than derived from the plan. Defaults to the plan's own billing interval.", "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "prices": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Amount in the currency's minor unit (for example, cents for USD)." } }, "required": ["currency", "amount"], "additionalProperties": false } } }, "required": [ "type", "durationCycles", "durationInterval", "prices" ], "additionalProperties": false } ] } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "offer" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "phases", "metadata", "startsAt", "endsAt", "active", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "DeletedOffer": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "object": { "type": "string", "const": "offer" }, "livemode": { "type": "boolean" } }, "required": ["deleted", "object", "livemode"], "additionalProperties": false }, "Payment": { "type": "object", "properties": { "paymentContext": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "first_subscription_payment", "trial_conversion", "recurring_billing", "plan_change", "reactivation", "subscription_resume", "one_time_payment", "overage", "adjustment" ], "description": "The original reason for the charge. Recovery never replaces this reason." }, "paymentLinkId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public payment link ID, independently of the reason, or null when no payment link originated the charge." }, "recovery": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "payment_recovery" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "dunning_retry" }, "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Current retry, starting at 1. The original decline is not a retry." }, "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Total retries applicable to this charge's dunning schedule." } }, "required": ["type", "attempt", "maxAttempts"], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": ["reason", "paymentLinkId", "recovery"], "additionalProperties": false }, { "type": "null" } ], "description": "Charge context captured for new payments. Null for historical payments with no captured context." }, "id": { "type": "string" }, "customerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": ["link", "charge"] }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "requires_action", "failed", "canceled" ] }, "provider": { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, "amountSubtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amountTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "description": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "payment" }, "livemode": { "type": "boolean" } }, "required": [ "paymentContext", "id", "customerId", "kind", "status", "provider", "amountSubtotal", "taxAmount", "amountTotal", "currency", "description", "metadata", "url", "expiresAt", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "PayoutBankAccount": { "type": "object", "properties": { "id": { "type": "string" }, "providerExternalAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "holderName": { "type": "string" }, "last4": { "type": "string" }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" }, "currency": { "type": "string" }, "accountType": { "anyOf": [ { "type": "string", "enum": ["checking", "savings"] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": ["active", "errored"] }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "payout_bank_account" }, "livemode": { "type": "boolean" } }, "required": [ "id", "providerExternalAccountId", "holderName", "last4", "bankName", "country", "currency", "accountType", "isDefault", "status", "createdAt", "object", "livemode" ], "additionalProperties": false }, "Payout": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "in_transit", "paid", "failed", "canceled"] }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fee": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerTransferId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "payout" }, "livemode": { "type": "boolean" } }, "required": [ "id", "status", "amount", "fee", "netAmount", "currency", "description", "providerTransferId", "createdAt", "object", "livemode" ], "additionalProperties": false }, "PayoutVerification": { "type": "object", "properties": { "object": { "type": "string", "const": "payout_account" }, "livemode": { "type": "boolean" } }, "required": ["object", "livemode"], "additionalProperties": false }, "RemovedPlanFromGroup": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "boolean" }, "object": { "type": "string", "const": "plan_group_membership" }, "livemode": { "type": "boolean" } }, "required": ["id", "removed", "object", "livemode"], "additionalProperties": false }, "ReorderedPlans": { "type": "object", "properties": { "reordered": { "type": "boolean" }, "object": { "type": "string", "const": "plan_group_order" }, "livemode": { "type": "boolean" } }, "required": ["reordered", "object", "livemode"], "additionalProperties": false }, "AddedPlanToGroup": { "type": "object", "properties": { "success": { "type": "boolean" }, "object": { "type": "string", "const": "plan_group_membership" }, "livemode": { "type": "boolean" } }, "required": ["success", "object", "livemode"], "additionalProperties": false }, "PlanGroupDetail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPublic": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "name", "sortOrder"], "additionalProperties": false } }, "object": { "type": "string", "const": "plan_group" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "description", "isPublic", "createdAt", "updatedAt", "plans", "object", "livemode" ], "additionalProperties": false }, "PlanGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPublic": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "plan_group" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "description", "isPublic", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "PlanFeature": { "type": "object", "properties": { "planId": { "type": "string" }, "featureId": { "type": "string" }, "enabled": { "type": "boolean" }, "includedAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unlimited": { "type": "boolean" }, "overage": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unitPrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["enabled", "unitPrice"], "additionalProperties": false }, "creditsPerUnit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pricingMode": { "type": "string", "enum": ["fixed", "ai_model"] }, "margin": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "object": { "type": "string", "const": "plan_feature" }, "livemode": { "type": "boolean" } }, "required": [ "planId", "featureId", "enabled", "includedAmount", "unlimited", "overage", "creditsPerUnit", "pricingMode", "margin", "object", "livemode" ], "additionalProperties": false }, "RemovedPlanFeature": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "boolean", "const": true }, "object": { "type": "string", "const": "plan_feature" }, "livemode": { "type": "boolean" } }, "required": ["id", "removed", "object", "livemode"], "additionalProperties": false }, "BillingInterval": { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly", "one_time"] }, "PlanPrice": { "type": "object", "properties": { "id": { "type": "string", "description": "Public plan price ID." }, "planId": { "type": "string" }, "billingInterval": { "$ref": "#/components/schemas/BillingInterval" }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Price in the currency's minor unit (for example, cents for USD)." }, "isDefault": { "type": "boolean" }, "trialDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "includedBalance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedCredits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "offerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Automatic introductory offer for this price." }, "inheritsFromPriceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public base price ID for a market price variant, or null for a base price." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Application metadata. Variant display names may use metadata.name." }, "marketPrices": { "type": "array", "items": { "type": "object", "properties": { "marketGroupId": { "type": "string", "description": "Public pricing market group ID." }, "currency": { "type": "string", "description": "Presentment currency for this market." }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Market price in the currency's minor unit." } }, "required": ["marketGroupId", "currency", "price"], "additionalProperties": false }, "description": "Country-market overrides. Variants inherit their base price for every market not listed." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "plan_price" }, "livemode": { "type": "boolean" } }, "required": [ "id", "planId", "billingInterval", "price", "isDefault", "trialDays", "includedBalance", "includedCredits", "offerId", "inheritsFromPriceId", "metadata", "marketPrices", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "PlanRegionalPricing": { "type": "object", "properties": { "priceId": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "includedBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["currency", "price"], "additionalProperties": false } }, "object": { "type": "string", "const": "plan_regional_pricing" }, "livemode": { "type": "boolean" } }, "required": ["priceId", "overrides", "object", "livemode"], "additionalProperties": false }, "DeletedPlanRegionalPricing": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "object": { "type": "string", "const": "plan_regional_pricing" }, "livemode": { "type": "boolean" } }, "required": ["deleted", "object", "livemode"], "additionalProperties": false }, "PlanRegionalPricingResult": { "type": "object", "properties": { "planId": { "type": "string" }, "currency": { "type": "string" }, "exchangeRate": { "type": "number" }, "pricesConfigured": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "featuresConfigured": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "object": { "type": "string", "const": "plan_regional_pricing" }, "livemode": { "type": "boolean" } }, "required": [ "planId", "currency", "exchangeRate", "pricesConfigured", "featuresConfigured", "object", "livemode" ], "additionalProperties": false }, "ConsumptionModel": { "type": "string", "enum": ["metered", "credits", "balance"] }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consumptionModel": { "anyOf": [ { "$ref": "#/components/schemas/ConsumptionModel" }, { "type": "null" } ] }, "isPublic": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isFree": { "type": "boolean" }, "blockOnExhaustion": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "planGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "features": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/FeatureType" }, "unitName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "includedAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "unlimited": { "type": "boolean" }, "overage": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "anyOf": [ { "type": "string", "enum": ["per_unit"] }, { "type": "null" } ] }, "unitPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["enabled", "model", "unitPrice"], "additionalProperties": false }, { "type": "null" } ] }, "regionalPrices": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "overageUnitPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "autoSynced": { "type": "boolean" } }, "required": ["currency", "overageUnitPrice", "autoSynced"], "additionalProperties": false } } }, "required": [ "code", "name", "type", "unitName", "enabled", "includedAmount", "unlimited", "overage", "regionalPrices" ], "additionalProperties": false } }, "prices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Public plan price ID." }, "billingInterval": { "$ref": "#/components/schemas/BillingInterval" }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Price in the currency's minor unit (for example, cents for USD)." }, "isDefault": { "type": "boolean" }, "trialDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "includedBalance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedCredits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "offerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Automatic introductory offer for this price. Pass a Promotional Offer ID when creating a subscription to override it." }, "inheritsFromPriceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public base price ID for a market price variant, or null for a base price." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Application metadata. Variant display names may use metadata.name." }, "marketPrices": { "type": "array", "items": { "type": "object", "properties": { "marketGroupId": { "type": "string", "description": "Public pricing market group ID." }, "currency": { "type": "string", "description": "Presentment currency for this market." }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Market price in the currency's minor unit." } }, "required": ["marketGroupId", "currency", "price"], "additionalProperties": false }, "description": "Country-market overrides. An empty array means currency pricing and then the global USD price remain the fallback." }, "regionalPrices": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "includedBalance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "autoSynced": { "type": "boolean" } }, "required": [ "currency", "price", "includedBalance", "autoSynced" ], "additionalProperties": false } } }, "required": [ "id", "billingInterval", "price", "isDefault", "trialDays", "includedBalance", "includedCredits", "offerId", "inheritsFromPriceId", "metadata", "marketPrices", "regionalPrices" ], "additionalProperties": false } }, "exchangeRates": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "exchangeRate": { "type": "number" } }, "required": ["currency", "exchangeRate"], "additionalProperties": false } }, "object": { "type": "string", "const": "plan" }, "livemode": { "type": "boolean" } }, "required": [ "id", "name", "code", "description", "consumptionModel", "isPublic", "isDefault", "isFree", "blockOnExhaustion", "sortOrder", "planGroupId", "metadata", "createdAt", "updatedAt", "features", "prices", "exchangeRates", "object", "livemode" ], "additionalProperties": false }, "PortalAccess": { "type": "object", "properties": { "portalUrl": { "type": "string" }, "object": { "type": "string", "const": "portal_session" }, "livemode": { "type": "boolean" } }, "required": ["portalUrl", "object", "livemode"], "additionalProperties": false }, "PromoCode": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "offerId": { "type": "string" }, "billingInterval": { "anyOf": [ { "$ref": "#/components/schemas/BillingInterval" }, { "type": "null" } ] }, "maxRedemptions": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "redemptionCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "promo_code" }, "livemode": { "type": "boolean" } }, "required": [ "id", "code", "offerId", "billingInterval", "maxRedemptions", "expiresAt", "isActive", "redemptionCount", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "SeatBalance": { "type": "object", "properties": { "current": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "asOf": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "seat_balance" }, "livemode": { "type": "boolean" } }, "required": ["current", "asOf", "object", "livemode"], "additionalProperties": false }, "SeatBalanceCollection": { "type": "object", "properties": { "balances": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "current": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "asOf": { "type": "string", "format": "date-time" } }, "required": ["current", "asOf"], "additionalProperties": false } }, "object": { "type": "string", "const": "seat_balance_collection" }, "livemode": { "type": "boolean" } }, "required": ["balances", "object", "livemode"], "additionalProperties": false }, "SeatEvent": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "featureCode": { "type": "string" }, "previousBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ts": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "seat_event" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "featureCode", "previousBalance", "newBalance", "ts", "createdAt", "object", "livemode" ], "additionalProperties": false }, "DeletedSubscriptionAddon": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "inactive" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "object": { "type": "string", "const": "subscription_addon" }, "livemode": { "type": "boolean" } }, "required": ["id", "status", "deactivatedAt", "object", "livemode"], "additionalProperties": false }, "SubscriptionAddon": { "type": "object", "properties": { "addonId": { "type": "string" }, "status": { "type": "string", "const": "active" }, "proratedCharge": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "object": { "type": "string", "const": "subscription_addon" }, "livemode": { "type": "boolean" } }, "required": [ "addonId", "status", "proratedCharge", "object", "livemode" ], "additionalProperties": false }, "BalanceAdjustment": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "balance_transaction" }, "livemode": { "type": "boolean" } }, "required": ["amount", "newBalance", "reason", "object", "livemode"], "additionalProperties": false }, "BalanceTopup": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "object": { "type": "string", "const": "balance_topup" }, "livemode": { "type": "boolean" } }, "required": ["amount", "object", "livemode"], "additionalProperties": false }, "SubscriptionStatus": { "type": "string", "enum": [ "draft", "pending_payment", "trialing", "active", "past_due", "paused", "canceled" ] }, "SubscriptionOfferApplication": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "appliesTo": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "plan_price" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "addon" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "credit_pack" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false } ] }, "offerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "direct", "introductory", "promo_code", "card_promotion", "custom" ] }, "status": { "type": "string", "enum": ["quoted", "applied", "failed", "expired"] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtotal": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "phases": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionOfferApplicationPhase" } }, "quotedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "appliedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "appliesTo", "offerId", "source", "status", "currency", "subtotal", "discountAmount", "total", "phases", "quotedAt", "expiresAt", "appliedAt" ], "additionalProperties": false }, "SubscriptionOfferApplicationPhase": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "durationInterval": { "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationDays", "durationInterval", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "percentage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationCycles", "durationInterval", "percentage", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationCycles", "durationInterval", "amount", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"] }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationCycles", "durationInterval", "price", "startsAt", "endsAt" ], "additionalProperties": false } ] }, "Subscription": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "basePrice": { "type": "number" } }, "required": ["id", "name", "basePrice"], "additionalProperties": false }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "billingInterval": { "anyOf": [ { "$ref": "#/components/schemas/BillingInterval" }, { "type": "null" } ] }, "trialEndsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "currentPeriod": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "daysRemaining": { "type": "number" } }, "required": ["start", "end", "daysRemaining"], "additionalProperties": false }, { "type": "null" } ] }, "cancellation": { "anyOf": [ { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effectiveAt": { "type": "string", "format": "date-time" } }, "required": ["scheduledAt", "reason", "effectiveAt"], "additionalProperties": false }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" }, "scheduledPlanChange": { "anyOf": [ { "type": "object", "properties": { "changeType": { "type": "string", "enum": ["plan_downgrade", "interval_change"] }, "newPlanId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newPlanName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newBillingInterval": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" } }, "required": [ "changeType", "newPlanId", "newPlanName", "newBillingInterval", "scheduledFor" ], "additionalProperties": false }, { "type": "null" } ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "billingDayOfMonth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextBillingDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkoutUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "offerApplications": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionOfferApplication" } }, "pause": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "scheduled" }, "mode": { "type": "string", "const": "period_end" }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "active" }, "mode": { "type": "string", "enum": ["immediate", "period_end"] }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "planGrant": { "type": "object", "properties": { "id": { "type": "string", "description": "The active Plan Grant ID." }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false, "description": "The higher plan whose access is temporarily applied." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the temporary access ends, or null when it lasts until revoked." } }, "required": ["id", "plan", "expiresAt"], "additionalProperties": false }, "consumptionModel": { "anyOf": [ { "$ref": "#/components/schemas/ConsumptionModel" }, { "type": "null" } ] }, "features": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "boolean" }, "enabled": { "type": "boolean" }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["code", "name", "type", "enabled"], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "usage" }, "usage": { "type": "object", "properties": { "current": { "type": "number" }, "included": { "type": "number" }, "overageQuantity": { "type": "number" }, "overageUnitPrice": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["current", "included", "overageQuantity"], "additionalProperties": false }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["included", "unlimited"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["code", "name", "type"], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "seats" }, "usage": { "type": "object", "properties": { "current": { "type": "number" }, "included": { "type": "number" }, "overageQuantity": { "type": "number" }, "overageUnitPrice": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["current", "included", "overageQuantity"], "additionalProperties": false }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["included", "unlimited"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["code", "name", "type", "usage"], "additionalProperties": false }, { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "quota" }, "usage": { "type": "object", "properties": { "current": { "type": "number" }, "included": { "type": "number" }, "overageQuantity": { "type": "number" }, "overageUnitPrice": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["current", "included", "overageQuantity"], "additionalProperties": false }, "baseAccess": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "number" }, "unlimited": { "type": "boolean" } }, "required": ["included", "unlimited"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["code", "name", "type"], "additionalProperties": false } ] } }, "credits": { "anyOf": [ { "type": "object", "properties": { "remaining": { "type": "number" }, "included": { "type": "number" }, "purchased": { "type": "number" } }, "required": ["remaining", "included", "purchased"], "additionalProperties": false }, { "type": "null" } ] }, "balance": { "anyOf": [ { "type": "object", "properties": { "remaining": { "type": "number" }, "included": { "type": "number" }, "currency": { "type": "string" } }, "required": ["remaining", "included", "currency"], "additionalProperties": false }, { "type": "null" } ] }, "priceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "subscription" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "plan", "name", "description", "status", "billingInterval", "trialEndsAt", "currentPeriod", "cancellation", "cancelAtPeriodEnd", "scheduledPlanChange", "startDate", "endDate", "billingDayOfMonth", "nextBillingDate", "checkoutUrl", "createdAt", "updatedAt", "offerApplications", "pause", "consumptionModel", "features", "credits", "balance", "priceId", "object", "livemode" ], "additionalProperties": false }, "PlanChange": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "const": "requires_checkout" }, "requiresCheckout": { "type": "boolean", "const": true }, "checkoutUrl": { "type": "string" }, "offerApplication": { "type": "object", "properties": { "id": { "type": "string" }, "offerId": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Subtotal in the currency's minor unit." }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Discount in the currency's minor unit." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total in the currency's minor unit." }, "phases": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationDays", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "percentage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Discount in basis points. 5000 means 50%." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Discount in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Fixed price in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "price" ], "additionalProperties": false } ] } }, "appliesTo": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "plan_price" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "addon" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "credit_pack" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false } ] } }, "required": [ "id", "offerId", "name", "currency", "subtotal", "discountAmount", "total", "phases", "appliesTo" ], "additionalProperties": false }, "object": { "type": "string", "const": "plan_change" }, "livemode": { "type": "boolean" } }, "required": [ "outcome", "requiresCheckout", "checkoutUrl", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "scheduled" }, "id": { "type": "string" }, "scheduled": { "type": "boolean", "const": true }, "scheduledFor": { "type": "string", "format": "date-time" }, "changeType": { "type": "string", "enum": [ "subscription.plan_downgrade", "subscription.interval_change", "subscription.cancel" ] }, "customerId": { "type": "string" }, "newPlanId": { "type": "string" }, "newPlanName": { "type": "string" }, "newBillingInterval": { "type": "string" }, "seatLimitWarning": { "type": "object", "properties": { "featureCode": { "type": "string" }, "featureName": { "type": "string" }, "currentSeats": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "included": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newPlanName": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date-time" } }, "required": [ "featureCode", "featureName", "currentSeats", "included", "newPlanName", "effectiveDate" ], "additionalProperties": false }, "object": { "type": "string", "const": "plan_change" }, "livemode": { "type": "boolean" } }, "required": [ "outcome", "id", "scheduled", "scheduledFor", "changeType", "customerId", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "completed" }, "id": { "type": "string" }, "scheduled": { "type": "boolean", "const": false }, "customerId": { "type": "string" }, "previousPlan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false }, "currentPlan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "name", "price"], "additionalProperties": false }, "billingInterval": { "type": "string" }, "billing": { "type": "object", "properties": { "credit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "creditsApplied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "charge": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "netAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalCharged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remainingCreditBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "credit", "creditsApplied", "charge", "taxAmount", "netAmount", "totalCharged", "remainingCreditBalance" ], "additionalProperties": false }, "invoiceId": { "type": "string" }, "offerApplication": { "type": "object", "properties": { "id": { "type": "string" }, "offerId": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Subtotal in the currency's minor unit." }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Discount in the currency's minor unit." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total in the currency's minor unit." }, "phases": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationDays", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "percentage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Discount in basis points. 5000 means 50%." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Discount in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Fixed price in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "price" ], "additionalProperties": false } ] } }, "appliesTo": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "plan_price" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "addon" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "credit_pack" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false } ] } }, "required": [ "id", "offerId", "name", "currency", "subtotal", "discountAmount", "total", "phases", "appliesTo" ], "additionalProperties": false }, "object": { "type": "string", "const": "plan_change" }, "livemode": { "type": "boolean" } }, "required": [ "outcome", "id", "scheduled", "customerId", "previousPlan", "currentPlan", "billingInterval", "billing", "object", "livemode" ], "additionalProperties": false } ] }, "CreditGrant": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "object": { "type": "string", "const": "credit_grant" }, "livemode": { "type": "boolean" } }, "required": ["credits", "object", "livemode"], "additionalProperties": false }, "PaymentMethodUpdateCheckout": { "type": "object", "properties": { "checkoutUrl": { "type": "string" }, "object": { "type": "string", "const": "checkout_session" }, "livemode": { "type": "boolean" } }, "required": ["checkoutUrl", "object", "livemode"], "additionalProperties": false }, "PreviewChange": { "type": "object", "properties": { "currency": { "type": "string" }, "currentPlanCredit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newPlanCharge": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "estimatedTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "effectiveDate": { "type": "string", "format": "date-time" }, "daysRemaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isUpgrade": { "type": "boolean" }, "offerApplication": { "type": "object", "properties": { "id": { "type": "string" }, "offerId": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Subtotal in the currency's minor unit." }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Discount in the currency's minor unit." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total in the currency's minor unit." }, "phases": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationDays", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "percentage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Discount in basis points. 5000 means 50%." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Discount in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Fixed price in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "price" ], "additionalProperties": false } ] } }, "appliesTo": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "plan_price" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "addon" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "credit_pack" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false } ] } }, "required": [ "id", "offerId", "name", "currency", "subtotal", "discountAmount", "total", "phases", "appliesTo" ], "additionalProperties": false }, "object": { "type": "string", "const": "plan_change_preview" }, "livemode": { "type": "boolean" } }, "required": [ "currency", "currentPlanCredit", "newPlanCharge", "estimatedTotal", "effectiveDate", "daysRemaining", "totalDays", "isUpgrade", "object", "livemode" ], "additionalProperties": false }, "ReactivatedSubscription": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "invoiceId": { "type": "string" }, "status": { "type": "string", "enum": ["processing", "succeeded"] }, "offerApplication": { "type": "object", "properties": { "id": { "type": "string" }, "offerId": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Subtotal in the currency's minor unit." }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Discount in the currency's minor unit." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total in the currency's minor unit." }, "phases": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "free_trial" }, "durationDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "type", "durationDays", "startsAt", "endsAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "percentage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Discount in basis points. 5000 means 50%." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "amount_off" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Discount in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_price" }, "durationCycles": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationInterval": { "anyOf": [ { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Fixed price in the application currency's minor unit." } }, "required": [ "type", "durationCycles", "durationInterval", "startsAt", "endsAt", "price" ], "additionalProperties": false } ] } }, "appliesTo": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "plan_price" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "addon" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "credit_pack" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false } ] } }, "required": [ "id", "offerId", "name", "currency", "subtotal", "discountAmount", "total", "phases", "appliesTo" ], "additionalProperties": false }, "object": { "type": "string", "const": "subscription_reactivation" }, "livemode": { "type": "boolean" } }, "required": [ "subscriptionId", "invoiceId", "status", "object", "livemode" ], "additionalProperties": false }, "RecoveryLink": { "type": "object", "properties": { "url": { "type": "string" }, "token": { "type": "string" }, "object": { "type": "string", "const": "recovery_link" }, "livemode": { "type": "boolean" } }, "required": ["url", "token", "object", "livemode"], "additionalProperties": false }, "SubscriptionResume": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["processing", "succeeded"] }, "object": { "type": "string", "const": "subscription_resume" }, "livemode": { "type": "boolean" } }, "required": [ "subscriptionId", "invoiceId", "status", "object", "livemode" ], "additionalProperties": false }, "SubscriptionSummary": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "billingInterval": { "anyOf": [ { "$ref": "#/components/schemas/BillingInterval" }, { "type": "null" } ] }, "trialEndsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "currentPeriod": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "daysRemaining": { "type": "number" } }, "required": ["start", "end", "daysRemaining"], "additionalProperties": false }, { "type": "null" } ] }, "cancellation": { "anyOf": [ { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effectiveAt": { "type": "string", "format": "date-time" } }, "required": ["scheduledAt", "reason", "effectiveAt"], "additionalProperties": false }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" }, "scheduledPlanChange": { "anyOf": [ { "type": "object", "properties": { "changeType": { "type": "string", "enum": ["plan_downgrade", "interval_change"] }, "newPlanId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newPlanName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newBillingInterval": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" } }, "required": [ "changeType", "newPlanId", "newPlanName", "newBillingInterval", "scheduledFor" ], "additionalProperties": false }, { "type": "null" } ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "billingDayOfMonth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextBillingDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkoutUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "offerApplications": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionOfferApplication" } }, "pause": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "scheduled" }, "mode": { "type": "string", "const": "period_end" }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "active" }, "mode": { "type": "string", "enum": ["immediate", "period_end"] }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "priceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "subscription" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "plan", "name", "description", "status", "billingInterval", "trialEndsAt", "currentPeriod", "cancellation", "cancelAtPeriodEnd", "scheduledPlanChange", "startDate", "endDate", "billingDayOfMonth", "nextBillingDate", "checkoutUrl", "createdAt", "updatedAt", "offerApplications", "pause", "priceId", "object", "livemode" ], "additionalProperties": false }, "PaymentProvider": { "type": "string", "enum": ["stripe", "commet", "dlocal"] }, "CreatedSubscription": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "billingInterval": { "anyOf": [ { "$ref": "#/components/schemas/BillingInterval" }, { "type": "null" } ] }, "trialEndsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "currentPeriod": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "daysRemaining": { "type": "number" } }, "required": ["start", "end", "daysRemaining"], "additionalProperties": false }, { "type": "null" } ] }, "cancellation": { "anyOf": [ { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effectiveAt": { "type": "string", "format": "date-time" } }, "required": ["scheduledAt", "reason", "effectiveAt"], "additionalProperties": false }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" }, "scheduledPlanChange": { "anyOf": [ { "type": "object", "properties": { "changeType": { "type": "string", "enum": ["plan_downgrade", "interval_change"] }, "newPlanId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newPlanName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "newBillingInterval": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" } }, "required": [ "changeType", "newPlanId", "newPlanName", "newBillingInterval", "scheduledFor" ], "additionalProperties": false }, { "type": "null" } ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "billingDayOfMonth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextBillingDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkoutUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "offerApplications": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionOfferApplication" } }, "pause": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "scheduled" }, "mode": { "type": "string", "const": "period_end" }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "active" }, "mode": { "type": "string", "enum": ["immediate", "period_end"] }, "requestedAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "resumeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "status", "mode", "requestedAt", "effectiveAt", "resumeAt" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "checkoutProvider": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProvider" }, { "type": "null" } ], "description": "Payment provider resolved for this checkout when the subscription response was created. This is an informational snapshot and may differ when the checkout is loaded if its country or the organization's routing changes." }, "priceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "type": "string", "const": "subscription" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "plan", "name", "description", "status", "billingInterval", "trialEndsAt", "currentPeriod", "cancellation", "cancelAtPeriodEnd", "scheduledPlanChange", "startDate", "endDate", "billingDayOfMonth", "nextBillingDate", "checkoutUrl", "createdAt", "updatedAt", "offerApplications", "pause", "checkoutProvider", "priceId", "object", "livemode" ], "additionalProperties": false }, "DeprecatedTestClockBilling": { "type": "object", "properties": { "object": { "type": "string", "const": "test_clock" }, "livemode": { "type": "boolean" } }, "required": ["object", "livemode"], "additionalProperties": false }, "TestClock": { "type": "object", "properties": { "simulatedTime": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "now": { "type": "string", "format": "date-time" }, "latestRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed"] }, "startedAtTime": { "type": "string", "format": "date-time" }, "targetTime": { "type": "string", "format": "date-time" }, "estimatedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "completedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["billing_cycle", "dunning_retry"] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "dueAt": { "type": "string", "format": "date-time" }, "subscriptionId": { "type": "string" }, "customerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "status", "dueAt", "subscriptionId", "customerName", "invoiceNumber", "invoiceId", "outcome", "detail", "error" ], "additionalProperties": false } } }, "required": [ "id", "status", "startedAtTime", "targetTime", "estimatedDeadlineCount", "completedDeadlineCount", "failedDeadlineCount", "error", "items" ], "additionalProperties": false }, { "type": "null" } ] }, "object": { "type": "string", "const": "test_clock" }, "livemode": { "type": "boolean" } }, "required": [ "simulatedTime", "isActive", "now", "latestRun", "object", "livemode" ], "additionalProperties": false }, "TestClockRun": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed"] }, "startedAtTime": { "type": "string", "format": "date-time" }, "targetTime": { "type": "string", "format": "date-time" }, "estimatedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "completedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failedDeadlineCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["billing_cycle", "dunning_retry"] }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "dueAt": { "type": "string", "format": "date-time" }, "subscriptionId": { "type": "string" }, "customerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "status", "dueAt", "subscriptionId", "customerName", "invoiceNumber", "invoiceId", "outcome", "detail", "error" ], "additionalProperties": false } }, "object": { "type": "string", "const": "test_clock_run" }, "livemode": { "type": "boolean" } }, "required": [ "id", "status", "startedAtTime", "targetTime", "estimatedDeadlineCount", "completedDeadlineCount", "failedDeadlineCount", "error", "items", "object", "livemode" ], "additionalProperties": false }, "Refund": { "type": "object", "properties": { "id": { "type": "string" }, "transactionId": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "chargeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled" ] }, "reason": { "anyOf": [ { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }, { "type": "null" } ] }, "object": { "type": "string", "const": "refund" }, "livemode": { "type": "boolean" } }, "required": [ "id", "transactionId", "amount", "currency", "chargeId", "status", "reason", "object", "livemode" ], "additionalProperties": false }, "TransactionRetry": { "type": "object", "properties": { "originalTransactionId": { "type": "string" }, "invoiceId": { "type": "string" }, "status": { "type": "string", "enum": ["processing", "succeeded"] }, "object": { "type": "string", "const": "transaction_retry" }, "livemode": { "type": "boolean" } }, "required": [ "originalTransactionId", "invoiceId", "status", "object", "livemode" ], "additionalProperties": false }, "TransactionStatus": { "type": "string", "enum": ["pending", "succeeded", "failed", "refunded", "disputed"] }, "Transaction": { "type": "object", "properties": { "paymentContext": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "first_subscription_payment", "trial_conversion", "recurring_billing", "plan_change", "reactivation", "subscription_resume", "one_time_payment", "overage", "adjustment" ], "description": "The original reason for the charge. Recovery never replaces this reason." }, "paymentLinkId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public payment link ID, independently of the reason, or null when no payment link originated the charge." }, "recovery": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "payment_recovery" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "dunning_retry" }, "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Current retry, starting at 1. The original decline is not a retry." }, "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Total retries applicable to this charge's dunning schedule." } }, "required": ["type", "attempt", "maxAttempts"], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": ["reason", "paymentLinkId", "recovery"], "additionalProperties": false }, { "type": "null" } ], "description": "Charge context captured for new payments. Null for historical payments with no captured context." }, "id": { "type": "string" }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grossAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Gross amount in USD cents. Null when the provider has not reported an honest USD figure; see presentmentAmount." }, "subtotal": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Subtotal in USD cents (gross minus tax). Null when grossAmount is null." }, "taxAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "presentmentAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Amount in the charge currency's smallest unit, as presented to the customer. Set for non-USD charges; null when the charge was made in USD." }, "currency": { "type": "string" }, "provider": { "description": "The payment provider the charge was routed to: stripe, commet, or dlocal.", "$ref": "#/components/schemas/PaymentProvider" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "availableAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "object": { "type": "string", "const": "transaction" }, "livemode": { "type": "boolean" } }, "required": [ "paymentContext", "id", "invoiceId", "grossAmount", "subtotal", "taxAmount", "presentmentAmount", "currency", "provider", "status", "customerEmail", "customerName", "paidAt", "createdAt", "updatedAt", "availableAt", "object", "livemode" ], "additionalProperties": false }, "TransactionListItem": { "type": "object", "properties": { "paymentContext": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "first_subscription_payment", "trial_conversion", "recurring_billing", "plan_change", "reactivation", "subscription_resume", "one_time_payment", "overage", "adjustment" ], "description": "The original reason for the charge. Recovery never replaces this reason." }, "paymentLinkId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public payment link ID, independently of the reason, or null when no payment link originated the charge." }, "recovery": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "payment_recovery" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "dunning_retry" }, "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Current retry, starting at 1. The original decline is not a retry." }, "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Total retries applicable to this charge's dunning schedule." } }, "required": ["type", "attempt", "maxAttempts"], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": ["reason", "paymentLinkId", "recovery"], "additionalProperties": false }, { "type": "null" } ], "description": "Charge context captured for new payments. Null for historical payments with no captured context." }, "id": { "type": "string" }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grossAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Gross amount in USD cents. Null when the provider has not reported an honest USD figure; see presentmentAmount." }, "subtotal": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Subtotal in USD cents (gross minus tax). Null when grossAmount is null." }, "taxAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "presentmentAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Amount in the charge currency's smallest unit, as presented to the customer. Set for non-USD charges; null when the charge was made in USD." }, "currency": { "type": "string" }, "provider": { "description": "The payment provider the charge was routed to: stripe, commet, or dlocal.", "$ref": "#/components/schemas/PaymentProvider" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "transaction" }, "livemode": { "type": "boolean" } }, "required": [ "paymentContext", "id", "invoiceId", "grossAmount", "subtotal", "taxAmount", "presentmentAmount", "currency", "provider", "status", "customerEmail", "customerName", "paidAt", "createdAt", "updatedAt", "object", "livemode" ], "additionalProperties": false }, "UsageCheck": { "oneOf": [ { "type": "object", "properties": { "allowed": { "type": "boolean" }, "subscriptionStatus": { "type": "string" }, "featureCode": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "message": { "type": "string" }, "consumptionModel": { "type": "string", "const": "metered" }, "current": { "type": "number" }, "remaining": { "type": "number" }, "unlimited": { "type": "boolean" }, "included": { "type": "number" }, "overageEnabled": { "type": "boolean" }, "overageUnitPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "object": { "type": "string", "const": "usage_check" }, "livemode": { "type": "boolean" } }, "required": [ "allowed", "subscriptionStatus", "featureCode", "quantity", "consumptionModel", "current", "remaining", "unlimited", "included", "overageEnabled", "overageUnitPrice", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "allowed": { "type": "boolean" }, "subscriptionStatus": { "type": "string" }, "featureCode": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "message": { "type": "string" }, "consumptionModel": { "type": "string", "const": "credits" }, "creditsPerUnit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "estimatedCredits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "planCredits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "purchasedCredits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalCredits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "object": { "type": "string", "const": "usage_check" }, "livemode": { "type": "boolean" } }, "required": [ "allowed", "subscriptionStatus", "featureCode", "quantity", "consumptionModel", "creditsPerUnit", "estimatedCredits", "planCredits", "purchasedCredits", "totalCredits", "object", "livemode" ], "additionalProperties": false }, { "type": "object", "properties": { "allowed": { "type": "boolean" }, "subscriptionStatus": { "type": "string" }, "featureCode": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "message": { "type": "string" }, "consumptionModel": { "type": "string", "const": "balance" }, "unitPrice": { "type": "number" }, "estimatedAmount": { "type": "number" }, "currentBalance": { "type": "number" }, "blockOnExhaustion": { "type": "boolean" }, "currency": { "type": "string" }, "object": { "type": "string", "const": "usage_check" }, "livemode": { "type": "boolean" } }, "required": [ "allowed", "subscriptionStatus", "featureCode", "quantity", "consumptionModel", "unitPrice", "estimatedAmount", "currentBalance", "blockOnExhaustion", "currency", "object", "livemode" ], "additionalProperties": false } ] }, "UsageEvent": { "type": "object", "properties": { "id": { "type": "string" }, "featureCode": { "type": "string" }, "value": { "type": "number" }, "customerId": { "type": "string" }, "eventId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ts": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string" }, "value": { "type": "string" } }, "required": ["property", "value"], "additionalProperties": false } }, "consumption": { "type": "object", "properties": { "model": { "type": "string", "enum": ["credits", "balance"] }, "deducted": { "type": "number" }, "remaining": { "type": "number" }, "blocked": { "type": "boolean" } }, "required": ["model", "deducted", "remaining", "blocked"], "additionalProperties": false }, "object": { "type": "string", "const": "usage_event" }, "livemode": { "type": "boolean" } }, "required": [ "id", "featureCode", "value", "customerId", "eventId", "ts", "createdAt", "properties", "object", "livemode" ], "additionalProperties": false }, "UsageQuota": { "type": "object", "properties": { "featureCode": { "type": "string" }, "current": { "type": "number" }, "included": { "type": "number" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "billedQuantity": { "type": "number" }, "unlimited": { "type": "boolean" }, "overageEnabled": { "type": "boolean" }, "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "object": { "type": "string", "const": "usage_quota" }, "livemode": { "type": "boolean" } }, "required": [ "featureCode", "current", "included", "remaining", "billedQuantity", "unlimited", "overageEnabled", "asOf", "object", "livemode" ], "additionalProperties": false }, "UsageQuotaEvent": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "featureCode": { "type": "string" }, "previousBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newBalance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ts": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "usage_quota_event" }, "livemode": { "type": "boolean" } }, "required": [ "id", "customerId", "featureCode", "previousBalance", "newBalance", "ts", "createdAt", "object", "livemode" ], "additionalProperties": false }, "UsageAdjustment": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "previousValue": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "adjustment": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "customerId": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ts": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "featureCode": { "type": "string" }, "object": { "type": "string", "const": "usage_adjustment" }, "livemode": { "type": "boolean" } }, "required": [ "id", "value", "previousValue", "adjustment", "customerId", "reason", "ts", "createdAt", "featureCode", "object", "livemode" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "apiVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "webhook" }, "livemode": { "type": "boolean" } }, "required": [ "id", "url", "events", "description", "isActive", "apiVersion", "createdAt", "object", "livemode" ], "additionalProperties": false }, "WebhookTest": { "type": "object", "properties": { "success": { "type": "boolean" }, "deliveryId": { "type": "string" }, "deliveredAt": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "webhook_delivery" }, "livemode": { "type": "boolean" } }, "required": [ "success", "deliveryId", "deliveredAt", "object", "livemode" ], "additionalProperties": false }, "CreatedWebhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "apiVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "secretKey": { "type": "string" }, "object": { "type": "string", "const": "webhook" }, "livemode": { "type": "boolean" } }, "required": [ "id", "url", "events", "description", "isActive", "apiVersion", "createdAt", "secretKey", "object", "livemode" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "details": {}, "doc_url": { "type": "string" } }, "required": ["type", "code", "message", "doc_url"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false } } } }