> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get all subscriptions ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json get /subscriptions openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /subscriptions: get: tags: - Subscriptions summary: Get all subscriptions operationId: GetSubscriptions 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' components: parameters: page: name: page in: query description: Page number schema: type: integer per_page: name: per_page in: query description: Number of records per page schema: type: integer schemas: SubscriptionResponse: allOf: - $ref: '#/components/schemas/SubscriptionExtendedBase' - type: object properties: id: type: string description: Unique identifier for the subscription example: b71befc2-4799-402c-9d13-ca1f72759c64 status: $ref: '#/components/schemas/SubscriptionStatus' plan_overrides: $ref: '#/components/schemas/PlanOverridesResponse' canceled_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: The date at which a pending subscription is canceled. example: '2025-01-01T00:00:00Z' terminated_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: The date at which an active subscription is canceled. example: '2025-01-01T00:00:00Z' current_period_start: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: Start date of the current billing period example: '2025-05-01T00:00:00Z' current_period_end: description: End date of the current billing period example: '2025-06-01T00:00:00Z' allOf: - $ref: '#/components/schemas/DateTimeWithZone' trial_ended_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- The date when the free trial is ended, represented in ISO 8601 date format example: '2025-05-01T00:00:00Z' PaginationMetadata: type: object properties: total_count: type: integer total_pages: type: integer current_page: type: integer 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 PlanOverridesResponse: allOf: - $ref: '#/components/schemas/PlanOverridesBase' - type: object properties: charges: type: array items: $ref: '#/components/schemas/UsageBasedCharge' minimum_commitment: $ref: '#/components/schemas/MinimumCommitment' chargeUsage: type: array items: $ref: '#/components/schemas/ChargeUsageThresholdResponse' taxes: type: array description: List of tax entities configured for the plan. items: $ref: '#/components/schemas/TaxResponse' trial_period: type: integer description: The number of days the plan's base cost is provided at no charge example: 5 DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' 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' 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 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 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 UsageBasedCharge: type: object required: - id - metric_id properties: id: type: string description: Unique identifier of the charge example: 1a901a90-1a90-1a90-1a90-1a901a901a90 metric_id: type: string description: Unique identifier of the metric charge_model: $ref: '#/components/schemas/ChargeModel' description: Defines the pricing model to calculate the charge properties: type: object description: Pricing thresholds that determine the charges taxes: type: array description: List of tax entities configured for the usage based charge. items: $ref: '#/components/schemas/TaxResponse' min_amount: allOf: - $ref: '#/components/schemas/Amount' 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' ChargeUsageThresholdResponse: allOf: - $ref: '#/components/schemas/ChargeUsageThresholdBase' - type: object properties: amount: $ref: '#/components/schemas/Amount' TaxResponse: description: >- Represents a customizable tax rate that can be applied to invoices and fees type: object allOf: - $ref: '#/components/schemas/TaxBase' - type: object properties: code: $ref: '#/components/schemas/TaxCode' id: type: string format: uuid description: Unique identifier of the tax example: 1a901a90-1a90-1a90-1a90-1a901a901a90 created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format example: '2025-06-01T00:00:00Z' ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string Amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' - type: object required: - currency_code properties: currency_code: $ref: '#/components/schemas/Currency' 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 MinimumCommitmentBase: type: object description: Minimum commitment for this plan. required: - amount properties: amount: allOf: - $ref: '#/components/schemas/Amount' invoice_display_name: type: string description: >- Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: Minimum Commitment (C1) taxes: type: array description: List of tax entities configured for the minimum commitment. items: $ref: '#/components/schemas/TaxResponse' 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' TaxBase: description: Base schema for tax request/response objects type: object required: - name properties: name: type: string description: Name of the tax example: TVA rate: type: string pattern: >- ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$ description: >- The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx. example: '20.00' description: type: string description: Detailed description of the tax for internal reference example: French standard VAT TaxCode: type: string description: >- Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: standard_vat 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}$ responses: Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: NOT_AUTHORIZED message: Authorization failed due to insufficient permissions. debug_id: 565f78f101498 details: - issue: PERMISSION_DENIED description: >- You do not have permission to access or perform operations on this resource. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' 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 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 ````