Create subscriptions - Paypal Docs

Limited Release

A subscription is a customer’s enrollment in a pricing plan with specific billing configuration. Subscriptions connect the following:

Customers who receive service and are billed for usage.
Pricing plans that define metrics, pricing models, and features.
Billing configuration that determines when billing starts and which payment method to use.

Prerequisites

Create and set up all pricing plans that you offer to customers.
Register customers who use Usage-based Billing plans.

1. Understand subscription configuration

Before you create a subscription, collect these configuration details from your customer and system. Then, you can make a POST call to the Create subscription endpoint to send the information to PayPal. Customer information External customer ID: Set this to the unique identifier (external_id) returned when you created the customer. This value links the subscription to a specific customer. Plan details

Plan code: Set this to the code for the pricing plan your customer selected.
Plan overrides: You can negotiate special contracts with customers. These contracts can include custom discounts and price adjustments that differ from your standard plan. When you create the subscription, you can override the base plan with these negotiated terms. You can override these plan elements:
- Subscription invoice display name
- Subscription fee
- Plan trial period
- Plan taxes
- Charge properties (except the charge model)
- Charge minimum spending
- Charge taxes
- Charge invoice display name
- Minimum commitment amount and display name

If you later update the original plan, you can choose to cascade those updates to subscriptions with overridden plan values. You can use the cascading_updates parameter in your plan update request to do this.

Billing setup

Billing time: Choose when billing cycles start. You can start them on a calendar date (like the 1st of each month) or on the same date the subscription begins each month.
Start date: Send the date when your customer’s subscription starts.
End date: Optionally specify when the subscription should end if it has a defined term.

Additional required information External ID: Create and set a unique identifier for your subscription.

2. Create subscription

Use a valid access token and make a POST call to the /v1/commerce/billing/subscriptions endpoint. Include the following parameters:

Parameter	Action
`name` string	Provide a human-readable name for the subscription.
`external_customer_id` Required, string	Set to the `external_id` returned when you registered the customer.
`external_id` Required, string	Set a unique identifier for this subscription. Use only alphanumeric characters, underscores, and hyphens.
`plan_code` Required, string	Set to the `code` returned when you created the pricing plan.
`billing_time` string	Set to `CALENDAR` to align billing cycles to calendar periods (for example, bill on the 1st of each month) or `ANNIVERSARY` to start billing cycles from the subscription date.
`start_date` string	Set the date when the subscription begins in ISO 8601 format with timezone. Usage tracking starts from this date.
`end_date` string	Set the date when the subscription ends in ISO 8601 format with timezone. Optional for subscriptions with a specific end date.
`plan_overrides` object	Add plan customizations based on negotiated contracts. Possible values: `amount`, `name`, `trial_period`, `tax_codes`, `charges`, `minimum_commitment`.
`plan_overrides.tax_codes` array	Provide an array of tax codes to apply at the plan level (for example, `["standard_vat"]`).
`plan_overrides.charges[].id` Required when plan_overrides.charges[] provided, string	Set to the `usage_based_charges[].id` returned when you created the pricing plan.
`plan_overrides.charges[].tax_codes` array	Provide an array of tax codes to apply to this charge (for example, `["standard_vat"]`).
`plan_overrides.minimum_commitment.tax_codes` array	Provide an array of tax codes to apply to the minimum commitment (for example, `["standard_vat"]`).

For information on all parameters, see API reference.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Premium Monthly Subscription",
      "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.05,
              "currency_code": "USD"
          },
          "name": "Plan-Name-_1753840215",
          "trial_period": 14,
          "tax_codes": [
              "standard_vat"
          ],
          "charges": [
              {
                  "id": "2e097d19-1350-4baf-8add-5d19ecef8113",
                  "properties": {
                      "amount": "100.15"
                  },
                  "min_amount": {
                      "value": 200.00
                  },
                  "tax_codes": [
                      "standard_vat"
                  ]
              }
          ],
          "minimum_commitment": {
              "invoice_display_name": "Negotiated Minimum Commitment",
              "amount": {
                  "value": 500.00
              },
              "tax_codes": [
                  "standard_vat"
              ]
          }
      }
  }'

A successful call returns a 201 Created response. The response includes the following parameter:

Parameter	Description	Further action
`external_id` string	Unique identifier for the subscription.	Use this `external_id` when querying current and past usage data.

For information on all parameters, see API reference.

3. Understand subscription lifecycle and manage subscriptions

Subscriptions progress through distinct states throughout their lifecycle. These states determine billing behavior and available management actions. To monitor a subscription’s current state, make a GET call to the /v1/commerce/billing/subscriptions/ endpoint and review the status parameter. The subscription’s lifecycle state determines the management actions you can perform to ensure proper subscription handling.

State	Description	Customer billing	Possible management actions
ACTIVE	Subscription is running and tracking usage	Customer is billed according to plan	Update subscription details – customer ID, plan configuration, billing setting, and customer metadata. Cancel subscription
PENDING	Subscription is created but not yet started	No billing occurs	Update subscription details - limited to plan configuration
CANCELED	Pending subscription is canceled before becoming active	No billing occurs	Subscription cannot be modified
TERMINATED	Previously active subscription is ended	No billing occurs, final invoice may be generated	Subscription cannot be modified

Usage-based Billing

​Prerequisites

​1. Understand subscription configuration

​2. Create subscription

​3. Understand subscription lifecycle and manage subscriptions

Prerequisites

1. Understand subscription configuration

2. Create subscription

3. Understand subscription lifecycle and manage subscriptions