> ## 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. # Create a new subscription ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json post /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: post: tags: - Subscriptions summary: Create a new subscription operationId: CreateSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionCreateRequest' examples: SimpleSubscriptionCreate: value: name: API Count Usage Subscription1 external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-1753840215 billing_time: ANNIVERSARY start_date: '2025-07-30T04:26:24Z' end_date: '2025-09-09T04:26:24Z' plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 2e097d19-1350-4baf-8add-5d19ecef8113 properties: amount: '100.15' min_amount: value: 200 currency_code: USD SubscriptionCreationWithPlanOverrides: value: name: API Count Usage Subscription1 external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-_1753840215 billing_time: ANNIVERSARY start_date: '2025-07-30T01:54:40Z' end_date: '2025-09-09T04:26:24Z' plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 2e097d19-1350-4baf-8add-5d19ecef8113 properties: amount: '100.15' min_amount: value: 200 currency_code: USD SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment: value: name: API Count Usage Subscription1 external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-_1753840215 billing_time: ANNIVERSARY start_date: '2025-07-30T01:54:40Z' end_date: '2025-09-09T04:26:24Z' plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 2e097d19-1350-4baf-8add-5d19ecef8113 properties: amount: '100.15' min_amount: value: 200 minimum_commitment: invoice_display_name: Negotiated Minimum Commitment amount: value: 500 responses: '201': description: Subscription created successfully headers: paypal-debug-id: description: PayPal debug ID for tracking schema: type: string example: 23e54e9b-dc6d-4ec1-bb6a-3714135ec3a9 content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponse' examples: SimpleSubscriptionCreate: value: id: b71befc2-4799-402c-9d13-ca1f72759c64 name: API Count Usage Subscription1 external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-1753840215 billing_time: ANNIVERSARY status: ACTIVE plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 99fa7a6b-d005-43a5-8bab-0df7a2a721fb metric_id: d0682999-67a0-418e-b29b-3757426db01f charge_model: STANDARD properties: amount: '100.15' min_amount: value: 200 currency_code: USD current_period_start: '2025-07-30T01:54:40Z' current_period_end: '2025-08-05T23:59:59Z' start_date: '2025-07-30T04:26:24Z' end_date: '2025-09-09T04:26:24Z' SubscriptionCreationWithPlanOverrides: value: name: API Count Usage Subscription1 external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-_1753840215 billing_time: ANNIVERSARY status: ACTIVE plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 99fa7a6b-d005-43a5-8bab-0df7a2a721fb metric_id: d0682999-67a0-418e-b29b-3757426db01f charge_model: STANDARD properties: amount: '100.15' min_amount: value: 200 currency_code: USD start_date: '2025-07-30T01:54:40Z' end_date: '2025-09-09T04:26:24Z' current_period_start: '2025-07-30T01:54:40Z' current_period_end: '2025-08-05T23:59:59Z' id: b71befc2-4799-402c-9d13-ca1f72759c64 SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment: value: name: API Count Usage Subscription1 start_date: '2025-07-30T01:54:40Z' end_date: '2025-09-09T04:26:24Z' external_customer_id: 5eb02857-a71e-4ea2-bcf9-1753840218 external_id: Subscription_External_1 plan_code: Plan-Code-_1753840215 billing_time: ANNIVERSARY status: ACTIVE plan_overrides: amount: value: 20 currency_code: USD name: Plan-Name-_1753840215 trial_period: 14 charges: - id: 99fa7a6b-d005-43a5-8bab-0df7a2a721fb metric_id: d0682999-67a0-418e-b29b-3757426db01f charge_model: STANDARD properties: amount: '100.15' min_amount: value: 200 currency_code: USD minimum_commitment: amount: value: 500 currency_code: USD invoice_display_name: Negotiated Minimum Commitment plan_code: Plan-Code-_1753840215 created_at: '2025-07-31T13:00:04Z' updated_at: '2025-07-31T13:00:04Z' current_period_start: '2025-07-30T01:54:40Z' current_period_end: '2025-08-05T23:59:59Z' id: b71befc2-4799-402c-9d13-ca1f72759c64 '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SubscriptionCreateRequest: allOf: - $ref: '#/components/schemas/SubscriptionExtendedBase' - type: object properties: plan_overrides: $ref: '#/components/schemas/PlanOverridesRequest' 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' 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' PlanOverridesRequest: allOf: - $ref: '#/components/schemas/PlanOverridesBase' - type: object properties: charges: type: array items: allOf: - $ref: '#/components/schemas/SubscriptionUsageBasedCharge' - type: object properties: min_amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' minimum_commitment: $ref: '#/components/schemas/MinimumCommitmentRequest' chargeUsage: type: array items: $ref: '#/components/schemas/ChargeUsageThresholdRequest' tax_codes: $ref: '#/components/schemas/TaxCodes' trial_period: type: integer description: The number of days the plan's base cost is provided at no charge example: 5 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 SubscriptionUsageBasedCharge: type: object required: - id properties: id: type: string description: Unique identifier of the charge example: 1a901a90-1a90-1a90-1a90-1a901a901a90 tax_codes: $ref: '#/components/schemas/TaxCodes' properties: type: object description: Pricing thresholds that determine the charges 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 MinimumCommitmentRequest: type: object description: Minimum commitment for this plan. required: - amount properties: amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' invoice_display_name: type: string description: >- Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: Minimum Commitment (C1) tax_codes: $ref: '#/components/schemas/TaxCodes' ChargeUsageThresholdRequest: allOf: - $ref: '#/components/schemas/ChargeUsageThresholdBase' - type: object properties: amount: $ref: '#/components/schemas/AmountNoCurrency' TaxCodes: type: array items: type: string description: List of unique codes used to identify taxes to be applied. example: - standard_vat 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' 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' 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' 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 Currency: type: string description: Currency code in ISO 4217 format. example: USD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ responses: 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. 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. 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. 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 ````