{ "openapi": "3.0.1", "info": { "title": "Usage Based Billing API", "version": "1.0.0", "description": "An Orchestrator for Usage Based Billing and Payments" }, "servers": [ { "url": "https://api-m.sandbox.paypal.com/v1/commerce/billing" } ], "security": [ { "BearerAuth": [ "read", "write" ] } ], "tags": [ { "name": "Alerts", "description": "API endpoints for managing subscription alerts" }, { "name": "Events", "description": "API endpoints for managing events" }, { "name": "Metrics", "description": "API endpoints for metrics and usage data" }, { "name": "Merchant Activation", "description": "API endpoint for merchant activation" }, { "name": "Credit Notes", "description": "API endpoints for credit notes management" }, { "name": "Customers", "description": "API endpoints for customer management" }, { "name": "Invoices", "description": "API endpoints for invoice management" }, { "name": "Plans", "description": "API endpoints for subscription plans" }, { "name": "Subscriptions", "description": "API endpoints for subscriptions" }, { "name": "Wallets", "description": "API endpoints for wallet management" }, { "name": "Taxes", "description": "API endpoints for tax management" }, { "name": "Billing Entities", "description": "API endpoints for billing entities" }, { "name": "Features", "description": "API endpoints for managing features and privileges" }, { "name": "Entitlements", "description": "API endpoints for managing plan and subscription entitlements" } ], "paths": { "/billing-entities": { "get": { "tags": [ "Billing Entities" ], "summary": "List all billing entities", "operationId": "GetBillingEntities", "responses": { "200": { "description": "List of billing entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityListResponse" }, "example": [ { "id": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c", "code": "acme_inc", "name": "Acme Inc", "default_currency": "USD", "finalize_zero_amount_invoice": true, "is_default": true, "address": { "line1": "123 Business Ave", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94107" }, "legal_name": "Acme Corporation Inc.", "legal_number": "US123456789", "email": "billing@acmeinc.com", "timezone": "America/Los_Angeles", "created_at": "2023-01-15T00:00:00Z", "updated_at": "2023-01-15T00:00:00Z" }, { "id": "c9f3b767-15fc-552d-b7c3-cfab0f3b1f8d", "code": "acme_eu", "name": "Acme Europe", "default_currency": "EUR", "finalize_zero_amount_invoice": true, "is_default": false, "address": { "line1": "456 Business Blvd", "city": "Paris", "country": "FR", "postal_code": "75001" }, "legal_name": "Acme Corporation SARL", "legal_number": "FR987654321", "email": "europe-billing@acmeinc.com", "timezone": "Europe/Paris", "created_at": "2023-01-15T00:00:00Z", "updated_at": "2023-01-15T00:00:00Z" } ] } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Billing Entities" ], "summary": "Create a billing entity", "operationId": "CreateBillingEntity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityCreateRequest" } } } }, "responses": { "201": { "description": "Billing entity created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityResponse" }, "example": { "id": "e7f4c956-23fc-663d-a8c3-egcb1f5d4h0e", "code": "acme_west", "name": "Acme Western Division", "default_currency": "USD", "finalize_zero_amount_invoice": true, "is_default": false, "address": { "line1": "789 Tech Boulevard", "line2": "Suite 1200", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94107" }, "legal_name": "Acme Corporation Western LLC", "legal_number": "US87654321", "email": "west-billing@acmeinc.com", "timezone": "America/Los_Angeles", "created_at": "2023-01-15T00:00:00Z", "updated_at": "2023-01-15T00:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/billing-entities/{billing_entity_code}": { "parameters": [ { "name": "billing_entity_code", "in": "path", "description": "Unique code identifier of the billing entity", "required": true, "schema": { "type": "string" }, "example": "acme_inc" } ], "get": { "tags": [ "Billing Entities" ], "summary": "Get a billing entity by code", "operationId": "GetBillingEntityByCode", "responses": { "200": { "description": "Billing entity details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityResponse" }, "example": { "id": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c", "code": "acme_inc", "name": "Acme Inc", "default_currency": "USD", "finalize_zero_amount_invoice": true, "is_default": true, "address": { "line1": "123 Business Ave", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94107" }, "legal_name": "Acme Corporation Inc.", "legal_number": "US123456789", "email": "billing@acmeinc.com", "timezone": "America/Los_Angeles", "created_at": "2023-01-15T00:00:00Z", "updated_at": "2023-01-15T00:00:00Z", "taxes": [ { "id": "d4e3c878-16fd-663e-c8d4-dgab0f4c2g9e", "name": "California State Sales Tax", "code": "us_ca_sales_tax_8_25", "description": "California State Sales Tax", "rate": "8.25", "created_at": "2023-01-15T00:00:00Z" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Billing Entities" ], "summary": "Update a billing entity by code", "operationId": "UpdateBillingEntityByCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityUpdateRequest" } } } }, "responses": { "200": { "description": "Billing entity updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntityResponse" }, "example": { "id": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c", "code": "acme_inc", "name": "Acme Inc (Updated)", "default_currency": "USD", "finalize_zero_amount_invoice": true, "is_default": true, "address": { "line1": "123 Business Ave, Suite 500", "line2": "Floor 5", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94107" }, "legal_name": "Acme Corporation Inc. LLC", "legal_number": "US987654321", "email": "billing-updated@acmeinc.com", "timezone": "America/Los_Angeles", "created_at": "2023-01-15T00:00:00Z", "updated_at": "2023-01-16T05:30:00Z", "taxes": [ { "id": "d4e3c878-16fd-663e-c8d4-dgab0f4c2g9e", "name": "California State Sales Tax", "code": "us_ca_sales_tax_8_25", "description": "California State Sales Tax", "rate": "8.25", "created_at": "2023-01-15T00:00:00Z" }, { "id": "e5f4d989-27ge-774f-d9e5-ehbc1g5d3h0f", "name": "San Francisco City Tax", "code": "us_sf_city_tax_1_25", "description": "San Francisco City Tax", "rate": "1.25", "created_at": "2023-01-16T05:30:00Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/taxes": { "post": { "tags": [ "Taxes" ], "summary": "Create a tax", "description": "Creates a new tax that can be applied to invoices", "operationId": "CreateTax", "requestBody": { "description": "Tax creation request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCreateRequest" }, "examples": { "StandardTax": { "value": { "name": "Standard VAT", "code": "standard_vat", "rate": "20.00", "description": "Standard Value Added Tax" } } } } } }, "responses": { "201": { "description": "Successfully created tax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxResponse" }, "example": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "name": "Standard VAT", "code": "standard_vat", "description": "Standard Value Added Tax", "rate": "20.00", "created_at": "2023-07-06T14:35:58Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Taxes" ], "summary": "List all taxes", "description": "Retrieves a paginated list of all taxes", "operationId": "GetTaxes", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Successfully retrieved taxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesPaginated" }, "example": { "taxes": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "name": "Standard VAT", "code": "standard_vat", "description": "Standard Value Added Tax", "rate": "20.00", "created_at": "2023-07-06T14:35:58Z" }, { "id": "2b902b90-2b90-2b90-2b90-2b902b902b90", "name": "Reduced VAT", "code": "reduced_vat", "description": "Reduced Value Added Tax", "rate": "5.00", "created_at": "2023-07-06T14:45:23Z" } ], "meta": { "total_count": 2, "total_pages": 1, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/taxes/{tax_code}": { "parameters": [ { "name": "tax_code", "in": "path", "description": "Unique identifier code for the tax", "required": true, "schema": { "type": "string" }, "example": "standard_vat" } ], "get": { "tags": [ "Taxes" ], "summary": "Retrieve a Tax", "description": "Retrieves an existing tax by its unique code", "operationId": "GetTaxByCode", "responses": { "200": { "description": "Successfully retrieved tax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxResponse" }, "example": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "name": "Standard VAT", "code": "standard_vat", "description": "Standard Value Added Tax", "rate": "20.00", "created_at": "2023-07-06T14:35:58Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Taxes" ], "summary": "Update a tax", "description": "Updates an existing tax", "operationId": "UpdateTax", "requestBody": { "description": "Tax update request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxUpdateRequest" }, "example": { "name": "Updated VAT", "rate": "21.50", "description": "Updated Value Added Tax" } } } }, "responses": { "200": { "description": "Successfully updated tax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxResponse" }, "example": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "name": "Updated VAT", "code": "standard_vat", "description": "Updated Value Added Tax", "rate": "21.50", "created_at": "2023-07-06T14:35:58Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Taxes" ], "summary": "Delete a tax", "description": "Deletes an existing tax", "operationId": "DeleteTax", "responses": { "204": { "description": "Tax deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/activate": { "post": { "operationId": "ActivateMerchant", "tags": [ "Merchant Activation" ], "summary": "Activate Usage Based Billing", "responses": { "200": { "description": "Merchant account activated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateMerchantResponse" }, "example": { "billing_tier_id": "NDc3Nzc1NTg0NTY0MTgyMzUzNw==.K7iva2SX08+9R52rAIfUwQvruZackQErIDDdEnUxxKE=" } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidAccessToken": { "summary": "Insufficient permissions", "value": { "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] } }, "accountNotActivated": { "summary": "Account not activated", "value": { "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "ACCOUNT_NOT_ACTIVATED", "description": "The account is not activated for Usage-based Billing." } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices": { "get": { "operationId": "GetInvoices", "tags": [ "Invoices" ], "summary": "Get all invoices", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" }, { "name": "status", "in": "query", "description": "Filter invoices by status", "required": false, "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "name": "payment_status", "in": "query", "description": "Filter invoices by payment status (e.g., pending, failed, succeeded)", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "FAILED", "SUCCEEDED" ], "default": "PENDING", "x-enum-varnames": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-descriptions": [ "The invoice is awaiting payment.", "The payment for the invoice has failed.", "The payment for the invoice was successful." ] } }, { "name": "external_customer_id", "in": "query", "description": "Filter invoices by external customer ID", "required": false, "schema": { "type": "string" } }, { "name": "issuing_date_from", "in": "query", "description": "Filter invoices issued on or after this date (ISO 8601 format)", "required": true, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "issuing_date_to", "in": "query", "description": "Filter invoices issued on or before this date (ISO 8601 format)", "required": true, "schema": { "$ref": "#/components/schemas/Date" } } ], "responses": { "200": { "description": "A list of invoices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "invoices": [ { "id": "27986ceb-bb27-461d-82b1-f044646e192d", "sequential_id": 5, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 220.2, "currency_code": "USD" } }, "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-012", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "Test Plan Override Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "country": "US" }, "phone": "+1 (555) 789-1234", "id": "5a31b634-3213-42f5-a184-c68f93e47dc1" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:00Z" }, { "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa", "sequential_id": 3, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 500.11, "currency_code": "USD" } }, "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-003", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "CUST_NLT_1752783445", "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445", "email": "sakdjas@comp.net", "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:02Z" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{invoice_id}": { "get": { "operationId": "GetInvoiceById", "tags": [ "Invoices" ], "summary": "Get a single invoice by ID", "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "responses": { "200": { "description": "A single invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceWithId" }, "example": { "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa", "sequential_id": 3, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 500.11, "currency_code": "USD" } }, "fees": [ { "id": "f3c91be7-85ba-4f41-857b-f844749e4f1b", "total_amount": { "value": 500, "currency_code": "USD" } }, { "id": "e58684ef-8e26-4339-a2ba-b243beffc3f1", "total_amount": { "value": 0.11, "currency_code": "USD" } } ], "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-003", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "Test Plan Override Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445", "email": "dsadiaj@bert.com", "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:02Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{invoice_id}/retry_payment": { "post": { "operationId": "RetryInvoicePayment", "tags": [ "Invoices" ], "summary": "Retry payment for a specific invoice", "parameters": [ { "name": "invoice_id", "in": "path", "description": "The ID of the invoice to retry payment for.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content. The payment retry was successfully triggered." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metrics": { "get": { "operationId": "GetMetrics", "tags": [ "Metrics" ], "summary": "Get all metrics", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "A list of metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResponse" } }, "pagination_metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "metrics": [ { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } ], "pagination_metadata": { "total_count": 1, "total_pages": 10, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateMetric", "tags": [ "Metrics" ], "summary": "Create a new metric", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricRequest" }, "example": { "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ] } } } }, "responses": { "201": { "description": "Metric created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metrics/{metric_code}": { "get": { "operationId": "GetMetricByCode", "tags": [ "Metrics" ], "summary": "Get a metric by code", "parameters": [ { "$ref": "#/components/parameters/metric_code" } ], "responses": { "200": { "description": "Metric retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateMetricByCode", "tags": [ "Metrics" ], "summary": "Update a metric by Code", "parameters": [ { "$ref": "#/components/parameters/metric_code" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricUpdateRequest" }, "example": { "name": "Updated Metric", "description": "This metric has been updated", "code": "updated_metric_code", "type": "METERED", "aggregation_type": "SUM", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1" ] } ] } } } }, "responses": { "200": { "description": "Metric updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteMetricByCode", "tags": [ "Metrics" ], "summary": "Delete a metric by Code", "parameters": [ { "$ref": "#/components/parameters/metric_code" } ], "responses": { "204": { "description": "Metric deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans": { "get": { "operationId": "GetPlans", "tags": [ "Plans" ], "summary": "Get all plans", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "A list of plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "plans": [ { "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" } ], "metadata": { "total_count": 29, "total_pages": 29, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreatePlan", "tags": [ "Plans" ], "summary": "Create a new plan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanCreateRequest" }, "examples": { "StandardChargeModel": { "summary": "Create a Standard Charge Model with required properties", "value": { "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1 } } ], "minimum_commitment": { "amount": { "value": 100 }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" } } }, "PackageChargeModel": { "summary": "Create a Package Charge Model with required properties", "value": { "name": "UBB Plan - Package Pro", "code": "PRO_PLAN_1754320623044_BTBS9M", "description": "Pro Plan - package charge model", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "PACKAGE", "properties": { "amount": "0.15", "package_size": 1000, "free_units": 500000 }, "min_amount": { "value": 1 } } ] } }, "PercentageChargeModel": { "summary": "Create a Percentage Charge Model with required properties", "value": { "name": "UBB Plan - Free Trial Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 14, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "PERCENTAGE", "properties": { "rate": "2.9", "fixed_amount": "0.30", "free_units_per_events": 5, "free_units_per_total_aggregation": "500", "per_transaction_min_amount": "100", "per_transaction_max_amount": "1000" }, "min_amount": { "value": 1 } } ] } }, "GraduatedChargeModel": { "summary": "Create a Graduated Charge Model with required properties", "value": { "name": "UBB Plan - Tiered Pro", "code": "PRO_TIERED_PLAN_1754320623044", "description": "Pro Plan - tiered charges", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "GRADUATED", "properties": { "graduated_ranges": [ { "from_value": 0, "to_value": 1000000, "per_unit_amount": "10", "flat_amount": "0" }, { "from_value": 1000001, "to_value": 2000000, "per_unit_amount": "8", "flat_amount": "0" }, { "from_value": 2000001, "to_value": 3000000, "per_unit_amount": "6", "flat_amount": "0" }, { "from_value": 3000001, "to_value": null, "per_unit_amount": "4", "flat_amount": "0" } ] }, "min_amount": { "value": 1 } } ] } }, "VolumeChargeModel": { "summary": "Create a Volume Charge Model with required properties", "value": { "name": "UBB Plan - Volume Based Pro", "code": "PRO_TIERED_PLAN_1754320623044", "description": "Pro Plan - volume based charges", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "VOLUME", "properties": { "volume_ranges": [ { "from_value": 0, "to_value": 10000, "flat_amount": "10", "per_unit_amount": "0.0010" }, { "from_value": 10001, "to_value": 50000, "flat_amount": "10", "per_unit_amount": "0.0008" }, { "from_value": 50001, "to_value": null, "flat_amount": "10", "per_unit_amount": "0.0006" } ] }, "min_amount": { "value": 1 } } ] } } } } } }, "responses": { "201": { "description": "Plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "examples": { "StandardChargeModel": { "summary": "Response of a Standard Charge Model with required properties", "value": { "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" } }, "PackageChargeModel": { "summary": "Response of a Package Charge Model with required properties", "value": { "name": "UBB Plan - Package Pro", "code": "PRO_PLAN_1754320623044_BTBS9M", "description": "Pro Plan - package charge model", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "PACKAGE", "properties": { "amount": "0.15", "package_size": 1000, "free_units": 500000 }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "created_at": "2025-07-29T22:00:19Z", "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c" } }, "PercentageChargeModel": { "summary": "Response of a Percentage Charge Model with required properties", "value": { "name": "UBB Plan - Free Trial Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 14, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "PERCENTAGE", "properties": { "rate": "1" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "created_at": "2025-07-29T22:00:19Z", "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c" } }, "GraduatedChargeModel": { "summary": "Response of a Graduated Charge Model with required properties", "value": { "name": "UBB Plan - Tiered Pro", "code": "PRO_TIERED_PLAN_1754320623044", "description": "Pro Plan - tiered charges", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "GRADUATED", "properties": { "graduated_ranges": [ { "from_value": 0, "to_value": 1000000, "per_unit_amount": "10", "flat_amount": "0" }, { "from_value": 1000001, "to_value": 2000000, "per_unit_amount": "8", "flat_amount": "0" }, { "from_value": 2000001, "to_value": 3000000, "per_unit_amount": "6", "flat_amount": "0" }, { "from_value": 3000001, "to_value": null, "per_unit_amount": "4", "flat_amount": "0" } ] }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "created_at": "2025-07-29T22:00:19Z", "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c" } }, "VolumeChargeModel": { "summary": "Response of a Volume Charge Model with required properties", "value": { "name": "UBB Plan - Volume Based Pro", "code": "PRO_TIERED_PLAN_1754320623044", "description": "Pro Plan - volume based charges", "billing_cycle": "MONTHLY", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "VOLUME", "properties": { "volume_ranges": [ { "from_value": 0, "to_value": 10000, "flat_amount": "10", "per_unit_amount": "0.0010" }, { "from_value": 10001, "to_value": 50000, "flat_amount": "10", "per_unit_amount": "0.0008" }, { "from_value": 50001, "to_value": null, "flat_amount": "10", "per_unit_amount": "0.0006" } ] }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "created_at": "2025-07-29T22:00:19Z", "id": "113adfe7-5d09-42f9-94c1-b5c8a7dcd55c" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans/{plan_code}": { "get": { "operationId": "GetPlanByCode", "tags": [ "Plans" ], "summary": "Get a plan by Code", "parameters": [ { "$ref": "#/components/parameters/plan_code" } ], "responses": { "200": { "description": "A plan object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "name": "test-plan", "code": "test-plan", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 1000, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdatePlanByCode", "tags": [ "Plans" ], "summary": "Update a plan by Code", "parameters": [ { "$ref": "#/components/parameters/plan_code" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdateRequest" } } } }, "responses": { "200": { "description": "A plan object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdateResponse" }, "example": { "status": "200 OK", "headers": { "Content-Type": "application/json" }, "body": { "name": "UBB Plan - Pro", "code": "ubb_plan_1753837176", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 170, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "cascading_updates": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "updated_at": "2025-07-31T08:41:19Z", "id": "95de3538-3827-496b-89a0-120745360830" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeletePlanByCode", "tags": [ "Plans" ], "summary": "Delete a plan by Code", "description": "Delete a plan by providing the plan ID. This operation permanently removes the plan from the system.", "parameters": [ { "$ref": "#/components/parameters/plan_code" } ], "responses": { "204": { "description": "Plan deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers": { "get": { "operationId": "GetCustomers", "tags": [ "Customers" ], "summary": "Get all customers", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Returns the customer with the specified ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "customers": [ { "id": "f772b19c-c5c2-426d-8871-346a6cd094c5", "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ] }, { "id": "3c25d14a-5fe4-455e-8862-dfb07d384d08", "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753642317", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateCustomer", "tags": [ "Customers" ], "summary": "Create a new customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } } }, "responses": { "201": { "description": "Customer created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ], "id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}": { "get": { "operationId": "GetCustomerById", "tags": [ "Customers" ], "summary": "Get a customer by ID", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ], "id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateCustomerById", "tags": [ "Customers" ], "summary": "Update a customer by ID", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "Hello Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "customer1@gmail.com", "address": { "line1": "123 First Street", "line2": "Alameda Court", "city": "San Jose", "state": "CA", "postal_code": "94551", "country": "US" }, "phone": "5839458934", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "id": "f772b19c-c5c2-426d-8871-346a6cd094c5", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteCustomerById", "tags": [ "Customers" ], "summary": "Delete a customer by ID", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" } ], "responses": { "204": { "description": "Customer deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/analytics/overdue-balance": { "get": { "operationId": "GetCustomerAnalyticsOverdueBalance", "tags": [ "Customers" ], "summary": "Retrieve customer analytics for overdue balance", "parameters": [ { "name": "external_customer_id", "in": "path", "description": "The unique external identifier of the customer used to filter their overdue balance.", "required": true, "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, { "name": "months", "in": "query", "description": "Limits the analytics data to the specified number of most recent months. Defaults to 12 if not provided.", "required": false, "schema": { "type": "integer", "default": 12, "minimum": 1 }, "example": 6 }, { "name": "currency", "in": "query", "description": "Filters the analytics data by the specified currency code (e.g., 'USD').", "required": false, "schema": { "$ref": "#/components/schemas/Currency" }, "example": "USD" } ], "responses": { "200": { "description": "Customer overdue balance analytics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverdueBalances" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/analytics/gross-revenue": { "get": { "operationId": "GetCustomerAnalyticsGrossRevenue", "tags": [ "Customers" ], "summary": "Retrieve customer gross revenue analytics", "parameters": [ { "name": "external_customer_id", "in": "path", "description": "The unique external identifier of the customer used to filter their gross revenue.", "required": true, "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, { "name": "months", "in": "query", "description": "Limits the analytics data to the specified number of most recent months. Defaults to 12 if not provided.", "required": false, "schema": { "type": "integer", "default": 12, "minimum": 1 }, "example": 6 }, { "name": "currency", "in": "query", "description": "Filters the analytics data by the specified currency code (e.g., 'USD').", "required": false, "schema": { "$ref": "#/components/schemas/Currency" }, "example": "USD" } ], "responses": { "200": { "description": "Customer gross revenue analytics retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrossRevenues" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/current_usage": { "get": { "operationId": "GetCustomersCurrentUsage", "tags": [ "Customers" ], "summary": "Get current usage for a customer", "description": "Retrieves the current billing period usage information for a specific customer", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" }, { "in": "query", "name": "subscription_id", "schema": { "$ref": "#/components/schemas/SubscriptionExternalId" }, "required": true, "description": "Filter by subscription ID." } ], "responses": { "200": { "description": "Returns the current usage for the specified customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUsage" }, "example": { "from_datetime": "2024-01-01T00:00:00Z", "to_datetime": "2024-01-31T23:59:59Z", "issuing_date": "2024-01-31", "total_amount": { "currency_code": "USD", "value": 270 }, "taxes_amount": { "currency_code": "USD", "value": 2.75 }, "charges_usage": [ { "units": "150.0", "events_count": 3050, "amount": { "currency_code": "USD", "value": 75 }, "charge": { "id": "1c31a90-1c31-1c31-1c31-1c311c311c31", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "2400.0", "events_count": 2400, "amount": { "currency_code": "USD", "value": 120 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } }, { "units": "500.0", "events_count": 500, "amount": { "currency_code": "USD", "value": 75 }, "charge": { "id": "1a901b42-1b42-1b42-1b42-1a901b421b42", "metric_id": "metric_03H3YT8P7Q5R3S1T2U0V4W9Z0", "charge_model": "STANDARD", "properties": { "amount": "0.15" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Bandwidth MB", "code": "bandwidth_mb", "aggregation_type": "SUM" } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/past_usage": { "get": { "operationId": "GetCustomerPastUsage", "tags": [ "Customers" ], "summary": "Get past usage for a customer", "description": "Retrieves historical usage information for a specific customer across previous billing periods", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "subscription_id", "schema": { "type": "string" }, "required": true, "description": "Filter by subscription ID." } ], "responses": { "200": { "description": "Returns the past usage for the specified customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPastUsage" }, "example": { "usage_periods": [ { "from_datetime": "2023-12-01T00:00:00Z", "to_datetime": "2023-12-31T23:59:59Z", "issuing_date": "2023-12-31", "total_amount": { "currency_code": "USD", "value": 250 }, "taxes_amount": { "currency_code": "USD", "value": 3.25 }, "charges_usage": [ { "units": "200.0", "events_count": 200, "amount": { "currency_code": "USD", "value": 100 }, "charge": { "id": "1c31a90-1c31-1c31-1c31-1c311c311c31", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "3000.0", "events_count": 3000, "amount": { "currency_code": "USD", "value": 150 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] }, { "from_datetime": "2023-11-01T00:00:00Z", "to_datetime": "2023-11-30T23:59:59Z", "issuing_date": "2023-11-30", "total_amount": { "currency_code": "USD", "value": 150 }, "taxes_amount": { "currency_code": "USD", "value": 2.1 }, "charges_usage": [ { "units": "120.0", "events_count": 120, "amount": { "currency_code": "USD", "value": 60 }, "charge": { "id": "1e1a90-1e1a-1e1a-1e1a-1e1a1e1a1e1a", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "1800.0", "events_count": 1800, "amount": { "currency_code": "USD", "value": 90 }, "charge": { "id": "1r67r67-1r67-1r67-1r67-1r671r671r67", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] }, { "from_datetime": "2023-10-01T00:00:00Z", "to_datetime": "2023-10-31T23:59:59Z", "issuing_date": "2023-10-31", "total_amount": { "currency_code": "USD", "value": 107.5 }, "taxes_amount": { "currency_code": "USD", "value": 1.85 }, "charges_usage": [ { "units": "95.0", "events_count": 95, "amount": { "currency_code": "USD", "value": 47.5 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "1200.0", "events_count": 1200, "amount": { "currency_code": "USD", "value": 60 }, "charge": { "id": "1a901b42-1b42-1b42-1b42-1a901b421b42", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] } ], "meta": { "current_page": 1, "total_count": 12, "total_pages": 2 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/portal_url": { "get": { "operationId": "GetEmbeddablePortalUrl", "tags": [ "Customers" ], "summary": "Get an embeddable URL to the customer portal", "parameters": [ { "$ref": "#/components/parameters/external_customer_id" } ], "responses": { "200": { "description": "Embeddable URL to the Customer Portal for the given external customer ID is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalEmbeddableUrlResponse" }, "example": { "url": "https://www.paypal.com/usage-billing/customer-portal/eyJ1dWlkIjoiNDQ4NmI3NGYtODM5ZC00ZTk2LWEyMTUtNDY3ZDYxMzgwNzFjIiwiZXhwaXJlc19pbiI6MzYwMH0=", "expires_in": 3600 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions": { "get": { "operationId": "GetSubscriptions", "tags": [ "Subscriptions" ], "summary": "Get all subscriptions", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_customer_id", "schema": { "type": "string", "example": "ext_cus_1234567890abcdef" }, "description": "Filter by external customer ID" }, { "in": "query", "name": "plan_code", "schema": { "type": "string", "example": "plan_1234567890abcdef" }, "description": "Filter by plan code" }, { "in": "query", "name": "status", "description": "Comma-separated list of statuses", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PENDING", "CANCELED", "TERMINATED" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "A list of subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "subscriptions": [ { "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6b13234", "external_id": "Subscription_1233", "plan_code": "Plan-Code-12345", "billing_time": "CALENDAR", "status": "ACTIVE", "start_date": "2025-06-27T20:44:21Z", "created_at": "2025-07-30T01:54:40Z", "current_period_start": "2025-07-01T00:00:00Z", "current_period_end": "2025-07-31T23:59:59Z", "id": "d9e9d0c0-d672-4299-8b8e-9d20ca20f465" }, { "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1751410090", "external_id": "Subscription_123353453453535-2025-07-01T22", "plan_code": "Plan-Code-2222", "billing_time": "CALENDAR", "status": "ACTIVE", "start_date": "2025-07-01T22:48:37Z", "created_at": "2025-07-30T01:54:40Z", "current_period_start": "2025-07-01T22:48:37Z", "current_period_end": "2025-07-31T23:59:59Z", "id": "35a75733-5940-42cc-97ed-1587d2d364e1" } ], "metadata": { "total_count": 24, "total_pages": 3, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateSubscription", "tags": [ "Subscriptions" ], "summary": "Create a new subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" }, "examples": { "SimpleSubscriptionCreate": { "value": { "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "start_date": "2025-07-30T04:26:24Z", "end_date": "2025-09-09T04:26:24Z", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] } } }, "SubscriptionCreationWithPlanOverrides": { "value": { "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-_1753840215", "billing_time": "ANNIVERSARY", "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] } } }, "SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment": { "value": { "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-_1753840215", "billing_time": "ANNIVERSARY", "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200 } } ], "minimum_commitment": { "invoice_display_name": "Negotiated Minimum Commitment", "amount": { "value": 500 } } } } } } } } }, "responses": { "201": { "description": "Subscription created successfully", "headers": { "paypal-debug-id": { "description": "PayPal debug ID for tracking", "schema": { "type": "string", "example": "23e54e9b-dc6d-4ec1-bb6a-3714135ec3a9" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "examples": { "SimpleSubscriptionCreate": { "value": { "id": "b71befc2-4799-402c-9d13-ca1f72759c64", "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "d0682999-67a0-418e-b29b-3757426db01f", "charge_model": "STANDARD", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] }, "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "start_date": "2025-07-30T04:26:24Z", "end_date": "2025-09-09T04:26:24Z" } }, "SubscriptionCreationWithPlanOverrides": { "value": { "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-_1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "d0682999-67a0-418e-b29b-3757426db01f", "charge_model": "STANDARD", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] }, "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "id": "b71befc2-4799-402c-9d13-ca1f72759c64" } }, "SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment": { "value": { "name": "API Count Usage Subscription1", "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-_1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "d0682999-67a0-418e-b29b-3757426db01f", "charge_model": "STANDARD", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 500, "currency_code": "USD" }, "invoice_display_name": "Negotiated Minimum Commitment", "plan_code": "Plan-Code-_1753840215", "created_at": "2025-07-31T13:00:04Z", "updated_at": "2025-07-31T13:00:04Z" } }, "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "id": "b71befc2-4799-402c-9d13-ca1f72759c64" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}": { "get": { "operationId": "GetSubscriptionById", "tags": [ "Subscriptions" ], "summary": "Get a subscription by ID", "parameters": [ { "$ref": "#/components/parameters/external_subscription_id" } ], "responses": { "200": { "description": "A subscription object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "name": "API Count Usage Subscription1", "external_customer_id": "CUSTOMER_1752766931284", "external_id": "SUB_1752779018503", "plan_code": "PLAN_CODE_1752694759534", "billing_time": "CALENDAR", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 0.2, "currency_code": "USD" }, "name": "Basic API Plan", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113", "charge_model": "STANDARD", "properties": { "amount": "0.01" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] }, "start_date": "2025-07-17T19:03:47Z", "created_at": "2025-07-30T01:54:40Z", "current_period_start": "2025-07-17T19:03:47Z", "current_period_end": "2025-07-31T23:59:59Z", "trial_ended_at": "2025-07-31T19:03:47Z", "id": "073a0619-f59c-4e7c-8dd4-02c83e583105" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateSubscriptionById", "tags": [ "Subscriptions" ], "summary": "Update a subscription", "description": "Updates an existing subscription's details such as name, or metadata. Can also schedule a future cancellation date.", "parameters": [ { "$ref": "#/components/parameters/external_subscription_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Updated subscription object", "headers": { "paypal-debug-id": { "description": "PayPal debug ID for tracking", "schema": { "type": "string", "example": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "name": "Subscription_External", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "d0682999-67a0-418e-b29b-3757426db01f", "charge_model": "STANDARD", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] }, "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "id": "b71befc2-4799-402c-9d13-ca1f72759c64" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/lifetime-usage": { "get": { "operationId": "GetLifetimeUsageBySubscriptionId", "tags": [ "Subscriptions" ], "summary": "Retrieve lifetime usage for a specific subscription", "parameters": [ { "$ref": "#/components/parameters/external_subscription_id" } ], "responses": { "200": { "description": "Returns the lifetime usage for the specified subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifetimeUsage" }, "example": { "external_subscription_id": "Subscription_External_1", "external_historical_usage_amount": { "value": 0, "currency_code": "USD" }, "invoiced_usage_amount": { "value": 0, "currency_code": "USD" }, "current_usage_amount": { "value": 0, "currency_code": "USD" }, "from": "2025-07-31T12:59:15Z", "to": "2025-08-01T07:04:39Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/cancel": { "post": { "operationId": "CancelSubscription", "tags": [ "Subscriptions" ], "summary": "Cancel a subscription", "description": "This endpoint allows you to cancel an existing subscription. You can either cancel immediately or set it to cancel at the end of the current billing period.", "parameters": [ { "$ref": "#/components/parameters/external_subscription_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCancel" }, "examples": { "cancelAtEndOfPeriod": { "summary": "Cancel at end of billing period", "value": { "cancel_option": "END_OF_PERIOD" } }, "cancelImmediately": { "summary": "Cancel immediately", "value": { "cancel_option": "IMMEDIATE" } }, "cancelWithEmptyRequest": { "summary": "Cancel subscription without cancel option specified in request", "value": {} } } } } }, "responses": { "200": { "description": "Updated subscription object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "examples": { "cancelActiveSubscriptionAtEndOfPeriod": { "summary": "An Active subscription canceled at end of period", "value": { "name": "Subscription-008", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-008", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "end_date": "2025-08-14T23:59:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb524" } }, "cancelActiveSubscriptionImmediately": { "summary": "An Active subscription canceled immediately", "value": { "name": "Subscription-009", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-009", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "TERMINATED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "terminated_at": "2025-08-11T20:50:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb525" } }, "cancelPendingSubscriptionImmediately": { "summary": "Pending subscription canceled immediately", "value": { "name": "Subscription-010", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-010", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "CANCELED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-21T00:00:00Z", "canceled_at": "2025-08-11T19:55:45Z", "id": "8492b68f-6303-4ad9-96f4-65f658f44011" } }, "cancelActiveSubscriptionWithoutCancelOptionSpecified": { "summary": "Active subscription canceled with out passing cancel option in request", "value": { "name": "Subscription-007", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-007", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "TERMINATED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "terminated_at": "2025-08-11T20:50:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb526" } } } } } }, "400": { "description": "Bad Request - Invalid request format or data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidRequestBody": { "summary": "Invalid cancel option provided", "value": { "name": "INVALID_REQUEST", "debug_id": "a109791e6c096bcaa74a45d27630d3e4", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "cancel_option", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "A parameter value is not valid." } ] } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Unprocessable Entity - Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "cancelPendingSubscriptionWithCancelOptionAsEndOfPeriod": { "summary": "Cancel pending subscription with cancel option as end of period", "value": { "name": "UNPROCESSABLE_ENTITY", "debug_id": "162925068ef2df7a6adb93b3a4d7869d", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "details": [ { "issue": "CANCEL_OPTION_NOT_SUPPORTED", "description": "Pending subscriptions can be cancelled only with cancel option as IMMEDIATE." } ] } }, "subscriptionAlreadyCancelled": { "summary": "Subscription already cancelled", "value": { "name": "UNPROCESSABLE_ENTITY", "debug_id": "162925068ef2df7a6adb93b3a4d7869d", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "details": [ { "issue": "SUBSCRIPTION_ALREADY_CANCELED", "description": "Subscription is already cancelled." } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/events": { "get": { "operationId": "GetEvents", "tags": [ "Events" ], "summary": "Query usage events", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_subscription_id", "schema": { "type": "string", "example": "sub_1234567890abcdef" }, "description": "Filter events by external subscription ID" }, { "in": "query", "name": "metric_code", "schema": { "type": "string", "example": "metric_123456ef" }, "description": "Filter events by metric code" }, { "in": "query", "name": "from_date", "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "description": "Start date for filtering events" }, { "in": "query", "name": "to_date", "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "description": "End date for filtering events" } ], "responses": { "200": { "description": "A list of usage events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "events": [ { "transaction_id": "event_1752016113", "external_subscription_id": "49fac470-fa34-4471-915e-bff1d05308ce", "metric_code": "EvolvAI_Billable_Metrics_1750804981", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "87b5897d-083f-490c-b5f5-d219087b4d73", "created_at": "2025-07-08T16:08:33-07:00" }, { "transaction_id": "event_1752016329", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-02T00:00:00Z", "properties": { "gb": 12 }, "id": "42365b30-368a-4a0e-be4f-b790dab2cde9", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016319", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "38d78dd1-219e-43bb-af97-7e888e952605", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016316", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f910721", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "2ee6fbfc-132c-4628-9138-450b27d68b32", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016310", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_17514954851", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "67505fef-8dae-4547-b595-5f4265ac6a82", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016198", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "7f4d2d59-4691-4372-9931-aabef31a1cec", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016186", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "aa237cc9-e975-4486-a5cf-f2c0999190a9", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016165", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-06T00:00:00Z", "properties": { "gb": 12 }, "id": "528be51f-ee55-4c14-8306-50a26638190f", "created_at": "2025-01-06T00:00:00Z" }, { "transaction_id": "event_1752016139", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "fe027df2-078f-4a92-9335-1c0f1c0d4123", "created_at": "2025-01-05T00:00:00Z" }, { "transaction_id": "event_1752016138", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-04T00:00:00Z", "properties": { "gb": 12 }, "id": "91b72931-6c5e-48e4-8156-27621857c9c5", "created_at": "2025-01-03T00:00:00Z" } ], "metadata": { "current_page": 1, "total_pages": 4, "total_count": 32 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateEvent", "tags": [ "Events" ], "summary": "Create a new usage event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" } } } }, "responses": { "201": { "description": "Event created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" }, "example": { "transaction_id": "event_1753818829", "metric_code": "91624203-791a-4639-8c86-4693948b3a41", "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a", "timestamp": "2025-07-29T12:53:49.076-07:00", "properties": { "gb": 10 }, "id": "d80447f2-0f34-4612-86ae-152160dc66c5", "created_at": "2025-07-29T12:53:49-07:00" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/events/batch": { "post": { "operationId": "CreateEventsBatch", "tags": [ "Events" ], "summary": "Create multiple usage events in batch.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventRequest" } } } }, "example": { "events": [ { "transaction_id": "event_t1_1753838783", "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41", "metric_code": "Billable_Metrics_1753827008", "timestamp": "2023-01-01T00:00:00Z", "properties": { "gb": 10 } }, { "transaction_id": "event_t2_1753838783", "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41", "metric_code": "Billable_Metrics_1753827008", "timestamp": "2023-01-01T00:00:00Z", "properties": { "gb": 10 } } ] } } } }, "responses": { "201": { "description": "Events accepted for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsAcceptedWithResults" }, "example": { "status": "ACCEPTED", "results": { "success_count": 2, "error_count": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets": { "get": { "operationId": "GetWallets", "tags": [ "Wallets" ], "summary": "Get all wallets", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_customer_id", "schema": { "type": "string", "example": "ext_cus_1234567890abcdef" }, "description": "Filter by external customer ID", "required": true } ], "responses": { "200": { "description": "A list of wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/WalletWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateWallet", "tags": [ "Wallets" ], "summary": "Create a new wallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletCreate" } } } }, "responses": { "201": { "description": "Wallet created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" }, "example": { "id": "13fddcdc-725b-4ca7-a522-a162ff038567", "external_customer_id": "ext_cus_1234567890abcdef", "status": "ACTIVE", "available_balance": { "value": 110, "currency_code": "USD" }, "ongoing_usage": { "value": 0, "currency_code": "USD" }, "net_balance": { "value": 110, "currency_code": "USD" }, "name": "Prepaid Wallet", "rate_amount": "1.0", "available_credits": "110.0", "consumed_credits": "0.0", "ongoing_usage_credits": "0.0", "net_balance_credits": "110.0", "created_at": "2025-09-17T00:00:00Z", "applies_to": { "fee_types": [ "SUBSCRIPTION" ] }, "expiration_at": "2026-08-12T12:43:31Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets/{wallet_id}": { "get": { "operationId": "GetWalletById", "tags": [ "Wallets" ], "summary": "Retrieve a wallet by ID", "parameters": [ { "$ref": "#/components/parameters/wallet_id" } ], "responses": { "200": { "description": "Wallet retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" }, "example": { "id": "943254a2-0240-4414-bede-c0d211340c53", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358", "status": "ACTIVE", "available_balance": { "value": 3, "currency_code": "USD" }, "ongoing_usage": { "value": 0, "currency_code": "USD" }, "net_balance": { "value": 3, "currency_code": "USD" }, "name": "Prepaid", "rate_amount": "1.0", "available_credits": "3.0", "consumed_credits": "0.0", "ongoing_usage_credits": "0.0", "net_balance_credits": "3.0", "created_at": "2025-07-30T20:13:18Z", "expiration_at": "2026-10-08T00:00:00Z", "applies_to": { "fee_types": [ "SUBSCRIPTION", "CHARGE", "COMMITMENT" ] }, "recurring_transaction_rules": [ { "trigger": "INTERVAL", "method": "TARGET", "interval": "WEEKLY", "started_at": "2025-07-01T17:30:15Z", "expiration_at": "2026-10-08T00:00:00Z", "target_ongoing_balance": "200.0" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateWalletById", "tags": [ "Wallets" ], "summary": "Update a wallet", "parameters": [ { "$ref": "#/components/parameters/wallet_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletUpdate" } } } }, "responses": { "200": { "description": "Wallet updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "TerminateWalletById", "tags": [ "Wallets" ], "summary": "Terminate wallet", "parameters": [ { "$ref": "#/components/parameters/wallet_id" } ], "responses": { "200": { "description": "Wallet terminated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets/{wallet_id}/wallet-transactions": { "post": { "operationId": "CreateWalletTransaction", "tags": [ "Wallets" ], "summary": "Create Wallet transaction", "parameters": [ { "$ref": "#/components/parameters/wallet_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionRequest" } } } }, "responses": { "201": { "description": "Wallet transactions created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactions" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "GetWalletTransactions", "tags": [ "Wallets" ], "summary": "Get wallet transactions", "parameters": [ { "$ref": "#/components/parameters/wallet_id" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Wallet transactions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactions" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallet-transactions/{wallet_transaction_id}": { "get": { "operationId": "GetWalletTransactionById", "tags": [ "Wallets" ], "summary": "Get Wallet transaction by id", "parameters": [ { "$ref": "#/components/parameters/wallet_transaction_id" } ], "responses": { "200": { "description": "Wallet transaction by ID retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransaction" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credit-notes": { "get": { "operationId": "GetCreditNotes", "tags": [ "Credit Notes" ], "summary": "Get all credit notes", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" }, { "name": "external_customer_id", "in": "query", "description": "Filter credit notes by external customer ID", "required": false, "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "description": "Filter credit notes by invoice ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter credit notes by status", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteFilterStatus" } }, { "name": "credit_status", "in": "query", "description": "Filter credit notes by credit status (e.g., available, consumed, voided)", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteStatus" } }, { "name": "refund_status", "in": "query", "description": "Filter credit notes by refund status", "required": false, "schema": { "$ref": "#/components/schemas/RefundStatus" } }, { "name": "reason", "in": "query", "description": "Filter credit notes by reason", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteReason" } }, { "name": "id", "in": "query", "description": "Filter credit notes by ID", "required": false, "schema": { "type": "string" } }, { "name": "number", "in": "query", "description": "Filter credit notes by credit note number", "required": false, "schema": { "type": "string" } }, { "name": "issuing_date_from", "in": "query", "description": "Filter credit notes issued on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "issuing_date_to", "in": "query", "description": "Filter credit notes issued on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "created_at_from", "in": "query", "description": "Filter credit notes created on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "created_at_to", "in": "query", "description": "Filter credit notes created on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "updated_at_from", "in": "query", "description": "Filter credit notes updated on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "updated_at_to", "in": "query", "description": "Filter credit notes updated on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } } ], "responses": { "200": { "description": "A list of credit notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credit_notes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "credit_notes": [ { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "billing_entity_code": "lex_corp", "sequential_id": 3, "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "AVAILABLE", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 25, "currency_code": "USD" }, "refund_amount": { "value": 25, "currency_code": "USD" }, "balance_amount": { "value": 25, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "taxes_rate": 0.2, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "created_at": "2023-05-10T14:32:18Z", "updated_at": "2023-05-10T14:32:18Z" } ], "metadata": { "total_count": 1, "total_pages": 1, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateCreditNote", "tags": [ "Credit Notes" ], "summary": "Create a new credit note", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteCreateRequest" } } } }, "responses": { "201": { "description": "Credit note created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteWithId" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credit-notes/{credit_note_id}": { "get": { "operationId": "GetCreditNoteById", "tags": [ "Credit Notes" ], "summary": "Get a single credit note by ID", "parameters": [ { "name": "credit_note_id", "in": "path", "description": "The ID of the credit note", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A single credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteWithId" }, "example": { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "billing_entity_code": "lex_corp", "sequential_id": 3, "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "AVAILABLE", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 25, "currency_code": "USD" }, "refund_amount": { "value": 25, "currency_code": "USD" }, "balance_amount": { "value": 25, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "taxes_rate": 0.2, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "created_at": "2023-05-10T14:32:18Z", "updated_at": "2023-05-10T14:32:18Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credit-notes/{credit_note_id}/void": { "post": { "operationId": "VoidCreditNote", "tags": [ "Credit Notes" ], "summary": "Void a credit note", "description": "Voids a credit note, making it no longer available for use. This action cannot be undone.", "parameters": [ { "name": "credit_note_id", "in": "path", "description": "The ID of the credit note to void", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit note voided successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteWithId" }, "example": { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "sequential_id": 3, "billing_entity_code": "lex_corp", "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "VOIDED", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 0, "currency_code": "USD" }, "refund_amount": { "value": 0, "currency_code": "USD" }, "balance_amount": { "value": 0, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "taxes_rate": 0.2, "created_at": "2023-05-10T14:32:18Z", "updated_at": "2023-06-15T10:45:22Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/alerts": { "get": { "operationId": "GetAlertsByExternalId", "tags": [ "Alerts" ], "summary": "Retrieve subscription alerts", "description": "Retrieves all usage-based alerts configured for a specific subscription. Use this endpoint to monitor and manage billing alerts across different consumption thresholds.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Successfully retrieved the collection of alerts configured for the specified subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertList" }, "example": { "alerts": [ { "id": "7e6a89c9-ab69-4702-98f5-c245aca88080", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "storage_units_current_cycle", "name": "Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "units_used", "value": "500000.0", "recurring": false } ], "created_at": "2025-08-01T05:58:57Z" }, { "id": "14a42687-1814-4419-a111-76ff5792a786", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage amount", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_AMOUNT", "code": "storage_amount_current_cycle", "name": "Current Monetary Usage Alert specific to a Metric", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "1000.0", "recurring": false } ], "created_at": "2025-08-01T05:58:53Z" }, { "id": "13aac90e-927a-4203-8d42-11a388b91308", "external_subscription_id": "SUB_1752779018503", "type": "CURRENT_USAGE_AMOUNT", "code": "current_usage_amount_aggregated_current_cycle", "name": "Current Cycle Monetary Usage Alert", "previous_value": 0, "thresholds": [ { "code": "hard", "value": "9000.1", "recurring": false } ], "last_processed_at": "2025-08-03T10:04:21Z", "created_at": "2025-08-01T05:58:48Z" }, { "id": "f5ca7539-e540-4d92-a416-fcece5970bf4", "external_subscription_id": "SUB_1752779018503", "type": "LIFETIME_USAGE_AMOUNT", "code": "lifetime_usage_alert", "name": "Lifetime Monetary Usage Alert", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "5000.0", "recurring": false }, { "code": "hard", "value": "10000.0", "recurring": false }, { "code": "hard", "value": "2000.0", "recurring": true } ], "created_at": "2025-07-31T18:28:31Z" } ], "meta": { "total_count": 4, "total_pages": 1, "current_page": 1 } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateAlert", "tags": [ "Alerts" ], "summary": "Create subscription alert", "description": "Establishes a new usage-based alert for a subscription to notify merchants when consumption reaches specified thresholds. Supports multiple alert types including current billing period usage, lifetime usage, and metric-specific monitoring for both monetary amounts and consumption units.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } } ], "requestBody": { "required": true, "description": "Complete alert configuration including type, thresholds, and optional metric information. The alert type determines which fields are required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertInput" }, "example": { "code": "storage_monetary_alert", "metric_code": "Storage_Metrics_1753985710", "name": "Current Monetary Usage Alert specific to a Metric", "thresholds": [ { "code": "warn", "recurring": false, "value": "1000" } ], "type": "METRIC_CURRENT_USAGE_AMOUNT" } } } }, "responses": { "201": { "description": "Alert configuration successfully created and activated for the subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "14a42687-1814-4419-a111-76ff5792a786", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_AMOUNT", "code": "storage_monetary_alert", "name": "Current Monetary Usage Alert specific to a Metric", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "1000.0", "recurring": false } ], "last_processed_at": "2025-08-01T06:15:00Z", "created_at": "2025-08-01T05:58:53Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/alerts/{alert_code}": { "get": { "operationId": "GetAlertByExternalIdAndCode", "tags": [ "Alerts" ], "summary": "Retrieve specific subscription alert", "description": "Retrieves detailed information about a specific alert identified by its unique code within a subscription.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "alert_code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "responses": { "200": { "description": "Successfully retrieved the detailed configuration and current status of the specified alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "a3c9e51d-6c0d-4cad-a029-6e5c0c08fc52", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1754980238", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "0eb44a04-dc60-4d2c-aacb-90d5dbb2b048", "created_at": "2025-08-12T06:30:39Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "ALERT_CODE_1234567890", "name": "Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ], "last_processed_at": "2025-08-16T09:45:00Z", "created_at": "2025-08-12T06:31:47Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateAlertByExternalIdAndCode", "tags": [ "Alerts" ], "summary": "Modify subscription alert", "description": "Updates the configuration of an existing subscription alert.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "alert_code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "requestBody": { "required": true, "description": "Modified alert configuration containing updated threshold values and other configurable parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertUpdateInput" }, "example": { "code": "ALERT_CODE_UPDATED_1234567890", "name": "Updated Current Usage Alert specific to a Metric units", "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ] } } } }, "responses": { "200": { "description": "Alert configuration successfully updated with the provided changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "a3c9e51d-6c0d-4cad-a029-6e5c0c08fc52", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1754980238", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "0eb44a04-dc60-4d2c-aacb-90d5dbb2b048", "created_at": "2025-08-12T06:30:39Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "ALERT_CODE_UPDATED_1234567890", "name": "Updated Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ], "last_processed_at": "2025-08-16T09:45:00Z", "created_at": "2025-08-12T06:31:47Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteAlertByExternalIdAndCode", "tags": [ "Alerts" ], "summary": "Remove subscription alert", "description": "Permanently deletes a subscription alert identified by its unique code. This operation cannot be undone and will immediately stop all monitoring associated with this alert configuration.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "alert_code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "responses": { "204": { "description": "Alert successfully removed from the system. All monitoring associated with this alert has been permanently discontinued. No content is returned in the response body.", "content": { "application/json": { "example": { "status": "204 No Content", "headers": { "paypal-debug-id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/features": { "get": { "operationId": "GetFeatures", "tags": [ "Features" ], "summary": "List all features", "description": "Retrieves a comprehensive list of all features defined in your system. Features represent capabilities or functionalities that can be entitled to customers through subscription plans. Use this endpoint to discover available features when building plan configurations or displaying feature catalogs to administrators.", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Successfully retrieved the list of features with their complete configurations including all privileges", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "features": [ { "code": "seats", "name": "Number of seats", "description": "Number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" } ], "created_at": "2025-01-28T10:00:00Z" }, { "code": "api_access", "name": "API Access", "description": "Access to REST API endpoints", "privileges": [ { "code": "rate_limit", "name": "API Rate Limit", "value_type": "INTEGER" }, { "code": "endpoints", "name": "Available Endpoints", "value_type": "SELECT", "config": { "select_options": [ "basic", "standard", "premium", "all" ] } } ], "created_at": "2025-01-28T11:00:00Z" }, { "code": "sso", "name": "Single Sign-On", "description": "SSO authentication configuration", "privileges": [ { "code": "enabled", "name": "SSO Enabled", "value_type": "BOOLEAN" }, { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "config": { "select_options": [ "google", "okta", "azure", "saml" ] } } ], "created_at": "2025-01-28T12:00:00Z" } ], "metadata": { "current_page": 1, "total_count": 3, "total_pages": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateFeature", "tags": [ "Features" ], "summary": "Create a feature", "description": "Creates a new feature that represents a capability or functionality that can be entitled to customers. Features are the building blocks of your entitlement system - they define what can be granted to customers and what aspects can be configured. Each feature can have multiple privileges that allow fine-grained control over its behavior (e.g., a 'seats' feature might have 'max' and 'max_admins' privileges). Once created, features can be assigned to plans with specific privilege values.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureRequest" }, "examples": { "BasicFeatureCreation": { "summary": "Create a basic feature with integer and boolean privileges", "value": { "code": "seats", "name": "Number of seats", "description": "Number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN" } ] } }, "FeatureWithSelectPrivilege": { "summary": "Create a feature with a select-type privilege for predefined options", "value": { "code": "sso", "name": "Single Sign-On", "description": "SSO authentication configuration", "privileges": [ { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "config": { "select_options": [ "google", "okta", "azure", "saml" ] } }, { "code": "enabled", "name": "SSO Enabled", "value_type": "BOOLEAN" } ] } } } } } }, "responses": { "201": { "description": "Feature was successfully created and is now available for use in plan entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" }, "examples": { "BasicFeatureCreation": { "summary": "Response for basic feature creation", "value": { "code": "seats", "name": "Number of seats", "description": "Number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN" } ], "created_at": "2025-01-28T10:00:00Z" } }, "FeatureWithSelectPrivilege": { "summary": "Response for feature with select privilege", "value": { "code": "sso", "name": "Single Sign-On", "description": "SSO authentication configuration", "privileges": [ { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "config": { "select_options": [ "google", "okta", "azure", "saml" ] } }, { "code": "enabled", "name": "SSO Enabled", "value_type": "BOOLEAN" } ], "created_at": "2025-01-28T10:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/features/{feature_code}": { "get": { "operationId": "GetFeatureByCode", "tags": [ "Features" ], "summary": "Retrieve a feature", "description": "Retrieves complete details of a specific feature including all its privileges and configuration. Use this endpoint to inspect feature capabilities before creating entitlements or to display feature details in administrative interfaces.", "parameters": [ { "name": "feature_code", "in": "path", "required": true, "description": "The unique identifier code of the feature. This is the code that was specified when the feature was created.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the feature with all its properties and privileges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" }, "example": { "code": "seats", "name": "Number of seats", "description": "Number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN" } ], "created_at": "2025-01-28T10:00:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateFeature", "tags": [ "Features" ], "summary": "Update a feature", "description": "Updates an existing feature's properties including name, description, and privileges. The feature code itself cannot be changed. When updating privileges, the entire privileges array is replaced - to add or remove individual privileges, you must provide the complete desired list. Changes to features automatically propagate to all plans and subscriptions using them, though assigned values remain unchanged.", "parameters": [ { "name": "feature_code", "in": "path", "required": true, "description": "The unique identifier code of the feature. This is the code that was specified when the feature was created.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureUpdateRequest" }, "example": { "name": "User Seats", "description": "Maximum number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN" }, { "code": "guest_access", "name": "Allow guest access", "value_type": "BOOLEAN" } ] } } } }, "responses": { "200": { "description": "Feature was successfully updated with the new configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureResponse" }, "example": { "code": "seats", "name": "User Seats", "description": "Maximum number of users allowed in the account", "privileges": [ { "code": "max", "name": "Maximum seats", "value_type": "INTEGER" }, { "code": "max_admins", "name": "Maximum admin users", "value_type": "INTEGER" }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN" }, { "code": "guest_access", "name": "Allow guest access", "value_type": "BOOLEAN" } ], "created_at": "2025-01-28T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteFeature", "tags": [ "Features" ], "summary": "Delete a feature", "description": "Permanently deletes a feature from the system. This is a destructive operation that will remove the feature and all its associated entitlements from every plan and subscription. Use with caution as this cannot be undone. The operation will fail if the feature is currently assigned to any active plans or subscriptions to prevent accidental data loss.", "parameters": [ { "name": "feature_code", "in": "path", "required": true, "description": "The unique identifier code of the feature. This is the code that was specified when the feature was created.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Feature was successfully deleted and all associated data has been removed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/features/{feature_code}/privileges/{privilege_code}": { "delete": { "operationId": "DeleteFeaturePrivilege", "tags": [ "Features" ], "summary": "Delete a feature privilege", "description": "Removes a specific privilege from a feature definition. This is a destructive operation that affects all plans and subscriptions using this feature - the privilege and any values assigned to it will be permanently removed from all entitlements. Use this when a privilege is no longer needed or was created in error.", "parameters": [ { "name": "feature_code", "in": "path", "required": true, "description": "The unique identifier code of the feature containing the privilege to be deleted", "schema": { "type": "string" } }, { "name": "privilege_code", "in": "path", "required": true, "description": "The unique identifier code of the privilege to be removed from the feature. This must match an existing privilege code within the specified feature.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Privilege was successfully removed from the feature and all associated entitlements" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans/{plan_code}/entitlements": { "get": { "operationId": "GetPlanEntitlements", "tags": [ "Entitlements" ], "summary": "List all entitlements", "description": "Retrieve all entitlements assigned to a specific plan", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of plan entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEntitlementListResponse" }, "example": { "entitlements": [ { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 10 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 5 }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true } ] }, { "feature_code": "api_access", "name": "API Access", "description": "Access to REST API endpoints", "feature_privileges": [ { "code": "rate_limit", "name": "API Rate Limit", "value_type": "INTEGER", "value": 10000 }, { "code": "endpoints", "name": "Available Endpoints", "value_type": "SELECT", "value": "all", "config": { "select_options": [ "basic", "standard", "premium", "all" ] } } ] }, { "feature_code": "sso", "name": "Single Sign-On", "description": "SSO authentication configuration", "feature_privileges": [ { "code": "enabled", "name": "SSO Enabled", "value_type": "BOOLEAN", "value": true }, { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "value": "google", "config": { "select_options": [ "google", "okta" ] } } ] } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreatePlanEntitlement", "tags": [ "Entitlements" ], "summary": "Create an entitlement", "description": "Assign a feature to a plan with specific privilege values. This action removes all current entitlements and replaces with the new ones provided. To retain existing entitlements while adding new ones, apply a PATCH request.", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementRequest" } } }, "required": [ "entitlements" ] }, "example": { "entitlements": [ { "feature_code": "seats", "feature_privilege_values": { "max": 100, "max_admins": 10, "root": true, "guest_access": false } }, { "feature_code": "api_access", "feature_privilege_values": { "rate_limit": 10000, "endpoints": "all" } } ] } } } }, "responses": { "201": { "description": "Entitlements created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEntitlementListResponse" }, "example": { "entitlements": [ { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 100 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 10 }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true }, { "code": "guest_access", "name": "Allow guest access", "value_type": "BOOLEAN", "value": false } ] }, { "feature_code": "api_access", "name": "API Access", "description": "Access to REST API endpoints", "feature_privileges": [ { "code": "rate_limit", "name": "API Rate Limit", "value_type": "INTEGER", "value": 10000 }, { "code": "endpoints", "name": "Available Endpoints", "value_type": "SELECT", "value": "all", "config": { "select_options": [ "basic", "standard", "premium", "all" ] } } ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "UpdatePlanEntitlements", "tags": [ "Entitlements" ], "summary": "Partial update of entitlements", "description": "Update privilege values for one or more plan entitlements. Any new privileges or features you provide will be added. Existing values are overwritten if duplicates are found. Items not included in the request will be left unchanged.", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementRequest" } } }, "required": [ "entitlements" ] }, "example": { "entitlements": [ { "feature_code": "seats", "feature_privilege_values": { "max": 150, "max_admins": 15, "root": true, "guest_access": false, "provider": "google" } }, { "feature_code": "api_access", "feature_privilege_values": { "rate_limit": 25000, "endpoints": "all" } } ] } } } }, "responses": { "200": { "description": "Entitlements updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEntitlementListResponse" }, "example": { "entitlements": [ { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 150 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 15 }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true } ] }, { "feature_code": "api_access", "name": "API Access", "description": "Access to REST API endpoints", "feature_privileges": [ { "code": "rate_limit", "name": "API Rate Limit", "value_type": "INTEGER", "value": 25000 }, { "code": "endpoints", "name": "Available Endpoints", "value_type": "SELECT", "value": "all", "config": { "select_options": [ "basic", "standard", "premium", "all" ] } } ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans/{plan_code}/entitlements/{feature_code}": { "get": { "operationId": "GetPlanEntitlement", "tags": [ "Entitlements" ], "summary": "Retrieve an entitlement", "description": "Get details of a specific entitlement for a plan", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } }, { "name": "feature_code", "in": "path", "required": true, "description": "The unique code of the feature", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entitlement details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanEntitlementResponse" }, "example": { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 10 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 5 }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true }, { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "value": "google", "config": { "select_options": [ "google", "okta" ] } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeletePlanEntitlement", "tags": [ "Entitlements" ], "summary": "Delete an entitlement", "description": "Remove a feature entitlement from a plan", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } }, { "name": "feature_code", "in": "path", "required": true, "description": "The unique code of the feature", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Entitlement deleted successfully" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans/{plan_code}/entitlements/{feature_code}/privileges/{privilege_code}": { "delete": { "operationId": "DeletePlanEntitlementPrivilege", "tags": [ "Entitlements" ], "summary": "Remove a privilege from an entitlement", "description": "Remove a specific privilege from a plan entitlement", "parameters": [ { "name": "plan_code", "in": "path", "required": true, "description": "The unique code of the plan", "schema": { "type": "string" } }, { "name": "feature_code", "in": "path", "required": true, "description": "The unique code of the feature", "schema": { "type": "string" } }, { "name": "privilege_code", "in": "path", "required": true, "description": "The unique code of the privilege to remove", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Privilege removed successfully" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/entitlements": { "get": { "operationId": "GetSubscriptionEntitlements", "tags": [ "Entitlements" ], "summary": "List all subscription entitlements", "description": "Retrieve effective entitlements for a subscription, including plan defaults and subscription-specific overrides", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "The external ID of the subscription", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective entitlements for the subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntitlementListResponse" }, "example": { "entitlements": [ { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 15, "plan_value": 10, "override_value": 15 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 5, "plan_value": 5, "override_value": null }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true, "plan_value": true, "override_value": null }, { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "value": "okta", "plan_value": "google", "override_value": "okta", "config": { "select_options": [ "google", "okta" ] } } ] }, { "feature_code": "api_access", "name": "API Access", "description": "Access to REST API endpoints", "feature_privileges": [ { "code": "rate_limit", "name": "API Rate Limit", "value_type": "INTEGER", "value": 10000, "plan_value": 10000, "override_value": null }, { "code": "endpoints", "name": "Available Endpoints", "value_type": "SELECT", "value": "all", "plan_value": "all", "override_value": null, "config": { "select_options": [ "basic", "standard", "premium", "all" ] } } ] } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "UpdateSubscriptionEntitlements", "tags": [ "Entitlements" ], "summary": "Update subscription entitlements", "description": "This endpoint performs partial updates to subscription entitlements. The entitlements in the request are combined with existing entitlements associated with the subscription (even the ones inherited from plan) that are not mentioned in the request.", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "The external ID of the subscription", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementRequest" } } }, "required": [ "entitlements" ] }, "example": { "entitlements": [ { "feature_code": "seats", "feature_privilege_values": { "max": 250, "max_admins": 25, "guest_access": true } }, { "feature_code": "sso", "feature_privilege_values": { "provider": "saml" } } ] } } } }, "responses": { "200": { "description": "Entitlements updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntitlementListResponse" }, "example": { "entitlements": [ { "feature_code": "seats", "name": "Number of seats", "description": "Number of users of the account", "feature_privileges": [ { "code": "max", "name": "Maximum", "value_type": "INTEGER", "value": 250, "plan_value": 100, "override_value": 250 }, { "code": "max_admins", "name": "Max Admins", "value_type": "INTEGER", "value": 25, "plan_value": 10, "override_value": 25 }, { "code": "root", "name": "Allow root user", "value_type": "BOOLEAN", "value": true, "plan_value": true, "override_value": null }, { "code": "guest_access", "name": "Allow guest access", "value_type": "BOOLEAN", "value": true, "plan_value": false, "override_value": true } ] }, { "feature_code": "sso", "name": "Single Sign-On", "description": "SSO authentication configuration", "feature_privileges": [ { "code": "enabled", "name": "SSO Enabled", "value_type": "BOOLEAN", "value": true, "plan_value": true, "override_value": null }, { "code": "provider", "name": "SSO Provider", "value_type": "SELECT", "value": "saml", "plan_value": "google", "override_value": "saml", "config": { "select_options": [ "google", "okta", "azure", "saml" ] } } ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/entitlements/{feature_code}": { "delete": { "operationId": "DeleteSubscriptionEntitlementOverride", "tags": [ "Entitlements" ], "summary": "Remove an entitlement from a subscription", "description": "Remove a subscription-specific entitlement override, reverting to plan defaults", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "The external ID of the subscription", "schema": { "type": "string" } }, { "name": "feature_code", "in": "path", "required": true, "description": "The unique code of the feature", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Override removed successfully" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_subscription_id}/entitlements/{feature_code}/privileges/{privilege_code}": { "delete": { "operationId": "DeleteSubscriptionEntitlementPrivilegeOverride", "tags": [ "Entitlements" ], "summary": "Remove a privilege from a subscription entitlement override", "description": "Remove a specific privilege override from a subscription entitlement, reverting to plan default for that privilege", "parameters": [ { "name": "external_subscription_id", "in": "path", "required": true, "description": "The external ID of the subscription", "schema": { "type": "string" } }, { "name": "feature_code", "in": "path", "required": true, "description": "The unique code of the feature", "schema": { "type": "string" } }, { "name": "privilege_code", "in": "path", "required": true, "description": "The unique code of the privilege to remove", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Privilege override removed successfully" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "x-webhooks": { "usage-billing.subscription-alert.triggered": { "post": { "operationId": "SubscriptionAlertTriggered", "tags": [ "Alerts" ], "summary": "A new alert was triggered", "description": "Threshold defined in the alert was crossed.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the triggered alert", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/TriggeredAlertObject" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet.created": { "post": { "operationId": "WalletCreated", "tags": [ "Wallets" ], "summary": "Wallet created.", "description": "Webhook for wallet creation.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request for wallet creation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet.updated": { "post": { "operationId": "WalletUpdated", "tags": [ "Wallets" ], "summary": "Wallet update.", "description": "Webhook for wallet update.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request when wallet update happens.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet.terminated": { "post": { "operationId": "WalletTerminated", "tags": [ "Wallets" ], "summary": "Wallet terminated.", "description": "Webhook for wallet termination.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request for wallet termination.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet.net-balance-depleted": { "post": { "operationId": "WalletNetBalanceDepleted", "tags": [ "Wallets" ], "summary": "Wallet net balance depletion.", "description": "Webhook for wallet net balance depletion.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request when wallet net balance depletion happens", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet-transaction.created": { "post": { "operationId": "WalletTransactionCreated", "tags": [ "Wallets" ], "summary": "Wallet transaction created.", "description": "Webhook for wallet transaction creation.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request when wallet transaction creation happens.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.wallet-transaction.updated": { "post": { "operationId": "WalletTransactionUpdated", "tags": [ "Wallets" ], "summary": "Wallet transaction updated.", "description": "Webhook for wallet transaction update.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the request when wallet transaction update happens.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/WalletWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.invoice.created": { "post": { "operationId": "InvoiceCreated", "tags": [ "Invoices" ], "summary": "Invoice created.", "description": "Webhook for invoice creation.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the invoice when created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/InvoiceWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.invoice.payment.succeeded": { "post": { "operationId": "InvoicePaymentStatusUpdated", "tags": [ "Invoices" ], "summary": "Invoice payment status updated.", "description": "Webhook for payment status update of an invoice.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the invoice when the payment status is updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/InvoiceWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.invoice.payment.overdue": { "post": { "operationId": "InvoicePaymentOverdue", "tags": [ "Invoices" ], "summary": "Invoice payment overdue.", "description": "Webhook for an invoice payment overdue.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the invoice when payment is overdue.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/InvoiceWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.invoice.payment.failed": { "post": { "operationId": "InvoicePaymentStatusFailure", "tags": [ "Invoices" ], "summary": "Invoice payment failure.", "description": "Webhook for Invoice Payment failure.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the invoice when the payment status is failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/InvoiceWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.subscription.updated": { "post": { "operationId": "SubscriptionUpdated", "tags": [ "Subscriptions" ], "summary": "Subscription updated.", "description": "Webhook for Subscription updated.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the subscription when updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.subscription.terminated": { "post": { "operationId": "SubscriptionTerminated", "tags": [ "Subscriptions" ], "summary": "Subscription terminated.", "description": "Webhook for Subscription terminated.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the subscription when terminated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.subscription.trial.ended": { "post": { "operationId": "SubscriptionTrialEnded", "tags": [ "Subscriptions" ], "summary": "Subscription trial ended.", "description": "Webhook for Subscription trial ended.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the subscription when trial ended.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.credit-note.created": { "post": { "operationId": "CreditNoteCreated", "tags": [ "Credit Notes" ], "summary": "Credit Note created.", "description": "Webhook for credit note creation.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the credit note when created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/CreditNoteWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } }, "usage-billing.credit-note.refund.failed": { "post": { "operationId": "CreditNoteRefundFailure", "tags": [ "Credit Notes" ], "summary": "Credit Note refund failure.", "description": "Webhook for credit note refund failure.", "parameters": [ { "$ref": "#/components/parameters/paypal-transmission-id" }, { "$ref": "#/components/parameters/paypal-transmission-time" } ], "requestBody": { "description": "Details of the credit note when refund is failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelop" }, { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/CreditNoteWithId" } }, "required": [ "resource" ] } ] } } } }, "responses": { "204": { "description": "Return a 204 status to indicate that the data was received successfully." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "oauth2", "description": "Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.", "flows": { "clientCredentials": { "tokenUrl": "https://api-m.sandbox.paypal.com/v1/oauth2/token", "scopes": { "read": "Read access", "write": "Write access" } } } } }, "schemas": { "Currency": { "type": "string", "description": "Currency code in ISO 4217 format.", "example": "USD", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "Address": { "description": "Address of the customer or party.", "type": "object", "properties": { "line1": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 254, "description": "First line of the address.", "example": "123 Main St" }, "line2": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Second line of the address (optional). This can include apartment, suite, or unit numbers.", "example": "Apt 4B" }, "city": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "City of the customer or party.", "example": "New York" }, "state": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "State or region of the customer or party.", "example": "NY" }, "postal_code": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Postal or ZIP code of the customer or party. Typically required for countries with a postal code or an equivalent.", "example": "10001" }, "country": { "type": "string", "nullable": false, "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country of the customer or party. Use ISO 3166-1 alpha-2 country codes.", "example": "US" } } }, "Timezone": { "type": "string", "example": "UTC", "description": "The timezone of the billing entity", "x-enum": [ "UTC", "Africa/Algiers", "Africa/Cairo", "Africa/Casablanca", "Africa/Harare", "Africa/Johannesburg", "Africa/Monrovia", "Africa/Nairobi", "America/Argentina/Buenos_Aires", "America/Bogota", "America/Caracas", "America/Chicago", "America/Chihuahua", "America/Denver", "America/Godthab", "America/Guatemala", "America/Guyana", "America/Halifax", "America/Indiana/Indianapolis", "America/Juneau", "America/La_Paz", "America/Lima", "America/Los_Angeles", "America/Mazatlan", "America/Mexico_City", "America/Monterrey", "America/Montevideo", "America/New_York", "America/Phoenix", "America/Puerto_Rico", "America/Regina", "America/Santiago", "America/Sao_Paulo", "America/St_Johns", "America/Tijuana", "Asia/Almaty", "Asia/Baghdad", "Asia/Baku", "Asia/Bangkok", "Asia/Chongqing", "Asia/Colombo", "Asia/Dhaka", "Asia/Hong_Kong", "Asia/Irkutsk", "Asia/Jakarta", "Asia/Jerusalem", "Asia/Kabul", "Asia/Kamchatka", "Asia/Karachi", "Asia/Kathmandu", "Asia/Kolkata", "Asia/Krasnoyarsk", "Asia/Kuala_Lumpur", "Asia/Kuwait", "Asia/Magadan", "Asia/Muscat", "Asia/Novosibirsk", "Asia/Rangoon", "Asia/Riyadh", "Asia/Seoul", "Asia/Shanghai", "Asia/Singapore", "Asia/Srednekolymsk", "Asia/Taipei", "Asia/Tashkent", "Asia/Tbilisi", "Asia/Tehran", "Asia/Tokyo", "Asia/Ulaanbaatar", "Asia/Urumqi", "Asia/Vladivostok", "Asia/Yakutsk", "Asia/Yekaterinburg", "Asia/Yerevan", "Australia/Adelaide", "Australia/Brisbane", "Australia/Darwin", "Australia/Hobart", "Australia/Melbourne", "Australia/Perth", "Australia/Sydney", "Europe/Amsterdam", "Europe/Athens", "Europe/Belgrade", "Europe/Berlin", "Europe/Bratislava", "Europe/Brussels", "Europe/Bucharest", "Europe/Budapest", "Europe/Copenhagen", "Europe/Dublin", "Europe/Helsinki", "Europe/Istanbul", "Europe/Kaliningrad", "Europe/Kiev", "Europe/Lisbon", "Europe/Ljubljana", "Europe/London", "Europe/Madrid", "Europe/Minsk", "Europe/Moscow", "Europe/Paris", "Europe/Prague", "Europe/Riga", "Europe/Rome", "Europe/Samara", "Europe/Sarajevo", "Europe/Skopje", "Europe/Sofia", "Europe/Stockholm", "Europe/Tallinn", "Europe/Vienna", "Europe/Vilnius", "Europe/Volgograd", "Europe/Warsaw", "Europe/Zagreb", "Europe/Zurich", "Pacific/Apia", "Pacific/Auckland", "Pacific/Chatham", "Pacific/Fakaofo", "Pacific/Fiji", "Pacific/Guadalcanal", "Pacific/Guam", "Pacific/Honolulu", "Pacific/Majuro", "Pacific/Midway", "Pacific/Noumea", "Pacific/Pago_Pago", "Pacific/Port_Moresby", "Pacific/Tongatapu" ], "x-enum-descriptions": [ "Coordinated Universal Time (UTC), the primary time standard", "Algeria Time (UTC+1), used in Algeria", "Eastern European Time (UTC+2), used in Egypt", "Western European Time (UTC+0/+1), used in Morocco", "Central Africa Time (UTC+2), used in Zimbabwe", "South Africa Standard Time (UTC+2), used in South Africa", "Greenwich Mean Time (UTC+0), used in Liberia", "East Africa Time (UTC+3), used in Kenya", "Argentina Time (UTC-3), used in Buenos Aires", "Colombia Time (UTC-5), used in Colombia", "Venezuela Time (UTC-4), used in Venezuela", "Central Standard Time (UTC-6), used in central United States", "Mountain Standard Time (UTC-7), used in Chihuahua, Mexico", "Mountain Standard Time (UTC-7), used in mountain states of the United States", "West Greenland Time (UTC-3), used in Greenland", "Central America Time (UTC-6), used in Guatemala", "Guyana Time (UTC-4), used in Guyana", "Atlantic Standard Time (UTC-4), used in Halifax, Canada", "Eastern Standard Time (UTC-5), used in Indianapolis, United States", "Alaska Time (UTC-9), used in Juneau, Alaska", "Bolivia Time (UTC-4), used in La Paz", "Peru Time (UTC-5), used in Peru", "Pacific Standard Time (UTC-8), used in western United States", "Mexican Pacific Time (UTC-7), used in Mazatlan, Mexico", "Central Standard Time (UTC-6), used in Mexico City", "Mexican Central Standard Time (UTC-6), used in Monterrey, Mexico", "Uruguay Time (UTC-3), used in Uruguay", "Eastern Standard Time (UTC-5), used in eastern United States", "Mountain Standard Time (UTC-7), used in Phoenix, Arizona", "Atlantic Standard Time (UTC-4), used in Puerto Rico", "Central Standard Time (UTC-6), used in Saskatchewan, Canada", "Chile Standard Time (UTC-4), used in Santiago, Chile", "Brasília Time (UTC-3), used in São Paulo, Brazil", "Newfoundland Standard Time (UTC-3:30), used in Newfoundland, Canada", "Pacific Standard Time (UTC-8), used in Tijuana, Mexico", "Alma-Ata Time (UTC+6), used in Almaty, Kazakhstan", "Arabia Standard Time (UTC+3), used in Baghdad, Iraq", "Azerbaijan Time (UTC+4), used in Baku, Azerbaijan", "Indochina Time (UTC+7), used in Thailand", "China Standard Time (UTC+8), used in Chongqing, China", "India Standard Time (UTC+5:30), used in Sri Lanka", "Bangladesh Standard Time (UTC+6), used in Bangladesh", "Hong Kong Time (UTC+8), used in Hong Kong", "Irkutsk Time (UTC+8), used in Irkutsk, Russia", "Western Indonesian Time (UTC+7), used in Jakarta, Indonesia", "Israel Standard Time (UTC+2), used in Jerusalem, Israel", "Afghanistan Time (UTC+4:30), used in Afghanistan", "Kamchatka Time (UTC+12), used in Kamchatka, Russia", "Pakistan Standard Time (UTC+5), used in Pakistan", "Nepal Time (UTC+5:45), used in Nepal", "India Standard Time (UTC+5:30), used in India", "Krasnoyarsk Time (UTC+7), used in Krasnoyarsk, Russia", "Malaysia Time (UTC+8), used in Kuala Lumpur, Malaysia", "Arabia Standard Time (UTC+3), used in Kuwait", "Magadan Time (UTC+11), used in Magadan, Russia", "Gulf Standard Time (UTC+4), used in Muscat, Oman", "Novosibirsk Time (UTC+7), used in Novosibirsk, Russia", "Myanmar Time (UTC+6:30), used in Myanmar", "Arabia Standard Time (UTC+3), used in Saudi Arabia", "Korea Standard Time (UTC+9), used in South Korea", "China Standard Time (UTC+8), used in Shanghai, China", "Singapore Time (UTC+8), used in Singapore", "Srednekolymsk Time (UTC+11), used in Srednekolymsk, Russia", "Taiwan Time (UTC+8), used in Taiwan", "Uzbekistan Time (UTC+5), used in Tashkent, Uzbekistan", "Georgia Standard Time (UTC+4), used in Tbilisi, Georgia", "Iran Standard Time (UTC+3:30), used in Iran", "Japan Standard Time (UTC+9), used in Japan", "Ulaanbaatar Time (UTC+8), used in Mongolia", "China Standard Time (UTC+8), used in Urumqi, China", "Vladivostok Time (UTC+10), used in Vladivostok, Russia", "Yakutsk Time (UTC+9), used in Yakutsk, Russia", "Yekaterinburg Time (UTC+5), used in Yekaterinburg, Russia", "Armenia Time (UTC+4), used in Yerevan, Armenia", "Australian Central Standard Time (UTC+9:30), used in Adelaide, Australia", "Australian Eastern Standard Time (UTC+10), used in Brisbane, Australia", "Australian Central Standard Time (UTC+9:30), used in Darwin, Australia", "Australian Eastern Standard Time (UTC+10), used in Hobart, Australia", "Australian Eastern Standard Time (UTC+10), used in Melbourne, Australia", "Australian Western Standard Time (UTC+8), used in Perth, Australia", "Australian Eastern Standard Time (UTC+10), used in Sydney, Australia", "Central European Time (UTC+1), used in Amsterdam, Netherlands", "Eastern European Time (UTC+2), used in Athens, Greece", "Central European Time (UTC+1), used in Belgrade, Serbia", "Central European Time (UTC+1), used in Berlin, Germany", "Central European Time (UTC+1), used in Bratislava, Slovakia", "Central European Time (UTC+1), used in Brussels, Belgium", "Eastern European Time (UTC+2), used in Bucharest, Romania", "Central European Time (UTC+1), used in Budapest, Hungary", "Central European Time (UTC+1), used in Copenhagen, Denmark", "Irish Standard Time (UTC+0/+1), used in Dublin, Ireland", "Eastern European Time (UTC+2), used in Helsinki, Finland", "Turkey Time (UTC+3), used in Istanbul, Turkey", "Eastern European Time (UTC+2), used in Kaliningrad, Russia", "Eastern European Time (UTC+2), used in Kiev, Ukraine", "Western European Time (UTC+0/+1), used in Lisbon, Portugal", "Central European Time (UTC+1), used in Ljubljana, Slovenia", "Greenwich Mean Time/British Summer Time (UTC+0/+1), used in London, UK", "Central European Time (UTC+1), used in Madrid, Spain", "Moscow Standard Time (UTC+3), used in Minsk, Belarus", "Moscow Standard Time (UTC+3), used in Moscow, Russia", "Central European Time (UTC+1), used in Paris, France", "Central European Time (UTC+1), used in Prague, Czech Republic", "Eastern European Time (UTC+2), used in Riga, Latvia", "Central European Time (UTC+1), used in Rome, Italy", "Samara Time (UTC+4), used in Samara, Russia", "Central European Time (UTC+1), used in Sarajevo, Bosnia and Herzegovina", "Central European Time (UTC+1), used in Skopje, North Macedonia", "Eastern European Time (UTC+2), used in Sofia, Bulgaria", "Central European Time (UTC+1), used in Stockholm, Sweden", "Eastern European Time (UTC+2), used in Tallinn, Estonia", "Central European Time (UTC+1), used in Vienna, Austria", "Eastern European Time (UTC+2), used in Vilnius, Lithuania", "Moscow Standard Time (UTC+3), used in Volgograd, Russia", "Central European Time (UTC+1), used in Warsaw, Poland", "Central European Time (UTC+1), used in Zagreb, Croatia", "Central European Time (UTC+1), used in Zurich, Switzerland", "West Samoa Time (UTC+13), used in Samoa", "New Zealand Standard Time (UTC+12), used in Auckland, New Zealand", "Chatham Island Standard Time (UTC+12:45), used in Chatham Islands, New Zealand", "Tokelau Time (UTC+13), used in Tokelau", "Fiji Time (UTC+12), used in Fiji", "Solomon Islands Time (UTC+11), used in Solomon Islands", "Chamorro Standard Time (UTC+10), used in Guam", "Hawaii-Aleutian Standard Time (UTC-10), used in Hawaii", "Marshall Islands Time (UTC+12), used in Marshall Islands", "Samoa Standard Time (UTC-11), used in Midway Islands", "New Caledonia Time (UTC+11), used in New Caledonia", "Samoa Standard Time (UTC-11), used in American Samoa", "Papua New Guinea Time (UTC+10), used in Papua New Guinea", "Tonga Time (UTC+13), used in Tonga" ] }, "BillingEntityBase": { "description": "Base schema for billing entity request/response objects", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the billing entity", "example": "Acme Inc" }, "default_currency": { "$ref": "#/components/schemas/Currency" }, "finalize_zero_amount_invoice": { "type": "boolean", "description": "Whether to finalize invoices with zero amount", "example": true }, "address": { "$ref": "#/components/schemas/Address" }, "legal_name": { "type": "string", "description": "Legal name of the entity", "nullable": true, "example": "Acme Corporation Inc." }, "legal_number": { "type": "string", "description": "Legal registration number", "nullable": true, "example": "US123456789" }, "email": { "type": "string", "format": "email", "description": "Contact email for the entity", "nullable": true, "example": "billing@acmeinc.com" }, "timezone": { "$ref": "#/components/schemas/Timezone" } } }, "BillingEntityCode": { "type": "string", "description": "Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "acme_inc" }, "DateTimeWithZone": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601 format.", "example": "2023-10-01T12:00:00Z" }, "BillingEntity": { "description": "Represents a billing entity which can be associated with invoices, customers, and taxes", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BillingEntityBase" }, { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/BillingEntityCode" }, "is_default": { "type": "boolean", "description": "Whether this is the default billing entity", "example": false }, "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the billing entity", "example": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Creation timestamp", "example": "2023-01-15T00:00:00Z" } ] }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Last update timestamp", "example": "2023-01-15T00:00:00Z" } ] } } } ] }, "BillingEntityListResponse": { "description": "Array of billing entities", "type": "array", "items": { "$ref": "#/components/schemas/BillingEntity" } }, "ErrorDetail": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "location": { "type": "string" }, "issue": { "type": "string" }, "description": { "type": "string" } } }, "Error": { "type": "object", "properties": { "name": { "type": "string" }, "debug_id": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "BillingEntityCreateRequest": { "description": "Request body for creating a new billing entity", "allOf": [ { "$ref": "#/components/schemas/BillingEntityBase" }, { "type": "object", "required": [ "code" ], "properties": { "code": { "$ref": "#/components/schemas/BillingEntityCode" } } } ] }, "TaxBase": { "description": "Base schema for tax request/response objects", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the tax", "example": "TVA" }, "rate": { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)(?:0?\\.\\d{1,2}|[1-9]\\d?(?:\\.\\d{1,2})?|100(?:\\.0{1,2})?)$", "description": "The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.", "example": "20.00" }, "description": { "type": "string", "description": "Detailed description of the tax for internal reference", "example": "French standard VAT" } } }, "TaxCode": { "type": "string", "description": "Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "standard_vat" }, "TaxResponse": { "description": "Represents a customizable tax rate that can be applied to invoices and fees", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TaxBase" }, { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/TaxCode" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the tax", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format", "example": "2025-06-01T00:00:00Z" } ] } } } ] }, "BillingEntityWithTaxes": { "description": "A billing entity with associated tax details", "allOf": [ { "$ref": "#/components/schemas/BillingEntity" }, { "type": "object", "properties": { "taxes": { "type": "array", "description": "List of tax entities configured for the billing entity", "items": { "$ref": "#/components/schemas/TaxResponse" } } } } ] }, "BillingEntityResponse": { "description": "Response object for billing entity operations", "allOf": [ { "$ref": "#/components/schemas/BillingEntityWithTaxes" } ] }, "TaxCodes": { "type": "array", "items": { "type": "string" }, "description": "List of unique codes used to identify taxes to be applied.", "example": [ "standard_vat" ] }, "BillingEntityUpdateRequest": { "description": "Request body for updating an existing billing entity", "allOf": [ { "$ref": "#/components/schemas/BillingEntityBase" }, { "type": "object", "properties": { "tax_codes": { "$ref": "#/components/schemas/TaxCodes" } } } ] }, "PaginationMetadata": { "type": "object", "properties": { "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "current_page": { "type": "integer" } } }, "TaxesPaginated": { "description": "Paginated list of tax objects", "type": "object", "required": [ "taxes", "meta" ], "properties": { "taxes": { "type": "array", "items": { "$ref": "#/components/schemas/TaxResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "TaxCreateRequest": { "description": "Request body for creating a new tax", "allOf": [ { "$ref": "#/components/schemas/TaxBase" }, { "type": "object", "required": [ "code", "rate" ], "properties": { "code": { "$ref": "#/components/schemas/TaxCode" } } } ] }, "TaxUpdateRequest": { "description": "Request body for updating an existing tax", "allOf": [ { "$ref": "#/components/schemas/TaxBase" } ] }, "ActivateMerchantResponse": { "type": "object", "properties": { "billing_tier_id": { "type": "string", "example": "NDc3Nzc1NTg0NTY0MTgyMzUzNw==.K7iva2SX08+9R52rAIfUwQvruZackQErIDDdEnUxxKE=", "description": "The unique code for merchant to use when sending events." } }, "description": "Response object for activating a merchant account for usage based billing." }, "InvoiceStatus": { "type": "string", "nullable": true, "enum": [ "DRAFT", "FINALIZED" ], "x-enum-varnames": [ "DRAFT", "FINALIZED" ], "x-enum-descriptions": [ "The invoice is in draft state and can be modified", "The invoice has been finalized and cannot be modified" ], "description": "Status of the invoice", "example": "FINALIZED" }, "Date": { "type": "string", "format": "date", "description": "Date in ISO 8601 format (YYYY-MM-DD).", "example": "2023-10-01", "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8]))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$" }, "PaymentStatus": { "type": "string", "description": "Status of invoice payment", "enum": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-varnames": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-descriptions": [ "The invoice is awaiting payment", "The payment for the invoice has failed", "The payment for the invoice was successful" ], "example": "PENDING" }, "AmountNoCurrency": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number", "format": "decimal", "description": "The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).", "example": 120.35, "minimum": 0, "nullable": false, "default": 0 } } }, "Amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" }, { "type": "object", "required": [ "currency_code" ], "properties": { "currency_code": { "$ref": "#/components/schemas/Currency" } } } ] }, "AmountBreakdown": { "type": "object", "properties": { "fees": { "description": "The total amount of fees applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "credit_notes": { "description": "The total amount of credit notes applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "sub_total_excluding_taxes": { "description": "The subtotal amount of the invoice excluding taxes.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "taxes": { "description": "The total amount of taxes applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "sub_total_including_taxes": { "description": "The subtotal amount of the invoice including taxes.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "prepaid_credit": { "description": "The total amount of prepaid credits applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "progressive_billing_credit": { "description": "The total amount of progressive billing credits applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] } } }, "AmountWithBreakdown": { "type": "object", "properties": { "total_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "breakdown": { "allOf": [ { "$ref": "#/components/schemas/AmountBreakdown" } ] } } }, "FeeObject": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "format": "uuid", "description": "Unique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "total_amount": { "$ref": "#/components/schemas/Amount", "description": "The cost of this specific fee, including any applicable taxes.", "example": { "value": 1.2, "currency_code": "USD" } }, "name": { "type": "string", "nullable": true, "description": "The the name of the fee associated to any one of the charge, the credit, the subscription or the commitment", "example": "Basic Plan" } } }, "InvoiceType": { "type": "string", "nullable": true, "enum": [ "SUBSCRIPTION", "ONE_OFF", "CREDIT" ], "x-enum-varnames": [ "SUBSCRIPTION", "ONE_OFF", "CREDIT" ], "x-enum-descriptions": [ "Invoice generated for subscription recurring charges", "Invoice generated for one-time charges", "Credit note invoice for refunds or adjustments" ], "description": "Type of invoice", "example": "SUBSCRIPTION" }, "EmailAddress": { "type": "string", "description": "The internationalized email address.", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$", "example": "abc@test.com" }, "PaymentMethodToken": { "type": "string", "minLength": 1, "maxLength": 36, "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "pm_visa_4242" }, "PaymentMethodType": { "type": "string", "description": "Type of payment method used (e.g., CARD, ACH_DEBIT)", "enum": [ "CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY" ], "x-enum-varnames": [ "CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY" ], "x-enum-description": [ "Payment made using a Credit or Debit card.", "Payment made using PayPal.", "Payment made using Automated Clearing House (ACH) transfer.", "Payment made using Apple Pay." ], "example": "CARD" }, "CustomerMetadata": { "type": "object", "description": "Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format", "required": [ "key", "value", "display_in_invoice" ], "properties": { "key": { "type": "string", "example": "Purchase Order", "description": "The metadata object key", "maxLength": 20 }, "value": { "type": "string", "example": "123456789", "description": "The metadata object value", "maxLength": 100 }, "display_in_invoice": { "type": "boolean", "example": true, "description": "Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice." } } }, "Customer": { "title": "Customer", "description": "A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.", "type": "object", "required": [ "name", "email", "external_id" ], "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "ext_cust_12345" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "billing_entity_code": { "$ref": "#/components/schemas/BillingEntityCode" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodType" }, "taxes": { "type": "array", "description": "List of tax entities configured for the customer.", "items": { "$ref": "#/components/schemas/TaxResponse" } }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "CustomerWithId": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "BaseAppliedTax": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the applied tax.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "tax_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the tax.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "tax_name": { "type": "string", "description": "Name of the tax.", "example": "TVA" }, "tax_code": { "type": "string", "description": "Unique code used to identify the tax associated with the API request.", "example": "french_standard_vat" }, "tax_rate": { "type": "number", "description": "The percentage rate of the tax", "example": 20 }, "tax_description": { "type": "string", "description": "Internal description of the taxes", "example": "French standard VAT" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "Amount of the tax", "example": { "value": 20, "currency_code": "USD" } }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created.", "example": "2022-09-14T16:35:31Z" } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the invoice", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "billing_entity_code": { "$ref": "#/components/schemas/BillingEntityCode" }, "sequential_id": { "type": "integer", "description": "Sequential ID of the invoice, unique within the billing entity.", "example": 3 }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "payment_status": { "$ref": "#/components/schemas/PaymentStatus" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountWithBreakdown" } ], "description": "Total amount due for the invoice, including breakdown of fees, taxes, and discounts.", "example": { "total_amount": { "value": 19.99, "currency_code": "USD" }, "breakdown": { "fees": { "value": 1, "currency_code": "USD" }, "credit_notes": { "value": 0, "currency_code": "USD" }, "sub_total_excluding_taxes": { "value": 20, "currency_code": "USD" }, "taxes": { "value": 0.99, "currency_code": "USD" }, "sub_total_including_taxes": { "value": 19.99, "currency_code": "USD" } } } }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/FeeObject" } }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "Due date for the invoice payment", "example": "2023-01-15" }, "issued_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "Date when the invoice was issued", "example": "2023-01-01" }, "invoice_number": { "type": "string", "description": "Invoice number, unique within the billing entity.", "example": "INV-2023-001" }, "version_number": { "type": "string", "format": "number", "description": "Version number of the invoice, indicating the revision of the invoice.", "example": "INV-2023-001" }, "payment_overdue": { "type": "boolean", "description": "Indicates whether the invoice payment is overdue.", "example": false }, "invoice_type": { "$ref": "#/components/schemas/InvoiceType" }, "customer": { "$ref": "#/components/schemas/CustomerWithId" }, "billing_period": { "type": "array", "items": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the subscription", "example": "sub_01H3YT8P7Q5R3S1T2U0V4W9X8" }, "external_subscription_id": { "type": "string", "description": "The subscription external unique identifier supplied by client.", "example": "ext_id_23fw3" }, "plan_id": { "description": "Unique identifier for the plan", "type": "string", "example": "plan_01H3YT8P7Q5R3S1T2U0V4W9X8" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's payment method", "example": "pm_visa_4242" }, "payment_method_type": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodType" } ] }, "subscription_from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "subscription_to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "charges_from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "charges_to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "invoicing_reason": { "type": "string", "description": "Reason for invoicing, e.g., 'subscription', 'usage', 'one-time charge'", "example": "subscription" } } } }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "applied_taxes": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/BaseAppliedTax" }, { "type": "object", "properties": { "fees_amount": { "$ref": "#/components/schemas/AmountNoCurrency", "description": "The total fees amount to which the tax is applied.", "example": { "value": 10.05 } } } } ] } } } }, "InvoiceWithId": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "description": "Timestamp when the invoice was created", "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "example": "2023-01-01T00:00:00Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the invoice was last updated", "example": "2023-01-01T00:00:00Z" } } } ] }, "MetricType": { "type": "string", "default": "RECURRING", "enum": [ "METERED", "RECURRING" ], "description": "Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges.", "example": "METERED", "x-enum-varnames": [ "METERED", "RECURRING" ], "x-enum-descriptions": [ "Usage-based metric that charges based on the amount used.", "Fixed periodic charge that recurs at specified intervals." ] }, "MetricAggregationType": { "type": "string", "nullable": true, "enum": [ "COUNT", "SUM", "MAX", "COUNT_DISTINCT", "LATEST" ], "x-enum-varnames": [ "COUNT", "SUM", "MAX", "COUNT_DISTINCT", "LATEST" ], "x-enum-descriptions": [ "Count the number of events", "Sum the values of a numeric field", "Find the maximum value of a numeric field", "Count the number of distinct values", "Use the latest value" ], "description": "Aggregation type for the metric", "example": "SUM" }, "MetricBase": { "type": "object", "properties": { "name": { "type": "string", "description": "Descriptive name of the metric that represents a pricing component of your application. This is primarily used for display purposes in the user interface." }, "code": { "type": "string", "description": "Unique code used to identify the metric within your system. This code is used in API requests to associate events with the correct metric and must be unique across all metrics. Once created, this code cannot be changed." }, "type": { "$ref": "#/components/schemas/MetricType" }, "description": { "type": "string", "description": "Optional detailed description of the metric that provides additional context about what the metric measures and how it's used. This information is for internal use and helps document the purpose of the metric." }, "aggregation_type": { "$ref": "#/components/schemas/MetricAggregationType" }, "aggregation_field": { "type": "string", "description": "Property name within the event payload that will be used for aggregating usage data. This field specifies which value from the event should be used for calculations. It is required for aggregation types like 'SUM', 'MAX', and other types that operate on values, but not required for 'COUNT' aggregation." }, "field_filters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Property name within the event payload that will be used for filtering. This allows you to segment usage data based on specific event properties, such as region, tier, or any other dimension you track." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Array of specific values that the system should match against the filter key. Only events with matching key-value pairs will be included in the metric calculations. This enables differentiated pricing based on dimensions like region, environment, or other custom properties." } }, "required": [ "key", "values" ] } } } }, "MetricResponse": { "type": "object", "required": [ "id", "name", "code", "aggregation_type", "created_at" ], "allOf": [ { "$ref": "#/components/schemas/MetricBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the metric, automatically generated by the system upon creation. This ID is used internally to track the metric and cannot be modified." }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the metric was created. ISO 8601 format with timezone." }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the metric was last updated. ISO 8601 format with timezone." } } } ] }, "MetricRequest": { "type": "object", "required": [ "name", "code", "aggregation_type" ], "allOf": [ { "$ref": "#/components/schemas/MetricBase" } ] }, "MetricUpdateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetricBase" } ] }, "BillingCycle": { "type": "string", "description": "The billing cycle indicating how often the subscription is charged", "enum": [ "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ], "x-enum-varnames": [ "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ], "x-enum-descriptions": [ "Recurring billing occurs every week", "Recurring billing occurs every month", "Recurring billing occurs every three months", "Recurring billing occurs once a year" ], "example": "MONTHLY" }, "ChargeModel": { "type": "string", "description": "The pricing model applied to this charge", "enum": [ "STANDARD", "GRADUATED", "PACKAGE", "PERCENTAGE", "VOLUME" ], "x-enum-varnames": [ "STANDARD", "GRADUATED", "PACKAGE", "PERCENTAGE", "VOLUME" ], "x-enum-descriptions": [ "Standard pricing model where a fixed amount is charged per unit", "Graduated pricing model where the price per unit decreases as the quantity increases", "Package pricing model where a fixed price is charged for a set of units", "Percentage pricing model where a percentage of a base amount is charged", "Volume-based pricing model where the price varies based on the total volume consumed" ], "example": "GRADUATED", "default": "STANDARD" }, "UsageBasedCharge": { "type": "object", "required": [ "id", "metric_id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the charge", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "metric_id": { "type": "string", "description": "Unique identifier of the metric" }, "charge_model": { "$ref": "#/components/schemas/ChargeModel", "description": "Defines the pricing model to calculate the charge" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" }, "taxes": { "type": "array", "description": "List of tax entities configured for the usage based charge.", "items": { "$ref": "#/components/schemas/TaxResponse" } }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] } } }, "MinimumCommitmentBase": { "type": "object", "description": "Minimum commitment for this plan.", "required": [ "amount" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name.", "example": "Minimum Commitment (C1)" }, "taxes": { "type": "array", "description": "List of tax entities configured for the minimum commitment.", "items": { "$ref": "#/components/schemas/TaxResponse" } } } }, "MinimumCommitment": { "allOf": [ { "$ref": "#/components/schemas/MinimumCommitmentBase" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the minimum commitment, created by Lago.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "plan_code": { "type": "string", "example": "premium", "description": "The unique code representing the plan to be attached to the customer." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the minimum commitment was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.", "example": "2022-04-29T08:59:51Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.", "example": "2022-04-29T08:59:51Z" } } } ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the plan. This ID is used internally to track the plan and cannot be modified.", "example": "1a901a90-1a90-1a90-1a540-1a901a901a90" }, "name": { "type": "string" }, "code": { "type": "string" }, "billing_cycle": { "$ref": "#/components/schemas/BillingCycle" }, "description": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "trial_period": { "type": "integer" }, "pay_in_advance": { "type": "boolean" }, "taxes": { "type": "array", "description": "List of tax entities configured for the plan.", "items": { "$ref": "#/components/schemas/TaxResponse" } }, "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedCharge" } }, "minimum_commitment": { "allOf": [ { "$ref": "#/components/schemas/MinimumCommitment" } ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } }, "MinimumCommitmentRequest": { "type": "object", "description": "Minimum commitment for this plan.", "required": [ "amount" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name.", "example": "Minimum Commitment (C1)" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" } } }, "PlanRequest": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "billing_cycle": { "$ref": "#/components/schemas/BillingCycle" }, "description": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "trial_period": { "type": "integer" }, "pay_in_advance": { "type": "boolean" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "minimum_commitment": { "allOf": [ { "$ref": "#/components/schemas/MinimumCommitmentRequest" } ] } } }, "UsageBasedChargeCreateRequest": { "type": "object", "required": [ "metric_id" ], "properties": { "metric_id": { "type": "string", "description": "Unique identifier of the metric" }, "charge_model": { "$ref": "#/components/schemas/ChargeModel", "description": "Defines the pricing model to calculate the charge" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } }, "PlanCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanRequest" }, { "type": "object", "properties": { "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedChargeCreateRequest" } } } } ] }, "UsageBasedChargeUpdateRequest": { "type": "object", "required": [ "id", "metric_id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the charge", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "metric_id": { "type": "string", "description": "Unique identifier of the metric" }, "charge_model": { "$ref": "#/components/schemas/ChargeModel", "description": "Defines the pricing model to calculate the charge" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } }, "PlanUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanRequest" }, { "type": "object", "properties": { "cascading_updates": { "description": "Determines if changes made to the parent plan should be cascaded to the overridden plans in subscription", "type": "boolean", "example": true }, "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedChargeUpdateRequest" } } } } ] }, "PlanUpdateResponse": { "allOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "object", "properties": { "cascading_updates": { "description": "Determines if changes made to the parent plan should be cascaded to the children plans", "type": "boolean", "example": true }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } } ] }, "CustomerCreateRequest": { "title": "CustomerCreateRequest", "description": "Request body for creating a new customer.A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.", "type": "object", "required": [ "name", "email", "external_id" ], "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "ext_cust_12345" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "billing_entity_code": { "$ref": "#/components/schemas/BillingEntityCode" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "CustomerUpdateRequest": { "title": "CustomerUpdateRequest", "description": "Request body for updating an existing customer. All fields are optional except external_id, which is required as the external unique identifier .", "type": "object", "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "billing_entity_code": { "$ref": "#/components/schemas/BillingEntityCode" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "DateYearMonth": { "description": "The year and month, represented as a string in ISO 8601 'YYYY-MM' format (e.g., '2025-08'). For details, refer to RFC 3339 section 5.6 (Internet Date/Time Format).", "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "example": "2025-08" }, "OverdueBalance": { "type": "object", "description": "Represents the overdue balance data for a customer for a given month.", "properties": { "month": { "description": "The reference month for the overdue balance, formatted as an ISO 8601 year-month string ('yyyy-MM'), representing the first day of the month in UTC.", "allOf": [ { "$ref": "#/components/schemas/DateYearMonth" } ], "example": "2023-11" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total overdue balance amount for the specified customer during the reference month.", "example": { "value": 55, "currency_code": "USD" } } ] }, "invoice_ids": { "type": "array", "items": { "type": "string" }, "description": "An array of invoice IDs associated with the overdue balance for the reference month.", "example": [ "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" ] } } }, "OverdueBalances": { "type": "object", "description": "Represents a collection of monthly overdue balance records for a specific customer.", "properties": { "overdue_balances": { "type": "array", "description": "An array of monthly overdue balance entries for the specified customer.", "items": { "$ref": "#/components/schemas/OverdueBalance" } } } }, "GrossRevenue": { "type": "object", "description": "Represents the gross revenue data for a customer for a given month.", "properties": { "month": { "allOf": [ { "$ref": "#/components/schemas/DateYearMonth" }, { "description": "The reference month for the gross revenue, formatted as an ISO 8601 year-month string ('yyyy-MM'), representing the first day of the month in UTC.", "example": "2023-11" } ] }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total gross revenue amount for the specified customer during the reference month." } ] }, "invoices_count": { "type": "integer", "description": "The number of invoices included in the gross revenue calculation for the reference month.", "example": 10 } } }, "GrossRevenues": { "type": "object", "description": "Represents a collection of monthly gross revenue records for a specific customer.", "properties": { "gross_revenues": { "type": "array", "description": "An array of monthly gross revenue entries for the specified customer.", "items": { "$ref": "#/components/schemas/GrossRevenue" } } } }, "SubscriptionExternalId": { "type": "string", "description": "The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "SUB_1752779018503" }, "CustomerUsageMetric": { "title": "CustomerUsageMetric", "description": "Represents a metric used for customer usage. It includes the name, code, and aggregation type of the metric.", "type": "object", "required": [ "name", "code", "aggregation_type" ], "properties": { "name": { "type": "string", "description": "Name of the metric used for this charge." }, "code": { "type": "string", "description": "Unique code identifying the metric used for this charge." }, "aggregation_type": { "$ref": "#/components/schemas/MetricAggregationType" } } }, "CustomerChargeUsage": { "type": "object", "required": [ "units", "events_count", "amount", "charge", "metric" ], "properties": { "units": { "type": "string", "pattern": "^[0-9]+.?[0-9]*$", "example": "1.0", "description": "The number of units utilized for a specific charge item." }, "events_count": { "type": "integer", "example": 10, "description": "The total count of usage events that have been recorded for a particular charge during the specified time period." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "charge": { "allOf": [ { "$ref": "#/components/schemas/UsageBasedCharge" } ] }, "metric": { "allOf": [ { "$ref": "#/components/schemas/CustomerUsageMetric" } ] } } }, "CustomerUsage": { "type": "object", "required": [ "from_datetime", "to_datetime", "issuing_date", "total_amount", "taxes_amount", "charges_usage" ], "properties": { "from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Starting date of billing period, in the ISO 8601 datetime format in Universal Time (UTC).", "example": "2022-07-01T00:00:00Z" } ] }, "to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Ending date of the billing period, in the ISO 8601 datetime format in Universal Time (UTC).", "example": "2022-07-31T23:59:59Z" } ] }, "issuing_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "The date of creation of the invoice.", "example": "2022-08-01" }, "invoice_id": { "type": "string", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90", "description": "Unique invoice Id." }, "total_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ], "description": "The total amount for the current usage period, including all charges and taxes.", "example": { "value": 55, "currency_code": "USD" } }, "taxes_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ], "description": "The total amount of taxes applied to the current usage period.", "example": { "value": 5, "currency_code": "USD" } }, "charges_usage": { "type": "array", "description": "Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.", "items": { "$ref": "#/components/schemas/CustomerChargeUsage" } } } }, "CustomerPastUsage": { "type": "object", "required": [ "usage_periods", "meta" ], "properties": { "usage_periods": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerUsage" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "CustomerPortalEmbeddableUrlResponse": { "type": "object", "properties": { "url": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" } } }, "SubscriptionBase": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the subscription.", "example": "Subscription_1" }, "start_date": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format", "example": "2025-06-01T00:00:00Z" } ] }, "end_date": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format", "example": "2028-01-01T00:00:00Z" } ] } } }, "BillingTime": { "type": "string", "description": "The billing time for the subscription, which can be set as either anniversary or calendar", "enum": [ "CALENDAR", "ANNIVERSARY" ], "x-enum-varnames": [ "CALENDAR", "ANNIVERSARY" ], "x-enum-descriptions": [ "Calendar billing time - billing cycle at the first day of the week/month/year (billed with proration)", "Anniversary billing time - billing cycle based on the specific date the subscription started (billed fully)" ], "default": "CALENDAR", "example": "CALENDAR" }, "SubscriptionExtendedBase": { "required": [ "external_customer_id", "external_id", "plan_code" ], "allOf": [ { "$ref": "#/components/schemas/SubscriptionBase" }, { "type": "object", "properties": { "external_customer_id": { "type": "string", "description": "External reference to the customer", "pattern": "^[a-zA-Z0-9_-]*$", "example": "client-jkl101" }, "external_id": { "$ref": "#/components/schemas/SubscriptionExternalId" }, "plan_code": { "type": "string", "description": "The plan code", "example": "Plan-Code-1753840215" }, "billing_time": { "$ref": "#/components/schemas/BillingTime" } } } ] }, "SubscriptionStatus": { "type": "string", "description": "The status of the subscription", "enum": [ "PENDING", "ACTIVE", "TERMINATED", "CANCELED" ], "x-enum-varnames": [ "PENDING", "ACTIVE", "TERMINATED", "CANCELED" ], "x-enum-descriptions": [ "A previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period", "The subscription is currently active and applied to the customer", "The subscription is no longer active", "The subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer or when a subscription with a pending status is terminated" ], "example": "ACTIVE" }, "PlanOverridesBase": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "description": { "type": "string", "description": "The description on the plan", "example": "Plan for early stage startups" }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will appear on the invoice", "example": "Startup plan" }, "name": { "type": "string", "description": "The name of the plan", "example": "Startup" } } }, "ChargeUsageThresholdBase": { "type": "object", "properties": { "id": { "type": "string", "description": "Refers to the charge usage threshold unique identifier", "example": "545-1a90-1a90-1a90-1a90-1a901a901a90" }, "recurring": { "type": "string", "description": "Indicates if recurring invoices will be created", "example": "true" }, "threshold_display_name": { "type": "string", "description": "Indicates the name for the usage threshold", "example": "Startup" }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone" }, "updated_at": { "$ref": "#/components/schemas/DateTimeWithZone" } } }, "ChargeUsageThresholdResponse": { "allOf": [ { "$ref": "#/components/schemas/ChargeUsageThresholdBase" }, { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Amount" } } } ] }, "PlanOverridesResponse": { "allOf": [ { "$ref": "#/components/schemas/PlanOverridesBase" }, { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedCharge" } }, "minimum_commitment": { "$ref": "#/components/schemas/MinimumCommitment" }, "chargeUsage": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeUsageThresholdResponse" } }, "taxes": { "type": "array", "description": "List of tax entities configured for the plan.", "items": { "$ref": "#/components/schemas/TaxResponse" } }, "trial_period": { "type": "integer", "description": "The number of days the plan's base cost is provided at no charge", "example": 5 } } } ] }, "SubscriptionResponse": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionExtendedBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription", "example": "b71befc2-4799-402c-9d13-ca1f72759c64" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesResponse" }, "canceled_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date at which a pending subscription is canceled.", "example": "2025-01-01T00:00:00Z" } ] }, "terminated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date at which an active subscription is canceled.", "example": "2025-01-01T00:00:00Z" } ] }, "current_period_start": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Start date of the current billing period", "example": "2025-05-01T00:00:00Z" } ] }, "current_period_end": { "description": "End date of the current billing period", "example": "2025-06-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "trial_ended_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date when the free trial is ended, represented in ISO 8601 date format", "example": "2025-05-01T00:00:00Z" } ] } } } ] }, "SubscriptionUsageBasedCharge": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the charge", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" } } }, "ChargeUsageThresholdRequest": { "allOf": [ { "$ref": "#/components/schemas/ChargeUsageThresholdBase" }, { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/AmountNoCurrency" } } } ] }, "PlanOverridesRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanOverridesBase" }, { "type": "object", "properties": { "charges": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionUsageBasedCharge" }, { "type": "object", "properties": { "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } } ] } }, "minimum_commitment": { "$ref": "#/components/schemas/MinimumCommitmentRequest" }, "chargeUsage": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeUsageThresholdRequest" } }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "trial_period": { "type": "integer", "description": "The number of days the plan's base cost is provided at no charge", "example": 5 } } } ] }, "SubscriptionCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionExtendedBase" }, { "type": "object", "properties": { "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesRequest" } } } ] }, "PlanOverridesUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanOverridesBase" }, { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionUsageBasedCharge" } }, "minimum_commitment": { "$ref": "#/components/schemas/MinimumCommitmentRequest" }, "tax_codes": { "$ref": "#/components/schemas/TaxCodes" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } } ] }, "SubscriptionUpdateRequest": { "type": "object", "description": "Update request for a subscription.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionBase" }, { "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionStatus" }, { "description": "If the status field is not defined and multiple active and pending subscriptions exists, we will update the active subscription. However, if you wish to update a pending subscription, please ensure that you include the status attribute with the pending value in your request body." } ] }, "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesUpdateRequest" } } } ] }, "UsageThreshold": { "type": "object", "description": "Represents a usage threshold milestone for a subscription.", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The usage threshold amount" } ] }, "completion_ratio": { "type": "number", "format": "double", "description": "The ratio (between 0 and 1) representing the proportion of the threshold amount that has been used.", "example": 0.5 }, "reached_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date and time (in ISO 8601 format with timezone) when this usage threshold was reached.", "example": "2024-01-01T00:00:00Z" } ] } } }, "LifetimeUsage": { "type": "object", "description": "Represents the lifetime usage metrics for a given subscription.", "properties": { "external_subscription_id": { "type": "string", "description": "Unique external identifier of the subscription.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "external_historical_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total historical usage amount for this subscription, representing usage accumulated prior to the start of invoiced and current usage tracking." } ] }, "invoiced_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total usage amount, that has been invoiced for this subscription, provided by your own application." } ] }, "current_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total usage amount, accumulated for the subscription during the current billing period" } ] }, "from": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The start date and time (with timezone) of the tracked lifetime usage for the subscription." } ] }, "to": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The end date and time (with timezone) of the tracked lifetime usage for the subscription." } ] }, "usage_thresholds": { "type": "array", "description": "An array of usage thresholds configured in the subscription's plan.", "items": { "$ref": "#/components/schemas/UsageThreshold" } } } }, "CancelOption": { "type": "string", "description": "Option specifying how the subscription should be canceled", "enum": [ "IMMEDIATE", "END_OF_PERIOD" ], "x-enum-varnames": [ "IMMEDIATE", "END_OF_PERIOD" ], "x-enum-descriptions": [ "Cancel the subscription immediately", "Cancel the subscription at the end of the current billing period" ], "default": "IMMEDIATE", "example": "IMMEDIATE" }, "SubscriptionCancel": { "type": "object", "description": "Cancel request for a subscription.", "properties": { "cancel_option": { "$ref": "#/components/schemas/CancelOption" } } }, "EventBase": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for the transaction associated with the event", "example": "txn_1234567890abcdef" }, "external_subscription_id": { "type": "string", "description": "External subscription ID associated with the event", "example": "sub_1234567890abcdef" }, "metric_code": { "type": "string", "description": "Identifier for the targeted metric. This value must match the `code` property of an active metric; otherwise, it will be disregarded during processing.", "example": "event_code_123456" }, "timestamp": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the event occurred", "example": "2023-01-01T00:00:00Z" }, "properties": { "type": "object" } }, "required": [ "transaction_id", "metric_code", "external_subscription_id" ] }, "EventResponse": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event", "example": "evt_1234567890abcdef" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the event was created", "example": "2023-01-01T00:00:00Z" } } } ] }, "EventRequest": { "allOf": [ { "$ref": "#/components/schemas/EventBase" } ] }, "EventStatus": { "type": "string", "enum": [ "ACCEPTED" ], "description": "Status indicating that the event has been accepted for processing", "example": "ACCEPTED" }, "EventAccepted": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/EventStatus" } } }, "EventsAcceptedWithResults": { "allOf": [ { "$ref": "#/components/schemas/EventAccepted" }, { "type": "object", "properties": { "results": { "type": "object", "description": "Results of the accepted events", "properties": { "success_count": { "type": "integer", "description": "Number of events successfully processed", "example": 100 }, "error_count": { "type": "integer", "description": "Number of events that failed processing", "example": 5 }, "errors": { "type": "array", "description": "Details about failed events", "items": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Transaction ID of the failed event" }, "error_code": { "type": "string", "description": "Error code" }, "error_message": { "type": "string", "description": "Detailed error message" } } }, "example": [ { "transaction_id": "txn_1234567890abcdef", "error_code": "invalid_data", "error_message": "The event data is invalid" } ] } } } } } ] }, "WalletStatus": { "type": "string", "description": "Current status of the wallet", "enum": [ "ACTIVE", "TERMINATED", "PENDING" ], "x-enum-varnames": [ "ACTIVE", "TERMINATED", "PENDING" ], "x-enum-descriptions": [ "The wallet is active and can be used for transactions", "The wallet has been terminated and cannot be used", "The wallet is pending activation or processing" ], "example": "ACTIVE" }, "FeeType": { "type": "string", "description": "Types of fees that wallet prepaid credits can be applied to", "enum": [ "SUBSCRIPTION", "COMMITMENT", "CHARGE" ], "x-enum-varnames": [ "SUBSCRIPTION", "COMMITMENT", "CHARGE" ], "x-enum-descriptions": [ "Wallet prepaid credits used only for subscription payments", "Wallet prepaid credits used only for commitment payments", "Wallet prepaid credits used only for charge payments" ], "example": "SUBSCRIPTION" }, "PrepaidCreditAppliesTo": { "type": "object", "description": "Indicates whether the prepaid credit applies to the entire invoice or only to specific line items.", "properties": { "fee_types": { "type": "array", "items": { "$ref": "#/components/schemas/FeeType" }, "example": [ "SUBSCRIPTION" ] } } }, "RecurringTransactionTrigger": { "type": "string", "description": "Condition that triggers the recurring transaction rule", "enum": [ "INTERVAL", "THRESHOLD" ], "x-enum-varnames": [ "INTERVAL", "THRESHOLD" ], "x-enum-descriptions": [ "Recurring transaction rule triggered at a specific interval", "Recurring transaction rule triggered when a threshold is reached" ], "example": "THRESHOLD" }, "RecurringTransactionMethod": { "type": "string", "description": "Method for recurring transaction execution", "enum": [ "FIXED", "TARGET" ], "x-enum-varnames": [ "FIXED", "TARGET" ], "x-enum-descriptions": [ "Recurring transaction rule with fixed credits", "Recurring transaction rule with target ongoing balance" ], "example": "FIXED" }, "RecurringTransactionRule": { "type": "object", "description": "Defines a recurring wallet transaction rule that triggers based on specific conditions.", "required": [ "method", "trigger" ], "properties": { "trigger": { "$ref": "#/components/schemas/RecurringTransactionTrigger" }, "paid_credits": { "type": "string", "description": "Number of paid credits to be added when the rule is triggered. Must be a positive value", "example": "20.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "granted_credits": { "type": "string", "description": "Number of granted credits to be added when the rule is triggered. Must be a positive value", "example": "10.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "method": { "$ref": "#/components/schemas/RecurringTransactionMethod" }, "interval": { "$ref": "#/components/schemas/BillingCycle" }, "started_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Start date of the recurring wallet transaction rule", "example": "2025-01-01T00:00:00Z" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Expiration date of the recurring wallet transaction rule", "example": "2025-01-01T00:00:00Z" }, "threshold_credits": { "type": "string", "description": "Threshold of credits that triggers the recurring transaction rule.", "example": "5.0" }, "target_ongoing_balance": { "type": "string", "description": "Target ongoing balance that triggers the recurring transaction rule.", "example": "200.0" } } }, "Wallet": { "type": "object", "required": [ "external_customer_id", "rate_amount", "status" ], "properties": { "external_customer_id": { "type": "string", "description": "External system reference to the customer", "example": "client-12345" }, "status": { "$ref": "#/components/schemas/WalletStatus" }, "available_balance": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "ongoing_usage": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The ongoing usage of the wallet, and it reflects all current usage and draft invoices including taxes.", "example": { "value": 100, "currency_code": "USD" } } ] }, "net_balance": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "This represents the real-time balance after accounting for current usage,.", "example": { "value": 50, "currency_code": "USD" } } ] }, "name": { "type": "string", "description": "Human-readable wallet name", "example": "Prepaid Wallet" }, "rate_amount": { "type": "string", "description": "Price charged per credit unit", "example": "1.5" }, "available_credits": { "type": "string", "description": "Current credit balance available", "example": "28.0" }, "ongoing_usage_credits": { "type": "string", "description": "This reflects all current usage and draft invoices.", "example": "10.0" }, "net_balance_credits": { "type": "string", "description": "This represents the real time balance after accounting for current usage.", "example": "18.0" }, "consumed_credits": { "type": "string", "description": "Total credits consumed so far", "example": "2.0" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Date and time when the wallet was created, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2025-01-01T00:00:00Z" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Date and time when the wallet is set to expire, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2025-01-01T00:00:00Z" }, "terminated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Date and time when the wallet was terminated, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletId": { "type": "string", "description": "Unique identifier for the wallet", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "WalletWithId": { "allOf": [ { "$ref": "#/components/schemas/Wallet" }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WalletId", "description": "Unique identifier for the wallet", "example": "sub_01H3YT8P7Q5R3S1T2U0V4W9X8" } } } ] }, "WalletCreate": { "type": "object", "required": [ "external_customer_id", "currency", "rate_amount" ], "properties": { "external_customer_id": { "type": "string", "description": "External reference to the customer", "example": "client-xyz456" }, "currency": { "allOf": [ { "$ref": "#/components/schemas/Currency" } ], "description": "Currency in which the wallet operates", "example": "USD" }, "name": { "type": "string", "description": "Name of the wallet", "example": "Prepaid Wallet" }, "rate_amount": { "type": "string", "description": "Cost rate per credit unit, must be non zero positive value", "example": "1.5", "pattern": "^(?!0+(?:\\.0+)?$)\\d+(\\.\\d+)?$" }, "paid_credits": { "type": "string", "description": "Number of paid credits to initialize, must be positive value", "example": "10.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "granted_credits": { "type": "string", "description": "Number of granted credits to initialize, must be positive value", "example": "5.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated wallet name", "example": "Updated Wallet Name" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletTransactionPaymentStatus": { "type": "string", "description": "The payment status of the wallet transaction. Possible values are `pending`, `settled` or `failed`.", "enum": [ "PENDING", "SETTLED", "FAILED" ], "x-enum-descriptions": [ "Payment status of Transaction is PENDING.", "Payment status of Transaction is SETTLED.", "Payment status of Transaction is FAILED." ], "example": "SETTLED" }, "WalletTransactionSource": { "type": "string", "enum": [ "MANUAL", "INTERVAL", "THRESHOLD" ], "x-enum-descriptions": [ "Origin of wallet transaction is MANUAL.", "Origin of wallet transaction is INTERVAL.", "Origin of wallet transaction is THRESHOLD." ], "description": "The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`. `threshold`", "example": "MANUAL" }, "WalletTransactionTransactionStatus": { "type": "string", "description": "The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.", "enum": [ "PURCHASED", "GRANTED", "VOIDED", "INVOICED" ], "x-enum-descriptions": [ "Transaction status of Transaction is PURCHASED.", "Transaction status of Transaction is GRANTED.", "Transaction status of Transaction is VOIDED.", "Transaction status of Transaction is INVOICED." ], "example": "PURCHASED" }, "WalletTransactionType": { "type": "string", "description": "The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance).", "enum": [ "INBOUND", "OUTBOUND" ], "x-enum-descriptions": [ "Type of Transaction is INBOUND.", "Type of Transaction is OUTBOUND." ], "example": "INBOUND" }, "StringMap": { "type": "object", "properties": { "key": { "type": "string", "description": "Name of the key", "example": "reason" }, "value": { "type": "string", "description": "Value associated with the key", "example": "balance depleted" } }, "example": { "key": "reason", "value": "balance depleted" } }, "WalletTransaction": { "type": "object", "properties": { "wallet_transaction_id": { "type": "string", "description": "Unique identifier for the wallet transaction", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "wallet_id": { "allOf": [ { "$ref": "#/components/schemas/WalletId" }, { "description": "Unique identifier for the wallet", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" } ] }, "payment_status": { "$ref": "#/components/schemas/WalletTransactionPaymentStatus" }, "source": { "$ref": "#/components/schemas/WalletTransactionSource" }, "transaction_status": { "$ref": "#/components/schemas/WalletTransactionTransactionStatus" }, "transaction_type": { "$ref": "#/components/schemas/WalletTransactionType" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "Transaction amount involved in the specific wallet transaction." } ] }, "credits": { "type": "string", "pattern": "^[0-9]+.?[0-9]*$", "description": "The number of credits used in the wallet transaction.", "example": "100.0" }, "settled_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "failed_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date when the wallet transaction failed, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "metadata": { "type": "array", "description": "List of key-value pair contains the metadata about the wallet transaction.", "items": { "$ref": "#/components/schemas/StringMap" } } } }, "WalletTransactions": { "type": "object", "description": "The get wallet transactions response contains list of wallet transactions for the specified wallet id.", "properties": { "wallet_transactions": { "type": "array", "description": "The list of wallet transactions for the specified wallet id", "items": { "$ref": "#/components/schemas/WalletTransaction" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/PaginationMetadata" }, { "type": "object", "properties": { "next_page": { "type": "integer", "description": "Next page.", "example": 3 }, "prev_page": { "type": "integer", "description": "Previous page.", "example": 1 } } } ] } } }, "WalletTransactionRequest": { "type": "object", "description": "Defines the request object to create a wallet transaction.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of the wallet transaction applied on the wallet. Supported types are TOPUP, VOID.", "enum": [ "TOPUP", "VOID" ], "x-enum-varnames": [ "TOPUP", "VOID" ], "x-enum-description": [ "Add funds to the wallet with the given credits.", "Deduct funds from the wallet with the given value." ], "example": "TOPUP" }, "paid_credits": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of paid credits to be added. Applicable only to TOPUP type of transaction", "example": "20.0" }, "credits_to_void": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of credits and Only for type VOID, this field need to be passed in request.", "example": "20.0" }, "granted_credits": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of granted credits to be added. Applicable only to TOPUP type of transaction", "example": "10.0" }, "metadata": { "type": "array", "description": "List of key-value pair contains the metadata about the wallet transaction.", "items": { "$ref": "#/components/schemas/StringMap" } } } }, "CreditNoteFilterStatus": { "type": "string", "enum": [ "DRAFT", "FINALIZED", "VOIDED" ], "x-enum-varnames": [ "DRAFT", "FINALIZED", "VOIDED" ], "x-enum-descriptions": [ "Credit note is in draft state, not yet finalized.", "Credit note has been finalized and applied.", "Credit note has been voided and is no longer valid." ], "description": "Status values for filtering credit notes", "example": "FINALIZED" }, "CreditNoteStatus": { "type": "string", "description": "The status of the credit portion of the credit note", "enum": [ "AVAILABLE", "CONSUMED", "VOIDED" ], "x-enum-varnames": [ "AVAILABLE", "CONSUMED", "VOIDED" ], "x-enum-descriptions": [ "There's an amount remains available for future usage. The credit can be applied towards future transactions or invoices", "The credit amount has been fully consumed. The remaining amount is 0, indicating that the credit has been utilized in its entirety", "The remaining amount of the credit cannot be used any further. The credit has been voided and is no longer available for application or redemption" ], "example": "AVAILABLE" }, "RefundStatus": { "type": "string", "description": "The status of the refund portion of the credit note", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ], "x-enum-varnames": [ "PENDING", "SUCCEEDED", "FAILED" ], "x-enum-descriptions": [ "The refund is pending execution. The refund request has been initiated but has not been processed or completed yet", "The refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient", "The refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned" ], "example": "PENDING" }, "CreditNoteReason": { "type": "string", "description": "The reason for credit note creation", "enum": [ "DUPLICATED_CHARGE", "PRODUCT_UNSATISFACTORY", "ORDER_CHANGE", "ORDER_CANCELLATION", "FRAUDULENT_CHARGE", "OTHER" ], "x-enum-varnames": [ "DUPLICATED_CHARGE", "PRODUCT_UNSATISFACTORY", "ORDER_CHANGE", "ORDER_CANCELLATION", "FRAUDULENT_CHARGE", "OTHER" ], "x-enum-descriptions": [ "Credit note issued due to duplicate charge on customer account", "Credit note issued because the product or service was unsatisfactory", "Credit note issued due to changes made to the original order", "Credit note issued because the order was cancelled", "Credit note issued due to fraudulent or unauthorized charge", "Credit note issued for other reasons not covered by standard categories" ], "example": "OTHER" }, "CreditNoteItemObject": { "type": "object", "required": [ "id", "amount", "fee" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The credit note's item unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "The credit note's item amount.", "example": { "value": 1, "currency_code": "USD" } }, "fee": { "$ref": "#/components/schemas/FeeObject", "description": "The fee object related to the credit note item." } } }, "CreditNoteAppliedTaxObject": { "allOf": [ { "$ref": "#/components/schemas/BaseAppliedTax" } ], "type": "object", "properties": { "credit_note_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the credit note.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "base_amount": { "$ref": "#/components/schemas/Amount", "example": { "value": 1, "currency_code": "USD" } } } }, "CreditNote": { "type": "object", "required": [ "sequential_id", "billing_entity_code", "number", "invoice_id", "invoice_number", "issuing_date", "reason", "total_amount", "credit_amount", "refund_amount", "balance_amount", "taxes_amount", "taxes_rate", "sub_total_excluding_taxes_amount", "created_at", "updated_at" ], "properties": { "billing_entity_code": { "$ref": "#/components/schemas/BillingEntityCode" }, "sequential_id": { "type": "integer", "description": "The sequential identifier of the credit note, specifically scoped on the associated invoice. It provides a unique numerical identifier for the credit note within the context of the invoice.", "example": 2 }, "number": { "type": "string", "description": "The credit note unique number.", "example": "PP-1234-US" }, "invoice_id": { "type": "string", "format": "uuid", "description": "Unique identifier assigned to the invoice that the credit note belongs to", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "invoice_number": { "type": "string", "description": "The invoice unique number, related to the credit note.", "example": "PP-1234" }, "issuing_date": { "$ref": "#/components/schemas/Date", "description": "The date of creation of the credit note. It follows the ISO 8601 date format and provides the specific date when the credit note was created.", "example": "2022-12-06" }, "credit_status": { "$ref": "#/components/schemas/CreditNoteStatus" }, "refund_status": { "$ref": "#/components/schemas/RefundStatus" }, "reason": { "$ref": "#/components/schemas/CreditNoteReason" }, "description": { "type": "string", "nullable": true, "description": "The description of the credit note.", "example": "Free text" }, "total_amount": { "$ref": "#/components/schemas/Amount", "description": "The total amount of the credit note.", "example": { "value": 1.2, "currency_code": "USD" } }, "taxes_amount": { "$ref": "#/components/schemas/Amount", "description": "The tax amount of the credit note.", "example": { "value": 0.2, "currency_code": "USD" } }, "taxes_rate": { "type": "number", "description": "The tax rate associated with this specific credit note.", "example": 0.2 }, "sub_total_excluding_taxes_amount": { "$ref": "#/components/schemas/Amount", "description": "The subtotal of the credit note excluding any applicable taxes.", "example": { "value": 1, "currency_code": "USD" } }, "balance_amount": { "$ref": "#/components/schemas/Amount", "description": "The remaining credit note amount.", "example": { "value": 1, "currency_code": "USD" } }, "credit_amount": { "$ref": "#/components/schemas/Amount", "description": "The credited amount of the credit note.", "example": { "value": 1, "currency_code": "USD" } }, "refund_amount": { "$ref": "#/components/schemas/Amount", "description": "The refunded amount of the credit note.", "example": { "value": 0, "currency_code": "USD" } }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date when the credit note was created. It is expressed in Coordinated Universal Time (UTC).", "example": "2022-09-14T16:35:31Z" }, "updated_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date when the credit note was last updated. It is expressed in Coordinated Universal Time (UTC).", "example": "2022-09-14T16:35:31Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteItemObject" }, "description": "Array of credit note's items." }, "applied_taxes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteAppliedTaxObject" } } } }, "CreditNoteWithId": { "allOf": [ { "$ref": "#/components/schemas/CreditNote" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "CreditNoteCreateRequest": { "type": "object", "required": [ "invoice_id", "items" ], "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "The invoice unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "reason": { "$ref": "#/components/schemas/CreditNoteReason" }, "description": { "type": "string", "description": "The description of the credit note.", "example": "description" }, "credit_amount": { "$ref": "#/components/schemas/AmountNoCurrency", "nullable": true, "description": "The total amount to be credited on the customer balance.", "example": { "value": 0.1 } }, "refund_amount": { "$ref": "#/components/schemas/AmountNoCurrency", "nullable": true, "description": "The total amount to be refunded to the customer.", "example": { "value": 0.05 } }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "fee_id", "amount" ], "properties": { "fee_id": { "type": "string", "format": "uuid", "description": "The fee unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "amount": { "$ref": "#/components/schemas/AmountNoCurrency", "description": "The amount of the credit note item.", "example": { "value": 0.1 } } } }, "description": "The list of credit note's items.", "example": [ { "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "amount": { "value": 0.1 } }, { "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", "amount": { "value": 0.05 } } ] } } }, "AlertType": { "type": "string", "enum": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "description": "Type of alert", "x-enum-varnames": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-descriptions": [ "Alert based on current usage amount", "Alert based on metric current usage amount", "Alert based on metric current usage units", "Alert based on lifetime usage amount" ], "example": "CURRENT_USAGE_AMOUNT" }, "AlertThreshold": { "type": "object", "required": [ "value" ], "properties": { "code": { "type": "string", "description": "Identifier for this threshold. Used to distinguish between different thresholds.", "example": "warn" }, "value": { "type": "string", "pattern": "^[0-9]+\\.?[0-9]*$", "description": "A value that should trigger this alert. Must be a positive numeric string that can include a decimal point.", "example": "80.0" }, "recurring": { "type": "boolean", "description": "When true, enables retriggering of alerts at specified intervals after the last non-recurring threshold is exceeded. For example, with non-recurring thresholds at 500 and 1000, and a recurring threshold of 200, alerts will fire at 500, 1000, then every 200 thereafter (1200, 1400, etc.). Only one recurring threshold permitted per alert.", "example": false } } }, "Alert": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the alert, assigned by the system upon creation.", "example": "fb2d17b8-c66d-4269-b38e-9d62d37812e3" }, "external_subscription_id": { "type": "string", "description": "External identifier of the subscription that this alert is monitoring.", "example": "sub_external_12345" }, "metric": { "$ref": "#/components/schemas/MetricResponse" }, "type": { "$ref": "#/components/schemas/AlertType" }, "code": { "type": "string", "description": "The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts.", "example": "tokens_usage_alert" }, "name": { "type": "string", "description": "Human-readable display name for the alert. Used for identification in user interfaces.", "example": "Tokens Usage Alert" }, "previous_value": { "type": "number", "description": "The usage value from the last time this alert was evaluated. For monetary alerts, this represents currency amount; for unit alerts, this represents consumed units.", "example": 75.52 }, "last_processed_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when this alert was last evaluated by the system. Null for newly created alerts that haven't been processed yet. The system evaluates alerts at regular intervals (typically every 5 minutes) to check if usage has crossed any configured thresholds.", "example": "2025-05-01T12:00:00Z" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of configured thresholds that trigger this alert. Includes both one-time and recurring thresholds.", "example": [ { "code": "warn", "value": "80", "recurring": false } ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the alert was created.", "example": "2025-04-21T10:00:00Z" } } }, "AlertList": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" }, "description": "List of alerts", "example": [ { "id": "alert_01H3YT8P7Q5R3S1T2U0V4W9X8", "external_subscription_id": "sub_external_12345", "type": "CURRENT_USAGE_AMOUNT", "code": "current_usage_monetary_alert", "name": "Monetary Usage Alert", "previous_value": 1000, "last_processed_at": "2025-05-19T10:04:21Z", "thresholds": [ { "code": "warn", "recurring": false, "value": "99.0" } ], "created_at": "2025-04-20T10:00:00Z" } ] }, "meta": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "AlertInput": { "type": "object", "required": [ "type", "code", "thresholds" ], "properties": { "type": { "$ref": "#/components/schemas/AlertType" }, "code": { "type": "string", "description": "The unique code to identify the alert.", "example": "storage_metric_alert" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert. Required for metric-specific alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).", "example": "storage_metric" }, "name": { "type": "string", "description": "The name of the alert.", "example": "Usage Warning at 80%" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of thresholds that will trigger this alert. At least one threshold is required." } } }, "AlertUpdateInput": { "type": "object", "properties": { "code": { "type": "string", "description": "The unique code to identify the alert.", "example": "api_calls_usage_alerts" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert. Only for alerts based on a metric.", "example": "api_calls" }, "name": { "type": "string", "description": "The name of the alert.", "example": "Usage alerts for API calls" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of thresholds that will trigger this alert. At least one threshold is required." } } }, "FeatureBase": { "type": "object", "description": "Core properties that define a feature - a capability or functionality that can be entitled to customers through plans or subscriptions", "properties": { "code": { "type": "string", "description": "Unique identifier for the feature across your entire system. This code is used when creating entitlements and should represent the feature's function (e.g., 'seats', 'api-access', 'API_STORAGE'). Allows alphanumeric characters, underscores, and hyphens.", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "example": "USER-SEATS" }, "name": { "type": "string", "description": "Customer-facing name of the feature that clearly describes what functionality or capability it provides. This name appears in billing interfaces and customer portals.", "maxLength": 255, "example": "Number of seats" }, "description": { "type": "string", "description": "Detailed explanation of what this feature provides, its limitations, and how it affects the customer's experience.", "maxLength": 600, "example": "Number of users allowed in the account" } } }, "PrivilegeValueType": { "type": "string", "description": "Defines the data type that this privilege accepts when being assigned values in entitlements. 'INTEGER' for numeric limits, 'BOOLEAN' for on/off toggles, 'STRING' for text values, 'SELECT' for predefined options.", "enum": [ "STRING", "BOOLEAN", "INTEGER", "SELECT" ], "default": "STRING", "example": "INTEGER" }, "PrivilegeConfig": { "type": "object", "description": "Additional configuration for privileges that require constraints or options. Currently used for 'select' type privileges to define allowed values.", "properties": { "select_options": { "type": "array", "description": "Defines the allowed values when value_type is 'select'. When creating entitlements, only these predefined options can be assigned. Useful for features like SSO providers, regions, or service tiers.", "items": { "type": "string" }, "example": [ "google", "okta", "azure" ] } } }, "FeaturePrivilegeBase": { "type": "object", "description": "Defines a configurable aspect of a feature that can be assigned different values when entitled to plans or subscriptions", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Unique identifier for the privilege within its parent feature. Used as a key when assigning values to this privilege in entitlements. Allows alphanumeric characters, underscores, and hyphens.", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "example": "MAX-USERS" }, "name": { "type": "string", "description": "Human-friendly display name for the privilege shown in user interfaces. This helps users understand what aspect of the feature is being configured.", "maxLength": 255, "example": "Maximum seats" }, "value_type": { "$ref": "#/components/schemas/PrivilegeValueType" }, "config": { "$ref": "#/components/schemas/PrivilegeConfig" } } }, "FeatureResponse": { "type": "object", "description": "Complete feature object returned by the API, including all properties and server-generated fields like timestamps", "required": [ "code", "created_at" ], "allOf": [ { "$ref": "#/components/schemas/FeatureBase" }, { "type": "object", "properties": { "privileges": { "type": "array", "description": "Privileges associated with this feature. Can be empty", "items": { "$ref": "#/components/schemas/FeaturePrivilegeBase" } }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp indicating when this feature was first created in the system. Used for audit and tracking purposes." } } } ] }, "FeatureRequest": { "type": "object", "description": "Request payload for creating a new feature. Features represent entitleable capabilities that can be assigned to customers through plans.", "required": [ "code" ], "allOf": [ { "$ref": "#/components/schemas/FeatureBase" }, { "type": "object", "properties": { "privileges": { "type": "array", "description": "List of configurable privileges that define what aspects of this feature can be customized when creating entitlements. Each privilege can have different values assigned in different plans or subscriptions. Can be empty if the feature is simply on/off.", "items": { "$ref": "#/components/schemas/FeaturePrivilegeBase" } } } } ] }, "FeatureUpdateRequest": { "type": "object", "description": "Request payload for updating an existing feature. All fields are optional - only provided fields will be updated. Note that the feature code cannot be changed.", "properties": { "name": { "type": "string", "description": "Name of the feature", "maxLength": 255, "example": "Number of seats" }, "description": { "type": "string", "description": "Description of the feature", "maxLength": 600, "example": "Number of users allowed in the account" }, "privileges": { "type": "array", "description": "Updated list of privileges for the feature. This replaces the entire privileges array - to add or remove individual privileges, include the complete desired list.", "items": { "$ref": "#/components/schemas/FeaturePrivilegeBase" } } } }, "EntitlementPrivilegeBase": { "type": "object", "required": [ "code", "value_type" ], "properties": { "code": { "type": "string", "description": "Unique identifier for this specific privilege within the feature. Used as a key when setting privilege values.", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "example": "max" }, "name": { "type": "string", "description": "User-friendly display name for this privilege shown in interfaces. More descriptive than the code and helps users understand what this specific setting controls.", "maxLength": 255, "example": "Maximum" }, "value_type": { "$ref": "#/components/schemas/PrivilegeValueType" }, "config": { "$ref": "#/components/schemas/PrivilegeConfig" } } }, "PlanEntitlementPrivilege": { "type": "object", "required": [ "value" ], "allOf": [ { "$ref": "#/components/schemas/EntitlementPrivilegeBase" }, { "type": "object", "properties": { "value": { "description": "The specific value assigned to this privilege in the plan. The type of value must match the value_type field. For integer types, this represents numeric limits (e.g., 100 users); for boolean types, true/false settings (e.g., enable/disable features); for string or select types, specific configuration options (e.g., 'premium', 'basic').", "example": 100 } } } ] }, "PlanEntitlementResponse": { "type": "object", "required": [ "feature_code", "feature_privileges" ], "properties": { "feature_code": { "type": "string", "description": "Unique code used to identify the feature across the system. This serves as the primary identifier when assigning entitlements to plans and must be unique.", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "example": "USER-SEATS" }, "name": { "type": "string", "description": "Human-readable display name of the feature shown in user interfaces. More descriptive than the code and helps users understand the feature's purpose.", "maxLength": 255, "example": "Number of seats" }, "description": { "type": "string", "description": "Comprehensive explanation of what this feature provides to customers, how it works, and any important usage information. This helps users understand the value and functionality of the feature.", "maxLength": 600, "example": "Number of users of the account" }, "feature_privileges": { "type": "array", "description": "Collection of configurable privilege settings associated with this feature entitlement. Each privilege defines a specific capability, setting, or limit (e.g., maximum users, access level, enabled/disabled status) that can be assigned values in the plan. These privileges determine what capabilities customers receive with this feature.", "items": { "$ref": "#/components/schemas/PlanEntitlementPrivilege" } } } }, "PlanEntitlementListResponse": { "type": "object", "required": [ "entitlements" ], "properties": { "entitlements": { "type": "array", "description": "List of entitlements associated with the plan", "items": { "$ref": "#/components/schemas/PlanEntitlementResponse" } } } }, "EntitlementRequest": { "type": "object", "required": [ "feature_code", "feature_privilege_values" ], "properties": { "feature_code": { "type": "string", "description": "Unique code used to identify the feature across the system. This serves as the primary identifier when assigning entitlements to plans and must be unique.", "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "example": "USER-SEATS" }, "feature_privilege_values": { "type": "object", "description": "Object mapping privilege codes to their assigned values for this entitlement. Each key is a privilege code (e.g., 'max_users', 'api_rate_limit'), and each value is what you want to set for that privilege (e.g., 100, true, 'premium'). The value type must match what's expected for that privilege (integer, boolean, or string/select).", "example": { "rate_limit": 1000, "endpoints": "all" } } } }, "EntitlementPrivilegeOverride": { "type": "object", "required": [ "value", "plan_value", "override_value" ], "allOf": [ { "$ref": "#/components/schemas/EntitlementPrivilegeBase" }, { "type": "object", "properties": { "value": { "description": "The effective value for this privilege that will be applied. This is the final value after considering both plan and override values.", "example": 15 }, "plan_value": { "description": "The default value from the subscription's plan. This value applies when no override is set.", "example": 10 }, "override_value": { "description": "The subscription-specific override value, if one exists. If null, the plan value is being used.", "example": 15 } } } ] }, "SubscriptionEntitlementResponse": { "allOf": [ { "$ref": "#/components/schemas/PlanEntitlementResponse" }, { "type": "object", "properties": { "feature_privileges": { "type": "array", "description": "Collection of privilege settings with both plan values and subscription-specific overrides. Each privilege shows the effective value applied to this subscription, with details about which values come from the plan and which are overridden.", "items": { "$ref": "#/components/schemas/EntitlementPrivilegeOverride" } } } } ] }, "SubscriptionEntitlementListResponse": { "type": "object", "required": [ "entitlements" ], "properties": { "entitlements": { "type": "array", "description": "List of effective entitlements for the subscription, showing both plan values and subscription-specific overrides", "items": { "$ref": "#/components/schemas/SubscriptionEntitlementResponse" } } } }, "Link": { "type": "object", "properties": { "href": { "type": "string", "description": "URL for the action.", "format": "uri", "example": "https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA" }, "rel": { "type": "string", "description": "Relation type of the link.", "example": "self" }, "method": { "type": "string", "description": "HTTP method to use with the URL.", "example": "GET" } }, "required": [ "href", "rel", "method" ] }, "ResourceType": { "type": "string", "description": "Type of resource that triggered the webhook.", "enum": [ "subscription-alert", "wallet", "wallet-transaction", "credit-note", "invoice", "subscription" ], "x-enum-descriptions": [ "Alert related to subscription usage or status", "Wallet resource for all wallet related events", "Wallet transaction resource for all wallet transaction related events", "Credit note resource for all credit note related events", "Invoice resource for all invoice related events", "Subscription resource for all subscription related events" ] }, "EventType": { "type": "string", "description": "Type of event that occurred in webhooks.", "enum": [ "USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED", "USAGE-BILLING.WALLET.CREATED", "USAGE-BILLING.WALLET.UPDATED", "USAGE-BILLING.WALLET.NET-BALANCE-DEPLETED", "USAGE-BILLING.WALLET.TERMINATED", "USAGE-BILLING.WALLET-TRANSACTION.CREATED", "USAGE-BILLING.WALLET-TRANSACTION.UPDATED", "USAGE-BILLING.CREDIT-NOTE.CREATED", "USAGE-BILLING.CREDIT-NOTE.REFUND.FAILED", "USAGE-BILLING.INVOICE.CREATED", "USAGE-BILLING.INVOICE.PAYMENT.OVERDUE", "USAGE-BILLING.INVOICE.PAYMENT.SUCCEEDED", "USAGE-BILLING.INVOICE.PAYMENT.FAILED", "USAGE-BILLING.SUBSCRIPTION.UPDATED", "USAGE-BILLING.SUBSCRIPTION.TERMINATED", "USAGE-BILLING.SUBSCRIPTION.TRIAL.ENDED" ], "x-enum-descriptions": [ "An alert related to a subscription was triggered", "A wallet was created", "A wallet was updated", "The net balance of a wallet was depleted", "A wallet was terminated", "A wallet transaction was created", "A wallet transaction was updated", "A credit note was created", "A credit note refund attempt failed", "An invoice was created", "An invoice payment is overdue", "An invoice payment status was updated", "An invoice payment attempt failed", "A subscription was updated", "A subscription was terminated", "A subscription's trial period ended" ] }, "Envelop": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook event.", "example": "8PT597110X687430LKGECATA" }, "create_time": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Time when the webhook event was created.", "example": "2025-05-27T19:26:01Z" }, "event_version": { "type": "string", "description": "Version of the event schema.", "example": "1.0" }, "summary": { "type": "string", "description": "Brief description of the event.", "example": "A new alert was triggered." }, "resource_version": { "type": "string", "description": "Version of the resource schema.", "example": "1.0" }, "links": { "type": "array", "description": "HATEOAS links for the webhook event.", "items": { "$ref": "#/components/schemas/Link" } }, "resource_type": { "$ref": "#/components/schemas/ResourceType" }, "event_type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "id", "create_time", "resource_type", "event_type" ] }, "AlertTriggerType": { "type": "string", "nullable": true, "enum": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-varnames": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-descriptions": [ "Alert based on current usage amount", "Alert based on metric current usage amount", "Alert based on metric current usage units", "Alert based on lifetime usage amount" ], "description": "Type of alert trigger", "example": "CURRENT_USAGE_AMOUNT" }, "triggered_alert_AlertThreshold": { "type": "object", "properties": { "code": { "type": "string", "description": "Code representing the threshold.", "example": "hard_limit" }, "value": { "type": "string", "description": "Value at which the threshold was triggered.", "example": "1100" }, "recurring": { "type": "boolean", "description": "Indicates whether the threshold is recurring.", "example": false } }, "required": [ "code", "value" ] }, "TriggeredAlertObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the alert.", "example": "ff604dc4-2223-412a-a8f4-8fde7dfd3346" }, "external_subscription_id": { "type": "string", "description": "External identifier of the subscription associated with the alert.", "example": "0705ad6b-c063-421a-87b6-a6c25f98c842" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert.", "example": "storage_usage" }, "type": { "$ref": "#/components/schemas/AlertTriggerType" }, "code": { "type": "string", "description": "The code used to configure the alert.", "example": "storage_threshold_alert" }, "name": { "type": "string", "description": "The name used during the alert configuration.", "example": "Storage Usage Alert" }, "current_value": { "type": "number", "description": "The current usage value that was compared against configured thresholds when the alert was evaluated.", "example": 1200 }, "previous_value": { "type": "number", "description": "The usage value when the alert was evaluated previously.", "example": 900 }, "crossed_thresholds": { "type": "array", "description": "Array of thresholds that were crossed when the alert was triggered. Includes all applicable recurring thresholds.", "items": { "$ref": "#/components/schemas/triggered_alert_AlertThreshold" } }, "triggered_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Time when the alert was triggered.", "example": "2025-05-27T19:25:02Z" } }, "required": [ "id", "external_subscription_id", "code", "type", "current_value", "triggered_at" ] } }, "responses": { "Forbidden": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] } } } }, "InternalServerError": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error has occurred.", "debug_id": "90957fca61718" } } } }, "BadRequest": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "dc99e3955cdd8", "details": [ { "field": "/email", "value": "abc", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "The value of a field does not conform to the expected format." } ] } } } }, "UnprocessableEntity": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90957fca61718", "details": [ { "field": "/email", "value": "sdfwdj@sdfs.com", "location": "body", "issue": "UNSUPPORTED_EMAIL", "description": "The email provided is not supported." } ] } } } }, "NotFound": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflict - The request could not be completed due to a conflict with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90957fca61718", "details": [ { "field": "transaction_id", "issue": "RESOURCE_ALREADY_EXISTS", "description": "The resource identified by `field` already exists." } ] } } } } }, "parameters": { "page": { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer" } }, "per_page": { "name": "per_page", "in": "query", "description": "Number of records per page", "schema": { "type": "integer" } }, "invoice_id": { "name": "invoice_id", "in": "path", "required": true, "description": "The unique identifier of the invoice", "schema": { "type": "string" }, "example": "27986ceb-bb27-461d-82b1-f044646e192d" }, "metric_code": { "name": "metric_code", "in": "path", "required": true, "description": "The code of the metric", "schema": { "type": "string" }, "example": "Metric-Code-123" }, "plan_code": { "name": "plan_code", "in": "path", "required": true, "description": "The code of the plan", "schema": { "type": "string" }, "example": "Plan-Code-1758211957" }, "external_customer_id": { "name": "external_customer_id", "in": "path", "required": true, "description": "The unique external identifier of the customer", "schema": { "type": "string" }, "example": "9c402857-a71e-4ea2-bcf9-57d3a41bc6ba" }, "external_subscription_id": { "name": "external_subscription_id", "in": "path", "required": true, "description": "The unique external identifier of the subscription", "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, "wallet_id": { "in": "path", "name": "wallet_id", "required": true, "description": " Wallet ID", "schema": { "type": "string" }, "example": "8ef02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, "wallet_transaction_id": { "in": "path", "name": "wallet_transaction_id", "required": true, "description": " Wallet Transaction ID", "schema": { "type": "string" } }, "paypal-transmission-id": { "name": "paypal-transmission-id", "in": "header", "description": "The unique ID of the transmission, from the paypal-transmission-id HTTP header.", "schema": { "type": "string" } }, "paypal-transmission-time": { "name": "paypal-transmission-time", "in": "header", "description": "The date and time when the message was transmitted, from the paypal-transmission-time HTTP header.", "schema": { "type": "string" } } } } }