{ "openapi": "3.0.1", "info": { "title": "Usage Based Billing API", "version": "1.0.0", "description": "An Orchestrator for Usage Based Billing and Payments" }, "servers": [ { "url": "https://api-m.paypal.com/v1/commerce/billing" } ], "security": [ { "BearerAuth": [ "read", "write" ] } ], "tags": [ { "name": "Alerts", "description": "API endpoints for managing subscription alerts" }, { "name": "Events", "description": "API endpoints for managing events" }, { "name": "Metrics", "description": "API endpoints for metrics and usage data" }, { "name": "Merchant Activation", "description": "API endpoint for merchant activation" }, { "name": "Credit Notes", "description": "API endpoints for credit notes management" }, { "name": "Customers", "description": "API endpoints for customer management" }, { "name": "Invoices", "description": "API endpoints for invoice management" }, { "name": "Plans", "description": "API endpoints for subscription plans" }, { "name": "Subscriptions", "description": "API endpoints for subscriptions" }, { "name": "Wallets", "description": "API endpoints for wallet management" } ], "paths": { "/activate": { "post": { "operationId": "ActivateMerchant", "tags": [ "Merchant Activation" ], "summary": "Activate Usage Based Billing", "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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": "payment_status", "in": "query", "description": "Filter invoices by payment status (e.g., pending, failed, succeeded)", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "FAILED", "SUCCEEDED" ], "default": "PENDING", "x-enum-varnames": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-descriptions": [ "The invoice is awaiting payment.", "The payment for the invoice has failed.", "The payment for the invoice was successful." ] } }, { "name": "external_customer_id", "in": "query", "description": "Filter invoices by external customer ID", "required": false, "schema": { "type": "string" } }, { "name": "issuing_date_from", "in": "query", "description": "Filter invoices issued on or after this date (ISO 8601 format)", "required": true, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "issuing_date_to", "in": "query", "description": "Filter invoices issued on or before this date (ISO 8601 format)", "required": true, "schema": { "$ref": "#/components/schemas/Date" } } ], "responses": { "200": { "description": "A list of invoices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "invoices": [ { "id": "27986ceb-bb27-461d-82b1-f044646e192d", "sequential_id": 5, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 220.2, "currency_code": "USD" } }, "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-012", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "Test Plan Override Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "country": "US" }, "phone": "+1 (555) 789-1234", "id": "5a31b634-3213-42f5-a184-c68f93e47dc1" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:00Z" }, { "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa", "sequential_id": 3, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 500.11, "currency_code": "USD" } }, "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-003", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "CUST_NLT_1752783445", "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445", "email": "sakdjas@comp.net", "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:02Z" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{id}": { "get": { "operationId": "GetInvoiceById", "tags": [ "Invoices" ], "summary": "Get a single invoice by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "A single invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceWithId" }, "example": { "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa", "sequential_id": 3, "status": "FINALIZED", "payment_status": "PENDING", "amount": { "total_amount": { "value": 500.11, "currency_code": "USD" } }, "fees": [ { "id": "f3c91be7-85ba-4f41-857b-f844749e4f1b", "total_amount": { "value": 500, "currency_code": "USD" } }, { "id": "e58684ef-8e26-4339-a2ba-b243beffc3f1", "total_amount": { "value": 0.11, "currency_code": "USD" } } ], "due_date": "2025-07-28", "issued_date": "2025-07-28", "invoice_number": "PPC-9E32-202507-003", "version_number": "4", "payment_overdue": true, "invoice_type": "SUBSCRIPTION", "customer": { "name": "Test Plan Override Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445", "email": "dsadiaj@bert.com", "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3" }, "created_at": "2025-07-28T00:10:01Z", "updated_at": "2025-07-29T00:25:02Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{id}/retry_payment": { "post": { "operationId": "RetryInvoicePayment", "tags": [ "Invoices" ], "summary": "Retry payment for a specific invoice", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the invoice to retry payment for.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content. The payment retry was successfully triggered." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metrics": { "get": { "operationId": "GetMetrics", "tags": [ "Metrics" ], "summary": "Get all metrics", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "A list of metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResponse" } }, "pagination_metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "metrics": [ { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } ], "pagination_metadata": { "total_count": 1, "total_pages": 10, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateMetric", "tags": [ "Metrics" ], "summary": "Create a new metric", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricRequest" }, "example": { "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ] } } } }, "responses": { "201": { "description": "Metric created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metrics/{id}": { "get": { "operationId": "GetMetricById", "tags": [ "Metrics" ], "summary": "Get a metric by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Metric retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateMetricById", "tags": [ "Metrics" ], "summary": "Update a metric by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricUpdateRequest" }, "example": { "name": "Updated Metric", "description": "This metric has been updated", "code": "updated_metric_code", "type": "METERED", "aggregation_type": "SUM", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1" ] } ] } } } }, "responses": { "200": { "description": "Metric updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricResponse" }, "example": { "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD", "name": "API Requests", "code": "api_requests", "type": "METERED", "description": "Measures the total number of API requests made", "aggregation_type": "COUNT", "field_filters": [ { "key": "region", "values": [ "us-east-1", "us-west-1", "eu-west-1" ] } ], "created_at": "2023-05-10T14:32:18Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteMetricById", "tags": [ "Metrics" ], "summary": "Delete a metric by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "Metric deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans": { "get": { "operationId": "GetPlans", "tags": [ "Plans" ], "summary": "Get all plans", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "A list of plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "plans": [ { "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" } ], "metadata": { "total_count": 29, "total_pages": 29, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreatePlan", "tags": [ "Plans" ], "summary": "Create a new plan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanCreateRequest" } } } }, "responses": { "201": { "description": "Plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "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" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/plans/{id}": { "get": { "operationId": "GetPlanById", "tags": [ "Plans" ], "summary": "Get a plan by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "A plan object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "name": "test-plan", "code": "test-plan", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 1000, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdatePlanById", "tags": [ "Plans" ], "summary": "Update a plan by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdateRequest" } } } }, "responses": { "200": { "description": "A plan object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdateResponse" }, "example": { "status": "200 OK", "headers": { "Content-Type": "application/json" }, "body": { "name": "UBB Plan - Pro", "code": "ubb_plan_1753837176", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 170, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "cascading_updates": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "updated_at": "2025-07-31T08:41:19Z", "id": "95de3538-3827-496b-89a0-120745360830" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeletePlanById", "tags": [ "Plans" ], "summary": "Delete a plan by ID", "description": "Delete a plan by providing the plan ID. This operation permanently removes the plan from the system.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "Plan deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers": { "get": { "operationId": "GetCustomers", "tags": [ "Customers" ], "summary": "Get all customers", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Returns the customer with the specified ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "customers": [ { "id": "f772b19c-c5c2-426d-8871-346a6cd094c5", "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ] }, { "id": "3c25d14a-5fe4-455e-8862-dfb07d384d08", "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753642317", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateCustomer", "tags": [ "Customers" ], "summary": "Create a new customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } } }, "responses": { "201": { "description": "Customer created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ], "id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{id}": { "get": { "operationId": "GetCustomerById", "tags": [ "Customers" ], "summary": "Get a customer by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "TechStart Solutions", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "finance@techstart.io", "address": { "line1": "123 Innovation Way", "line2": "Suite 400", "city": "San Francisco", "state": "CA", "postal_code": "94087", "country": "US" }, "phone": "+1 (555) 789-1234", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ], "id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateCustomerById", "tags": [ "Customers" ], "summary": "Update a customer by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWithId" }, "example": { "name": "Hello Customer", "external_id": "5eb02857-a71e-4ea2-bcf9-1753826282", "email": "customer1@gmail.com", "address": { "line1": "123 First Street", "line2": "Alameda Court", "city": "San Jose", "state": "CA", "postal_code": "94551", "country": "US" }, "phone": "5839458934", "payment_method_token": "6ta69628uw121251c", "payment_method_type": "CARD", "id": "f772b19c-c5c2-426d-8871-346a6cd094c5", "metadata": [ { "key": "Purchase Order", "value": "PO-2023-4521", "display_in_invoice": true }, { "key": "Sales Region", "value": "West Coast", "display_in_invoice": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteCustomerById", "tags": [ "Customers" ], "summary": "Delete a customer by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "Customer deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/analytics/overdue-balance": { "get": { "operationId": "GetCustomerAnalyticsOverdueBalance", "tags": [ "Customers" ], "summary": "Retrieve customer analytics for overdue balance", "parameters": [ { "name": "external_customer_id", "in": "path", "description": "The unique external identifier of the customer used to filter their overdue balance.", "required": true, "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, { "name": "months", "in": "query", "description": "Limits the analytics data to the specified number of most recent months. Defaults to 12 if not provided.", "required": false, "schema": { "type": "integer", "default": 12, "minimum": 1 }, "example": 6 }, { "name": "currency", "in": "query", "description": "Filters the analytics data by the specified currency code (e.g., 'USD').", "required": false, "schema": { "$ref": "#/components/schemas/Currency" }, "example": "USD" } ], "responses": { "200": { "description": "Customer overdue balance analytics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverdueBalances" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{external_customer_id}/analytics/gross-revenue": { "get": { "operationId": "GetCustomerAnalyticsGrossRevenue", "tags": [ "Customers" ], "summary": "Retrieve customer gross revenue analytics", "parameters": [ { "name": "external_customer_id", "in": "path", "description": "The unique external identifier of the customer used to filter their gross revenue.", "required": true, "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, { "name": "months", "in": "query", "description": "Limits the analytics data to the specified number of most recent months. Defaults to 12 if not provided.", "required": false, "schema": { "type": "integer", "default": 12, "minimum": 1 }, "example": 6 }, { "name": "currency", "in": "query", "description": "Filters the analytics data by the specified currency code (e.g., 'USD').", "required": false, "schema": { "$ref": "#/components/schemas/Currency" }, "example": "USD" } ], "responses": { "200": { "description": "Customer gross revenue analytics retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrossRevenues" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{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/id" }, { "in": "query", "name": "subscription_id", "schema": { "$ref": "#/components/schemas/SubscriptionExternalId" }, "required": true, "description": "Filter by subscription ID." } ], "responses": { "200": { "description": "Returns the current usage for the specified customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUsage" }, "example": { "from_datetime": "2024-01-01T00:00:00Z", "to_datetime": "2024-01-31T23:59:59Z", "issuing_date": "2024-01-31", "total_amount": { "currency_code": "USD", "value": 270 }, "taxes_amount": { "currency_code": "USD", "value": 2.75 }, "charges_usage": [ { "units": "150.0", "events_count": 3050, "amount": { "currency_code": "USD", "value": 75 }, "charge": { "id": "1c31a90-1c31-1c31-1c31-1c311c311c31", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "2400.0", "events_count": 2400, "amount": { "currency_code": "USD", "value": 120 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } }, { "units": "500.0", "events_count": 500, "amount": { "currency_code": "USD", "value": 75 }, "charge": { "id": "1a901b42-1b42-1b42-1b42-1a901b421b42", "metric_id": "metric_03H3YT8P7Q5R3S1T2U0V4W9Z0", "charge_model": "STANDARD", "properties": { "amount": "0.15" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Bandwidth MB", "code": "bandwidth_mb", "aggregation_type": "SUM" } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{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/id" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "subscription_id", "schema": { "type": "string" }, "required": true, "description": "Filter by subscription ID." } ], "responses": { "200": { "description": "Returns the past usage for the specified customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPastUsage" }, "example": { "usage_periods": [ { "from_datetime": "2023-12-01T00:00:00Z", "to_datetime": "2023-12-31T23:59:59Z", "issuing_date": "2023-12-31", "total_amount": { "currency_code": "USD", "value": 250 }, "taxes_amount": { "currency_code": "USD", "value": 3.25 }, "charges_usage": [ { "units": "200.0", "events_count": 200, "amount": { "currency_code": "USD", "value": 100 }, "charge": { "id": "1c31a90-1c31-1c31-1c31-1c311c311c31", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "3000.0", "events_count": 3000, "amount": { "currency_code": "USD", "value": 150 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] }, { "from_datetime": "2023-11-01T00:00:00Z", "to_datetime": "2023-11-30T23:59:59Z", "issuing_date": "2023-11-30", "total_amount": { "currency_code": "USD", "value": 150 }, "taxes_amount": { "currency_code": "USD", "value": 2.1 }, "charges_usage": [ { "units": "120.0", "events_count": 120, "amount": { "currency_code": "USD", "value": 60 }, "charge": { "id": "1e1a90-1e1a-1e1a-1e1a-1e1a1e1a1e1a", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "1800.0", "events_count": 1800, "amount": { "currency_code": "USD", "value": 90 }, "charge": { "id": "1r67r67-1r67-1r67-1r67-1r671r671r67", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] }, { "from_datetime": "2023-10-01T00:00:00Z", "to_datetime": "2023-10-31T23:59:59Z", "issuing_date": "2023-10-31", "total_amount": { "currency_code": "USD", "value": 107.5 }, "taxes_amount": { "currency_code": "USD", "value": 1.85 }, "charges_usage": [ { "units": "95.0", "events_count": 95, "amount": { "currency_code": "USD", "value": 47.5 }, "charge": { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8", "charge_model": "STANDARD", "properties": { "amount": "0.50" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "API Calls", "code": "api_calls", "aggregation_type": "COUNT" } }, { "units": "1200.0", "events_count": 1200, "amount": { "currency_code": "USD", "value": 60 }, "charge": { "id": "1a901b42-1b42-1b42-1b42-1a901b421b42", "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9", "charge_model": "STANDARD", "properties": { "amount": "0.05" }, "min_amount": { "value": 0.01, "currency_code": "USD" } }, "metric": { "name": "Storage GB-Hours", "code": "storage_gb_hours", "aggregation_type": "SUM" } } ] } ], "meta": { "current_page": 1, "total_count": 12, "total_pages": 2 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{id}/portal_url": { "get": { "operationId": "GetEmbeddablePortalUrl", "tags": [ "Customers" ], "summary": "Get an embeddable URL to the customer portal", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Embeddable URL to the Customer Portal for the given external customer ID is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalEmbeddableUrlResponse" }, "example": { "url": "https://www.paypal.com/usage-billing/customer-portal/eyJ1dWlkIjoiNDQ4NmI3NGYtODM5ZC00ZTk2LWEyMTUtNDY3ZDYxMzgwNzFjIiwiZXhwaXJlc19pbiI6MzYwMH0=", "expires_in": 3600 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions": { "get": { "operationId": "GetSubscriptions", "tags": [ "Subscriptions" ], "summary": "Get all subscriptions", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_customer_id", "schema": { "type": "string", "example": "ext_cus_1234567890abcdef" }, "description": "Filter by external customer ID" }, { "in": "query", "name": "plan_code", "schema": { "type": "string", "example": "plan_1234567890abcdef" }, "description": "Filter by plan code" }, { "in": "query", "name": "status", "description": "Comma-separated list of statuses", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PENDING", "CANCELED", "TERMINATED" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "A list of subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "subscriptions": [ { "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6b13234", "external_id": "Subscription_1233", "plan_code": "Plan-Code-12345", "billing_time": "CALENDAR", "status": "ACTIVE", "start_date": "2025-06-27T20:44:21Z", "created_at": "2025-07-30T01:54:40Z", "current_period_start": "2025-07-01T00:00:00Z", "current_period_end": "2025-07-31T23:59:59Z", "id": "d9e9d0c0-d672-4299-8b8e-9d20ca20f465" }, { "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1751410090", "external_id": "Subscription_123353453453535-2025-07-01T22", "plan_code": "Plan-Code-2222", "billing_time": "CALENDAR", "status": "ACTIVE", "start_date": "2025-07-01T22:48:37Z", "created_at": "2025-07-30T01:54:40Z", "current_period_start": "2025-07-01T22:48:37Z", "current_period_end": "2025-07-31T23:59:59Z", "id": "35a75733-5940-42cc-97ed-1587d2d364e1" } ], "metadata": { "total_count": 24, "total_pages": 3, "current_page": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateSubscription", "tags": [ "Subscriptions" ], "summary": "Create a new subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" }, "examples": { "SimpleSubscriptionCreate": { "value": { "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "start_date": "2025-07-30T04:26:24Z", "end_date": "2025-09-09T04:26:24Z", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "metric_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": [ { "metric_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": [ { "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200 } } ], "minimum_commitment": { "invoice_display_name": "Negotiated Minimum Commitment", "amount": { "value": 500 } } } } } } } } }, "responses": { "201": { "description": "Subscription created successfully", "headers": { "paypal-debug-id": { "description": "PayPal debug ID for tracking", "schema": { "type": "string", "example": "23e54e9b-dc6d-4ec1-bb6a-3714135ec3a9" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "examples": { "SimpleSubscriptionCreate": { "value": { "id": "b71befc2-4799-402c-9d13-ca1f72759c64", "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113", "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", "created_at": "2022-08-08T00:00:00Z", "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z" } }, "SubscriptionCreationWithPlanOverrides": { "value": { "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": "2e097d19-1350-4baf-8add-5d19ecef8113", "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", "created_at": "2022-07-30T00:00:00Z", "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "id": "b71befc2-4799-402c-9d13-ca1f72759c64" } }, "SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment": { "value": { "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": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200 } } ], "minimum_commitment": { "amount": { "value": 500, "currency_code": "USD" }, "plan_code": "Plan-Code-_1753840215", "created_at": "2025-07-31T13:00:04Z", "updated_at": "2025-07-31T13:00:04Z" } }, "start_date": "2025-07-30T01:54:40Z", "end_date": "2025-09-09T04:26:24Z", "created_at": "2022-07-30T00:00:00Z", "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/{id}": { "get": { "operationId": "GetSubscriptionById", "tags": [ "Subscriptions" ], "summary": "Get a subscription by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "A subscription object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "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", "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", "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/id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Updated subscription object", "headers": { "paypal-debug-id": { "description": "PayPal debug ID for tracking", "schema": { "type": "string", "example": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "name": "Subscription_External", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113", "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", "created_at": "2025-07-30T01:54:40Z", "updated_at": "2025-08-05T23:59:59Z", "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/ext_sub_id" } ], "responses": { "200": { "description": "Returns the lifetime usage for the specified subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifetimeUsage" }, "example": { "external_subscription_id": "Subscription_External_1", "external_historical_usage_amount": { "value": 0, "currency_code": "USD" }, "invoiced_usage_amount": { "value": 0, "currency_code": "USD" }, "current_usage_amount": { "value": 0, "currency_code": "USD" }, "from": "2025-07-31T12:59:15Z", "to": "2025-08-01T07:04:39Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{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/id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCancel" }, "examples": { "cancelAtEndOfPeriod": { "summary": "Cancel at end of billing period", "value": { "cancel_option": "END_OF_PERIOD" } }, "cancelImmediately": { "summary": "Cancel immediately", "value": { "cancel_option": "IMMEDIATE" } }, "cancelWithEmptyRequest": { "summary": "Cancel subscription without cancel option specified in request", "value": {} } } } } }, "responses": { "200": { "description": "Updated subscription object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "examples": { "cancelActiveSubscriptionAtEndOfPeriod": { "summary": "An Active subscription canceled at end of period", "value": { "name": "Subscription-008", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-008", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "end_date": "2025-08-14T23:59:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb524" } }, "cancelActiveSubscriptionImmediately": { "summary": "An Active subscription canceled immediately", "value": { "name": "Subscription-009", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-009", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "TERMINATED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "terminated_at": "2025-08-11T20:50:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb525" } }, "cancelPendingSubscriptionImmediately": { "summary": "Pending subscription canceled immediately", "value": { "name": "Subscription-010", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-010", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "CANCELED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-21T00:00:00Z", "canceled_at": "2025-08-11T19:55:45Z", "id": "8492b68f-6303-4ad9-96f4-65f658f44011" } }, "cancelActiveSubscriptionWithoutCancelOptionSpecified": { "summary": "Active subscription canceled with out passing cancel option in request", "value": { "name": "Subscription-007", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1754931701", "external_id": "Subscription-007", "plan_code": "Plan-Code-343435-1754679147", "billing_time": "ANNIVERSARY", "status": "TERMINATED", "plan_overrides": { "amount": { "value": 50, "currency_code": "USD" }, "name": "Storage usage plan", "trial_period": 14, "charges": [ { "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "properties": { "amount": "1.11" } } ] }, "start_date": "2025-08-01T00:00:00Z", "terminated_at": "2025-08-11T20:50:59Z", "current_period_start": "2025-08-08T00:00:00Z", "current_period_end": "2025-08-14T23:59:59Z", "id": "464a77f7-3905-4717-a669-255febedb526" } } } } } }, "400": { "description": "Bad Request - Invalid request format or data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidRequestBody": { "summary": "Invalid cancel option provided", "value": { "name": "INVALID_REQUEST", "debug_id": "a109791e6c096bcaa74a45d27630d3e4", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "cancel_option", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "A parameter value is not valid." } ] } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Unprocessable Entity - Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "cancelPendingSubscriptionWithCancelOptionAsEndOfPeriod": { "summary": "Cancel pending subscription with cancel option as end of period", "value": { "name": "UNPROCESSABLE_ENTITY", "debug_id": "162925068ef2df7a6adb93b3a4d7869d", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "details": [ { "issue": "CANCEL_OPTION_NOT_SUPPORTED", "description": "Pending subscriptions can be cancelled only with cancel option as IMMEDIATE." } ] } }, "subscriptionAlreadyCancelled": { "summary": "Subscription already cancelled", "value": { "name": "UNPROCESSABLE_ENTITY", "debug_id": "162925068ef2df7a6adb93b3a4d7869d", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "details": [ { "issue": "SUBSCRIPTION_ALREADY_CANCELED", "description": "Subscription is already cancelled." } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/events": { "get": { "operationId": "GetEvents", "tags": [ "Events" ], "summary": "Query usage events", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_subscription_id", "schema": { "type": "string", "example": "sub_1234567890abcdef" }, "description": "Filter events by external subscription ID" }, { "in": "query", "name": "metric_code", "schema": { "type": "string", "example": "metric_123456ef" }, "description": "Filter events by metric code" }, { "in": "query", "name": "from_date", "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "description": "Start date for filtering events" }, { "in": "query", "name": "to_date", "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "description": "End date for filtering events" } ], "responses": { "200": { "description": "A list of usage events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "events": [ { "transaction_id": "event_1752016113", "external_subscription_id": "49fac470-fa34-4471-915e-bff1d05308ce", "metric_code": "EvolvAI_Billable_Metrics_1750804981", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "87b5897d-083f-490c-b5f5-d219087b4d73", "created_at": "2025-07-08T16:08:33-07:00" }, { "transaction_id": "event_1752016329", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-02T00:00:00Z", "properties": { "gb": 12 }, "id": "42365b30-368a-4a0e-be4f-b790dab2cde9", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016319", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "38d78dd1-219e-43bb-af97-7e888e952605", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016316", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f910721", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "2ee6fbfc-132c-4628-9138-450b27d68b32", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016310", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_17514954851", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "67505fef-8dae-4547-b595-5f4265ac6a82", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016198", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "7f4d2d59-4691-4372-9931-aabef31a1cec", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016186", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "aa237cc9-e975-4486-a5cf-f2c0999190a9", "created_at": "2025-01-02T00:00:00Z" }, { "transaction_id": "event_1752016165", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-06T00:00:00Z", "properties": { "gb": 12 }, "id": "528be51f-ee55-4c14-8306-50a26638190f", "created_at": "2025-01-06T00:00:00Z" }, { "transaction_id": "event_1752016139", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-01T00:00:00Z", "properties": { "gb": 12 }, "id": "fe027df2-078f-4a92-9335-1c0f1c0d4123", "created_at": "2025-01-05T00:00:00Z" }, { "transaction_id": "event_1752016138", "external_subscription_id": "b40f7d03-cf36-4cb6-b7af-bb3468f91072", "metric_code": "EvolvAI_Billable_Metrics_1751495485", "timestamp": "2025-01-04T00:00:00Z", "properties": { "gb": 12 }, "id": "91b72931-6c5e-48e4-8156-27621857c9c5", "created_at": "2025-01-03T00:00:00Z" } ], "metadata": { "current_page": 1, "total_pages": 4, "total_count": 32 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateEvent", "tags": [ "Events" ], "summary": "Create a new usage event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" } } } }, "responses": { "201": { "description": "Event created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" }, "example": { "transaction_id": "event_1753818829", "metric_code": "91624203-791a-4639-8c86-4693948b3a41", "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a", "timestamp": "2025-07-29T12:53:49.076-07:00", "properties": { "gb": 10 }, "id": "d80447f2-0f34-4612-86ae-152160dc66c5", "created_at": "2025-07-29T12:53:49-07:00" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/events/batch": { "post": { "operationId": "CreateEventsBatch", "tags": [ "Events" ], "summary": "Create multiple usage events in batch.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventRequest" } } } }, "example": { "events": [ { "transaction_id": "event_t1_1753838783", "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41", "metric_code": "Billable_Metrics_1753827008", "timestamp": "2023-01-01T00:00:00Z", "properties": { "gb": 10 } }, { "transaction_id": "event_t2_1753838783", "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41", "metric_code": "Billable_Metrics_1753827008", "timestamp": "2023-01-01T00:00:00Z", "properties": { "gb": 10 } } ] } } } }, "responses": { "201": { "description": "Events accepted for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsAcceptedWithResults" }, "example": { "status": "ACCEPTED", "results": { "success_count": 2, "error_count": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets": { "get": { "operationId": "GetWallets", "tags": [ "Wallets" ], "summary": "Get all wallets", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "in": "query", "name": "external_customer_id", "schema": { "type": "string", "example": "ext_cus_1234567890abcdef" }, "description": "Filter by external customer ID", "required": true } ], "responses": { "200": { "description": "A list of wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/WalletWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateWallet", "tags": [ "Wallets" ], "summary": "Create a new wallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletCreate" } } } }, "responses": { "201": { "description": "Wallet created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" }, "example": { "id": "13fddcdc-725b-4ca7-a522-a162ff038567", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753815437", "status": "ACTIVE", "available_balance": { "value": 0, "currency_code": "USD" }, "ongoing_usage": { "value": 0, "currency_code": "USD" }, "net_balance": { "value": 0, "currency_code": "USD" }, "name": "Prepaid", "rate_amount": "1.0", "available_credits": "0.0", "consumed_credits": "0.0", "ongoing_usage_credits": "0.0", "net_balance_credits": "0.0", "created_at": "2025-07-29T18:57:27Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets/{id}": { "get": { "operationId": "GetWalletById", "tags": [ "Wallets" ], "summary": "Retrieve a wallet by ID", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Wallet retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" }, "example": { "id": "943254a2-0240-4414-bede-c0d211340c53", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358", "status": "ACTIVE", "available_balance": { "value": 3, "currency_code": "USD" }, "ongoing_usage": { "value": 0, "currency_code": "USD" }, "net_balance": { "value": 3, "currency_code": "USD" }, "name": "Prepaid", "rate_amount": "1.0", "available_credits": "3.0", "consumed_credits": "0.0", "ongoing_usage_credits": "0.0", "net_balance_credits": "3.0", "created_at": "2025-07-30T20:13:18Z", "expiration_at": "2026-10-08T00:00:00Z", "recurring_transaction_rules": [ { "trigger": "INTERVAL", "paid_credits": "0.0", "granted_credits": "0.0", "method": "TARGET", "interval": "WEEKLY", "started_at": "2025-07-01T17:30:15Z", "expiration_at": "2026-10-08T00:00:00Z", "threshold_credits": "0.0", "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/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/id" } ], "responses": { "200": { "description": "Wallet terminated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWithId" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallets/{wallet_id}/wallet-transactions": { "post": { "operationId": "CreateWalletTransaction", "tags": [ "Wallets" ], "summary": "Create Wallet transaction", "parameters": [ { "$ref": "#/components/parameters/wallet_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionRequest" } } } }, "responses": { "201": { "description": "Wallet transactions created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactions" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "GetWalletTransactions", "tags": [ "Wallets" ], "summary": "Get wallet transactions", "parameters": [ { "$ref": "#/components/parameters/wallet_id" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Wallet transactions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactions" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/wallet-transactions/{wallet_transaction_id}": { "get": { "operationId": "GetWalletTransactionById", "tags": [ "Wallets" ], "summary": "Get Wallet transaction by id", "parameters": [ { "$ref": "#/components/parameters/wallet_transaction_id" } ], "responses": { "200": { "description": "Wallet transaction by ID retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransaction" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credit-notes": { "get": { "operationId": "GetCreditNotes", "tags": [ "Credit Notes" ], "summary": "Get all credit notes", "parameters": [ { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" }, { "name": "external_customer_id", "in": "query", "description": "Filter credit notes by external customer ID", "required": false, "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "description": "Filter credit notes by invoice ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter credit notes by status", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteFilterStatus" } }, { "name": "credit_status", "in": "query", "description": "Filter credit notes by credit status (e.g., available, consumed, voided)", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteStatus" } }, { "name": "refund_status", "in": "query", "description": "Filter credit notes by refund status", "required": false, "schema": { "$ref": "#/components/schemas/RefundStatus" } }, { "name": "reason", "in": "query", "description": "Filter credit notes by reason", "required": false, "schema": { "$ref": "#/components/schemas/CreditNoteReason" } }, { "name": "id", "in": "query", "description": "Filter credit notes by ID", "required": false, "schema": { "type": "string" } }, { "name": "number", "in": "query", "description": "Filter credit notes by credit note number", "required": false, "schema": { "type": "string" } }, { "name": "issuing_date_from", "in": "query", "description": "Filter credit notes issued on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "issuing_date_to", "in": "query", "description": "Filter credit notes issued on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "created_at_from", "in": "query", "description": "Filter credit notes created on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "created_at_to", "in": "query", "description": "Filter credit notes created on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "updated_at_from", "in": "query", "description": "Filter credit notes updated on or after this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } }, { "name": "updated_at_to", "in": "query", "description": "Filter credit notes updated on or before this date (ISO 8601 format)", "required": false, "schema": { "$ref": "#/components/schemas/DateTimeWithZone" } } ], "responses": { "200": { "description": "A list of credit notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credit_notes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteWithId" } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "example": { "credit_notes": [ { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "billing_entity_code": "lex_corp", "sequential_id": 3, "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "AVAILABLE", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 25, "currency_code": "USD" }, "refund_amount": { "value": 25, "currency_code": "USD" }, "balance_amount": { "value": 25, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "taxes_rate": 0.2, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "coupons_adjustment_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/{id}": { "get": { "operationId": "GetCreditNoteById", "tags": [ "Credit Notes" ], "summary": "Get a single credit note by ID", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the credit note", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A single credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteWithId" }, "example": { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "billing_entity_code": "lex_corp", "sequential_id": 3, "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "AVAILABLE", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 25, "currency_code": "USD" }, "refund_amount": { "value": 25, "currency_code": "USD" }, "balance_amount": { "value": 25, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "taxes_rate": 0.2, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "coupons_adjustment_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/{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": "id", "in": "path", "description": "The ID of the credit note to void", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit note voided successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteWithId" }, "example": { "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD", "sequential_id": 3, "billing_entity_code": "lex_corp", "number": "CN-2023-0001", "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD", "invoice_number": "INV-2023-001", "issuing_date": "2023-06-01", "credit_status": "VOIDED", "refund_status": "SUCCEEDED", "reason": "ORDER_CANCELLATION", "description": "Refund for cancelled subscription", "total_amount": { "value": 50, "currency_code": "USD" }, "credit_amount": { "value": 0, "currency_code": "USD" }, "refund_amount": { "value": 0, "currency_code": "USD" }, "balance_amount": { "value": 0, "currency_code": "USD" }, "taxes_amount": { "value": 0, "currency_code": "USD" }, "sub_total_excluding_taxes_amount": { "value": 0, "currency_code": "USD" }, "coupons_adjustment_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_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_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Successfully retrieved the collection of alerts configured for the specified subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertList" }, "example": { "alerts": [ { "id": "7e6a89c9-ab69-4702-98f5-c245aca88080", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "storage_units_current_cycle", "name": "Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "units_used", "value": "500000.0", "recurring": false } ], "created_at": "2025-08-01T05:58:57Z" }, { "id": "14a42687-1814-4419-a111-76ff5792a786", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage amount", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_AMOUNT", "code": "storage_amount_current_cycle", "name": "Current Monetary Usage Alert specific to a Metric", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "1000.0", "recurring": false } ], "created_at": "2025-08-01T05:58:53Z" }, { "id": "13aac90e-927a-4203-8d42-11a388b91308", "external_subscription_id": "SUB_1752779018503", "type": "CURRENT_USAGE_AMOUNT", "code": "current_usage_amount_aggregated_current_cycle", "name": "Current Cycle Monetary Usage Alert", "previous_value": 0, "thresholds": [ { "code": "hard", "value": "9000.1", "recurring": false } ], "last_processed_at": "2025-08-03T10:04:21Z", "created_at": "2025-08-01T05:58:48Z" }, { "id": "f5ca7539-e540-4d92-a416-fcece5970bf4", "external_subscription_id": "SUB_1752779018503", "type": "LIFETIME_USAGE_AMOUNT", "code": "lifetime_usage_alert", "name": "Lifetime Monetary Usage Alert", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "5000.0", "recurring": false }, { "code": "hard", "value": "10000.0", "recurring": false }, { "code": "hard", "value": "2000.0", "recurring": true } ], "created_at": "2025-07-31T18:28:31Z" } ], "meta": { "total_count": 4, "total_pages": 1, "current_page": 1 } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateAlert", "tags": [ "Alerts" ], "summary": "Create subscription alert", "description": "Establishes a new usage-based alert for a subscription to notify merchants when consumption reaches specified thresholds. Supports multiple alert types including current billing period usage, lifetime usage, and metric-specific monitoring for both monetary amounts and consumption units.", "parameters": [ { "name": "external_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } } ], "requestBody": { "required": true, "description": "Complete alert configuration including type, thresholds, and optional metric information. The alert type determines which fields are required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertInput" }, "example": { "code": "storage_monetary_alert", "metric_code": "Storage_Metrics_1753985710", "name": "Current Monetary Usage Alert specific to a Metric", "thresholds": [ { "code": "warn", "recurring": false, "value": "1000" } ], "type": "METRIC_CURRENT_USAGE_AMOUNT" } } } }, "responses": { "201": { "description": "Alert configuration successfully created and activated for the subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "14a42687-1814-4419-a111-76ff5792a786", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1753985710", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "1e421308-7ead-4aef-b527-64dd05569668", "created_at": "2025-07-31T18:15:12Z" }, "type": "METRIC_CURRENT_USAGE_AMOUNT", "code": "storage_monetary_alert", "name": "Current Monetary Usage Alert specific to a Metric", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "1000.0", "recurring": false } ], "last_processed_at": "2025-08-01T06:15:00Z", "created_at": "2025-08-01T05:58:53Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{external_id}/alerts/{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_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "responses": { "200": { "description": "Successfully retrieved the detailed configuration and current status of the specified alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "a3c9e51d-6c0d-4cad-a029-6e5c0c08fc52", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1754980238", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "0eb44a04-dc60-4d2c-aacb-90d5dbb2b048", "created_at": "2025-08-12T06:30:39Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "ALERT_CODE_1234567890", "name": "Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ], "last_processed_at": "2025-08-16T09:45:00Z", "created_at": "2025-08-12T06:31:47Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "UpdateAlertByExternalIdAndCode", "tags": [ "Alerts" ], "summary": "Modify subscription alert", "description": "Updates the configuration of an existing subscription alert.", "parameters": [ { "name": "external_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "requestBody": { "required": true, "description": "Modified alert configuration containing updated threshold values and other configurable parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertUpdateInput" }, "example": { "code": "ALERT_CODE_UPDATED_1234567890", "name": "Updated Current Usage Alert specific to a Metric units", "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ] } } } }, "responses": { "200": { "description": "Alert configuration successfully updated with the provided changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "a3c9e51d-6c0d-4cad-a029-6e5c0c08fc52", "external_subscription_id": "SUB_1752779018503", "metric": { "name": "Storage usage", "code": "Storage_Metrics_1754980238", "type": "METERED", "description": "GB of storage used in my application", "aggregation_type": "SUM", "aggregation_field": "gb", "field_filters": [ { "key": "region", "values": [ "us-west1" ] } ], "id": "0eb44a04-dc60-4d2c-aacb-90d5dbb2b048", "created_at": "2025-08-12T06:30:39Z" }, "type": "METRIC_CURRENT_USAGE_UNITS", "code": "ALERT_CODE_UPDATED_1234567890", "name": "Updated Current Usage Alert specific to a Metric units", "previous_value": 0, "thresholds": [ { "code": "warn", "value": "200000.0", "recurring": false }, { "code": "hard", "value": "250000.0", "recurring": false }, { "code": "recurring", "value": "50000.0", "recurring": true } ], "last_processed_at": "2025-08-16T09:45:00Z", "created_at": "2025-08-12T06:31:47Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteAlertByExternalIdAndCode", "tags": [ "Alerts" ], "summary": "Remove subscription alert", "description": "Permanently deletes a subscription alert identified by its unique code. This operation cannot be undone and will immediately stop all monitoring associated with this alert configuration.", "parameters": [ { "name": "external_id", "in": "path", "required": true, "description": "Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.", "schema": { "type": "string", "example": "SUB_1752779018503" } }, { "name": "code", "in": "path", "required": true, "description": "Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.", "schema": { "type": "string", "example": "ALERT_CODE_1234567890" } } ], "responses": { "204": { "description": "Alert successfully removed from the system. All monitoring associated with this alert has been permanently discontinued. No content is returned in the response body.", "content": { "application/json": { "example": { "status": "204 No Content", "headers": { "paypal-debug-id": "f772b19c-c5c2-426d-8871-346a6cd094c5" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "x-webhooks": { "commerce.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." } } } }, "commerce.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." } } } }, "commerce.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." } } } }, "commerce.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." } } } }, "commerce.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." } } } }, "commerce.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." } } } }, "commerce.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." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "oauth2", "description": "Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.", "flows": { "clientCredentials": { "tokenUrl": "https://api-m.sandbox.paypal.com/v1/oauth2/token", "scopes": { "read": "Read access", "write": "Write access" } } } } }, "responses": { "NoContent": { "description": "No Content" }, "Forbidden": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] } } } }, "InternalServerError": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error has occurred.", "debug_id": "90957fca61718" } } } }, "NotFound": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "dc99e3955cdd8", "details": [ { "field": "/email", "value": "abc", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "The value of a field does not conform to the expected format." } ] } } } }, "UnprocessableEntity": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90957fca61718", "details": [ { "field": "/email", "value": "sdfwdj@sdfs.com", "location": "body", "issue": "UNSUPPORTED_EMAIL", "description": "The email provided is not supported." } ] } } } }, "Conflict": { "description": "Conflict - The request could not be completed due to a conflict with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90957fca61718", "details": [ { "field": "transaction_id", "issue": "RESOURCE_ALREADY_EXISTS", "description": "The resource identified by `field` already exists." } ] } } } } }, "schemas": { "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" } } } }, "Date": { "type": "string", "format": "date", "description": "Date in ISO 8601 format (YYYY-MM-DD).", "example": "2023-10-01", "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8]))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$" }, "InvoiceStatus": { "type": "string", "nullable": true, "enum": [ "DRAFT", "FINALIZED" ], "x-enum-varnames": [ "DRAFT", "FINALIZED" ], "x-enum-descriptions": [ "The invoice is in draft state and can be modified", "The invoice has been finalized and cannot be modified" ], "description": "Status of the invoice", "example": "FINALIZED" }, "PaymentStatus": { "type": "string", "description": "Status of invoice payment", "enum": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-varnames": [ "PENDING", "FAILED", "SUCCEEDED" ], "x-enum-descriptions": [ "The invoice is awaiting payment", "The payment for the invoice has failed", "The payment for the invoice was successful" ], "example": "PENDING" }, "AmountNoCurrency": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number", "format": "decimal", "description": "The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).", "example": 120.35, "minimum": 0, "nullable": false, "default": 0 } } }, "Currency": { "type": "string", "description": "Currency code in ISO 4217 format.", "example": "USD", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "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" } ] }, "coupons": { "description": "The total amount of discounts applied to the invoice through coupons.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "credit_notes": { "description": "The total amount of credit notes applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "sub_total_excluding_taxes": { "description": "The subtotal amount of the invoice excluding taxes.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "taxes": { "description": "The total amount of taxes applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "sub_total_including_taxes": { "description": "The subtotal amount of the invoice including taxes.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "prepaid_credit": { "description": "The total amount of prepaid credits applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "progressive_billing_credit": { "description": "The total amount of progressive billing credits applied to the invoice.", "allOf": [ { "$ref": "#/components/schemas/Amount" } ] } } }, "AmountWithBreakdown": { "type": "object", "properties": { "total_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "breakdown": { "allOf": [ { "$ref": "#/components/schemas/AmountBreakdown" } ] } } }, "FeeObject": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "format": "uuid", "description": "Unique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "total_amount": { "$ref": "#/components/schemas/Amount", "description": "The cost of this specific fee, including any applicable taxes.", "example": { "value": 1.2, "currency_code": "USD" } } } }, "InvoiceType": { "type": "string", "nullable": true, "enum": [ "SUBSCRIPTION", "ONE_OFF", "CREDIT" ], "x-enum-varnames": [ "SUBSCRIPTION", "ONE_OFF", "CREDIT" ], "x-enum-descriptions": [ "Invoice generated for subscription recurring charges", "Invoice generated for one-time charges", "Credit note invoice for refunds or adjustments" ], "description": "Type of invoice", "example": "SUBSCRIPTION" }, "EmailAddress": { "type": "string", "description": "The internationalized email address.", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$", "example": "abc@test.com" }, "Address": { "description": "Address of the customer or party.", "type": "object", "properties": { "line1": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 254, "description": "First line of the address.", "example": "123 Main St" }, "line2": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Second line of the address (optional). This can include apartment, suite, or unit numbers.", "example": "Apt 4B" }, "city": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "City of the customer or party.", "example": "New York" }, "state": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "State or region of the customer or party.", "example": "NY" }, "postal_code": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Postal or ZIP code of the customer or party. Typically required for countries with a postal code or an equivalent.", "example": "10001" }, "country": { "type": "string", "nullable": false, "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country of the customer or party. Use ISO 3166-1 alpha-2 country codes.", "example": "US" } } }, "PaymentMethodToken": { "type": "string", "minLength": 1, "maxLength": 36, "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "pm_visa_4242" }, "PaymentMethodType": { "type": "string", "description": "Type of payment method used (e.g., CARD, ACH_DEBIT)", "enum": [ "CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY" ], "x-enum-varnames": [ "CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY" ], "x-enum-description": [ "Payment made using a Credit or Debit card.", "Payment made using PayPal.", "Payment made using Automated Clearing House (ACH) transfer.", "Payment made using Apple Pay." ], "example": "CARD" }, "CustomerMetadata": { "type": "object", "description": "Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format", "required": [ "key", "value", "display_in_invoice" ], "properties": { "key": { "type": "string", "example": "Purchase Order", "description": "The metadata object key" }, "value": { "type": "string", "example": "123456789", "description": "The metadata object value" }, "display_in_invoice": { "type": "boolean", "example": true, "description": "Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice." } } }, "Customer": { "title": "Customer", "description": "A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.", "type": "object", "required": [ "name", "email", "external_id" ], "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "ext_cust_12345" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodType" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "CustomerWithId": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "DateTimeWithZone": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601 format.", "example": "2023-10-01T12:00:00Z" }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the invoice", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "sequential_id": { "type": "integer", "description": "Sequential ID of the invoice, unique within the billing entity.", "example": 3 }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "payment_status": { "$ref": "#/components/schemas/PaymentStatus" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountWithBreakdown" } ], "description": "Total amount due for the invoice, including breakdown of fees, taxes, and discounts.", "example": { "total_amount": { "amount_cents": 19.99, "currency": "USD" }, "breakdown": { "fees": { "amount_cents": 1, "currency": "USD" }, "coupons": { "amount_cents": 2, "currency": "USD" }, "credit_notes": { "amount_cents": 0, "currency": "USD" }, "sub_total_excluding_taxes": { "amount_cents": 20, "currency": "USD" }, "taxes": { "amount_cents": 0.99, "currency": "USD" }, "sub_total_including_taxes": { "amount_cents": 19.99, "currency": "USD" } } } }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/FeeObject" } }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "Due date for the invoice payment", "example": "2023-01-15" }, "issued_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "Date when the invoice was issued", "example": "2023-01-01" }, "invoice_number": { "type": "string", "description": "Invoice number, unique within the billing entity.", "example": "INV-2023-001" }, "version_number": { "type": "string", "format": "number", "description": "Version number of the invoice, indicating the revision of the invoice.", "example": "INV-2023-001" }, "payment_overdue": { "type": "boolean", "description": "Indicates whether the invoice payment is overdue.", "example": "false" }, "invoice_type": { "$ref": "#/components/schemas/InvoiceType" }, "customer": { "$ref": "#/components/schemas/CustomerWithId" }, "billing_period": { "type": "array", "items": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the subscription", "example": "sub_01H3YT8P7Q5R3S1T2U0V4W9X8" }, "external_subscription_id": { "type": "string", "description": "The subscription external unique identifier supplied by client.", "example": "ext_id_23fw3" }, "plan_id": { "description": "Unique identifier for the plan", "type": "string", "example": "plan_01H3YT8P7Q5R3S1T2U0V4W9X8" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's payment method", "example": "pm_visa_4242" }, "payment_method_type": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodType" } ] }, "subscription_from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "subscription_to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "charges_from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "charges_to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "invoicing_reason": { "type": "string", "description": "Reason for invoicing, e.g., 'subscription', 'usage', 'one-time charge'", "example": "subscription" } } } }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } }, "InvoiceWithId": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "description": "Timestamp when the invoice was created", "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "example": "2023-01-01T00:00:00Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the invoice was last updated", "example": "2023-01-01T00:00:00Z" } } } ] }, "PaginationMetadata": { "type": "object", "properties": { "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "current_page": { "type": "integer" } } }, "MetricType": { "type": "string", "default": "RECURRING", "enum": [ "METERED", "RECURRING" ], "description": "Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges.", "example": "METERED", "x-enum-varnames": [ "METERED", "RECURRING" ], "x-enum-descriptions": [ "Usage-based metric that charges based on the amount used.", "Fixed periodic charge that recurs at specified intervals." ] }, "MetricAggregationType": { "type": "string", "nullable": true, "enum": [ "COUNT", "SUM", "MAX", "COUNT_DISTINCT", "LATEST" ], "x-enum-varnames": [ "COUNT", "SUM", "MAX", "COUNT_DISTINCT", "LATEST" ], "x-enum-descriptions": [ "Count the number of events", "Sum the values of a numeric field", "Find the maximum value of a numeric field", "Count the number of distinct values", "Use the latest value" ], "description": "Aggregation type for the metric", "example": "SUM" }, "MetricBase": { "type": "object", "properties": { "name": { "type": "string", "description": "Descriptive name of the metric that represents a pricing component of your application. This is primarily used for display purposes in the user interface." }, "code": { "type": "string", "description": "Unique code used to identify the metric within your system. This code is used in API requests to associate events with the correct metric and must be unique across all metrics. Once created, this code cannot be changed." }, "type": { "$ref": "#/components/schemas/MetricType" }, "description": { "type": "string", "description": "Optional detailed description of the metric that provides additional context about what the metric measures and how it's used. This information is for internal use and helps document the purpose of the metric." }, "aggregation_type": { "$ref": "#/components/schemas/MetricAggregationType" }, "aggregation_field": { "type": "string", "description": "Property name within the event payload that will be used for aggregating usage data. This field specifies which value from the event should be used for calculations. It is required for aggregation types like 'SUM', 'MAX', and other types that operate on values, but not required for 'COUNT' aggregation." }, "field_filters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Property name within the event payload that will be used for filtering. This allows you to segment usage data based on specific event properties, such as region, tier, or any other dimension you track." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Array of specific values that the system should match against the filter key. Only events with matching key-value pairs will be included in the metric calculations. This enables differentiated pricing based on dimensions like region, environment, or other custom properties." } }, "required": [ "key", "values" ] } } } }, "MetricResponse": { "type": "object", "required": [ "id", "name", "code", "aggregation_type", "created_at" ], "allOf": [ { "$ref": "#/components/schemas/MetricBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the metric, automatically generated by the system upon creation. This ID is used internally to track the metric and cannot be modified." }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the metric was created. ISO 8601 format with timezone." }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the metric was last updated. ISO 8601 format with timezone." } } } ] }, "MetricRequest": { "type": "object", "required": [ "name", "code", "aggregation_type" ], "allOf": [ { "$ref": "#/components/schemas/MetricBase" } ] }, "MetricUpdateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetricBase" } ] }, "BillingCycle": { "type": "string", "description": "The billing cycle indicating how often the subscription is charged", "enum": [ "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ], "x-enum-varnames": [ "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ], "x-enum-descriptions": [ "Recurring billing occurs every week", "Recurring billing occurs every month", "Recurring billing occurs every three months", "Recurring billing occurs once a year" ], "example": "MONTHLY" }, "ChargeModel": { "type": "string", "description": "The pricing model applied to this charge", "enum": [ "STANDARD", "GRADUATED", "PACKAGE", "PERCENTAGE", "VOLUME" ], "x-enum-varnames": [ "STANDARD", "GRADUATED", "PACKAGE", "PERCENTAGE", "VOLUME" ], "x-enum-descriptions": [ "Standard pricing model where a fixed amount is charged per unit", "Graduated pricing model where the price per unit decreases as the quantity increases", "Package pricing model where a fixed price is charged for a set of units", "Percentage pricing model where a percentage of a base amount is charged", "Volume-based pricing model where the price varies based on the total volume consumed" ], "example": "GRADUATED", "default": "STANDARD" }, "UsageBasedCharge": { "type": "object", "required": [ "id", "metric_id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the charge", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "metric_id": { "type": "string", "description": "Unique identifier of the metric" }, "charge_model": { "$ref": "#/components/schemas/ChargeModel", "description": "Defines the pricing model to calculate the charge" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } }, "MinimumCommitmentBase": { "type": "object", "description": "Minimum commitment for this plan.", "required": [ "amount" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name.", "example": "Minimum Commitment (C1)" } } }, "MinimumCommitment": { "allOf": [ { "$ref": "#/components/schemas/MinimumCommitmentBase" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the minimum commitment, created by Lago.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "plan_code": { "type": "string", "example": "premium", "description": "The unique code representing the plan to be attached to the customer." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the minimum commitment was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.", "example": "2022-04-29T08:59:51Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.", "example": "2022-04-29T08:59:51Z" } } } ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the plan. This ID is used internally to track the plan and cannot be modified.", "example": "1a901a90-1a90-1a90-1a540-1a901a901a90" }, "name": { "type": "string" }, "code": { "type": "string" }, "billing_cycle": { "$ref": "#/components/schemas/BillingCycle" }, "description": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "trial_period": { "type": "integer" }, "pay_in_advance": { "type": "boolean" }, "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedCharge" } }, "minimum_commitment": { "allOf": [ { "$ref": "#/components/schemas/MinimumCommitment" } ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } }, "MinimumCommitmentRequest": { "type": "object", "description": "Minimum commitment for this plan.", "required": [ "amount" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name.", "example": "Minimum Commitment (C1)" } } }, "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" }, "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" }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } }, "PlanCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanRequest" }, { "type": "object", "properties": { "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedChargeCreateRequest" } } } } ] }, "UsageBasedChargeUpdateRequest": { "type": "object", "required": [ "id", "metric_id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the charge", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "metric_id": { "type": "string", "description": "Unique identifier of the metric" }, "charge_model": { "$ref": "#/components/schemas/ChargeModel", "description": "Defines the pricing model to calculate the charge" }, "properties": { "type": "object", "description": "Pricing thresholds that determine the charges" }, "min_amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } }, "PlanUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanRequest" }, { "type": "object", "properties": { "cascading_updates": { "description": "Determines if changes made to the parent plan should be cascaded to the overridden plans in subscription", "type": "boolean", "example": "true" }, "usage_based_charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedChargeUpdateRequest" } } } } ] }, "PlanUpdateResponse": { "allOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "object", "properties": { "cascading_updates": { "description": "Determines if changes made to the parent plan should be cascaded to the children plans", "type": "boolean", "example": "true" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } } ] }, "CustomerCreateRequest": { "title": "CustomerCreateRequest", "description": "Request body for creating a new customer.A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.", "type": "object", "required": [ "name", "email", "external_id" ], "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "ext_cust_12345" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "CustomerUpdateRequest": { "title": "CustomerUpdateRequest", "description": "Request body for updating an existing customer. All fields are optional except external_id, which is required as the external unique identifier .", "type": "object", "properties": { "name": { "type": "string", "nullable": false, "minLength": 1, "maxLength": 512, "description": "Full name of the customer", "example": "John Doe" }, "email": { "$ref": "#/components/schemas/EmailAddress" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "format": "phone", "description": "Primary phone number of the customer, including country code if available.", "example": "+1-234-567-8900" }, "payment_method_token": { "allOf": [ { "$ref": "#/components/schemas/PaymentMethodToken" } ], "description": "Token representing the customer's saved payment method in PayPal Vault.", "example": "03t59758xv4247939" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "DateYearMonth": { "description": "The year and month, represented as a string in ISO 8601 'YYYY-MM' format (e.g., '2025-08'). For details, refer to RFC 3339 section 5.6 (Internet Date/Time Format).", "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "example": "2025-08" }, "OverdueBalance": { "type": "object", "description": "Represents the overdue balance data for a customer for a given month.", "properties": { "month": { "description": "The reference month for the overdue balance, formatted as an ISO 8601 year-month string ('yyyy-MM'), representing the first day of the month in UTC.", "allOf": [ { "$ref": "#/components/schemas/DateYearMonth" } ], "example": "2023-11" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total overdue balance amount for the specified customer during the reference month.", "example": { "value": 55, "currency_code": "USD" } } ] }, "invoice_ids": { "type": "array", "items": { "type": "string" }, "description": "An array of invoice IDs associated with the overdue balance for the reference month.", "example": [ "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" ] } } }, "OverdueBalances": { "type": "object", "description": "Represents a collection of monthly overdue balance records for a specific customer.", "properties": { "overdue_balances": { "type": "array", "description": "An array of monthly overdue balance entries for the specified customer.", "items": { "$ref": "#/components/schemas/OverdueBalance" } } } }, "GrossRevenue": { "type": "object", "description": "Represents the gross revenue data for a customer for a given month.", "properties": { "month": { "allOf": [ { "$ref": "#/components/schemas/DateYearMonth" }, { "description": "The reference month for the gross revenue, formatted as an ISO 8601 year-month string ('yyyy-MM'), representing the first day of the month in UTC.", "example": "2023-11" } ] }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total gross revenue amount for the specified customer during the reference month." } ] }, "invoices_count": { "type": "integer", "description": "The number of invoices included in the gross revenue calculation for the reference month.", "example": 10 } } }, "GrossRevenues": { "type": "object", "description": "Represents a collection of monthly gross revenue records for a specific customer.", "properties": { "gross_revenues": { "type": "array", "description": "An array of monthly gross revenue entries for the specified customer.", "items": { "$ref": "#/components/schemas/GrossRevenue" } } } }, "SubscriptionExternalId": { "type": "string", "description": "The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.", "pattern": "^[a-zA-Z0-9_-]*$", "example": "SUB_1752779018503" }, "CustomerUsageMetric": { "title": "CustomerUsageMetric", "description": "Represents a metric used for customer usage. It includes the name, code, and aggregation type of the metric.", "type": "object", "required": [ "name", "code", "aggregation_type" ], "properties": { "name": { "type": "string", "description": "Name of the metric used for this charge." }, "code": { "type": "string", "description": "Unique code identifying the metric used for this charge." }, "aggregation_type": { "$ref": "#/components/schemas/MetricAggregationType" } } }, "CustomerChargeUsage": { "type": "object", "required": [ "units", "events_count", "amount", "charge", "metric" ], "properties": { "units": { "type": "string", "pattern": "^[0-9]+.?[0-9]*$", "example": "1.0", "description": "The number of units utilized for a specific charge item." }, "events_count": { "type": "integer", "example": 10, "description": "The total count of usage events that have been recorded for a particular charge during the specified time period." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "charge": { "allOf": [ { "$ref": "#/components/schemas/UsageBasedCharge" } ] }, "metric": { "allOf": [ { "$ref": "#/components/schemas/CustomerUsageMetric" } ] } } }, "CustomerUsage": { "type": "object", "required": [ "from_datetime", "to_datetime", "issuing_date", "total_amount", "taxes_amount", "charges_usage" ], "properties": { "from_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Starting date of billing period, in the ISO 8601 datetime format in Universal Time (UTC).", "example": "2022-07-01T00:00:00Z" } ] }, "to_datetime": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Ending date of the billing period, in the ISO 8601 datetime format in Universal Time (UTC).", "example": "2022-07-31T23:59:59Z" } ] }, "issuing_date": { "allOf": [ { "$ref": "#/components/schemas/Date" } ], "description": "The date of creation of the invoice.", "example": "2022-08-01" }, "invoice_id": { "type": "string", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90", "description": "Unique invoice Id." }, "total_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ], "description": "The total amount for the current usage period, including all charges and taxes.", "example": { "value": 55, "currency_code": "USD" } }, "taxes_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ], "description": "The total amount of taxes applied to the current usage period.", "example": { "value": 5, "currency_code": "USD" } }, "charges_usage": { "type": "array", "description": "Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.", "items": { "$ref": "#/components/schemas/CustomerChargeUsage" } } } }, "CustomerPastUsage": { "type": "object", "required": [ "usage_periods", "meta" ], "properties": { "usage_periods": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerUsage" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "CustomerPortalEmbeddableUrlResponse": { "type": "object", "properties": { "url": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" } } }, "SubscriptionBase": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the subscription.", "example": "Subscription_1" }, "start_date": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format", "example": "2025-06-01T00:00:00Z" } ] }, "end_date": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format", "example": "2028-01-01T00:00:00Z" } ] } } }, "BillingTime": { "type": "string", "description": "The billing time for the subscription, which can be set as either anniversary or calendar", "enum": [ "CALENDAR", "ANNIVERSARY" ], "x-enum-varnames": [ "CALENDAR", "ANNIVERSARY" ], "x-enum-descriptions": [ "Calendar billing time - billing cycle at the first day of the week/month/year (billed with proration)", "Anniversary billing time - billing cycle based on the specific date the subscription started (billed fully)" ], "default": "CALENDAR", "example": "CALENDAR" }, "SubscriptionExtendedBase": { "required": [ "external_customer_id", "external_id", "plan_code" ], "allOf": [ { "$ref": "#/components/schemas/SubscriptionBase" }, { "type": "object", "properties": { "external_customer_id": { "type": "string", "description": "External reference to the customer", "pattern": "^[a-zA-Z0-9_-]*$", "example": "client-jkl101" }, "external_id": { "$ref": "#/components/schemas/SubscriptionExternalId" }, "plan_code": { "type": "string", "description": "The plan code", "example": "Plan-Code-1753840215" }, "billing_time": { "$ref": "#/components/schemas/BillingTime" } } } ] }, "SubscriptionStatus": { "type": "string", "description": "The status of the subscription", "enum": [ "PENDING", "ACTIVE", "TERMINATED", "CANCELED" ], "x-enum-varnames": [ "PENDING", "ACTIVE", "TERMINATED", "CANCELED" ], "x-enum-descriptions": [ "A previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period", "The subscription is currently active and applied to the customer", "The subscription is no longer active", "The subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer or when a subscription with a pending status is terminated" ], "example": "ACTIVE" }, "PlanOverridesBase": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "description": { "type": "string", "description": "The description on the plan", "example": "Plan for early stage startups" }, "invoice_display_name": { "type": "string", "description": "Specifies the name that will appear on the invoice", "example": "Startup plan" }, "name": { "type": "string", "description": "The name of the plan", "example": "Startup" }, "trial_period": { "type": "integer", "description": "The number of days the plan's base cost is provided at no charge", "example": 5 } } }, "ChargeUsageThresholdBase": { "type": "object", "properties": { "id": { "type": "string", "description": "Refers to the charge usage threshold unique identifier", "example": "545-1a90-1a90-1a90-1a90-1a901a901a90" }, "recurring": { "type": "string", "description": "Indicates if recurring invoices will be created", "example": "true" }, "threshold_display_name": { "type": "string", "description": "Indicates the name for the usage threshold", "example": "Startup" }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone" }, "updated_at": { "$ref": "#/components/schemas/DateTimeWithZone" } } }, "ChargeUsageThresholdResponse": { "allOf": [ { "$ref": "#/components/schemas/ChargeUsageThresholdBase" }, { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Amount" } } } ] }, "PlanOverridesResponse": { "allOf": [ { "$ref": "#/components/schemas/PlanOverridesBase" }, { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBasedCharge" } }, "minimum_commitment": { "$ref": "#/components/schemas/MinimumCommitment" }, "chargeUsage": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeUsageThresholdResponse" } } } } ] }, "SubscriptionResponse": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionExtendedBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription", "example": "b71befc2-4799-402c-9d13-ca1f72759c64" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesResponse" }, "canceled_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date at which a pending subscription is canceled.", "example": "2025-01-01T00:00:00Z" } ] }, "terminated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date at which an active subscription is canceled.", "example": "2025-01-01T00:00:00Z" } ] }, "current_period_start": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "Start date of the current billing period", "example": "2025-05-01T00:00:00Z" } ] }, "current_period_end": { "description": "End date of the current billing period", "example": "2025-06-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ] } } } ] }, "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": { "$ref": "#/components/schemas/UsageBasedChargeCreateRequest" } }, "minimum_commitment": { "$ref": "#/components/schemas/MinimumCommitmentRequest" }, "chargeUsage": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeUsageThresholdRequest" } } } } ] }, "SubscriptionCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionExtendedBase" }, { "type": "object", "properties": { "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesRequest" } } } ] }, "PlanOverridesUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PlanOverridesRequest" }, { "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/AmountNoCurrency" } ] } } } ] }, "SubscriptionUpdateRequest": { "type": "object", "description": "Update request for a subscription.", "allOf": [ { "$ref": "#/components/schemas/SubscriptionBase" }, { "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionStatus" }, { "description": "If the status field is not defined and multiple active and pending subscriptions exists, we will update the active subscription. However, if you wish to update a pending subscription, please ensure that you include the status attribute with the pending value in your request body." } ] }, "plan_overrides": { "$ref": "#/components/schemas/PlanOverridesUpdateRequest" } } } ] }, "UsageThreshold": { "type": "object", "description": "Represents a usage threshold milestone for a subscription.", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The usage threshold amount" } ] }, "completion_ratio": { "type": "number", "format": "double", "description": "The ratio (between 0 and 1) representing the proportion of the threshold amount that has been used.", "example": 0.5 }, "reached_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The date and time (in ISO 8601 format with timezone) when this usage threshold was reached.", "example": "2024-01-01T00:00:00Z" } ] } } }, "LifetimeUsage": { "type": "object", "description": "Represents the lifetime usage metrics for a given subscription.", "properties": { "external_subscription_id": { "type": "string", "description": "Unique external identifier of the subscription.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "external_historical_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total historical usage amount for this subscription, representing usage accumulated prior to the start of invoiced and current usage tracking." } ] }, "invoiced_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total usage amount, that has been invoiced for this subscription, provided by your own application." } ] }, "current_usage_amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The total usage amount, accumulated for the subscription during the current billing period" } ] }, "from": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The start date and time (with timezone) of the tracked lifetime usage for the subscription." } ] }, "to": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" }, { "description": "The end date and time (with timezone) of the tracked lifetime usage for the subscription." } ] }, "usage_thresholds": { "type": "array", "description": "An array of usage thresholds configured in the subscription's plan.", "items": { "$ref": "#/components/schemas/UsageThreshold" } } } }, "CancelOption": { "type": "string", "description": "Option specifying how the subscription should be canceled", "enum": [ "IMMEDIATE", "END_OF_PERIOD" ], "x-enum-varnames": [ "IMMEDIATE", "END_OF_PERIOD" ], "x-enum-descriptions": [ "Cancel the subscription immediately", "Cancel the subscription at the end of the current billing period" ], "default": "IMMEDIATE", "example": "IMMEDIATE" }, "SubscriptionCancel": { "type": "object", "description": "Cancel request for a subscription.", "properties": { "cancel_option": { "$ref": "#/components/schemas/CancelOption" } } }, "EventBase": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for the transaction associated with the event", "example": "txn_1234567890abcdef" }, "external_subscription_id": { "type": "string", "description": "External subscription ID associated with the event", "example": "sub_1234567890abcdef" }, "metric_code": { "type": "string", "description": "Identifier for the targeted metric. This value must match the `code` property of an active metric; otherwise, it will be disregarded during processing.", "example": "event_code_123456" }, "timestamp": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the event occurred", "example": "2023-01-01T00:00:00Z" }, "properties": { "type": "object" } }, "required": [ "transaction_id", "metric_code", "external_subscription_id" ] }, "EventResponse": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event", "example": "evt_1234567890abcdef" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Timestamp when the event was created", "example": "2023-01-01T00:00:00Z" } } } ] }, "EventRequest": { "allOf": [ { "$ref": "#/components/schemas/EventBase" } ] }, "EventStatus": { "type": "string", "enum": [ "ACCEPTED" ], "description": "Status indicating that the event has been accepted for processing", "example": "ACCEPTED" }, "EventAccepted": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/EventStatus" } } }, "EventsAcceptedWithResults": { "allOf": [ { "$ref": "#/components/schemas/EventAccepted" }, { "type": "object", "properties": { "results": { "type": "object", "description": "Results of the accepted events", "properties": { "success_count": { "type": "integer", "description": "Number of events successfully processed", "example": 100 }, "error_count": { "type": "integer", "description": "Number of events that failed processing", "example": 5 }, "errors": { "type": "array", "description": "Details about failed events", "items": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Transaction ID of the failed event" }, "error_code": { "type": "string", "description": "Error code" }, "error_message": { "type": "string", "description": "Detailed error message" } } }, "example": [ { "transaction_id": "txn_1234567890abcdef", "error_code": "invalid_data", "error_message": "The event data is invalid" } ] } } } } } ] }, "WalletStatus": { "type": "string", "description": "Current status of the wallet", "enum": [ "ACTIVE", "TERMINATED", "PENDING" ], "x-enum-varnames": [ "ACTIVE", "TERMINATED", "PENDING" ], "x-enum-descriptions": [ "The wallet is active and can be used for transactions", "The wallet has been terminated and cannot be used", "The wallet is pending activation or processing" ], "example": "ACTIVE" }, "FeeType": { "type": "string", "description": "Types of fees that wallet prepaid credits can be applied to", "enum": [ "SUBSCRIPTION", "COMMITMENT", "CHARGE" ], "x-enum-varnames": [ "SUBSCRIPTION", "COMMITMENT", "CHARGE" ], "x-enum-descriptions": [ "Wallet prepaid credits used only for subscription payments", "Wallet prepaid credits used only for commitment payments", "Wallet prepaid credits used only for charge payments" ], "example": "SUBSCRIPTION" }, "PrepaidCreditAppliesTo": { "type": "object", "description": "Indicates whether the prepaid credit applies to the entire invoice or only to specific line items.", "properties": { "fee_types": { "type": "array", "items": { "$ref": "#/components/schemas/FeeType" }, "example": [ "SUBSCRIPTION" ] } } }, "RecurringTransactionTrigger": { "type": "string", "description": "Condition that triggers the recurring transaction rule", "enum": [ "INTERVAL", "THRESHOLD" ], "x-enum-varnames": [ "INTERVAL", "THRESHOLD" ], "x-enum-descriptions": [ "Recurring transaction rule triggered at a specific interval", "Recurring transaction rule triggered when a threshold is reached" ], "example": "THRESHOLD" }, "RecurringTransactionMethod": { "type": "string", "description": "Method for recurring transaction execution", "enum": [ "FIXED", "TARGET" ], "x-enum-varnames": [ "FIXED", "TARGET" ], "x-enum-descriptions": [ "Recurring transaction rule with fixed credits", "Recurring transaction rule with target ongoing balance" ], "example": "FIXED" }, "RecurringTransactionRule": { "type": "object", "description": "Defines a recurring wallet transaction rule that triggers based on specific conditions.", "required": [ "trigger" ], "properties": { "trigger": { "$ref": "#/components/schemas/RecurringTransactionTrigger" }, "paid_credits": { "type": "string", "description": "Number of paid credits to be added when the rule is triggered. Must be a positive value", "example": "20.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "granted_credits": { "type": "string", "description": "Number of granted credits to be added when the rule is triggered. Must be a positive value", "example": "10.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "method": { "$ref": "#/components/schemas/RecurringTransactionMethod" }, "interval": { "$ref": "#/components/schemas/BillingCycle" }, "started_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Start date of the recurring wallet transaction rule", "example": "2025-01-01T00:00:00Z" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Expiration date of the recurring wallet transaction rule", "example": "2025-01-01T00:00:00Z" }, "threshold_credits": { "type": "string", "description": "Threshold of credits that triggers the recurring transaction rule.", "example": "5.0" }, "target_ongoing_balance": { "type": "string", "description": "Target ongoing balance that triggers the recurring transaction rule.", "example": "200.0" } } }, "Wallet": { "type": "object", "required": [ "external_customer_id", "rate_amount", "status" ], "properties": { "external_customer_id": { "type": "string", "description": "External system reference to the customer", "example": "client-12345" }, "status": { "$ref": "#/components/schemas/WalletStatus" }, "available_balance": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ] }, "ongoing_usage": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "The ongoing usage of the wallet, and it reflects all current usage and draft invoices including taxes.", "example": { "value": 100, "currency_code": "USD" } } ] }, "net_balance": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "This represents the real-time balance after accounting for current usage,.", "example": { "value": 50, "currency_code": "USD" } } ] }, "name": { "type": "string", "description": "Human-readable wallet name", "example": "Prepaid Wallet" }, "rate_amount": { "type": "string", "description": "Price charged per credit unit", "example": "1.5" }, "available_credits": { "type": "string", "description": "Current credit balance available", "example": "28.0" }, "ongoing_usage_credits": { "type": "string", "description": "This reflects all current usage and draft invoices.", "example": "10.0" }, "net_balance_credits": { "type": "string", "description": "This represents the real time balance after accounting for current usage.", "example": "18.0" }, "consumed_credits": { "type": "string", "description": "Total credits consumed so far", "example": "2.0" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "terminated_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletId": { "type": "string", "description": "Unique identifier for the wallet", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "WalletWithId": { "allOf": [ { "$ref": "#/components/schemas/Wallet" }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WalletId", "description": "Unique identifier for the wallet", "example": "sub_01H3YT8P7Q5R3S1T2U0V4W9X8" } } } ] }, "WalletCreate": { "type": "object", "required": [ "external_customer_id", "currency", "rate_amount" ], "properties": { "external_customer_id": { "type": "string", "description": "External reference to the customer", "example": "client-xyz456" }, "currency": { "allOf": [ { "$ref": "#/components/schemas/Currency" } ], "description": "Currency in which the wallet operates", "example": "USD" }, "name": { "type": "string", "description": "Name of the wallet", "example": "Prepaid Wallet" }, "rate_amount": { "type": "string", "description": "Cost rate per credit unit, must be non zero positive value", "example": "1.5", "pattern": "^(?!0+(?:\\.0+)?$)\\d+(\\.\\d+)?$" }, "paid_credits": { "type": "string", "description": "Number of paid credits to initialize, must be positive value", "example": "10.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "granted_credits": { "type": "string", "description": "Number of granted credits to initialize, must be positive value", "example": "5.0", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated wallet name", "example": "Updated Wallet Name" }, "expiration_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Cancelled date of the subscription", "example": "2025-01-01T00:00:00Z" }, "applies_to": { "allOf": [ { "$ref": "#/components/schemas/PrepaidCreditAppliesTo" } ] }, "recurring_transaction_rules": { "type": "array", "description": "List of recurring transaction rules for automatic top-ups", "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringTransactionRule" } ] } } } }, "WalletTransactionPaymentStatus": { "type": "string", "description": "The payment status of the wallet transaction. Possible values are `pending`, `settled` or `failed`.", "enum": [ "PENDING", "SETTLED", "FAILED" ], "x-enum-descriptions": [ "Payment status of Transaction is PENDING.", "Payment status of Transaction is SETTLED.", "Payment status of Transaction is FAILED." ], "example": "SETTLED" }, "WalletTransactionSource": { "type": "string", "enum": [ "MANUAL", "INTERVAL", "THRESHOLD" ], "x-enum-descriptions": [ "Origin of wallet transaction is MANUAL.", "Origin of wallet transaction is INTERVAL.", "Origin of wallet transaction is THRESHOLD." ], "description": "The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`. `threshold`", "example": "MANUAL" }, "WalletTransactionTransactionStatus": { "type": "string", "description": "The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.", "enum": [ "PURCHASED", "GRANTED", "VOIDED", "INVOICED" ], "x-enum-descriptions": [ "Transaction status of Transaction is PURCHASED.", "Transaction status of Transaction is GRANTED.", "Transaction status of Transaction is VOIDED.", "Transaction status of Transaction is INVOICED." ], "example": "PURCHASED" }, "WalletTransactionType": { "type": "string", "description": "The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance).", "enum": [ "INBOUND", "OUTBOUND" ], "x-enum-descriptions": [ "Type of Transaction is INBOUND.", "Type of Transaction is OUTBOUND." ], "example": "INBOUND" }, "StringMap": { "type": "object", "properties": { "key": { "type": "string", "description": "Name of the key", "example": "reason" }, "value": { "type": "string", "description": "Value associated with the key", "example": "balance depleted" } }, "example": { "key": "reason", "value": "balance depleted" } }, "WalletTransaction": { "type": "object", "properties": { "wallet_transaction_id": { "type": "string", "description": "Unique identifier for the wallet transaction", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "wallet_id": { "allOf": [ { "$ref": "#/components/schemas/WalletId" }, { "description": "Unique identifier for the wallet", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" } ] }, "payment_status": { "$ref": "#/components/schemas/WalletTransactionPaymentStatus" }, "source": { "$ref": "#/components/schemas/WalletTransactionSource" }, "transaction_status": { "$ref": "#/components/schemas/WalletTransactionTransactionStatus" }, "transaction_type": { "$ref": "#/components/schemas/WalletTransactionType" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" }, { "description": "Transaction amount involved in the specific wallet transaction." } ] }, "credits": { "type": "string", "pattern": "^[0-9]+.?[0-9]*$", "description": "The number of credits used in the wallet transaction.", "example": "100.0" }, "settled_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "failed_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date when the wallet transaction failed, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).", "example": "2022-04-29T08:59:51Z" }, "metadata": { "type": "array", "description": "List of key-value pair contains the metadata about the wallet transaction.", "items": { "$ref": "#/components/schemas/StringMap" } } } }, "WalletTransactions": { "type": "object", "description": "The get wallet transactions response contains list of wallet transactions for the specified wallet id.", "properties": { "wallet_transactions": { "type": "array", "description": "The list of wallet transactions for the specified wallet id", "items": { "$ref": "#/components/schemas/WalletTransaction" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/PaginationMetadata" }, { "type": "object", "properties": { "next_page": { "type": "integer", "description": "Next page.", "example": 3 }, "prev_page": { "type": "integer", "description": "Previous page.", "example": 1 } } } ] } } }, "WalletTransactionRequest": { "type": "object", "description": "Defines the request object to create a wallet transaction.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of the wallet transaction applied on the wallet. Supported types are TOPUP, VOID.", "enum": [ "TOPUP", "VOID" ], "x-enum-varnames": [ "TOPUP", "VOID" ], "x-enum-description": [ "Add funds to the wallet with the given credits.", "Deduct funds from the wallet with the given value." ], "example": "TOPUP" }, "paid_credits": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of paid credits to be added. Applicable only to TOPUP type of transaction", "example": "20.0" }, "credits_to_void": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of credits and Only for type VOID, this field need to be passed in request.", "example": "20.0" }, "granted_credits": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Number of granted credits to be added. Applicable only to TOPUP type of transaction", "example": "10.0" }, "metadata": { "type": "array", "description": "List of key-value pair contains the metadata about the wallet transaction.", "items": { "$ref": "#/components/schemas/StringMap" } } } }, "CreditNoteFilterStatus": { "type": "string", "enum": [ "DRAFT", "FINALIZED", "VOIDED" ], "x-enum-varnames": [ "DRAFT", "FINALIZED", "VOIDED" ], "x-enum-descriptions": [ "Credit note is in draft state, not yet finalized.", "Credit note has been finalized and applied.", "Credit note has been voided and is no longer valid." ], "description": "Status values for filtering credit notes", "example": "FINALIZED" }, "CreditNoteStatus": { "type": "string", "description": "The status of the credit portion of the credit note", "enum": [ "AVAILABLE", "CONSUMED", "VOIDED" ], "x-enum-varnames": [ "AVAILABLE", "CONSUMED", "VOIDED" ], "x-enum-descriptions": [ "There's an amount remains available for future usage. The credit can be applied towards future transactions or invoices", "The credit amount has been fully consumed. The remaining amount is 0, indicating that the credit has been utilized in its entirety", "The remaining amount of the credit cannot be used any further. The credit has been voided and is no longer available for application or redemption" ], "example": "AVAILABLE" }, "RefundStatus": { "type": "string", "description": "The status of the refund portion of the credit note", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ], "x-enum-varnames": [ "PENDING", "SUCCEEDED", "FAILED" ], "x-enum-descriptions": [ "The refund is pending execution. The refund request has been initiated but has not been processed or completed yet", "The refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient", "The refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned" ], "example": "PENDING" }, "CreditNoteReason": { "type": "string", "description": "The reason for credit note creation", "enum": [ "DUPLICATED_CHARGE", "PRODUCT_UNSATISFACTORY", "ORDER_CHANGE", "ORDER_CANCELLATION", "FRAUDULENT_CHARGE", "OTHER" ], "x-enum-varnames": [ "DUPLICATED_CHARGE", "PRODUCT_UNSATISFACTORY", "ORDER_CHANGE", "ORDER_CANCELLATION", "FRAUDULENT_CHARGE", "OTHER" ], "x-enum-descriptions": [ "Credit note issued due to duplicate charge on customer account", "Credit note issued because the product or service was unsatisfactory", "Credit note issued due to changes made to the original order", "Credit note issued because the order was cancelled", "Credit note issued due to fraudulent or unauthorized charge", "Credit note issued for other reasons not covered by standard categories" ], "example": "OTHER" }, "CreditNoteItemObject": { "type": "object", "required": [ "id", "amount", "fee" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The credit note's item unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "The credit note's item amount.", "example": { "value": 1, "currency_code": "USD" } }, "fee": { "$ref": "#/components/schemas/FeeObject", "description": "The fee object related to the credit note item." } } }, "BaseAppliedTax": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the applied tax.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "tax_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the tax.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "tax_name": { "type": "string", "description": "Name of the tax.", "example": "TVA" }, "tax_code": { "type": "string", "description": "Unique code used to identify the tax associated with the API request.", "example": "french_standard_vat" }, "tax_rate": { "type": "number", "description": "The percentage rate of the tax", "example": 20 }, "tax_description": { "type": "string", "description": "Internal description of the taxes", "example": "French standard VAT" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "Amount of the tax", "example": { "value": 20, "currency_code": "USD" } }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created.", "example": "2022-09-14T16:35:31Z" } } }, "CreditNoteAppliedTaxObject": { "allOf": [ { "$ref": "#/components/schemas/BaseAppliedTax" } ], "type": "object", "properties": { "credit_note_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the credit note.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "base_amount": { "$ref": "#/components/schemas/Amount", "example": { "value": 1, "currency_code": "USD" } } } }, "CreditNote": { "type": "object", "required": [ "sequential_id", "billing_entity_code", "number", "invoice_id", "invoice_number", "issuing_date", "reason", "total_amount", "credit_amount", "refund_amount", "balance_amount", "taxes_amount", "taxes_rate", "sub_total_excluding_taxes_amount", "coupons_adjustment_amount", "created_at", "updated_at" ], "properties": { "billing_entity_code": { "type": "string", "example": "acme_corp", "description": "The unique code of the billing entity associated with the credit note." }, "sequential_id": { "type": "integer", "description": "The sequential identifier of the credit note, specifically scoped on the associated invoice. It provides a unique numerical identifier for the credit note within the context of the invoice.", "example": 2 }, "number": { "type": "string", "description": "The credit note unique number.", "example": "PP-1234-US" }, "invoice_id": { "type": "string", "format": "uuid", "description": "Unique identifier assigned to the invoice that the credit note belongs to", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "invoice_number": { "type": "string", "description": "The invoice unique number, related to the credit note.", "example": "PP-1234" }, "issuing_date": { "$ref": "#/components/schemas/Date", "description": "The date of creation of the credit note. It follows the ISO 8601 date format and provides the specific date when the credit note was created.", "example": "2022-12-06" }, "credit_status": { "$ref": "#/components/schemas/CreditNoteStatus" }, "refund_status": { "$ref": "#/components/schemas/RefundStatus" }, "reason": { "$ref": "#/components/schemas/CreditNoteReason" }, "description": { "type": "string", "nullable": true, "description": "The description of the credit note.", "example": "Free text" }, "total_amount": { "$ref": "#/components/schemas/Amount", "description": "The total amount of the credit note.", "example": { "value": 1.2, "currency_code": "USD" } }, "taxes_amount": { "$ref": "#/components/schemas/Amount", "description": "The tax amount of the credit note.", "example": { "value": 0.2, "currency_code": "USD" } }, "taxes_rate": { "type": "number", "description": "The tax rate associated with this specific credit note.", "example": 0.2 }, "sub_total_excluding_taxes_amount": { "$ref": "#/components/schemas/Amount", "description": "The subtotal of the credit note excluding any applicable taxes.", "example": { "value": 1, "currency_code": "USD" } }, "balance_amount": { "$ref": "#/components/schemas/Amount", "description": "The remaining credit note amount.", "example": { "value": 1, "currency_code": "USD" } }, "credit_amount": { "$ref": "#/components/schemas/Amount", "description": "The credited amount of the credit note.", "example": { "value": 1, "currency_code": "USD" } }, "refund_amount": { "$ref": "#/components/schemas/Amount", "description": "The refunded amount of the credit note.", "example": { "value": 0, "currency_code": "USD" } }, "coupons_adjustment_amount": { "$ref": "#/components/schemas/Amount", "description": "The pro-rated amount of the coupons applied to the source invoice.", "example": { "value": 0.2, "currency_code": "USD" } }, "created_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date when the credit note was created. It is expressed in Coordinated Universal Time (UTC).", "example": "2022-09-14T16:35:31Z" }, "updated_at": { "$ref": "#/components/schemas/DateTimeWithZone", "description": "The date when the credit note was last updated. It is expressed in Coordinated Universal Time (UTC).", "example": "2022-09-14T16:35:31Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteItemObject" }, "description": "Array of credit note's items." }, "applied_taxes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteAppliedTaxObject" } }, "self_billed": { "type": "boolean", "example": false, "description": "Indicates if the credit note belongs to self-billed invoice. Self-billing is a process where an organization creates the invoice on behalf of the partner." } } }, "CreditNoteWithId": { "allOf": [ { "$ref": "#/components/schemas/CreditNote" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "CreditNoteCreateRequest": { "type": "object", "required": [ "invoice_id", "items" ], "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "The invoice unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "reason": { "$ref": "#/components/schemas/CreditNoteReason" }, "description": { "type": "string", "description": "The description of the credit note.", "example": "description" }, "credit_amount": { "$ref": "#/components/schemas/AmountNoCurrency", "nullable": true, "description": "The total amount to be credited on the customer balance.", "example": { "value": 0.1 } }, "refund_amount": { "$ref": "#/components/schemas/AmountNoCurrency", "nullable": true, "description": "The total amount to be refunded to the customer.", "example": { "value": 0.05 } }, "items": { "type": "array", "items": { "type": "object", "required": [ "fee_id", "amount" ], "properties": { "fee_id": { "type": "string", "format": "uuid", "description": "The fee unique identifier.", "example": "1a901a90-1a90-1a90-1a90-1a901a901a90" }, "amount": { "$ref": "#/components/schemas/AmountNoCurrency", "description": "The amount of the credit note item.", "example": { "value": 0.1 } } } }, "description": "The list of credit note's items.", "example": [ { "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "total_amount": { "value": 0.1, "currency_code": "USD" } }, { "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", "total_amount": { "value": 0.05 } } ] } } }, "AlertType": { "type": "string", "enum": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "description": "Type of alert", "x-enum-varnames": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-descriptions": [ "Alert based on current usage amount", "Alert based on metric current usage amount", "Alert based on metric current usage units", "Alert based on lifetime usage amount" ], "example": "CURRENT_USAGE_AMOUNT" }, "AlertThreshold": { "type": "object", "required": [ "value" ], "properties": { "code": { "type": "string", "description": "Identifier for this threshold. Used to distinguish between different thresholds.", "example": "warn" }, "value": { "type": "string", "pattern": "^[0-9]+\\.?[0-9]*$", "description": "A value that should trigger this alert. Must be a positive numeric string that can include a decimal point.", "example": "80.0" }, "recurring": { "type": "boolean", "description": "When true, enables retriggering of alerts at specified intervals after the last non-recurring threshold is exceeded. For example, with non-recurring thresholds at 500 and 1000, and a recurring threshold of 200, alerts will fire at 500, 1000, then every 200 thereafter (1200, 1400, etc.). Only one recurring threshold permitted per alert.", "example": false } } }, "Alert": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the alert, assigned by the system upon creation.", "example": "fb2d17b8-c66d-4269-b38e-9d62d37812e3" }, "external_subscription_id": { "type": "string", "description": "External identifier of the subscription that this alert is monitoring.", "example": "sub_external_12345" }, "metric": { "$ref": "#/components/schemas/MetricResponse" }, "type": { "$ref": "#/components/schemas/AlertType" }, "code": { "type": "string", "description": "The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts.", "example": "tokens_usage_alert" }, "name": { "type": "string", "description": "Human-readable display name for the alert. Used for identification in user interfaces.", "example": "Tokens Usage Alert" }, "previous_value": { "type": "number", "description": "The usage value from the last time this alert was evaluated. For monetary alerts, this represents currency amount; for unit alerts, this represents consumed units.", "example": 75.52 }, "last_processed_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when this alert was last evaluated by the system. Null for newly created alerts that haven't been processed yet. The system evaluates alerts at regular intervals (typically every 5 minutes) to check if usage has crossed any configured thresholds.", "example": "2025-05-01T12:00:00Z" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of configured thresholds that trigger this alert. Includes both one-time and recurring thresholds.", "example": [ { "code": "warn", "value": "80", "recurring": false } ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "The date and time when the alert was created.", "example": "2025-04-21T10:00:00Z" } } }, "AlertList": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" }, "description": "List of alerts", "example": [ { "id": "alert_01H3YT8P7Q5R3S1T2U0V4W9X8", "external_subscription_id": "sub_external_12345", "type": "current_usage_amount", "code": "current_usage_monetary_alert", "name": "Monetary Usage Alert", "previous_value": 1000, "last_processed_at": "2025-05-19T10:04:21Z", "thresholds": [ { "code": "warn", "recurring": false, "value": "99.0" } ], "created_at": "2025-04-20T10:00:00Z" } ] }, "meta": { "$ref": "#/components/schemas/PaginationMetadata" } } }, "AlertInput": { "type": "object", "required": [ "type", "code", "thresholds" ], "properties": { "type": { "$ref": "#/components/schemas/AlertType" }, "code": { "type": "string", "description": "The unique code to identify the alert.", "example": "storage_metric_alert" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert. Required for metric-specific alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).", "example": "storage_metric" }, "name": { "type": "string", "description": "The name of the alert.", "example": "Usage Warning at 80%" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of thresholds that will trigger this alert. At least one threshold is required." } } }, "AlertUpdateInput": { "type": "object", "properties": { "code": { "type": "string", "description": "The unique code to identify the alert.", "example": "api_calls_usage_alerts" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert. Only for alerts based on a metric.", "example": "api_calls" }, "name": { "type": "string", "description": "The name of the alert.", "example": "Usage alerts for API calls" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/AlertThreshold" }, "description": "List of thresholds that will trigger this alert. At least one threshold is required." } } }, "Link": { "type": "object", "properties": { "href": { "type": "string", "description": "URL for the action.", "format": "uri", "example": "https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA" }, "rel": { "type": "string", "description": "Relation type of the link.", "example": "self" }, "method": { "type": "string", "description": "HTTP method to use with the URL.", "example": "GET" } }, "required": [ "href", "rel", "method" ] }, "ResourceType": { "type": "string", "description": "Type of resource that triggered the webhook.", "enum": [ "subscription-alert", "wallet", "wallet-transaction" ], "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" ] }, "EventType": { "type": "string", "description": "Type of event that occurred in webhooks.", "enum": [ "COMMERCE.BILLING.SUBSCRIPTION-ALERT.TRIGGERED", "COMMERCE.BILLING.WALLET.CREATED", "COMMERCE.BILLING.WALLET.UPDATED", "COMMERCE.BILLING.WALLET.NET-BALANCE-DEPLETED", "COMMERCE.BILLING.WALLET.TERMINATED", "COMMERCE.BILLING.WALLET-TRANSACTION.CREATED", "COMMERCE.BILLING.WALLET-TRANSACTION.UPDATED" ], "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" ] }, "Envelop": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook event.", "example": "8PT597110X687430LKGECATA" }, "create_time": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Time when the webhook event was created.", "example": "2025-05-27T19:26:01Z" }, "event_version": { "type": "string", "description": "Version of the event schema.", "example": "1.0" }, "summary": { "type": "string", "description": "Brief description of the event.", "example": "A new alert was triggered." }, "resource_version": { "type": "string", "description": "Version of the resource schema.", "example": "1.0" }, "links": { "type": "array", "description": "HATEOAS links for the webhook event.", "items": { "$ref": "#/components/schemas/Link" } }, "resource_type": { "$ref": "#/components/schemas/ResourceType" }, "event_type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "id", "create_time", "resource_type", "event_type" ] }, "AlertTriggerType": { "type": "string", "nullable": true, "enum": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-varnames": [ "CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_AMOUNT", "METRIC_CURRENT_USAGE_UNITS", "LIFETIME_USAGE_AMOUNT" ], "x-enum-descriptions": [ "Alert based on current usage amount", "Alert based on metric current usage amount", "Alert based on metric current usage units", "Alert based on lifetime usage amount" ], "description": "Type of alert trigger", "example": "CURRENT_USAGE_AMOUNT" }, "triggered_alert_AlertThreshold": { "type": "object", "properties": { "code": { "type": "string", "description": "Code representing the threshold.", "example": "hard_limit" }, "value": { "type": "string", "description": "Value at which the threshold was triggered.", "example": "1100" }, "recurring": { "type": "boolean", "description": "Indicates whether the threshold is recurring.", "example": false } }, "required": [ "code", "value" ] }, "TriggeredAlertObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the alert.", "example": "ff604dc4-2223-412a-a8f4-8fde7dfd3346" }, "external_subscription_id": { "type": "string", "description": "External identifier of the subscription associated with the alert.", "example": "0705ad6b-c063-421a-87b6-a6c25f98c842" }, "metric_code": { "type": "string", "description": "The code of the metric associated with the alert.", "example": "storage_usage" }, "type": { "$ref": "#/components/schemas/AlertTriggerType" }, "code": { "type": "string", "description": "The code used to configure the alert.", "example": "storage_threshold_alert" }, "name": { "type": "string", "description": "The name used during the alert configuration.", "example": "Storage Usage Alert" }, "current_value": { "type": "number", "description": "The current usage value that was compared against configured thresholds when the alert was evaluated.", "example": 1200 }, "previous_value": { "type": "number", "description": "The usage value when the alert was evaluated previously.", "example": 900 }, "crossed_thresholds": { "type": "array", "description": "Array of thresholds that were crossed when the alert was triggered. Includes all applicable recurring thresholds.", "items": { "$ref": "#/components/schemas/triggered_alert_AlertThreshold" } }, "triggered_at": { "allOf": [ { "$ref": "#/components/schemas/DateTimeWithZone" } ], "description": "Time when the alert was triggered.", "example": "2025-05-27T19:25:02Z" } }, "required": [ "id", "external_subscription_id", "code", "type", "current_value", "triggered_at" ] } }, "parameters": { "per_page": { "name": "per_page", "in": "query", "description": "Number of records per page", "schema": { "type": "integer" } }, "page": { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer" } }, "id": { "name": "id", "in": "path", "required": true, "description": "Resource ID", "schema": { "type": "string" } }, "ext_sub_id": { "name": "external_subscription_id", "in": "path", "required": true, "description": "The unique external identifier of the subscription whose lifetime usage is to be retrieved.", "schema": { "type": "string" }, "example": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" }, "wallet_id": { "in": "path", "name": "wallet_id", "required": true, "description": " Wallet ID", "schema": { "type": "string" } }, "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" } } } } }