{ "openapi": "3.1.0", "info": { "title": "meteroid", "description": "", "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" }, "version": "0.1.0" }, "paths": { "/api/v1/addons": { "get": { "tags": [ "Add-ons" ], "summary": "List add-ons", "operationId": "list_addons", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "Include archived add-ons in the results (default: false)", "required": false, "schema": { "type": "boolean" } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `created_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of add-ons", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Add-ons" ], "summary": "Create an add-on", "operationId": "create_addon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAddOnRequest" } } }, "required": true }, "responses": { "201": { "description": "Add-on created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOn" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/addons/{addon_id}": { "get": { "tags": [ "Add-ons" ], "summary": "Get add-on details", "operationId": "get_addon", "parameters": [ { "name": "addon_id", "in": "path", "description": "Add-on ID", "required": true, "schema": { "$ref": "#/components/schemas/AddOnId" } } ], "responses": { "200": { "description": "Add-on details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOn" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Add-on not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Add-ons" ], "summary": "Update an add-on", "operationId": "update_addon", "parameters": [ { "name": "addon_id", "in": "path", "description": "Add-on ID", "required": true, "schema": { "$ref": "#/components/schemas/AddOnId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAddOnRequest" } } }, "required": true }, "responses": { "200": { "description": "Add-on updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOn" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Add-on not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/addons/{addon_id}/archive": { "post": { "tags": [ "Add-ons" ], "summary": "Archive an add-on", "operationId": "archive_addon", "parameters": [ { "name": "addon_id", "in": "path", "description": "Add-on ID", "required": true, "schema": { "$ref": "#/components/schemas/AddOnId" } } ], "responses": { "204": { "description": "Add-on archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Add-on not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/addons/{addon_id}/entitlements": { "get": { "tags": [ "Add-ons", "Entitlements" ], "summary": "List add-on entitlements", "operationId": "list_add_on_entitlements", "parameters": [ { "name": "addon_id", "in": "path", "description": "Add-on ID", "required": true, "schema": { "$ref": "#/components/schemas/AddOnId" } } ], "responses": { "200": { "description": "Resolved entitlements for this add-on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Add-on not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/addons/{addon_id}/unarchive": { "post": { "tags": [ "Add-ons" ], "summary": "Unarchive an add-on", "operationId": "unarchive_addon", "parameters": [ { "name": "addon_id", "in": "path", "description": "Add-on ID", "required": true, "schema": { "$ref": "#/components/schemas/AddOnId" } } ], "responses": { "204": { "description": "Add-on unarchived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Add-on not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/batch-jobs": { "get": { "tags": [ "Batch Jobs" ], "summary": "List batch jobs", "description": "List batch jobs with optional filtering by type and status.", "operationId": "list_batch_jobs", "parameters": [ { "name": "job_type", "in": "query", "required": false, "schema": { "type": "string", "title": "BatchJobType", "enum": [ "EVENT_CSV_IMPORT", "CUSTOMER_CSV_IMPORT", "SUBSCRIPTION_CSV_IMPORT", "SUBSCRIPTION_PLAN_MIGRATION" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "title": "BatchJobStatus", "enum": [ "PENDING", "CHUNKING", "PROCESSING", "COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "CANCELLED" ] } } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of batch jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJobListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/batch-jobs/{batch_job_id}": { "get": { "tags": [ "Batch Jobs" ], "summary": "Get batch job detail", "description": "Retrieve a single batch job with its chunks and failures.", "operationId": "get_batch_job", "parameters": [ { "name": "batch_job_id", "in": "path", "description": "Batch job ID", "required": true, "schema": { "$ref": "#/components/schemas/BatchJobId" } } ], "responses": { "200": { "description": "Batch job detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJobDetailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Batch job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/batch-jobs/{batch_job_id}/failures": { "get": { "tags": [ "Batch Jobs" ], "summary": "List batch job failures", "description": "Retrieve paginated failures for a batch job.", "operationId": "list_batch_job_failures", "parameters": [ { "name": "batch_job_id", "in": "path", "description": "Batch job ID", "required": true, "schema": { "$ref": "#/components/schemas/BatchJobId" } }, { "name": "chunk_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BatchJobChunkId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of failures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJobFailuresResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Batch job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/checkout-sessions": { "get": { "tags": [ "Checkout Sessions" ], "summary": "List checkout sessions", "operationId": "list_checkout_sessions", "parameters": [ { "name": "customer_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CustomerId" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "title": "CheckoutSessionStatus", "enum": [ "CREATED", "AWAITING_PAYMENT", "COMPLETED", "EXPIRED", "CANCELLED" ] } } ], "responses": { "200": { "description": "List of checkout sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCheckoutSessionsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Checkout Sessions" ], "summary": "Create a checkout session", "operationId": "create_checkout_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/checkout-sessions/{id}": { "get": { "tags": [ "Checkout Sessions" ], "summary": "Get a checkout session by ID", "operationId": "get_checkout_session", "parameters": [ { "name": "id", "in": "path", "description": "Checkout session ID", "required": true, "schema": { "$ref": "#/components/schemas/CheckoutSessionId" } } ], "responses": { "200": { "description": "Checkout session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCheckoutSessionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/checkout-sessions/{id}/cancel": { "post": { "tags": [ "Checkout Sessions" ], "summary": "Cancel a checkout session", "operationId": "cancel_checkout_session", "parameters": [ { "name": "id", "in": "path", "description": "Checkout session ID", "required": true, "schema": { "$ref": "#/components/schemas/CheckoutSessionId" } } ], "responses": { "200": { "description": "Checkout session cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelCheckoutSessionResponse" } } } }, "400": { "description": "Bad request - session cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons", "operationId": "list_coupons", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "title": "CouponFilter", "enum": [ "ALL", "ACTIVE", "INACTIVE", "ARCHIVED" ] } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `code`, `created_at`, `expires_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of coupons", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Coupons" ], "summary": "Create a coupon", "operationId": "create_coupon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCouponRequest" } } }, "required": true }, "responses": { "201": { "description": "Coupon created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons/{coupon_id}": { "get": { "tags": [ "Coupons" ], "summary": "Get coupon details", "operationId": "get_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "responses": { "200": { "description": "Coupon details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Coupons" ], "summary": "Update a coupon", "operationId": "update_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCouponRequest" } } }, "required": true }, "responses": { "200": { "description": "Coupon updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons/{coupon_id}/archive": { "post": { "tags": [ "Coupons" ], "summary": "Archive a coupon", "operationId": "archive_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "responses": { "204": { "description": "Coupon archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons/{coupon_id}/disable": { "post": { "tags": [ "Coupons" ], "summary": "Disable a coupon", "operationId": "disable_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "responses": { "204": { "description": "Coupon disabled" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons/{coupon_id}/enable": { "post": { "tags": [ "Coupons" ], "summary": "Enable a coupon", "operationId": "enable_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "responses": { "204": { "description": "Coupon enabled" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/coupons/{coupon_id}/unarchive": { "post": { "tags": [ "Coupons" ], "summary": "Unarchive a coupon", "operationId": "unarchive_coupon", "parameters": [ { "name": "coupon_id", "in": "path", "description": "Coupon ID", "required": true, "schema": { "$ref": "#/components/schemas/CouponId" } } ], "responses": { "204": { "description": "Coupon unarchived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Coupon not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/credit-notes/{credit_note_id}/download": { "get": { "tags": [ "Credit Notes" ], "operationId": "download_credit_note_pdf", "parameters": [ { "name": "credit_note_id", "in": "path", "description": "Credit Note ID", "required": true, "schema": { "$ref": "#/components/schemas/CreditNoteId" }, "example": "cn_123" } ], "responses": { "200": { "description": "Credit Note PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Unused dummy struct only used for an OpenAPI definition." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Credit note not found or PDF not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "List customers with optional pagination and search filtering.", "operationId": "list_customers", "parameters": [ { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `email`, `alias`, `created_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "operationId": "create_customer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Customer successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "409": { "description": "Customer already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers/{id_or_alias}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "description": "Retrieve a single customer by ID or alias.", "operationId": "get_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "operationId": "update_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Customers" ], "summary": "Archive a customer", "description": "No linked entity will be deleted. You need to terminate all active subscriptions before archiving a customer, or the call will fail.", "operationId": "archive_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Customers" ], "summary": "Patch customer", "description": "Partially update a customer. Only provided fields will be updated.", "operationId": "patch_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers/{id_or_alias}/entitlements": { "get": { "tags": [ "Customers", "Entitlements" ], "summary": "List customer entitlements", "operationId": "get_effective_entitlements", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "Customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers/{id_or_alias}/portal-token": { "post": { "tags": [ "Customers" ], "summary": "Generate a portal token for a customer", "description": "Generates a JWT token that grants access to the customer portal.\nThe token can be used to access invoices, payment methods, and other portal features.", "operationId": "create_portal_token", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portal token generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalTokenResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers/{id_or_alias}/unarchive": { "post": { "tags": [ "Customers" ], "summary": "Restore an archived customer", "operationId": "unarchive_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/events/ingest": { "post": { "tags": [ "Events" ], "summary": "Ingest events", "description": "Ingest usage events for metering and billing purposes.\n\nEvents are deduplicated by `(event_id, customer_id)` — re-sending the same pair will not be\ndouble-counted. If timestamps differ across duplicates, the event with the latest timestamp is used.\n\nBy default, any invalid event rejects the entire batch. Set `allow_partial_failures` to `true` to ingest valid events and receive per-event failure details in the response body.", "operationId": "ingest_events", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventsRequest" } } }, "required": true }, "responses": { "200": { "description": "Events ingested successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/features": { "get": { "tags": [ "Features" ], "summary": "List features", "operationId": "list_features", "parameters": [ { "name": "statuses", "in": "query", "description": "Filter by feature status. Repeat the param to select multiple, omit to return all.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureStatus" } } }, { "name": "product_id", "in": "query", "description": "Filter by product. Omit to return features across all products.", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" } }, { "name": "search", "in": "query", "description": "Search by feature name.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of features", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/features/{id_or_code}": { "get": { "tags": [ "Features" ], "summary": "Get feature details", "operationId": "get_feature", "parameters": [ { "name": "id_or_code", "in": "path", "description": "Feature ID or code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feature details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Feature not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "description": "List invoices with optional filtering by customer, subscription, or status.", "operationId": "list_invoices", "parameters": [ { "name": "customer_id", "in": "query", "description": "Filter by customer ID or alias", "required": false, "schema": { "type": "string" } }, { "name": "subscription_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SubscriptionId" } }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "title": "InvoiceStatus", "enum": [ "DRAFT", "FINALIZED", "UNCOLLECTIBLE", "VOID" ] } } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `invoice_number`, `customer_name`, `amount`, `invoice_date`, `status`, `payment_status`. Direction: `asc` or `desc`. Default: `invoice_date.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/invoices/{invoice_id}": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice", "description": "Retrieve a single invoice with its payment transactions.", "operationId": "get_invoice_by_id", "parameters": [ { "name": "invoice_id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "$ref": "#/components/schemas/InvoiceId" }, "example": "inv_123" } ], "responses": { "200": { "description": "Invoice details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/invoices/{invoice_id}/download": { "get": { "tags": [ "Invoices" ], "summary": "Download invoice PDF", "description": "Download the PDF document for an invoice.", "operationId": "download_invoice_pdf", "parameters": [ { "name": "invoice_id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "$ref": "#/components/schemas/InvoiceId" }, "example": "inv_123" } ], "responses": { "200": { "description": "Invoice PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Unused dummy struct only used for an OpenAPI definition." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Invoice not found or PDF not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/metrics": { "get": { "tags": [ "Metrics" ], "summary": "List billable metrics", "operationId": "list_metrics", "parameters": [ { "name": "product_family_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductFamilyId" } }, { "name": "search", "in": "query", "description": "Search by metric name or code", "required": false, "schema": { "type": "string" } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `code`, `created_at`. Direction: `asc` or `desc`. Default: `name.asc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Metrics" ], "summary": "Create a billable metric", "operationId": "create_metric", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricRequest" } } }, "required": true }, "responses": { "201": { "description": "Metric created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/metrics/{metric_id}": { "get": { "tags": [ "Metrics" ], "summary": "Get metric details", "operationId": "get_metric", "parameters": [ { "name": "metric_id", "in": "path", "description": "Metric ID", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "200": { "description": "Metric details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Metric not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Metrics" ], "summary": "Update a billable metric", "description": "Partially update metric fields. Code and aggregation_type are immutable.", "operationId": "update_metric", "parameters": [ { "name": "metric_id", "in": "path", "description": "Metric ID", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricRequest" } } }, "required": true }, "responses": { "200": { "description": "Metric updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Metric not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/metrics/{metric_id}/archive": { "post": { "tags": [ "Metrics" ], "summary": "Archive a billable metric", "operationId": "archive_metric", "parameters": [ { "name": "metric_id", "in": "path", "description": "Metric ID", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "204": { "description": "Metric archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Metric not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/metrics/{metric_id}/unarchive": { "post": { "tags": [ "Metrics" ], "summary": "Unarchive a billable metric", "operationId": "unarchive_metric", "parameters": [ { "name": "metric_id", "in": "path", "description": "Metric ID", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "204": { "description": "Metric unarchived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Metric not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plan-versions/{plan_version_id}/entitlements": { "get": { "tags": [ "Plans", "Entitlements" ], "summary": "List plan version entitlements", "operationId": "list_plan_version_entitlements", "parameters": [ { "name": "plan_version_id", "in": "path", "description": "Plan version ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanVersionId" } } ], "responses": { "200": { "description": "Resolved entitlements for this plan version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans": { "get": { "tags": [ "Plans" ], "summary": "List plans", "operationId": "list_plans", "parameters": [ { "name": "product_family_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductFamilyId" } }, { "name": "search", "in": "query", "description": "Search by plan name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by plan status (can be repeated)", "required": false, "schema": { "type": "array", "items": { "type": "string", "title": "PlanStatus", "enum": [ "DRAFT", "ACTIVE", "INACTIVE", "ARCHIVED" ] } } }, { "name": "plan_type", "in": "query", "description": "Filter by plan type (can be repeated)", "required": false, "schema": { "type": "array", "items": { "type": "string", "title": "PlanType", "enum": [ "STANDARD", "FREE", "CUSTOM" ] } } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `status`, `plan_type`, `created_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Plans" ], "summary": "Create a plan", "description": "Create a new plan with components and pricing. Set `status` to `ACTIVE` to\npublish immediately, or `DRAFT` to stage for review.", "operationId": "create_plan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}": { "get": { "tags": [ "Plans" ], "summary": "Get plan details", "description": "Retrieve a specific plan. Use `?version=draft` for the draft version,\n`?version=2` for a specific version number, or omit for the active version.", "operationId": "get_plan_details", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "version", "in": "query", "description": "Filter by version: \"draft\", a version number, or omitted for active", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Plans" ], "summary": "Replace a plan", "description": "Full replacement of a plan's version. On a draft plan, updates in-place.\nOn a published plan, creates a new version. Set `status` to `DRAFT` to\nstage as a new draft without publishing.", "operationId": "replace_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Plans" ], "summary": "Update plan metadata", "description": "Partially update plan-level fields (name, description, self_service_rank).\nDoes not modify version-level configuration or components.", "operationId": "patch_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}/archive": { "post": { "tags": [ "Plans" ], "summary": "Archive a plan", "operationId": "archive_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "responses": { "204": { "description": "Plan archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}/publish": { "post": { "tags": [ "Plans" ], "summary": "Publish a draft plan version", "description": "Publishes the current draft version, making it the active version.", "operationId": "publish_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "responses": { "200": { "description": "Plan published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "409": { "description": "No draft version to publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}/unarchive": { "post": { "tags": [ "Plans" ], "summary": "Unarchive a plan", "operationId": "unarchive_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "responses": { "204": { "description": "Plan unarchived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}/versions": { "get": { "tags": [ "Plans" ], "summary": "List plan versions", "operationId": "list_plan_versions", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Plan versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersionListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/product_families": { "get": { "tags": [ "Product Families" ], "summary": "List product families", "operationId": "list_product_families", "parameters": [ { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `created_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of product families", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamilyListResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Product Families" ], "summary": "Create product family", "operationId": "create_product_family", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamilyCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Customer successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamily" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/product_families/{id_or_alias}": { "get": { "tags": [ "Product Families" ], "summary": "Get product family", "description": "Retrieve a single product family by ID or alias.", "operationId": "get_product_family_by_id_or_alias", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "product_family ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ProductFamily", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamily" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/products": { "get": { "tags": [ "Products" ], "summary": "List products", "operationId": "list_products", "parameters": [ { "name": "product_family_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductFamilyId" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `name`, `created_at`. Direction: `asc` or `desc`. Default: `name.asc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create a product", "operationId": "create_product", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } }, "required": true }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/products/{product_id}": { "get": { "tags": [ "Products" ], "summary": "Get product details", "operationId": "get_product", "parameters": [ { "name": "product_id", "in": "path", "description": "Product ID", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" } } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "description": "Partially update product fields. The fee_type is immutable and cannot be changed.", "operationId": "update_product", "parameters": [ { "name": "product_id", "in": "path", "description": "Product ID", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } }, "required": true }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/products/{product_id}/archive": { "post": { "tags": [ "Products" ], "summary": "Archive a product", "operationId": "archive_product", "parameters": [ { "name": "product_id", "in": "path", "description": "Product ID", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" } } ], "responses": { "204": { "description": "Product archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/products/{product_id}/entitlements": { "get": { "tags": [ "Products", "Entitlements" ], "summary": "List product entitlements", "operationId": "list_product_entitlements", "parameters": [ { "name": "product_id", "in": "path", "description": "Product ID", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" } } ], "responses": { "200": { "description": "List entitlements for this product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/products/{product_id}/unarchive": { "post": { "tags": [ "Products" ], "summary": "Unarchive a product", "operationId": "unarchive_product", "parameters": [ { "name": "product_id", "in": "path", "description": "Product ID", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" } } ], "responses": { "204": { "description": "Product unarchived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions", "description": "List subscriptions with optional filtering by customer or plan.", "operationId": "list_subscriptions", "parameters": [ { "name": "customer_id", "in": "query", "description": "Filter by customer ID or alias", "required": false, "schema": { "type": "string" } }, { "name": "plan_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "title": "SubscriptionStatus", "enum": [ "PENDING_ACTIVATION", "PENDING_CHARGE", "TRIAL_ACTIVE", "ACTIVE", "TRIAL_EXPIRED", "PAUSED", "SUSPENDED", "CANCELLED", "COMPLETED", "SUPERSEDED", "ERRORED" ] } } }, { "name": "order_by", "in": "query", "description": "Sort order. Format: `column.direction`. Allowed columns: `customer_name`, `plan_name`, `mrr_cents`, `billing_start_date`, `end_date`, `status`, `created_at`. Direction: `asc` or `desc`. Default: `created_at.desc`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-indexed)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Subscriptions" ], "summary": "Create subscription", "description": "Create a new subscription for a customer with a specific plan.", "operationId": "create_subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Subscription successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions/{subscription_id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get subscription details", "description": "Retrieve detailed information about a subscription including price components and schedules.", "operationId": "subscription_details", "parameters": [ { "name": "subscription_id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" } } ], "responses": { "200": { "description": "Details of subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Subscriptions" ], "summary": "Update subscription", "description": "Update subscription settings like payment configuration, billing options, etc.", "operationId": "update_subscription", "parameters": [ { "name": "subscription_id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions/{subscription_id}/cancel": { "post": { "tags": [ "Subscriptions" ], "summary": "Cancel subscription", "description": "Cancel a subscription either immediately or at the end of the billing period.", "operationId": "cancel_subscription", "parameters": [ { "name": "subscription_id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" }, "example": "sub_123" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "Subscription canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions/{subscription_id}/entitlements": { "get": { "tags": [ "Subscriptions", "Entitlements" ], "summary": "List subscription entitlements", "operationId": "list_subscription_entitlements", "parameters": [ { "name": "subscription_id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" } } ], "responses": { "200": { "description": "Effective entitlements for this subscription, with live usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveEntitlementListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/usage/customer/{customer_id}": { "get": { "tags": [ "Usage" ], "summary": "Get customer usage", "description": "Retrieve aggregated usage data for a customer over a specified period.", "operationId": "get_customer_usage", "parameters": [ { "name": "customer_id", "in": "path", "description": "Customer ID or alias", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "metric_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "200": { "description": "Customer usage data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/usage/subscription/{subscription_id}": { "get": { "tags": [ "Usage" ], "summary": "Get subscription usage", "description": "Retrieve aggregated usage data for a subscription's usage-based components.\nIf start_date/end_date are omitted, defaults to the current billing period.", "operationId": "get_subscription_usage", "parameters": [ { "name": "subscription_id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "metric_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "200": { "description": "Subscription usage data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/usage/summary": { "get": { "tags": [ "Usage" ], "summary": "Get usage summary", "description": "Retrieve aggregated usage data across all customers for the tenant.", "operationId": "get_usage_summary", "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "metric_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AddOn": { "type": "object", "required": [ "id", "name", "product_id", "price_id", "self_serviceable", "created_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/Entitlement" } }, "fee_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductFeeTypeEnum" } ] }, "id": { "$ref": "#/components/schemas/AddOnId" }, "max_instances_per_subscription": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "price_id": { "$ref": "#/components/schemas/PriceId" }, "product_id": { "$ref": "#/components/schemas/ProductId" }, "self_serviceable": { "type": "boolean" } } }, "AddOnEvent": { "allOf": [ { "$ref": "#/components/schemas/AddOnEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "AddOnEventData": { "type": "object", "required": [ "add_on_id", "name", "product_id", "price_id", "self_serviceable", "created_at" ], "properties": { "add_on_id": { "$ref": "#/components/schemas/AddOnId" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "fee_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductFeeTypeEnum" } ] }, "max_instances_per_subscription": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "price_id": { "$ref": "#/components/schemas/PriceId" }, "product_id": { "$ref": "#/components/schemas/ProductId" }, "self_serviceable": { "type": "boolean" } } }, "AddOnId": { "type": "string", "format": "MeteroidId", "examples": [ "add_7n42DGM5Tflk9n8mt7Fhc7" ] }, "AddOnListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddOn" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "Address": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] } } }, "AppliedCoupon": { "type": "object", "required": [ "id", "coupon_id", "is_active", "created_at" ], "properties": { "applied_amount": { "type": [ "string", "null" ], "format": "decimal" }, "applied_count": { "type": [ "integer", "null" ], "format": "int32" }, "coupon_id": { "$ref": "#/components/schemas/CouponId" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/AppliedCouponId" }, "is_active": { "type": "boolean" }, "last_applied_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AppliedCouponDetailed": { "type": "object", "required": [ "coupon", "applied_coupon" ], "properties": { "applied_coupon": { "$ref": "#/components/schemas/AppliedCoupon" }, "coupon": { "$ref": "#/components/schemas/SubscriptionCoupon" } } }, "AppliedCouponId": { "type": "string", "format": "MeteroidId", "examples": [ "sub_cou_7n42DGM5Tflk9n8mt7Fhc7" ] }, "AvailableParameters": { "type": "object", "properties": { "billing_periods": { "type": "object", "description": "Map of component_id -> available billing periods (e.g., \"MONTHLY\", \"ANNUAL\")", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPeriodEnum" } }, "propertyNames": { "type": "string" } }, "capacity_thresholds": { "type": "object", "description": "Map of component_id -> available capacity values", "additionalProperties": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "propertyNames": { "type": "string" } }, "slot_components": { "type": "array", "items": { "type": "string" }, "description": "List of component_ids that support slot parametrization (initial slot count)" } } }, "BankAccountId": { "type": "string", "format": "MeteroidId", "examples": [ "ba_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BankTransferPaymentMethodConfig": { "type": "object", "properties": { "account_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BankAccountId" } ] } } }, "BatchJobChunkId": { "type": "string", "format": "MeteroidId", "examples": [ "bjch_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BatchJobDetailResponse": { "type": "object", "required": [ "id", "job_type", "status", "processed_items", "failed_items", "created_by", "created_at", "failure_count", "has_error_csv" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "error_csv_url": { "type": [ "string", "null" ] }, "failed_items": { "type": "integer", "format": "int32" }, "failure_count": { "type": "integer", "format": "int64" }, "has_error_csv": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/BatchJobId" }, "input_file_name": { "type": [ "string", "null" ] }, "input_file_url": { "type": [ "string", "null" ] }, "job_type": { "$ref": "#/components/schemas/BatchJobType" }, "processed_items": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/components/schemas/BatchJobStatus" }, "total_items": { "type": [ "integer", "null" ], "format": "int32" } } }, "BatchJobFailuresResponse": { "type": "object", "required": [ "data", "total_count" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchJobItemFailureResponse" } }, "total_count": { "type": "integer", "format": "int64" } } }, "BatchJobId": { "type": "string", "format": "MeteroidId", "examples": [ "bjob_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BatchJobItemFailureResponse": { "type": "object", "required": [ "id", "chunk_id", "item_index", "reason" ], "properties": { "chunk_id": { "$ref": "#/components/schemas/BatchJobChunkId" }, "id": { "type": "string", "format": "uuid" }, "item_identifier": { "type": [ "string", "null" ] }, "item_index": { "type": "integer", "format": "int32" }, "reason": { "type": "string" } } }, "BatchJobListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchJobResponse" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "BatchJobResponse": { "type": "object", "required": [ "id", "job_type", "status", "processed_items", "failed_items", "created_by", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "failed_items": { "type": "integer", "format": "int32" }, "id": { "$ref": "#/components/schemas/BatchJobId" }, "input_file_name": { "type": [ "string", "null" ] }, "job_type": { "$ref": "#/components/schemas/BatchJobType" }, "processed_items": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/components/schemas/BatchJobStatus" }, "total_items": { "type": [ "integer", "null" ], "format": "int32" } } }, "BatchJobStatus": { "type": "string", "title": "BatchJobStatus", "enum": [ "PENDING", "CHUNKING", "PROCESSING", "COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "CANCELLED" ] }, "BatchJobType": { "type": "string", "title": "BatchJobType", "enum": [ "EVENT_CSV_IMPORT", "CUSTOMER_CSV_IMPORT", "SUBSCRIPTION_CSV_IMPORT", "SUBSCRIPTION_PLAN_MIGRATION" ] }, "BillableMetricId": { "type": "string", "format": "MeteroidId", "examples": [ "bm_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BillingConfig": { "type": "object", "properties": { "billing_cycles": { "type": [ "integer", "null" ], "format": "int32" }, "net_terms": { "type": "integer", "format": "int32" }, "period_start_day": { "type": [ "integer", "null" ], "format": "int32" } } }, "BillingCycleResetPeriod": { "type": "object", "description": "Resets each time your subscription renews — anchored to your billing cycle." }, "BillingMetricAggregateEnum": { "type": "string", "enum": [ "COUNT", "LATEST", "MAX", "MIN", "MEAN", "SUM", "COUNT_DISTINCT" ] }, "BillingPeriodEnum": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "SEMIANNUAL", "ANNUAL" ] }, "BillingType": { "type": "string", "enum": [ "ADVANCE", "ARREARS" ] }, "BillingTypeEnum": { "type": "string", "enum": [ "ADVANCE", "ARREARS" ] }, "BooleanEffectiveEntitlementValue": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "BooleanEntitlementValue": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "BooleanFeatureType": { "type": "object" }, "BooleanResolvedEntitlementValue": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "CalendarResetPeriod": { "type": "object", "description": "Resets on calendar boundaries (e.g. the 1st of every month) — not tied to subscription start date.", "required": [ "unit", "interval" ], "properties": { "interval": { "type": "integer", "format": "int32", "minimum": 0 }, "unit": { "$ref": "#/components/schemas/CalendarUnit" } } }, "CalendarUnit": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH", "YEAR" ] }, "CancelCheckoutSessionResponse": { "type": "object", "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/CheckoutSession" } } }, "CancelSubscriptionRequest": { "type": "object", "properties": { "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "If not provided, the cancellation will be effective at the end of the current billing or committed period." }, "reason": { "type": [ "string", "null" ] } } }, "CancelSubscriptionResponse": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } } }, "CapacityFee": { "type": "object", "required": [ "rate", "included", "overage_rate", "metric_id" ], "properties": { "included": { "type": "integer", "format": "int64", "minimum": 0 }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "overage_rate": { "type": "string", "format": "decimal" }, "rate": { "type": "string", "format": "decimal" } } }, "CapacityFeeStructure": { "type": "object", "required": [ "metric_id" ], "properties": { "metric_id": { "$ref": "#/components/schemas/BillableMetricId" } } }, "CapacityPlanFee": { "type": "object", "description": "Capacity-based fee with included committed usage and overage", "required": [ "metric_id", "thresholds", "cadence" ], "properties": { "cadence": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityThreshold" } } } }, "CapacityPricing": { "type": "object", "required": [ "rate", "included", "overage_rate" ], "properties": { "included": { "type": "integer", "format": "int64", "minimum": 0 }, "overage_rate": { "type": "string", "format": "decimal" }, "rate": { "type": "string", "format": "decimal" } } }, "CapacityThreshold": { "type": "object", "required": [ "included_amount", "price", "per_unit_overage" ], "properties": { "included_amount": { "type": "integer", "format": "int64", "minimum": 0 }, "per_unit_overage": { "type": "string", "format": "decimal" }, "price": { "type": "string", "format": "decimal" } } }, "CheckoutSession": { "type": "object", "required": [ "id", "customer_id", "plan_version_id", "status", "checkout_type", "created_at" ], "properties": { "billing_day_anchor": { "type": [ "integer", "null" ], "format": "int32" }, "billing_start_date": { "type": [ "string", "null" ], "format": "date" }, "checkout_type": { "$ref": "#/components/schemas/CheckoutType" }, "checkout_url": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "coupon_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the session expires. None means the session never expires." }, "id": { "$ref": "#/components/schemas/CheckoutSessionId" }, "net_terms": { "type": [ "integer", "null" ], "format": "int32" }, "payment_methods_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodsConfig" } ] }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "status": { "$ref": "#/components/schemas/CheckoutSessionStatus" }, "subscription_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionId" } ] }, "trial_duration_days": { "type": [ "integer", "null" ], "format": "int32" } } }, "CheckoutSessionId": { "type": "string", "format": "MeteroidId", "examples": [ "che_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CheckoutSessionStatus": { "type": "string", "title": "CheckoutSessionStatus", "enum": [ "CREATED", "AWAITING_PAYMENT", "COMPLETED", "EXPIRED", "CANCELLED" ] }, "CheckoutType": { "type": "string", "enum": [ "SELF_SERVE", "SUBSCRIPTION_ACTIVATION", "PLAN_CHANGE", "ADDON_PURCHASE" ] }, "ComponentOverride": { "type": "object", "required": [ "component_id", "name", "price_entry" ], "properties": { "component_id": { "$ref": "#/components/schemas/PriceComponentId" }, "name": { "type": "string" }, "price_entry": { "$ref": "#/components/schemas/PriceEntry" } } }, "ComponentParameterization": { "type": "object", "required": [ "component_id", "parameters" ], "properties": { "component_id": { "$ref": "#/components/schemas/PriceComponentId" }, "parameters": { "$ref": "#/components/schemas/ComponentParameters" } } }, "ComponentParameters": { "type": "object", "properties": { "billing_period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPeriodEnum" } ] }, "committed_capacity": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "initial_slot_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CountryCode": { "type": "string", "format": "CountryCode", "examples": [ "US", "GB", "FR" ] }, "Coupon": { "type": "object", "required": [ "id", "code", "discount", "reusable", "disabled", "created_at", "redemption_count", "plan_ids" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "disabled": { "type": "boolean" }, "discount": { "$ref": "#/components/schemas/CouponDiscount" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/CouponId" }, "plan_ids": { "type": "array", "items": { "$ref": "#/components/schemas/PlanId" } }, "recurring_value": { "type": [ "integer", "null" ], "format": "int32" }, "redemption_count": { "type": "integer", "format": "int32" }, "redemption_limit": { "type": [ "integer", "null" ], "format": "int32" }, "reusable": { "type": "boolean" } } }, "CouponDiscount": { "oneOf": [ { "$ref": "#/components/schemas/PercentageDiscount" }, { "$ref": "#/components/schemas/FixedDiscount" } ], "discriminator": { "propertyName": "type", "mapping": { "FIXED": "#/components/schemas/FixedDiscount", "PERCENTAGE": "#/components/schemas/PercentageDiscount" } } }, "CouponEvent": { "allOf": [ { "$ref": "#/components/schemas/CouponEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "CouponEventData": { "type": "object", "required": [ "coupon_id", "code", "description", "discount", "reusable", "disabled", "created_at" ], "properties": { "code": { "type": "string" }, "coupon_id": { "$ref": "#/components/schemas/CouponId" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "disabled": { "type": "boolean" }, "discount": { "$ref": "#/components/schemas/CouponDiscount" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "recurring_value": { "type": [ "integer", "null" ], "format": "int32" }, "redemption_limit": { "type": [ "integer", "null" ], "format": "int32" }, "reusable": { "type": "boolean" } } }, "CouponId": { "type": "string", "format": "MeteroidId", "examples": [ "cou_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CouponLineItem": { "type": "object", "required": [ "coupon_id", "name", "total" ], "properties": { "coupon_id": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "integer", "format": "int64" } } }, "CouponListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "CreateAddOnRequest": { "type": "object", "required": [ "name", "product_id", "price_id" ], "properties": { "description": { "type": [ "string", "null" ] }, "max_instances_per_subscription": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "price_id": { "$ref": "#/components/schemas/PriceId" }, "product_id": { "$ref": "#/components/schemas/ProductId" }, "self_serviceable": { "type": "boolean" } } }, "CreateCheckoutSessionRequest": { "type": "object", "required": [ "customer_id", "plan_version_id" ], "properties": { "add_ons": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CreateSubscriptionAddOn" } }, "auto_advance_invoices": { "type": [ "boolean", "null" ], "description": "If false, invoices will stay in Draft until manually reviewed and finalized. Default is true." }, "billing_day_anchor": { "type": [ "integer", "null" ], "format": "int32" }, "billing_start_date": { "type": [ "string", "null" ], "format": "date" }, "charge_automatically": { "type": [ "boolean", "null" ], "description": "Automatically try to charge the customer's configured payment method on finalize. Default is true." }, "components": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateSubscriptionComponents" } ] }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_ids": { "type": "array", "items": { "$ref": "#/components/schemas/CouponId" } }, "customer_id": { "type": "string", "format": "CustomerId or customer alias", "description": "Customer ID or alias" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "expires_in_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "Session expiry time in hours. Default is 1 hour for self-serve checkout.", "minimum": 0 }, "invoice_memo": { "type": [ "string", "null" ] }, "invoice_threshold": { "type": [ "string", "null" ], "format": "decimal" }, "metadata": {}, "net_terms": { "type": [ "integer", "null" ], "format": "int32" }, "payment_methods_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodsConfig", "description": "Payment methods configuration. If not specified, inherits from the invoicing entity." } ] }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "purchase_order": { "type": [ "string", "null" ] }, "trial_duration_days": { "type": [ "integer", "null" ], "format": "int32" } } }, "CreateCheckoutSessionResponse": { "type": "object", "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/CheckoutSession" } } }, "CreateCouponRequest": { "type": "object", "required": [ "code", "discount" ], "properties": { "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "discount": { "$ref": "#/components/schemas/CouponDiscount" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "plan_ids": { "type": "array", "items": { "$ref": "#/components/schemas/PlanId" } }, "recurring_value": { "type": [ "integer", "null" ], "format": "int32" }, "redemption_limit": { "type": [ "integer", "null" ], "format": "int32" }, "reusable": { "type": "boolean" } } }, "CreateMetricRequest": { "type": "object", "required": [ "name", "code", "aggregation_type", "product_family_id" ], "properties": { "aggregation_key": { "type": [ "string", "null" ] }, "aggregation_type": { "$ref": "#/components/schemas/BillingMetricAggregateEnum" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] }, "segmentation_matrix": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MetricSegmentationMatrix" } ] }, "unit_conversion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitConversion" } ] }, "usage_group_key": { "type": [ "string", "null" ] } } }, "CreatePlanRequest": { "type": "object", "required": [ "name", "product_family_id", "plan_type", "status", "currency", "components" ], "properties": { "add_ons": { "type": "array", "items": { "$ref": "#/components/schemas/PlanAddOnInput" } }, "billing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingConfig" } ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PriceComponentInput" } }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "self_service_rank": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "trial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TrialConfig" } ] } } }, "CreateProductRequest": { "type": "object", "required": [ "name", "product_family_id", "fee_structure" ], "properties": { "catalog": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "fee_structure": { "$ref": "#/components/schemas/ProductFeeStructure" }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" } } }, "CreateSubscriptionAddOn": { "type": "object", "required": [ "add_on_id" ], "properties": { "add_on_id": { "$ref": "#/components/schemas/AddOnId" }, "customization": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionAddOnCustomization" } ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CreateSubscriptionComponents": { "type": "object", "properties": { "extra_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ExtraComponent" } }, "overridden_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComponentOverride" } }, "parameterized_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComponentParameterization" } }, "remove_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PriceComponentId" } } } }, "CreditNoteEvent": { "allOf": [ { "$ref": "#/components/schemas/CreditNoteEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "CreditNoteEventData": { "type": "object", "required": [ "credit_note_id", "customer_id", "invoice_id", "status", "currency", "total", "tax_amount", "refunded_amount_cents", "credited_amount_cents", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "credit_note_id": { "$ref": "#/components/schemas/CreditNoteId" }, "credited_amount_cents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "invoice_id": { "$ref": "#/components/schemas/InvoiceId" }, "refunded_amount_cents": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/CreditNoteStatus" }, "tax_amount": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "CreditNoteId": { "type": "string", "format": "MeteroidId", "examples": [ "crn_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CreditNoteStatus": { "type": "string", "enum": [ "DRAFT", "FINALIZED", "VOIDED" ] }, "Currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNH", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ], "examples": [ "EUR" ] }, "CustomTaxRate": { "type": "object", "required": [ "tax_code", "name", "rate" ], "properties": { "name": { "type": "string" }, "rate": { "type": "string" }, "tax_code": { "type": "string" } } }, "Customer": { "type": "object", "required": [ "id", "name", "invoicing_emails", "currency", "invoicing_entity_id", "custom_taxes" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_taxes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTaxRate" } }, "id": { "$ref": "#/components/schemas/CustomerId" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "$ref": "#/components/schemas/InvoicingEntityId" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerCreateRequest": { "type": "object", "required": [ "name", "invoicing_emails", "currency", "custom_taxes" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_taxes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTaxRate" } }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoicingEntityId" } ] }, "is_tax_exempt": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerDetails": { "type": "object", "required": [ "id", "name", "snapshot_at" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "email": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/CustomerId" }, "name": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerEvent": { "allOf": [ { "$ref": "#/components/schemas/CustomerEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ], "description": "Event-specific webhook schemas for type-safe webhook payloads" }, "CustomerEventData": { "type": "object", "required": [ "customer_id", "name", "invoicing_emails", "currency" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] } } }, "CustomerId": { "type": "string", "format": "MeteroidId", "examples": [ "cus_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CustomerListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "CustomerPatchRequest": { "type": "object", "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Currency" } ] }, "custom_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CustomTaxRate" } }, "invoicing_emails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "invoicing_entity_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoicingEntityId" } ] }, "is_tax_exempt": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerPaymentMethodId": { "type": "string", "format": "MeteroidId", "examples": [ "pm_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CustomerPortalTokenResponse": { "type": "object", "required": [ "token", "portal_url" ], "properties": { "portal_url": { "type": "string", "description": "Base URL of the customer portal" }, "token": { "type": "string", "description": "JWT token for portal access" } } }, "CustomerUpdateRequest": { "type": "object", "required": [ "name", "invoicing_emails", "currency", "invoicing_entity_id", "custom_taxes" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_taxes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTaxRate" } }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "$ref": "#/components/schemas/InvoicingEntityId" }, "is_tax_exempt": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "DoubleSegmentationMatrix": { "type": "object", "required": [ "dimension1", "dimension2" ], "properties": { "dimension1": { "$ref": "#/components/schemas/MetricDimension" }, "dimension2": { "$ref": "#/components/schemas/MetricDimension" } } }, "EffectiveEntitlement": { "type": "object", "description": "Merged entitlement value for a feature for a specific customer, enriched with live usage data.", "required": [ "feature", "value" ], "properties": { "feature": { "$ref": "#/components/schemas/FeatureRef" }, "value": { "$ref": "#/components/schemas/EffectiveEntitlementValue" } } }, "EffectiveEntitlementListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveEntitlement" } } } }, "EffectiveEntitlementValue": { "oneOf": [ { "$ref": "#/components/schemas/BooleanEffectiveEntitlementValue" }, { "$ref": "#/components/schemas/MeteredEffectiveEntitlementValue" } ], "discriminator": { "propertyName": "type", "mapping": { "BOOLEAN": "#/components/schemas/BooleanEffectiveEntitlementValue", "METERED": "#/components/schemas/MeteredEffectiveEntitlementValue" } } }, "Entitlement": { "type": "object", "description": "A raw entitlement row attached to one entity (feature, plan version, add-on, or subscription).", "required": [ "id", "feature_id", "value", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "feature_id": { "$ref": "#/components/schemas/FeatureId" }, "id": { "$ref": "#/components/schemas/EntitlementId" }, "updated_at": { "type": "string", "format": "date-time" }, "value": { "$ref": "#/components/schemas/EntitlementValue" } } }, "EntitlementId": { "type": "string", "format": "MeteroidId", "examples": [ "ent_7n42DGM5Tflk9n8mt7Fhc7" ] }, "EntitlementProductRef": { "type": "object", "description": "Minimal reference to the product a feature belongs to.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ProductId" }, "name": { "type": "string" } } }, "EntitlementValue": { "oneOf": [ { "$ref": "#/components/schemas/BooleanEntitlementValue" }, { "$ref": "#/components/schemas/MeteredEntitlementValue" } ], "discriminator": { "propertyName": "type", "mapping": { "BOOLEAN": "#/components/schemas/BooleanEntitlementValue", "METERED": "#/components/schemas/MeteredEntitlementValue" } } }, "ErrorCode": { "type": "string", "enum": [ "BAD_REQUEST", "NOT_FOUND", "CONFLICT", "FORBIDDEN", "UNAUTHORIZED", "TOO_MANY_REQUESTS", "INTERNAL_SERVER_ERROR" ] }, "Event": { "type": "object", "required": [ "event_id", "code", "customer_id", "timestamp" ], "properties": { "code": { "type": "string", "description": "Billable metric code. Max 512 characters." }, "customer_id": { "type": "string", "description": "Meteroid customer ID or external customer alias." }, "event_id": { "type": "string", "description": "Unique event identifier. Max 255 characters. A UUID or ULID is recommended." }, "properties": { "type": "object", "description": "Arbitrary string key-value pairs used by billable metrics for filtering and aggregation.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "region": "us-east-1", "tier": "pro", "bytes": "1048576" } }, "timestamp": { "type": "string", "description": "RFC 3339 timestamp. Defaults to ingestion time if omitted.\nMust be between 24 hours ago and 1 hour from now. Set `allow_backfilling` to remove the past limit.", "example": "2026-01-15T10:30:00Z" } } }, "EventId": { "type": "string", "format": "MeteroidId", "examples": [ "evt_7n42DGM5Tflk9n8mt7Fhc7" ] }, "EventType": { "type": "string", "enum": [ "metric.created", "customer.created", "subscription.created", "invoice.created", "invoice.finalized", "invoice.paid", "invoice.voided", "invoice.consolidated", "quote.accepted", "quote.converted", "credit_note.created", "credit_note.finalized", "credit_note.voided", "plan.created", "plan.published", "plan.archived", "product.created", "product.updated", "product.archived", "metric.updated", "metric.archived", "coupon.created", "coupon.updated", "coupon.archived", "addon.created", "addon.updated", "addon.archived" ] }, "ExistingPriceRef": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/PriceId" } } }, "ExistingProductRef": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/ProductId" } } }, "ExternalPaymentMethodConfig": { "type": "object" }, "ExtraComponent": { "type": "object", "required": [ "name", "product_ref", "price_entry" ], "properties": { "name": { "type": "string" }, "price_entry": { "$ref": "#/components/schemas/PriceEntry" }, "product_ref": { "$ref": "#/components/schemas/ProductRef" } } }, "ExtraRecurringBillingTypeEnum": { "type": "string", "enum": [ "ADVANCE", "ARREARS" ] }, "ExtraRecurringFeeStructure": { "type": "object", "required": [ "billing_type" ], "properties": { "billing_type": { "$ref": "#/components/schemas/ExtraRecurringBillingTypeEnum" } } }, "ExtraRecurringPlanFee": { "type": "object", "description": "Extra recurring fee", "required": [ "unit_price", "quantity", "billing_type", "cadence" ], "properties": { "billing_type": { "$ref": "#/components/schemas/BillingType" }, "cadence": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "string", "format": "decimal" } } }, "ExtraRecurringPricing": { "type": "object", "required": [ "unit_price", "quantity" ], "properties": { "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "string", "format": "decimal" } } }, "Feature": { "type": "object", "required": [ "id", "name", "code", "feature_type", "status", "created_at" ], "properties": { "code": { "type": "string", "description": "Unique key used to reference this feature in your code. Cannot be changed after creation." }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "entitlement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Entitlement", "description": "Feature-level (default) entitlement, applied to all subscriptions as the lowest-priority." } ] }, "feature_type": { "$ref": "#/components/schemas/FeatureType" }, "id": { "$ref": "#/components/schemas/FeatureId" }, "name": { "type": "string" }, "product": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntitlementProductRef", "description": "Product this feature belongs to." } ] }, "status": { "$ref": "#/components/schemas/FeatureStatus" } } }, "FeatureId": { "type": "string", "format": "MeteroidId", "examples": [ "feat_7n42DGM5Tflk9n8mt7Fhc7" ] }, "FeatureListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Feature" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "FeatureRef": { "type": "object", "required": [ "id", "name", "code" ], "properties": { "code": { "type": "string", "description": "Unique key used to reference this feature in your code. Cannot be changed after creation." }, "id": { "$ref": "#/components/schemas/FeatureId" }, "name": { "type": "string" }, "product": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntitlementProductRef" } ] } } }, "FeatureStatus": { "type": "string", "description": "Lifecycle status of a feature.", "enum": [ "ACTIVE", "DISABLED", "ARCHIVED" ] }, "FeatureType": { "oneOf": [ { "$ref": "#/components/schemas/BooleanFeatureType" }, { "$ref": "#/components/schemas/MeteredFeatureType" } ], "discriminator": { "propertyName": "type", "mapping": { "BOOLEAN": "#/components/schemas/BooleanFeatureType", "METERED": "#/components/schemas/MeteredFeatureType" } } }, "Fee": { "oneOf": [ { "$ref": "#/components/schemas/RatePlanFee" }, { "$ref": "#/components/schemas/SlotPlanFee" }, { "$ref": "#/components/schemas/CapacityPlanFee" }, { "$ref": "#/components/schemas/UsagePlanFee" }, { "$ref": "#/components/schemas/ExtraRecurringPlanFee" }, { "$ref": "#/components/schemas/OneTimePlanFee" } ], "discriminator": { "propertyName": "type", "mapping": { "CAPACITY": "#/components/schemas/CapacityPlanFee", "EXTRA_RECURRING": "#/components/schemas/ExtraRecurringPlanFee", "ONE_TIME": "#/components/schemas/OneTimePlanFee", "RATE": "#/components/schemas/RatePlanFee", "SLOT": "#/components/schemas/SlotPlanFee", "USAGE": "#/components/schemas/UsagePlanFee" } } }, "FixedDiscount": { "type": "object", "required": [ "currency", "amount" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } } }, "FixedWindowResetPeriod": { "type": "object", "description": "Resets at regular intervals — anchored to your subscription's exact activation time.", "required": [ "unit", "interval" ], "properties": { "interval": { "type": "integer", "format": "int32", "minimum": 0 }, "unit": { "$ref": "#/components/schemas/CalendarUnit" } } }, "GetCheckoutSessionResponse": { "type": "object", "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/CheckoutSession" } } }, "GroupedUsage": { "type": "object", "required": [ "value", "dimensions" ], "properties": { "dimensions": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "value": { "type": "string", "format": "decimal" } } }, "IngestEventsRequest": { "type": "object", "required": [ "events" ], "properties": { "allow_backfilling": { "type": [ "boolean", "null" ], "description": "Allow events with timestamps more than 1 day in the past. Defaults to `false`." }, "allow_partial_failures": { "type": [ "boolean", "null" ], "description": "Accept the batch even if some events fail validation. Defaults to `false`.\nWhen `true`, valid events are ingested and failures are reported in the response body.\nWhen `false` (default), any invalid event rejects the entire batch." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "1–100 events per request." } } }, "IngestEventsResponse": { "type": "object", "properties": { "failures": { "type": "array", "items": { "$ref": "#/components/schemas/IngestFailure" }, "description": "Events that failed to ingest. Omitted when no failures." } } }, "IngestFailure": { "type": "object", "required": [ "event_id", "reason" ], "properties": { "event_id": { "type": "string" }, "reason": { "type": "string" } } }, "Invoice": { "type": "object", "required": [ "id", "invoice_number", "status", "customer_id", "currency", "invoice_date", "subtotal", "subtotal_recurring", "tax_amount", "total", "amount_due", "line_items", "tax_breakdown", "transactions", "payment_status", "customer_details", "applied_credits", "coupons", "invoice_type", "net_terms", "created_at" ], "properties": { "amount_due": { "type": "integer", "format": "int64" }, "applied_credits": { "type": "integer", "format": "int64" }, "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/CouponLineItem" } }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "$ref": "#/components/schemas/Currency" }, "customer_details": { "$ref": "#/components/schemas/CustomerDetails" }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/InvoiceId" }, "invoice_date": { "type": "string", "format": "date" }, "invoice_number": { "type": "string" }, "invoice_type": { "$ref": "#/components/schemas/InvoiceType" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "marked_as_uncollectible_at": { "type": [ "string", "null" ], "format": "date-time" }, "memo": { "type": [ "string", "null" ] }, "net_terms": { "type": "integer", "format": "int32" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "payment_status": { "$ref": "#/components/schemas/InvoicePaymentStatus" }, "purchase_order": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "subscription_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionId" } ] }, "subtotal": { "type": "integer", "format": "int64" }, "subtotal_recurring": { "type": "integer", "format": "int64" }, "tax_amount": { "type": "integer", "format": "int64" }, "tax_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/TaxBreakdownItem" } }, "total": { "type": "integer", "format": "int64" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "voided_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceEvent": { "allOf": [ { "$ref": "#/components/schemas/InvoiceEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "InvoiceEventData": { "type": "object", "required": [ "invoice_id", "customer_id", "status", "currency", "total", "tax_amount", "created_at" ], "properties": { "consolidated_into_invoice_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoiceId", "description": "Set on `invoice.consolidated`: the parent invoice this one was merged into." } ] }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "invoice_id": { "$ref": "#/components/schemas/InvoiceId" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "tax_amount": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "InvoiceId": { "type": "string", "format": "MeteroidId", "examples": [ "inv_7n42DGM5Tflk9n8mt7Fhc7" ] }, "InvoiceLineItem": { "type": "object", "required": [ "name", "amount_total", "start_date", "end_date", "tax_rate", "sub_line_items" ], "properties": { "amount_total": { "type": "integer", "format": "int64" }, "description": { "type": [ "string", "null" ] }, "end_date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "quantity": { "type": "string", "format": "decimal" }, "start_date": { "type": "string", "format": "date" }, "sub_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/SubLineItem" } }, "tax_rate": { "type": "string", "format": "decimal" }, "unit_price": { "type": "string", "format": "decimal" } } }, "InvoiceListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "InvoicePaymentStatus": { "type": "string", "enum": [ "UNPAID", "PARTIALLY_PAID", "PAID", "ERRORED" ] }, "InvoiceStatus": { "type": "string", "title": "InvoiceStatus", "enum": [ "DRAFT", "FINALIZED", "UNCOLLECTIBLE", "VOID" ] }, "InvoiceType": { "type": "string", "enum": [ "RECURRING", "ONE_OFF", "ADJUSTMENT", "USAGE_THRESHOLD" ] }, "InvoicingEntityId": { "type": "string", "format": "MeteroidId", "examples": [ "ive_7n42DGM5Tflk9n8mt7Fhc7" ] }, "LinkedSegmentationMatrix": { "type": "object", "required": [ "dimension1_key", "dimension2_key", "values" ], "properties": { "dimension1_key": { "type": "string" }, "dimension2_key": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } } } }, "ListCheckoutSessionsResponse": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "MatrixDimension": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "MatrixPlanPricing": { "type": "object", "required": [ "rates" ], "properties": { "rates": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixRow" } } } }, "MatrixPricing": { "type": "object", "required": [ "rates" ], "properties": { "rates": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixRow" } } } }, "MatrixRow": { "type": "object", "required": [ "dimension1", "per_unit_price" ], "properties": { "dimension1": { "$ref": "#/components/schemas/MatrixDimension" }, "dimension2": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MatrixDimension" } ] }, "per_unit_price": { "type": "string", "format": "decimal" } } }, "MeteredEffectiveEntitlementValue": { "type": "object", "required": [ "spec", "usage" ], "properties": { "spec": { "$ref": "#/components/schemas/MeteredEntitlementSpec" }, "usage": { "$ref": "#/components/schemas/MeteredEntitlementUsage" } } }, "MeteredEntitlementSpec": { "type": "object", "required": [ "metric_id", "reset_period", "enabled" ], "properties": { "enabled": { "type": "boolean" }, "limit": { "type": [ "string", "null" ], "format": "decimal" }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "reset_period": { "$ref": "#/components/schemas/ResetPeriod" } } }, "MeteredEntitlementUsage": { "type": "object", "properties": { "consumed": { "type": [ "string", "null" ], "format": "decimal" }, "remaining": { "type": [ "string", "null" ], "format": "decimal" }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "MeteredEntitlementValue": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Per-entitlement kill switch. `false` means disabled." }, "limit": { "type": [ "string", "null" ], "format": "decimal", "description": "Cap on usage. Null means unlimited." }, "reset_period": { "$ref": "#/components/schemas/ResetPeriod" } } }, "MeteredFeatureType": { "type": "object", "required": [ "metric_id" ], "properties": { "metric_id": { "$ref": "#/components/schemas/BillableMetricId" } } }, "MeteredResolvedEntitlementValue": { "type": "object", "required": [ "metric_id", "reset_period", "enabled" ], "properties": { "enabled": { "type": "boolean" }, "limit": { "type": [ "string", "null" ], "format": "decimal" }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "reset_period": { "$ref": "#/components/schemas/ResetPeriod" } } }, "Metric": { "type": "object", "required": [ "id", "name", "code", "aggregation_type", "product_family_id", "created_at" ], "properties": { "aggregation_key": { "type": [ "string", "null" ] }, "aggregation_type": { "$ref": "#/components/schemas/BillingMetricAggregateEnum" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/BillableMetricId" }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] }, "segmentation_matrix": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MetricSegmentationMatrix" } ] }, "unit_conversion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitConversion" } ] }, "usage_group_key": { "type": [ "string", "null" ] } } }, "MetricDimension": { "type": "object", "required": [ "key", "values" ], "properties": { "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "MetricEvent": { "allOf": [ { "$ref": "#/components/schemas/MetricEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "MetricEventData": { "type": "object", "required": [ "metric_id", "name", "code", "aggregation_type", "created_at", "product_family_id" ], "properties": { "aggregation_key": { "type": [ "string", "null" ] }, "aggregation_type": { "$ref": "#/components/schemas/BillingMetricAggregateEnum" }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] }, "segmentation_matrix": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MetricSegmentationMatrix" } ] }, "unit_conversion_factor": { "type": [ "integer", "null" ], "format": "int32" }, "unit_conversion_rounding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitConversionRoundingEnum" } ] }, "usage_group_key": { "type": [ "string", "null" ] } } }, "MetricListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSummary" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "MetricSegmentationMatrix": { "oneOf": [ { "$ref": "#/components/schemas/MetricDimension" }, { "$ref": "#/components/schemas/DoubleSegmentationMatrix" }, { "$ref": "#/components/schemas/LinkedSegmentationMatrix" } ], "discriminator": { "propertyName": "type", "mapping": { "DOUBLE": "#/components/schemas/DoubleSegmentationMatrix", "LINKED": "#/components/schemas/LinkedSegmentationMatrix", "SINGLE": "#/components/schemas/MetricDimension" } } }, "MetricSummary": { "type": "object", "required": [ "id", "name", "code", "aggregation_type", "created_at" ], "properties": { "aggregation_key": { "type": [ "string", "null" ] }, "aggregation_type": { "$ref": "#/components/schemas/BillingMetricAggregateEnum" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/BillableMetricId" }, "name": { "type": "string" } } }, "MetricUsage": { "type": "object", "required": [ "metric_id", "metric_name", "metric_code", "total_value", "grouped_usage" ], "properties": { "grouped_usage": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedUsage" } }, "metric_code": { "type": "string" }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "metric_name": { "type": "string" }, "total_value": { "type": "string", "format": "decimal" } } }, "NeverResetPeriod": { "type": "object", "description": "Never resets — counts all usage since the subscription was activated." }, "NewProductRef": { "type": "object", "required": [ "name", "fee_type", "fee_structure" ], "properties": { "fee_structure": { "$ref": "#/components/schemas/ProductFeeStructure" }, "fee_type": { "$ref": "#/components/schemas/ProductFeeTypeEnum" }, "name": { "type": "string" } } }, "OneTimeFee": { "type": "object", "required": [ "rate", "quantity" ], "properties": { "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, "OneTimeFeeStructure": { "type": "object" }, "OneTimePlanFee": { "type": "object", "description": "One-time fee", "required": [ "unit_price", "quantity" ], "properties": { "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "string", "format": "decimal" } } }, "OneTimePricing": { "type": "object", "required": [ "unit_price", "quantity" ], "properties": { "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "string", "format": "decimal" } } }, "OnlineMethodConfig": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "OnlineMethodsConfig": { "type": "object", "properties": { "card": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnlineMethodConfig" } ] }, "direct_debit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnlineMethodConfig" } ] } } }, "OnlinePaymentMethodConfig": { "type": "object", "properties": { "config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnlineMethodsConfig", "description": "If None, inherits all online providers from invoicing entity." } ] } } }, "PackagePlanPricing": { "type": "object", "required": [ "block_size", "rate" ], "properties": { "block_size": { "type": "integer", "format": "int64", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, "PackagePricing": { "type": "object", "required": [ "block_size", "rate" ], "properties": { "block_size": { "type": "integer", "format": "int64", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, "PaginationResponse": { "type": "object", "required": [ "page", "per_page", "total_items", "total_pages" ], "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0 }, "per_page": { "type": "integer", "format": "int32", "minimum": 0 }, "total_items": { "type": "integer", "format": "int64", "minimum": 0 }, "total_pages": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PatchPlanRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "self_service_rank": { "type": [ "integer", "null" ], "format": "int32" } } }, "PaymentMethodInfo": { "type": "object", "required": [ "payment_method_type" ], "properties": { "account_number_hint": { "type": [ "string", "null" ] }, "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypeEnum" } } }, "PaymentMethodTypeEnum": { "type": "string", "enum": [ "CARD", "BANK_TRANSFER", "WALLET", "OTHER" ] }, "PaymentMethodsConfig": { "oneOf": [ { "$ref": "#/components/schemas/OnlinePaymentMethodConfig" }, { "$ref": "#/components/schemas/BankTransferPaymentMethodConfig" }, { "$ref": "#/components/schemas/ExternalPaymentMethodConfig" } ], "description": "Online (card/direct debit), BankTransfer, or External.", "discriminator": { "propertyName": "type", "mapping": { "bank_transfer": "#/components/schemas/BankTransferPaymentMethodConfig", "external": "#/components/schemas/ExternalPaymentMethodConfig", "online": "#/components/schemas/OnlinePaymentMethodConfig" } } }, "PaymentStatusEnum": { "type": "string", "enum": [ "READY", "PENDING", "SETTLED", "CANCELLED", "FAILED" ] }, "PaymentTransactionId": { "type": "string", "format": "MeteroidId", "examples": [ "pay_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PaymentTypeEnum": { "type": "string", "enum": [ "PAYMENT", "REFUND" ] }, "PerUnitPlanPricing": { "type": "object", "required": [ "rate" ], "properties": { "rate": { "type": "string", "format": "decimal" } } }, "PerUnitPricing": { "type": "object", "required": [ "rate" ], "properties": { "rate": { "type": "string", "format": "decimal" } } }, "PercentageDiscount": { "type": "object", "required": [ "percentage" ], "properties": { "percentage": { "type": "string" } } }, "Plan": { "type": "object", "required": [ "id", "name", "created_at", "plan_type", "status", "product_family", "version_id", "version", "currency", "net_terms", "price_components", "available_parameters" ], "properties": { "available_parameters": { "$ref": "#/components/schemas/AvailableParameters" }, "billing_cycles": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/Entitlement" } }, "id": { "$ref": "#/components/schemas/PlanId" }, "name": { "type": "string" }, "net_terms": { "type": "integer", "format": "int32" }, "period_start_day": { "type": [ "integer", "null" ], "format": "int32" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "price_components": { "type": "array", "items": { "$ref": "#/components/schemas/PriceComponent" } }, "product_family": { "$ref": "#/components/schemas/ProductFamily" }, "self_service_rank": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "trial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TrialConfig" } ] }, "version": { "type": "integer", "format": "int32" }, "version_id": { "$ref": "#/components/schemas/PlanVersionId" } } }, "PlanAddOnInput": { "type": "object", "required": [ "add_on_id" ], "properties": { "add_on_id": { "$ref": "#/components/schemas/AddOnId" }, "max_instances": { "type": [ "integer", "null" ], "format": "int32" }, "price_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PriceId" } ] }, "self_serviceable": { "type": [ "boolean", "null" ] } } }, "PlanEvent": { "allOf": [ { "$ref": "#/components/schemas/PlanEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "PlanEventData": { "type": "object", "required": [ "plan_id", "name", "plan_type", "status", "currency", "version", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "version": { "type": "integer", "format": "int32" } } }, "PlanId": { "type": "string", "format": "MeteroidId", "examples": [ "plan_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PlanListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "PlanStatusEnum": { "type": "string", "title": "PlanStatus", "enum": [ "DRAFT", "ACTIVE", "INACTIVE", "ARCHIVED" ] }, "PlanTypeEnum": { "type": "string", "title": "PlanType", "enum": [ "STANDARD", "FREE", "CUSTOM" ] }, "PlanUsagePricingModel": { "oneOf": [ { "$ref": "#/components/schemas/PerUnitPlanPricing" }, { "$ref": "#/components/schemas/TieredPlanPricing" }, { "$ref": "#/components/schemas/VolumePlanPricing" }, { "$ref": "#/components/schemas/PackagePlanPricing" }, { "$ref": "#/components/schemas/MatrixPlanPricing" } ], "discriminator": { "propertyName": "type", "mapping": { "MATRIX": "#/components/schemas/MatrixPlanPricing", "PACKAGE": "#/components/schemas/PackagePlanPricing", "PER_UNIT": "#/components/schemas/PerUnitPlanPricing", "TIERED": "#/components/schemas/TieredPlanPricing", "VOLUME": "#/components/schemas/VolumePlanPricing" } } }, "PlanVersionId": { "type": "string", "format": "MeteroidId", "examples": [ "plv_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PlanVersionListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanVersionSummary" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "PlanVersionSummary": { "type": "object", "required": [ "id", "version", "is_draft", "currency", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "id": { "$ref": "#/components/schemas/PlanVersionId" }, "is_draft": { "type": "boolean" }, "version": { "type": "integer", "format": "int32" } } }, "PriceComponent": { "type": "object", "required": [ "id", "name" ], "properties": { "fee": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Fee" } ] }, "id": { "$ref": "#/components/schemas/PriceComponentId" }, "name": { "type": "string" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] } } }, "PriceComponentId": { "type": "string", "format": "MeteroidId", "examples": [ "price_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PriceComponentInput": { "type": "object", "required": [ "name", "fee" ], "properties": { "fee": { "$ref": "#/components/schemas/Fee" }, "name": { "type": "string" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] } } }, "PriceEntry": { "oneOf": [ { "$ref": "#/components/schemas/ExistingPriceRef" }, { "$ref": "#/components/schemas/PriceInput" } ], "discriminator": { "propertyName": "type", "mapping": { "EXISTING": "#/components/schemas/ExistingPriceRef", "NEW": "#/components/schemas/PriceInput" } } }, "PriceId": { "type": "string", "format": "MeteroidId", "examples": [ "pri_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PriceInput": { "type": "object", "required": [ "cadence", "currency", "pricing" ], "properties": { "cadence": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "currency": { "type": "string" }, "pricing": { "$ref": "#/components/schemas/Pricing" } } }, "Pricing": { "oneOf": [ { "$ref": "#/components/schemas/RatePricing" }, { "$ref": "#/components/schemas/SlotPricing" }, { "$ref": "#/components/schemas/CapacityPricing" }, { "$ref": "#/components/schemas/UsagePricing" }, { "$ref": "#/components/schemas/ExtraRecurringPricing" }, { "$ref": "#/components/schemas/OneTimePricing" } ], "discriminator": { "propertyName": "type", "mapping": { "CAPACITY": "#/components/schemas/CapacityPricing", "EXTRA_RECURRING": "#/components/schemas/ExtraRecurringPricing", "ONE_TIME": "#/components/schemas/OneTimePricing", "RATE": "#/components/schemas/RatePricing", "SLOT": "#/components/schemas/SlotPricing", "USAGE": "#/components/schemas/UsagePricing" } } }, "Product": { "type": "object", "required": [ "id", "name", "fee_type", "fee_structure", "product_family_id", "catalog", "created_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "catalog": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "fee_structure": { "$ref": "#/components/schemas/ProductFeeStructure" }, "fee_type": { "$ref": "#/components/schemas/ProductFeeTypeEnum" }, "id": { "$ref": "#/components/schemas/ProductId" }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" } } }, "ProductEvent": { "allOf": [ { "$ref": "#/components/schemas/ProductEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "ProductEventData": { "type": "object", "required": [ "product_id", "name", "fee_type", "product_family_id", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "fee_type": { "$ref": "#/components/schemas/ProductFeeTypeEnum" }, "name": { "type": "string" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_id": { "$ref": "#/components/schemas/ProductId" } } }, "ProductFamily": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ProductFamilyId" }, "name": { "type": "string" } } }, "ProductFamilyCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "ProductFamilyId": { "type": "string", "format": "MeteroidId", "examples": [ "pf_7n42DGM5Tflk9n8mt7Fhc7" ] }, "ProductFamilyListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFamily" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "ProductFeeStructure": { "oneOf": [ { "$ref": "#/components/schemas/RateFeeStructure" }, { "$ref": "#/components/schemas/SlotFeeStructure" }, { "$ref": "#/components/schemas/CapacityFeeStructure" }, { "$ref": "#/components/schemas/UsageFeeStructure" }, { "$ref": "#/components/schemas/ExtraRecurringFeeStructure" }, { "$ref": "#/components/schemas/OneTimeFeeStructure" } ], "discriminator": { "propertyName": "type", "mapping": { "CAPACITY": "#/components/schemas/CapacityFeeStructure", "EXTRA_RECURRING": "#/components/schemas/ExtraRecurringFeeStructure", "ONE_TIME": "#/components/schemas/OneTimeFeeStructure", "RATE": "#/components/schemas/RateFeeStructure", "SLOT": "#/components/schemas/SlotFeeStructure", "USAGE": "#/components/schemas/UsageFeeStructure" } } }, "ProductFeeTypeEnum": { "type": "string", "enum": [ "RATE", "SLOT", "CAPACITY", "USAGE", "EXTRA_RECURRING", "ONE_TIME" ] }, "ProductId": { "type": "string", "format": "MeteroidId", "examples": [ "prd_7n42DGM5Tflk9n8mt7Fhc7" ] }, "ProductListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "ProductRef": { "oneOf": [ { "$ref": "#/components/schemas/ExistingProductRef" }, { "$ref": "#/components/schemas/NewProductRef" } ], "discriminator": { "propertyName": "type", "mapping": { "EXISTING": "#/components/schemas/ExistingProductRef", "NEW": "#/components/schemas/NewProductRef" } } }, "QuoteEvent": { "allOf": [ { "$ref": "#/components/schemas/QuoteEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "QuoteEventData": { "type": "object", "required": [ "quote_id", "customer_id" ], "properties": { "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "quote_id": { "$ref": "#/components/schemas/QuoteId" }, "subscription_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionId" } ] } } }, "QuoteId": { "type": "string", "format": "MeteroidId", "examples": [ "quo_7n42DGM5Tflk9n8mt7Fhc7" ] }, "RateFee": { "type": "object", "required": [ "rate" ], "properties": { "rate": { "type": "string", "format": "decimal" } } }, "RateFeeStructure": { "type": "object" }, "RatePlanFee": { "type": "object", "description": "Recurring rate fee (e.g., monthly subscription)", "required": [ "rates" ], "properties": { "rates": { "type": "array", "items": { "$ref": "#/components/schemas/TermRate" } } } }, "RatePricing": { "type": "object", "required": [ "rate" ], "properties": { "rate": { "type": "string", "format": "decimal" } } }, "RecurringFee": { "type": "object", "required": [ "rate", "quantity", "billing_type" ], "properties": { "billing_type": { "$ref": "#/components/schemas/BillingTypeEnum" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, "ReplacePlanRequest": { "type": "object", "required": [ "name", "currency", "components" ], "properties": { "add_ons": { "type": "array", "items": { "$ref": "#/components/schemas/PlanAddOnInput" } }, "billing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingConfig" } ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PriceComponentInput" } }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanStatusEnum" } ] }, "trial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TrialConfig" } ] } } }, "ResetPeriod": { "oneOf": [ { "$ref": "#/components/schemas/BillingCycleResetPeriod", "description": "Resets each time your subscription renews — anchored to your billing cycle." }, { "$ref": "#/components/schemas/CalendarResetPeriod", "description": "Resets on calendar boundaries (e.g. the 1st of every month) — not tied to subscription start date." }, { "$ref": "#/components/schemas/FixedWindowResetPeriod", "description": "Resets at regular intervals — anchored to your subscription's exact activation time." }, { "$ref": "#/components/schemas/SlidingWindowResetPeriod", "description": "Always ends at now — e.g. 30 days means the last 30 days, old usage drops off automatically." }, { "$ref": "#/components/schemas/NeverResetPeriod", "description": "Never resets — counts all usage since the subscription was activated." } ], "discriminator": { "propertyName": "type", "mapping": { "BILLING_CYCLE": "#/components/schemas/BillingCycleResetPeriod", "CALENDAR": "#/components/schemas/CalendarResetPeriod", "FIXED_WINDOW": "#/components/schemas/FixedWindowResetPeriod", "NEVER": "#/components/schemas/NeverResetPeriod", "SLIDING_WINDOW": "#/components/schemas/SlidingWindowResetPeriod" } } }, "ResolvedEntitlement": { "type": "object", "description": "Merged entitlement value for a feature across the priority hierarchy, without usage data.", "required": [ "feature", "value" ], "properties": { "feature": { "$ref": "#/components/schemas/FeatureRef" }, "value": { "$ref": "#/components/schemas/ResolvedEntitlementValue" } } }, "ResolvedEntitlementListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedEntitlement" } } } }, "ResolvedEntitlementValue": { "oneOf": [ { "$ref": "#/components/schemas/BooleanResolvedEntitlementValue" }, { "$ref": "#/components/schemas/MeteredResolvedEntitlementValue" } ], "discriminator": { "propertyName": "type", "mapping": { "BOOLEAN": "#/components/schemas/BooleanResolvedEntitlementValue", "METERED": "#/components/schemas/MeteredResolvedEntitlementValue" } } }, "RestErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" } } }, "ShippingAddress": { "type": "object", "required": [ "same_as_billing" ], "properties": { "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "same_as_billing": { "type": "boolean" } } }, "SlidingWindowResetPeriod": { "type": "object", "description": "Always ends at now — e.g. 30 days means the last 30 days, old usage drops off automatically.", "required": [ "unit", "interval" ], "properties": { "interval": { "type": "integer", "format": "int32", "minimum": 0 }, "unit": { "$ref": "#/components/schemas/CalendarUnit" } } }, "SlotDowngradePolicyEnum": { "type": "string", "enum": [ "REMOVE_AT_END_OF_PERIOD" ] }, "SlotFee": { "type": "object", "required": [ "unit", "unit_rate", "initial_slots" ], "properties": { "initial_slots": { "type": "integer", "format": "int32", "minimum": 0 }, "max_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "unit": { "type": "string" }, "unit_rate": { "type": "string", "format": "decimal" } } }, "SlotFeeStructure": { "type": "object", "required": [ "slot_unit_name", "upgrade_policy", "downgrade_policy" ], "properties": { "downgrade_policy": { "$ref": "#/components/schemas/SlotDowngradePolicyEnum" }, "slot_unit_name": { "type": "string" }, "upgrade_policy": { "$ref": "#/components/schemas/SlotUpgradePolicyEnum" } } }, "SlotPlanFee": { "type": "object", "description": "Slot-based fee (e.g., per-seat pricing)", "required": [ "rates", "slot_unit_name" ], "properties": { "minimum_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "quota": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/TermRate" } }, "slot_unit_name": { "type": "string" } } }, "SlotPricing": { "type": "object", "required": [ "unit_rate" ], "properties": { "max_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "unit_rate": { "type": "string", "format": "decimal" } } }, "SlotUpgradePolicyEnum": { "type": "string", "enum": [ "PRORATED" ] }, "SubLineItem": { "type": "object", "required": [ "id", "name", "total", "quantity", "unit_price" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "string", "format": "decimal" }, "total": { "type": "integer", "format": "int64" }, "unit_price": { "type": "string", "format": "decimal" } } }, "Subscription": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency", "plan_id", "plan_name", "plan_version_id", "plan_version", "status", "start_date", "current_period_start", "net_terms", "mrr_cents", "period", "created_at", "auto_advance_invoices", "charge_automatically" ], "properties": { "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the subscription was activated (first payment or activation condition met)" }, "auto_advance_invoices": { "type": "boolean", "description": "If false, invoices will stay in Draft until manually reviewed and finalized. Default to true." }, "billing_day_anchor": { "type": "integer", "format": "int32" }, "billing_start_date": { "type": [ "string", "null" ], "format": "date", "description": "When billing started (after any trial period)" }, "charge_automatically": { "type": "boolean", "description": "Automatically try to charge the customer's configured payment method on finalize." }, "created_at": { "type": "string", "format": "date-time", "description": "When the subscription was created" }, "currency": { "$ref": "#/components/schemas/Currency" }, "current_period_end": { "type": [ "string", "null" ], "format": "date", "description": "Current billing period end date" }, "current_period_start": { "type": "string", "format": "date", "description": "Current billing period start date" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "When the subscription ends (if set)" }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "invoice_memo": { "type": [ "string", "null" ], "description": "Default memo for invoices" }, "mrr_cents": { "type": "integer", "format": "int64", "description": "Monthly recurring revenue in cents", "minimum": 0 }, "net_terms": { "type": "integer", "format": "int32", "description": "Payment terms in days (0 = due on issue)", "minimum": 0 }, "payment_methods_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodsConfig", "description": "Payment methods configuration (Online, BankTransfer, or External)" } ] }, "period": { "$ref": "#/components/schemas/BillingPeriodEnum", "description": "Billing period (monthly, annual, etc.)" }, "plan_description": { "type": [ "string", "null" ] }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer", "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "purchase_order": { "type": [ "string", "null" ] }, "start_date": { "type": "string", "format": "date", "description": "When the subscription contract starts (benefits apply from this date)" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "trial_duration": { "type": [ "integer", "null" ], "format": "int32", "description": "Trial duration in days", "minimum": 0 } } }, "SubscriptionActivationConditionEnum": { "type": "string", "enum": [ "ON_START", "ON_CHECKOUT", "MANUAL" ] }, "SubscriptionAddOn": { "type": "object", "required": [ "name", "period", "fee", "quantity" ], "properties": { "add_on_id": { "$ref": "#/components/schemas/AddOnId" }, "fee": { "$ref": "#/components/schemas/SubscriptionFee" }, "id": { "$ref": "#/components/schemas/SubscriptionAddOnId" }, "name": { "type": "string" }, "period": { "$ref": "#/components/schemas/SubscriptionFeeBillingPeriodEnum" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SubscriptionAddOnCustomization": { "oneOf": [ { "$ref": "#/components/schemas/SubscriptionAddOnPriceOverride" }, { "$ref": "#/components/schemas/SubscriptionAddOnParameterization" } ], "discriminator": { "propertyName": "type", "mapping": { "PARAMETERIZATION": "#/components/schemas/SubscriptionAddOnParameterization", "PRICE_OVERRIDE": "#/components/schemas/SubscriptionAddOnPriceOverride" } } }, "SubscriptionAddOnId": { "type": "string", "format": "MeteroidId", "examples": [ "sub_add_7n42DGM5Tflk9n8mt7Fhc7" ] }, "SubscriptionAddOnParameterization": { "type": "object", "properties": { "billing_period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPeriodEnum" } ] }, "committed_capacity": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "initial_slot_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "SubscriptionAddOnPriceOverride": { "type": "object", "required": [ "price_entry" ], "properties": { "name": { "type": [ "string", "null" ] }, "price_entry": { "$ref": "#/components/schemas/PriceEntry" } } }, "SubscriptionComponent": { "type": "object", "required": [ "name", "period", "fee" ], "properties": { "fee": { "$ref": "#/components/schemas/SubscriptionFee" }, "name": { "type": "string" }, "period": { "$ref": "#/components/schemas/SubscriptionFeeBillingPeriodEnum" }, "price_component_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PriceComponentId" } ] }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] } } }, "SubscriptionCoupon": { "type": "object", "description": "Coupon as embedded in subscription details — a subset of the `Coupon` resource\nreturned by the coupons API.", "required": [ "id", "code", "description", "discount", "reusable", "disabled" ], "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "disabled": { "type": "boolean" }, "discount": { "$ref": "#/components/schemas/CouponDiscount" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/CouponId" }, "recurring_value": { "type": [ "integer", "null" ], "format": "int32" }, "redemption_limit": { "type": [ "integer", "null" ], "format": "int32" }, "reusable": { "type": "boolean" } } }, "SubscriptionCreateRequest": { "type": "object", "required": [ "plan_id", "customer_id_or_alias", "start_date", "activation_condition" ], "properties": { "activation_condition": { "$ref": "#/components/schemas/SubscriptionActivationConditionEnum" }, "add_ons": { "type": "array", "items": { "$ref": "#/components/schemas/CreateSubscriptionAddOn" } }, "auto_advance_invoices": { "type": "boolean" }, "billing_day_anchor": { "type": [ "integer", "null" ], "format": "int32", "maximum": 32767, "minimum": 1 }, "charge_automatically": { "type": "boolean" }, "coupon_codes": { "type": "array", "items": { "type": "string" } }, "customer_id_or_alias": { "type": "string", "format": "CustomerId or customer alias" }, "end_date": { "type": "string", "format": "date", "examples": [ "2025-11-01" ] }, "invoice_memo": { "type": "string" }, "net_terms": { "type": "integer", "format": "int32", "minimum": 0 }, "payment_methods_config": { "$ref": "#/components/schemas/PaymentMethodsConfig", "description": "Payment methods configuration. If not specified, inherits from the invoicing entity." }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "price_components": { "$ref": "#/components/schemas/CreateSubscriptionComponents" }, "purchase_order": { "type": [ "string", "null" ] }, "skip_past_invoices": { "type": "boolean", "description": "Migration mode: when true with a past start_date, skip creating invoices for past cycles.\nThe subscription will be set to the current billing period with correct cycle_index." }, "start_date": { "type": "string", "format": "date", "examples": [ "2024-11-01" ] }, "trial_days": { "type": "integer", "format": "int32", "minimum": 0 }, "version": { "type": "integer", "format": "int32" } } }, "SubscriptionDetails": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency", "plan_id", "plan_name", "plan_version_id", "plan_version", "status", "start_date", "current_period_start", "net_terms", "mrr_cents", "period", "created_at", "auto_advance_invoices", "charge_automatically", "components", "add_ons", "applied_coupons" ], "properties": { "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the subscription was activated (first payment or activation condition met)" }, "add_ons": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAddOn" } }, "applied_coupons": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedCouponDetailed" } }, "auto_advance_invoices": { "type": "boolean" }, "billing_day_anchor": { "type": "integer", "format": "int32" }, "billing_start_date": { "type": [ "string", "null" ], "format": "date", "description": "When billing started (after any trial period)" }, "charge_automatically": { "type": "boolean" }, "checkout_url": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionComponent" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the subscription was created" }, "currency": { "$ref": "#/components/schemas/Currency" }, "current_period_end": { "type": [ "string", "null" ], "format": "date", "description": "Current billing period end date" }, "current_period_start": { "type": "string", "format": "date", "description": "Current billing period start date" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "When the subscription ends (if set)" }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/Entitlement" } }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "invoice_memo": { "type": [ "string", "null" ], "description": "Default memo for invoices" }, "mrr_cents": { "type": "integer", "format": "int64", "description": "Monthly recurring revenue in cents", "minimum": 0 }, "net_terms": { "type": "integer", "format": "int32", "description": "Payment terms in days (0 = due on issue)", "minimum": 0 }, "payment_methods_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodsConfig" } ] }, "period": { "$ref": "#/components/schemas/BillingPeriodEnum", "description": "Billing period (monthly, annual, etc.)" }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer", "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "purchase_order": { "type": [ "string", "null" ] }, "start_date": { "type": "string", "format": "date", "description": "When the subscription contract starts (benefits apply from this date)" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "trial_duration": { "type": [ "integer", "null" ], "format": "int32", "description": "Trial duration in days", "minimum": 0 } } }, "SubscriptionEvent": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventData" }, { "type": "object", "required": [ "id", "type", "timestamp" ], "properties": { "id": { "$ref": "#/components/schemas/EventId" }, "timestamp": { "type": "string", "format": "date-time" }, "type": { "$ref": "#/components/schemas/EventType" } } } ] }, "SubscriptionEventData": { "type": "object", "required": [ "subscription_id", "customer_id", "customer_name", "billing_day_anchor", "currency", "start_date", "plan_name", "version", "created_at", "net_terms", "mrr_cents", "period", "status" ], "properties": { "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "billing_day_anchor": { "type": "integer", "format": "int32", "minimum": 0 }, "billing_start_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "invoice_memo": { "type": [ "string", "null" ] }, "invoice_threshold": { "type": [ "string", "null" ] }, "mrr_cents": { "type": "integer", "format": "int64", "minimum": 0 }, "net_terms": { "type": "integer", "format": "int32", "minimum": 0 }, "period": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "plan_name": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "subscription_id": { "$ref": "#/components/schemas/SubscriptionId" }, "trial_duration": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SubscriptionFee": { "oneOf": [ { "$ref": "#/components/schemas/RateFee" }, { "$ref": "#/components/schemas/OneTimeFee" }, { "$ref": "#/components/schemas/RecurringFee" }, { "$ref": "#/components/schemas/CapacityFee" }, { "$ref": "#/components/schemas/SlotFee" }, { "$ref": "#/components/schemas/UsageFee" } ], "discriminator": { "propertyName": "type", "mapping": { "CAPACITY": "#/components/schemas/CapacityFee", "ONE_TIME": "#/components/schemas/OneTimeFee", "RATE": "#/components/schemas/RateFee", "RECURRING": "#/components/schemas/RecurringFee", "SLOT": "#/components/schemas/SlotFee", "USAGE": "#/components/schemas/UsageFee" } } }, "SubscriptionFeeBillingPeriodEnum": { "type": "string", "enum": [ "ONE_TIME", "MONTHLY", "QUARTERLY", "SEMIANNUAL", "ANNUAL" ] }, "SubscriptionId": { "type": "string", "format": "MeteroidId", "examples": [ "sub_7n42DGM5Tflk9n8mt7Fhc7" ] }, "SubscriptionListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "SubscriptionStatusEnum": { "type": "string", "title": "SubscriptionStatus", "enum": [ "PENDING_ACTIVATION", "PENDING_CHARGE", "TRIAL_ACTIVE", "ACTIVE", "TRIAL_EXPIRED", "PAUSED", "SUSPENDED", "CANCELLED", "COMPLETED", "SUPERSEDED", "ERRORED" ] }, "SubscriptionUpdateRequest": { "type": "object", "properties": { "auto_advance_invoices": { "type": [ "boolean", "null" ], "description": "If false, invoices will stay in Draft until manually reviewed and finalized." }, "charge_automatically": { "type": [ "boolean", "null" ], "description": "Automatically try to charge the customer's configured payment method on finalize." }, "invoice_memo": { "type": [ "string", "null" ], "description": "Default memo for invoices" }, "net_terms": { "type": [ "integer", "null" ], "format": "int32", "description": "Payment terms in days (0 = due on issue)", "minimum": 0 }, "payment_methods_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodsConfig", "description": "Payment methods configuration (Online, BankTransfer, or External)" } ] }, "purchase_order": { "type": [ "string", "null" ], "description": "Purchase order number" } } }, "SubscriptionUpdateResponse": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionDetails" } } }, "TaxBreakdownItem": { "type": "object", "required": [ "taxable_amount", "tax_amount", "tax_rate", "name" ], "properties": { "exemption_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaxExemptionType" } ] }, "name": { "type": "string" }, "tax_amount": { "type": "integer", "format": "int64", "minimum": 0 }, "tax_rate": { "type": "string", "format": "decimal" }, "taxable_amount": { "type": "integer", "format": "int64", "minimum": 0 } } }, "TaxExemptionType": { "type": "string", "enum": [ "REVERSE_CHARGE", "TAX_EXEMPT", "NOT_REGISTERED" ] }, "TermRate": { "type": "object", "required": [ "term", "price" ], "properties": { "price": { "type": "string", "format": "decimal" }, "term": { "$ref": "#/components/schemas/BillingPeriodEnum" } } }, "TierRow": { "type": "object", "required": [ "first_unit", "rate" ], "properties": { "first_unit": { "type": "integer", "format": "int64", "minimum": 0 }, "flat_cap": { "type": [ "string", "null" ], "format": "decimal" }, "flat_fee": { "type": [ "string", "null" ], "format": "decimal" }, "rate": { "type": "string", "format": "decimal" } } }, "TieredPlanPricing": { "type": "object", "required": [ "tiers" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } }, "TieredPricing": { "type": "object", "required": [ "tiers" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } }, "Transaction": { "type": "object", "required": [ "id", "amount", "currency", "status", "payment_type" ], "properties": { "amount": { "type": "integer", "format": "int64", "minimum": 0 }, "currency": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/PaymentTransactionId" }, "payment_method_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CustomerPaymentMethodId" } ] }, "payment_method_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodInfo" } ] }, "payment_type": { "$ref": "#/components/schemas/PaymentTypeEnum" }, "processed_at": { "type": [ "string", "null" ], "format": "date-time" }, "provider_transaction_id": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/PaymentStatusEnum" } } }, "TrialConfig": { "type": "object", "required": [ "duration_days", "is_free" ], "properties": { "duration_days": { "type": "integer", "format": "int32", "minimum": 0 }, "is_free": { "type": "boolean" }, "trialing_plan_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanId" } ] } } }, "UnitConversion": { "type": "object", "required": [ "factor", "rounding" ], "properties": { "factor": { "type": "integer", "format": "int32" }, "rounding": { "$ref": "#/components/schemas/UnitConversionRoundingEnum" } } }, "UnitConversionRoundingEnum": { "type": "string", "enum": [ "UP", "DOWN", "NEAREST", "NEAREST_HALF", "NEAREST_DECILE", "NONE" ] }, "UpdateAddOnRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "max_instances_per_subscription": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "price_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PriceId" } ] }, "self_serviceable": { "type": [ "boolean", "null" ] } } }, "UpdateCouponRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "discount": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CouponDiscount" } ] }, "plan_ids": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PlanId" } } } }, "UpdateMetricRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "segmentation_matrix": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MetricSegmentationMatrix" } ] }, "unit_conversion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitConversion" } ] } } }, "UpdateProductRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "fee_structure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductFeeStructure" } ] }, "name": { "type": [ "string", "null" ] } } }, "UsageFee": { "type": "object", "required": [ "metric_id", "model" ], "properties": { "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "model": { "$ref": "#/components/schemas/UsagePricingModel" } } }, "UsageFeeStructure": { "type": "object", "required": [ "metric_id", "model" ], "properties": { "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "model": { "$ref": "#/components/schemas/UsageModelEnum" } } }, "UsageModelEnum": { "type": "string", "enum": [ "PER_UNIT", "TIERED", "VOLUME", "PACKAGE", "MATRIX" ] }, "UsagePlanFee": { "type": "object", "description": "Usage-based fee", "required": [ "metric_id", "pricing", "cadence" ], "properties": { "cadence": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "pricing": { "$ref": "#/components/schemas/PlanUsagePricingModel" } } }, "UsagePricing": { "type": "object", "required": [ "model" ], "properties": { "model": { "$ref": "#/components/schemas/UsagePricingModel" } } }, "UsagePricingModel": { "oneOf": [ { "$ref": "#/components/schemas/PerUnitPricing" }, { "$ref": "#/components/schemas/TieredPricing" }, { "$ref": "#/components/schemas/VolumePricing" }, { "$ref": "#/components/schemas/PackagePricing" }, { "$ref": "#/components/schemas/MatrixPricing" } ], "discriminator": { "propertyName": "type", "mapping": { "MATRIX": "#/components/schemas/MatrixPricing", "PACKAGE": "#/components/schemas/PackagePricing", "PER_UNIT": "#/components/schemas/PerUnitPricing", "TIERED": "#/components/schemas/TieredPricing", "VOLUME": "#/components/schemas/VolumePricing" } } }, "UsageResponse": { "type": "object", "required": [ "period_start", "period_end", "usage" ], "properties": { "period_end": { "type": "string", "format": "date" }, "period_start": { "type": "string", "format": "date" }, "usage": { "type": "array", "items": { "$ref": "#/components/schemas/MetricUsage" } } } }, "VolumePlanPricing": { "type": "object", "required": [ "tiers" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } }, "VolumePricing": { "type": "object", "required": [ "tiers" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Meteroid", "description": "Meteroid API" }, { "name": "Add-ons" }, { "name": "Batch Jobs" }, { "name": "Checkout Sessions" }, { "name": "Coupons" }, { "name": "Credit Notes" }, { "name": "Customers" }, { "name": "Entitlements" }, { "name": "Events" }, { "name": "Features" }, { "name": "Invoices" }, { "name": "Metrics" }, { "name": "Plans" }, { "name": "Product Families" }, { "name": "Products" }, { "name": "Subscriptions" }, { "name": "Usage" } ], "webhooks": { "addon.archived": { "post": { "summary": "addon.archived webhook", "description": "An add-on was archived", "operationId": "webhook_addon_archived", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "addon.archived", "add_on_id": "add_7n42DGM5Tflk9n8mt7Fhc7", "name": "Extra Storage", "description": "Additional storage capacity", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "price_id": "pri_7n42DGM5Tflk9n8mt7Fhc7", "fee_type": "USAGE", "self_serviceable": true, "max_instances_per_subscription": 5, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "addon.created": { "post": { "summary": "addon.created webhook", "description": "A new add-on was created", "operationId": "webhook_addon_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "addon.created", "add_on_id": "add_7n42DGM5Tflk9n8mt7Fhc7", "name": "Extra Storage", "description": "Additional storage capacity", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "price_id": "pri_7n42DGM5Tflk9n8mt7Fhc7", "fee_type": "USAGE", "self_serviceable": true, "max_instances_per_subscription": 5, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "addon.updated": { "post": { "summary": "addon.updated webhook", "description": "An add-on was updated", "operationId": "webhook_addon_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "addon.updated", "add_on_id": "add_7n42DGM5Tflk9n8mt7Fhc7", "name": "Extra Storage", "description": "Additional storage capacity", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "price_id": "pri_7n42DGM5Tflk9n8mt7Fhc7", "fee_type": "USAGE", "self_serviceable": true, "max_instances_per_subscription": 5, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "coupon.archived": { "post": { "summary": "coupon.archived webhook", "description": "A coupon was archived", "operationId": "webhook_coupon_archived", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "coupon.archived", "coupon_id": "cou_7n42DGM5Tflk9n8mt7Fhc7", "code": "WELCOME20", "description": "20% off for new customers", "discount": { "type": "PERCENTAGE", "percentage": "20" }, "redemption_limit": 100, "recurring_value": 3, "reusable": false, "disabled": false, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "coupon.created": { "post": { "summary": "coupon.created webhook", "description": "A new coupon was created", "operationId": "webhook_coupon_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "coupon.created", "coupon_id": "cou_7n42DGM5Tflk9n8mt7Fhc7", "code": "WELCOME20", "description": "20% off for new customers", "discount": { "type": "PERCENTAGE", "percentage": "20" }, "redemption_limit": 100, "recurring_value": 3, "reusable": false, "disabled": false, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "coupon.updated": { "post": { "summary": "coupon.updated webhook", "description": "A coupon was updated", "operationId": "webhook_coupon_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "coupon.updated", "coupon_id": "cou_7n42DGM5Tflk9n8mt7Fhc7", "code": "WELCOME20", "description": "20% off for new customers", "discount": { "type": "PERCENTAGE", "percentage": "20" }, "redemption_limit": 100, "recurring_value": 3, "reusable": false, "disabled": false, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "credit_note.created": { "post": { "summary": "credit_note.created webhook", "description": "A new credit note was created", "operationId": "webhook_credit_note_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "credit_note.created", "credit_note_id": "crn_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 5000, "tax_amount": 1000, "refunded_amount_cents": 0, "credited_amount_cents": 5000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "credit_note.finalized": { "post": { "summary": "credit_note.finalized webhook", "description": "A credit note was finalized", "operationId": "webhook_credit_note_finalized", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "credit_note.finalized", "credit_note_id": "crn_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 5000, "tax_amount": 1000, "refunded_amount_cents": 0, "credited_amount_cents": 5000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "credit_note.voided": { "post": { "summary": "credit_note.voided webhook", "description": "A credit note was voided", "operationId": "webhook_credit_note_voided", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "credit_note.voided", "credit_note_id": "crn_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 5000, "tax_amount": 1000, "refunded_amount_cents": 0, "credited_amount_cents": 5000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "customer.created": { "post": { "summary": "customer.created webhook", "description": "A new customer was created", "operationId": "webhook_customer_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "customer.created", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "name": "Acme Corporation", "alias": "ACME", "billing_email": "billing@acme.example", "invoicing_emails": [ "invoices@acme.example" ], "phone": "+1-555-0123", "currency": "USD", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "invoice.consolidated": { "post": { "summary": "invoice.consolidated webhook", "description": "An invoice was merged into a consolidated invoice and is superseded by its parent", "operationId": "webhook_invoice_consolidated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "invoice.consolidated", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 10000, "tax_amount": 2000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "invoice.created": { "post": { "summary": "invoice.created webhook", "description": "A new invoice was created", "operationId": "webhook_invoice_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "invoice.created", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 10000, "tax_amount": 2000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "invoice.finalized": { "post": { "summary": "invoice.finalized webhook", "description": "An invoice was finalized", "operationId": "webhook_invoice_finalized", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "invoice.finalized", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 10000, "tax_amount": 2000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "invoice.paid": { "post": { "summary": "invoice.paid webhook", "description": "An invoice was paid", "operationId": "webhook_invoice_paid", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "invoice.paid", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 10000, "tax_amount": 2000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "invoice.voided": { "post": { "summary": "invoice.voided webhook", "description": "An invoice was voided", "operationId": "webhook_invoice_voided", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "invoice.voided", "invoice_id": "inv_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "status": "DRAFT", "currency": "EUR", "total": 10000, "tax_amount": 2000, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "metric.archived": { "post": { "summary": "metric.archived webhook", "description": "A billable metric was archived", "operationId": "webhook_metric_archived", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "metric.archived", "metric_id": "bm_7n42DGM5Tflk9n8mt7Fhc7", "name": "Api Calls", "code": "api_calls", "aggregation_type": "COUNT", "created_at": "1970-01-01T00:00:00", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "metric.created": { "post": { "summary": "metric.created webhook", "description": "A new billable metric was created", "operationId": "webhook_metric_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "metric.created", "metric_id": "bm_7n42DGM5Tflk9n8mt7Fhc7", "name": "Api Calls", "code": "api_calls", "aggregation_type": "COUNT", "created_at": "1970-01-01T00:00:00", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "metric.updated": { "post": { "summary": "metric.updated webhook", "description": "A billable metric was updated", "operationId": "webhook_metric_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "metric.updated", "metric_id": "bm_7n42DGM5Tflk9n8mt7Fhc7", "name": "Api Calls", "code": "api_calls", "aggregation_type": "COUNT", "created_at": "1970-01-01T00:00:00", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "plan.archived": { "post": { "summary": "plan.archived webhook", "description": "A plan was archived", "operationId": "webhook_plan_archived", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "plan.archived", "plan_id": "plan_7n42DGM5Tflk9n8mt7Fhc7", "name": "Enterprise Plan", "description": "Our enterprise tier", "plan_type": "STANDARD", "status": "ACTIVE", "currency": "USD", "version": 1, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "plan.created": { "post": { "summary": "plan.created webhook", "description": "A new plan was created", "operationId": "webhook_plan_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "plan.created", "plan_id": "plan_7n42DGM5Tflk9n8mt7Fhc7", "name": "Enterprise Plan", "description": "Our enterprise tier", "plan_type": "STANDARD", "status": "ACTIVE", "currency": "USD", "version": 1, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "plan.published": { "post": { "summary": "plan.published webhook", "description": "A plan version was published", "operationId": "webhook_plan_published", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "plan.published", "plan_id": "plan_7n42DGM5Tflk9n8mt7Fhc7", "name": "Enterprise Plan", "description": "Our enterprise tier", "plan_type": "STANDARD", "status": "ACTIVE", "currency": "USD", "version": 1, "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "product.archived": { "post": { "summary": "product.archived webhook", "description": "A product was archived", "operationId": "webhook_product_archived", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "product.archived", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "name": "API Calls Product", "description": "Usage-based API calls product", "fee_type": "USAGE", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "product.created": { "post": { "summary": "product.created webhook", "description": "A new product was created", "operationId": "webhook_product_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "product.created", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "name": "API Calls Product", "description": "Usage-based API calls product", "fee_type": "USAGE", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "product.updated": { "post": { "summary": "product.updated webhook", "description": "A product was updated", "operationId": "webhook_product_updated", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "product.updated", "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7", "name": "API Calls Product", "description": "Usage-based API calls product", "fee_type": "USAGE", "product_family_id": "pf_7n42DGM5Tflk9n8mt7Fhc7", "created_at": "1970-01-01T00:00:00.000Z", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "quote.accepted": { "post": { "summary": "quote.accepted webhook", "description": "A quote was accepted", "operationId": "webhook_quote_accepted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "quote.accepted", "quote_id": "quo_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "quote.converted": { "post": { "summary": "quote.converted webhook", "description": "A quote was converted into subscription", "operationId": "webhook_quote_converted", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "quote.converted", "quote_id": "quo_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "subscription.created": { "post": { "summary": "subscription.created webhook", "description": "A new subscription was created", "operationId": "webhook_subscription_created", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEvent" }, "example": { "id": "evt_7n42DGM5Tflk9n8mt7Fhc7", "type": "subscription.created", "subscription_id": "sub_7n42DGM5Tflk9n8mt7Fhc7", "customer_id": "cus_7n42DGM5Tflk9n8mt7Fhc7", "customer_alias": "ACME", "customer_name": "Acme Corporation", "billing_day_anchor": 1, "currency": "EUR", "start_date": "1970-01-01", "plan_name": "default", "version": 0, "created_at": "1970-01-01T00:00:00.000Z", "net_terms": 0, "mrr_cents": 0, "period": "MONTHLY", "status": "PENDING_ACTIVATION", "timestamp": "1970-01-01T00:00:00.000Z" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } } }