Skip to main content
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

​
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 with all required request parameters. On successful subscription creation, the PayPal server returns a subscription ID. 
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"
              ]
          }
      }
  }'

​
Request body parameters

For the exhaustive list of request parameters, see API reference.
Parameter nameDescription
name
string		Human-readable name for the subscription. Used for display and identification.
external_customer_id
Required, string		Unique identifier that identifies the customer. Use the external_id you provided when you registered the customer.
external_id
Required, string		Unique identifier for the subscription. Must contain only alphanumeric characters, underscores, and hyphens.
plan_code
Required, string		Unique code that identifies the pricing plan. Use the code you provided when you created the pricing plan.
billing_time
string		Determines billing cycle alignment.

Possible values:
CALENDAR: Billing cycles align to calendar periods (for example, monthly subscriptions bill on the 1st of each month)
ANNIVERSARY: Billing cycles start from the subscription date
start_date
string		Date when the subscription begins. Usage tracking starts from this date. Must be in ISO 8601 format with timezone.
end_date
string		Date when the subscription ends. Must be in ISO 8601 format with timezone. Optional for subscriptions with a specific end date.
plan_overrides
object		Plan customizations based on negotiated special contracts. The customizations are applicable only to this subscription and do not change the base plan. Can include amount, name, trial_period, tax_codes, charges, and minimum_commitment (optional).
plan_overrides.tax_codes
array		List of unique codes used to identify taxes to be applied at the plan level. Example: ["standard_vat"].
plan_overrides.charges[].id
Required when plan_overrides.charges[] provided, string		Unique identifier that identifies the charge to override. Use the id from the plan’s usage_based_charges[] array.
plan_overrides.charges[].tax_codes
array		List of unique codes used to identify taxes to be applied to this charge. Example: ["standard_vat"].
plan_overrides.minimum_commitment.tax_codes
array		List of unique codes used to identify taxes to be applied to the minimum commitment. Example: ["standard_vat"].

​
Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response parameters, see API reference.
Parameter nameDescription and further action
external_id
string		Unique identifier for the subscription.
Use this external_id in future operations, such as when querying current and past usage data.
status
string		Current status of the subscription.

Possible values: ACTIVE, PENDING, CANCELED, TERMINATED.
current_period_start
string		Start date of the current billing period in ISO 8601 format.
current_period_end
string		End date of the current billing period in ISO 8601 format.
created_at
string		Timestamp when the subscription was created in ISO 8601 format.

​
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.
StateDescriptionCustomer billingPossible management actions
ACTIVESubscription is running and tracking usageCustomer is billed according to planUpdate subscription details – customer ID, plan configuration, billing setting, and customer metadata.

Cancel subscription
PENDINGSubscription is created but not yet startedNo billing occursUpdate subscription details - limited to plan configuration

CANCELEDPending subscription is canceled before becoming activeNo billing occursSubscription cannot be modified
TERMINATEDPreviously active subscription is endedNo billing occurs, final invoice may be generatedSubscription cannot be modified