openapi: 3.2.0 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 description: PayPal API Sandbox 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" examples: default: value: - 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" examples: default: value: 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 examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: default: value: 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 examples: default: value: 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" examples: default: value: 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 examples: default: value: 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 examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: - ext_cus_1234567890abcdef description: Filter by external customer ID - in: query name: plan_code schema: type: string examples: - 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" examples: default: value: 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 examples: - 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" examples: default: value: 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 examples: - f772b19c-c5c2-426d-8871-346a6cd094c5 content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" examples: default: value: 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" examples: default: value: 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 examples: - sub_1234567890abcdef description: Filter events by external subscription ID - in: query name: metric_code schema: type: string examples: - metric_123456ef description: Filter events by metric code - in: query name: from_date schema: type: string format: date-time examples: - 2023-01-01T00:00:00Z description: Start date for filtering events - in: query name: to_date schema: type: string format: date-time examples: - 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: - 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: - 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" examples: default: value: 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 examples: - 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" examples: default: value: 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" examples: default: value: 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 examples: - 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 examples: - 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" examples: default: value: 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 examples: - 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 examples: - 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" examples: default: value: 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" examples: default: value: 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 examples: - 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 examples: - 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: examples: default: value: 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" examples: default: value: 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" examples: default: 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 "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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: default: value: 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" examples: default: value: 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 examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: default: value: 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" examples: default: value: 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" 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: /api/oauth-proxy scopes: read: Read access write: Write access schemas: Currency: type: string description: Currency code in ISO 4217 format. minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ examples: - USD 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. examples: - 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. examples: - Apt 4B city: type: string nullable: false minLength: 1 maxLength: 512 description: City of the customer or party. examples: - New York state: type: string nullable: false minLength: 1 maxLength: 512 description: State or region of the customer or party. examples: - 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. examples: - "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. examples: - US Timezone: type: string 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 examples: - UTC BillingEntityBase: description: Base schema for billing entity request/response objects type: object required: - name properties: name: type: string description: Name of the billing entity examples: - Acme Inc default_currency: $ref: "#/components/schemas/Currency" finalize_zero_amount_invoice: type: boolean description: Whether to finalize invoices with zero amount examples: - true address: $ref: "#/components/schemas/Address" legal_name: type: - string - "null" description: Legal name of the entity examples: - Acme Corporation Inc. legal_number: type: - string - "null" description: Legal registration number examples: - US123456789 email: type: - string - "null" format: email description: Contact email for the entity examples: - 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_-]*$ examples: - acme_inc DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. examples: - 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 examples: - false id: type: string format: uuid description: The unique identifier for the billing entity examples: - b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c created_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" - description: Creation timestamp examples: - 2023-01-15T00:00:00Z updated_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" - description: Last update timestamp examples: - 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 examples: - 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. examples: - "20.00" description: type: string description: Detailed description of the tax for internal reference examples: - 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_-]*$ examples: - 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 examples: - 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 examples: - 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. examples: - - 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 description: The unique code for merchant to use when sending events. examples: - NDc3Nzc1NTg0NTY0MTgyMzUzNw==.K7iva2SX08+9R52rAIfUwQvruZackQErIDDdEnUxxKE= description: Response object for activating a merchant account for usage based billing. InvoiceStatus: type: - string - "null" 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 examples: - FINALIZED Date: type: string format: date description: Date in ISO 8601 format (YYYY-MM-DD). 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)$ examples: - 2023-10-01 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 examples: - 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). minimum: 0 nullable: false default: 0 examples: - 120.35 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 - "null" format: uuid description: Unique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 total_amount: $ref: "#/components/schemas/Amount" description: The cost of this specific fee, including any applicable taxes. examples: - value: 1.2 currency_code: USD name: type: - string - "null" description: The the name of the fee associated to any one of the charge, the credit, the subscription or the commitment examples: - Basic Plan InvoiceType: type: - string - "null" 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 examples: - SUBSCRIPTION EmailAddress: type: string description: The internationalized email address. minLength: 3 maxLength: 254 pattern: ^.+@[^"\-].+$ examples: - abc@test.com PaymentMethodToken: type: string minLength: 1 maxLength: 36 description: Token representing the customer's saved payment method in PayPal Vault. examples: - 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. examples: - 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 description: The metadata object key maxLength: 20 examples: - Purchase Order value: type: string description: The metadata object value maxLength: 100 examples: - "123456789" display_in_invoice: type: boolean 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. examples: - true 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 examples: - 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_-]*$ examples: - 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. examples: - +1-234-567-8900 payment_method_token: allOf: - $ref: "#/components/schemas/PaymentMethodToken" description: Token representing the customer's saved payment method in PayPal Vault. examples: - 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. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 tax_id: type: string format: uuid description: Unique identifier of the tax. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 tax_name: type: string description: Name of the tax. examples: - TVA tax_code: type: string description: Unique code used to identify the tax associated with the API request. examples: - french_standard_vat tax_rate: type: number description: The percentage rate of the tax examples: - 20 tax_description: type: string description: Internal description of the taxes examples: - French standard VAT amount: $ref: "#/components/schemas/Amount" description: Amount of the tax examples: - 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. examples: - 2022-09-14T16:35:31Z Invoice: type: object properties: id: type: string description: The unique identifier of the invoice examples: - 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. examples: - 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. examples: - 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 examples: - 2023-01-15 issued_date: allOf: - $ref: "#/components/schemas/Date" description: Date when the invoice was issued examples: - 2023-01-01 invoice_number: type: string description: Invoice number, unique within the billing entity. examples: - INV-2023-001 version_number: type: string format: number description: Version number of the invoice, indicating the revision of the invoice. examples: - INV-2023-001 payment_overdue: type: boolean description: Indicates whether the invoice payment is overdue. examples: - 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 examples: - sub_01H3YT8P7Q5R3S1T2U0V4W9X8 external_subscription_id: type: string description: The subscription external unique identifier supplied by client. examples: - ext_id_23fw3 plan_id: description: Unique identifier for the plan type: string examples: - plan_01H3YT8P7Q5R3S1T2U0V4W9X8 payment_method_token: allOf: - $ref: "#/components/schemas/PaymentMethodToken" description: Token representing the customer's payment method examples: - 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' examples: - 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. examples: - 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" examples: - 2023-01-01T00:00:00Z updated_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Timestamp when the invoice was last updated examples: - 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. 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. examples: - METERED MetricAggregationType: type: - string - "null" 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 examples: - 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 examples: - 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 default: STANDARD examples: - GRADUATED UsageBasedCharge: type: object required: - id - metric_id properties: id: type: string description: Unique identifier of the charge examples: - 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. examples: - 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. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 plan_code: type: string description: The unique code representing the plan to be attached to the customer. examples: - premium 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. examples: - 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. examples: - 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. examples: - 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. examples: - 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 examples: - 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 examples: - 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 examples: - 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 examples: - 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_-]*$ examples: - 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. examples: - +1-234-567-8900 payment_method_token: allOf: - $ref: "#/components/schemas/PaymentMethodToken" description: Token representing the customer's saved payment method in PayPal Vault. examples: - 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 examples: - 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. examples: - +1-234-567-8900 payment_method_token: allOf: - $ref: "#/components/schemas/PaymentMethodToken" description: Token representing the customer's saved payment method in PayPal Vault. examples: - 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])$ examples: - 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" examples: - 2023-11 amount: allOf: - $ref: "#/components/schemas/Amount" - description: The total overdue balance amount for the specified customer during the reference month. examples: - 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. examples: - - 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. examples: - 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. examples: - 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_-]*$ examples: - 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]*$ description: The number of units utilized for a specific charge item. examples: - "1.0" events_count: type: integer description: The total count of usage events that have been recorded for a particular charge during the specified time period. examples: - 10 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). examples: - 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). examples: - 2022-07-31T23:59:59Z issuing_date: allOf: - $ref: "#/components/schemas/Date" description: The date of creation of the invoice. examples: - 2022-08-01 invoice_id: type: string description: Unique invoice Id. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 total_amount: allOf: - $ref: "#/components/schemas/Amount" description: The total amount for the current usage period, including all charges and taxes. examples: - value: 55 currency_code: USD taxes_amount: allOf: - $ref: "#/components/schemas/Amount" description: The total amount of taxes applied to the current usage period. examples: - 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. examples: - 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 examples: - 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 examples: - 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 examples: - 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_-]*$ examples: - client-jkl101 external_id: $ref: "#/components/schemas/SubscriptionExternalId" plan_code: type: string description: The plan code examples: - 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 examples: - ACTIVE PlanOverridesBase: type: object properties: amount: $ref: "#/components/schemas/Amount" description: type: string description: The description on the plan examples: - Plan for early stage startups invoice_display_name: type: string description: Specifies the name that will appear on the invoice examples: - Startup plan name: type: string description: The name of the plan examples: - Startup ChargeUsageThresholdBase: type: object properties: id: type: string description: Refers to the charge usage threshold unique identifier examples: - 545-1a90-1a90-1a90-1a90-1a901a901a90 recurring: type: string description: Indicates if recurring invoices will be created examples: - "true" threshold_display_name: type: string description: Indicates the name for the usage threshold examples: - 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 examples: - 5 SubscriptionResponse: allOf: - $ref: "#/components/schemas/SubscriptionExtendedBase" - type: object properties: id: type: string description: Unique identifier for the subscription examples: - 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. examples: - 2025-01-01T00:00:00Z terminated_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" - description: The date at which an active subscription is canceled. examples: - 2025-01-01T00:00:00Z current_period_start: allOf: - $ref: "#/components/schemas/DateTimeWithZone" - description: Start date of the current billing period examples: - 2025-05-01T00:00:00Z current_period_end: description: End date of the current billing period allOf: - $ref: "#/components/schemas/DateTimeWithZone" examples: - 2025-06-01T00:00:00Z trial_ended_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" - description: The date when the free trial is ended, represented in ISO 8601 date format examples: - 2025-05-01T00:00:00Z SubscriptionUsageBasedCharge: type: object required: - id properties: id: type: string description: Unique identifier of the charge examples: - 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 examples: - 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. examples: - 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. examples: - 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. examples: - 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 examples: - 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 examples: - txn_1234567890abcdef external_subscription_id: type: string description: External subscription ID associated with the event examples: - 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. examples: - event_code_123456 timestamp: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Timestamp when the event occurred examples: - 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 examples: - evt_1234567890abcdef created_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Timestamp when the event was created examples: - 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 examples: - 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 examples: - 100 error_count: type: integer description: Number of events that failed processing examples: - 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 examples: - - 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 examples: - 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 examples: - 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" examples: - - 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 examples: - 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 examples: - 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 pattern: ^(0|[1-9]\d*)(\.\d+)?$ examples: - "20.0" granted_credits: type: string description: Number of granted credits to be added when the rule is triggered. Must be a positive value pattern: ^(0|[1-9]\d*)(\.\d+)?$ examples: - "10.0" 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 examples: - 2025-01-01T00:00:00Z expiration_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Expiration date of the recurring wallet transaction rule examples: - 2025-01-01T00:00:00Z threshold_credits: type: string description: Threshold of credits that triggers the recurring transaction rule. examples: - "5.0" target_ongoing_balance: type: string description: Target ongoing balance that triggers the recurring transaction rule. examples: - "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 examples: - 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. examples: - value: 100 currency_code: USD net_balance: allOf: - $ref: "#/components/schemas/Amount" - description: This represents the real-time balance after accounting for current usage,. examples: - value: 50 currency_code: USD name: type: string description: Human-readable wallet name examples: - Prepaid Wallet rate_amount: type: string description: Price charged per credit unit examples: - "1.5" available_credits: type: string description: Current credit balance available examples: - "28.0" ongoing_usage_credits: type: string description: This reflects all current usage and draft invoices. examples: - "10.0" net_balance_credits: type: string description: This represents the real time balance after accounting for current usage. examples: - "18.0" consumed_credits: type: string description: Total credits consumed so far examples: - "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). examples: - 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). examples: - 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). examples: - 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 examples: - 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 examples: - sub_01H3YT8P7Q5R3S1T2U0V4W9X8 WalletCreate: type: object required: - external_customer_id - currency - rate_amount properties: external_customer_id: type: string description: External reference to the customer examples: - client-xyz456 currency: allOf: - $ref: "#/components/schemas/Currency" description: Currency in which the wallet operates examples: - USD name: type: string description: Name of the wallet examples: - Prepaid Wallet rate_amount: type: string description: Cost rate per credit unit, must be non zero positive value pattern: ^(?!0+(?:\.0+)?$)\d+(\.\d+)?$ examples: - "1.5" paid_credits: type: string description: Number of paid credits to initialize, must be positive value pattern: ^(0|[1-9]\d*)(\.\d+)?$ examples: - "10.0" granted_credits: type: string description: Number of granted credits to initialize, must be positive value pattern: ^(0|[1-9]\d*)(\.\d+)?$ examples: - "5.0" expiration_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Cancelled date of the subscription examples: - 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 examples: - Updated Wallet Name expiration_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Cancelled date of the subscription examples: - 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. examples: - 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` examples: - 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. examples: - 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. examples: - INBOUND StringMap: type: object properties: key: type: string description: Name of the key examples: - reason value: type: string description: Value associated with the key examples: - balance depleted examples: - key: reason value: balance depleted WalletTransaction: type: object properties: wallet_transaction_id: type: string description: Unique identifier for the wallet transaction examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 wallet_id: allOf: - $ref: "#/components/schemas/WalletId" - description: Unique identifier for the wallet examples: - 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. examples: - "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). examples: - 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). examples: - 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). examples: - 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. examples: - 3 prev_page: type: integer description: Previous page. examples: - 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. examples: - TOPUP paid_credits: type: string pattern: ^\d+(\.\d+)?$ description: Number of paid credits to be added. Applicable only to TOPUP type of transaction examples: - "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. examples: - "20.0" granted_credits: type: string pattern: ^\d+(\.\d+)?$ description: Number of granted credits to be added. Applicable only to TOPUP type of transaction examples: - "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 examples: - 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 examples: - 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 examples: - 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 examples: - OTHER CreditNoteItemObject: type: object required: - id - amount - fee properties: id: type: string format: uuid description: The credit note's item unique identifier. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 amount: $ref: "#/components/schemas/Amount" description: The credit note's item amount. examples: - 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. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 base_amount: $ref: "#/components/schemas/Amount" examples: - 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. examples: - 2 number: type: string description: The credit note unique number. examples: - PP-1234-US invoice_id: type: string format: uuid description: Unique identifier assigned to the invoice that the credit note belongs to examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 invoice_number: type: string description: The invoice unique number, related to the credit note. examples: - 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. examples: - 2022-12-06 credit_status: $ref: "#/components/schemas/CreditNoteStatus" refund_status: $ref: "#/components/schemas/RefundStatus" reason: $ref: "#/components/schemas/CreditNoteReason" description: type: - string - "null" description: The description of the credit note. examples: - Free text total_amount: $ref: "#/components/schemas/Amount" description: The total amount of the credit note. examples: - value: 1.2 currency_code: USD taxes_amount: $ref: "#/components/schemas/Amount" description: The tax amount of the credit note. examples: - value: 0.2 currency_code: USD taxes_rate: type: number description: The tax rate associated with this specific credit note. examples: - 0.2 sub_total_excluding_taxes_amount: $ref: "#/components/schemas/Amount" description: The subtotal of the credit note excluding any applicable taxes. examples: - value: 1 currency_code: USD balance_amount: $ref: "#/components/schemas/Amount" description: The remaining credit note amount. examples: - value: 1 currency_code: USD credit_amount: $ref: "#/components/schemas/Amount" description: The credited amount of the credit note. examples: - value: 1 currency_code: USD refund_amount: $ref: "#/components/schemas/Amount" description: The refunded amount of the credit note. examples: - 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). examples: - 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). examples: - 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. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 reason: $ref: "#/components/schemas/CreditNoteReason" description: type: string description: The description of the credit note. examples: - description credit_amount: description: The total amount to be credited on the customer balance. example: value: 0.1 anyOf: - $ref: "#/components/schemas/AmountNoCurrency" - type: "null" refund_amount: description: The total amount to be refunded to the customer. example: value: 0.05 anyOf: - $ref: "#/components/schemas/AmountNoCurrency" - type: "null" items: type: array minItems: 1 items: type: object required: - fee_id - amount properties: fee_id: type: string format: uuid description: The fee unique identifier. examples: - 1a901a90-1a90-1a90-1a90-1a901a901a90 amount: $ref: "#/components/schemas/AmountNoCurrency" description: The amount of the credit note item. examples: - value: 0.1 description: The list of credit note's items. examples: - - 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 examples: - CURRENT_USAGE_AMOUNT AlertThreshold: type: object required: - value properties: code: type: string description: Identifier for this threshold. Used to distinguish between different thresholds. examples: - 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. examples: - "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. examples: - false Alert: type: object properties: id: type: string description: Unique identifier for the alert, assigned by the system upon creation. examples: - fb2d17b8-c66d-4269-b38e-9d62d37812e3 external_subscription_id: type: string description: External identifier of the subscription that this alert is monitoring. examples: - 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. examples: - tokens_usage_alert name: type: string description: Human-readable display name for the alert. Used for identification in user interfaces. examples: - 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. examples: - 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. examples: - 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. examples: - - code: warn value: "80" recurring: false created_at: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: The date and time when the alert was created. examples: - 2025-04-21T10:00:00Z AlertList: type: object properties: alerts: type: array items: $ref: "#/components/schemas/Alert" description: List of alerts examples: - - 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. examples: - 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). examples: - storage_metric name: type: string description: The name of the alert. examples: - 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. examples: - 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. examples: - api_calls name: type: string description: The name of the alert. examples: - 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_-]+$ examples: - 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 examples: - 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 examples: - 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 examples: - 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 examples: - - 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_-]+$ examples: - 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 examples: - 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 examples: - Number of seats description: type: string description: Description of the feature maxLength: 600 examples: - 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_-]+$ examples: - 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 examples: - 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'). examples: - 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_-]+$ examples: - 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 examples: - 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 examples: - 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_-]+$ examples: - 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). examples: - 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. examples: - 15 plan_value: description: The default value from the subscription's plan. This value applies when no override is set. examples: - 10 override_value: description: The subscription-specific override value, if one exists. If null, the plan value is being used. examples: - 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 examples: - https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA rel: type: string description: Relation type of the link. examples: - self method: type: string description: HTTP method to use with the URL. examples: - 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. examples: - 8PT597110X687430LKGECATA create_time: allOf: - $ref: "#/components/schemas/DateTimeWithZone" description: Time when the webhook event was created. examples: - 2025-05-27T19:26:01Z event_version: type: string description: Version of the event schema. examples: - "1.0" summary: type: string description: Brief description of the event. examples: - A new alert was triggered. resource_version: type: string description: Version of the resource schema. examples: - "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 - "null" 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 examples: - CURRENT_USAGE_AMOUNT triggered_alert_AlertThreshold: type: object properties: code: type: string description: Code representing the threshold. examples: - hard_limit value: type: string description: Value at which the threshold was triggered. examples: - "1100" recurring: type: boolean description: Indicates whether the threshold is recurring. examples: - false required: - code - value TriggeredAlertObject: type: object properties: id: type: string description: Unique identifier for the alert. examples: - ff604dc4-2223-412a-a8f4-8fde7dfd3346 external_subscription_id: type: string description: External identifier of the subscription associated with the alert. examples: - 0705ad6b-c063-421a-87b6-a6c25f98c842 metric_code: type: string description: The code of the metric associated with the alert. examples: - storage_usage type: $ref: "#/components/schemas/AlertTriggerType" code: type: string description: The code used to configure the alert. examples: - storage_threshold_alert name: type: string description: The name used during the alert configuration. examples: - Storage Usage Alert current_value: type: number description: The current usage value that was compared against configured thresholds when the alert was evaluated. examples: - 1200 previous_value: type: number description: The usage value when the alert was evaluated previously. examples: - 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. examples: - 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" examples: default: 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. InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: "#/components/schemas/Error" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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" examples: default: value: 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 examples: default: value: 27986ceb-bb27-461d-82b1-f044646e192d metric_code: name: metric_code in: path required: true description: The code of the metric schema: type: string examples: default: value: Metric-Code-123 plan_code: name: plan_code in: path required: true description: The code of the plan schema: type: string examples: default: value: 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 examples: default: value: 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 examples: default: value: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba wallet_id: in: path name: wallet_id required: true description: " Wallet ID" schema: type: string examples: default: value: 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 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.