Skip to main content
A subscription connects the following entities:
  • A customer.
  • The plan that the customer chooses. This defines what metric you charge the customer for and how you calculate the charges for usage.
A subscription also defines the billing configuration for the specific customer-plan relationship. This determines how you charge the customer - including when billing starts and which payment method to use. To create and configure subscriptions:
  1. Understand subscription configuration
  2. Create subscription
  3. Understand subscription lifecycle and manage subscriptions

​
Prerequisites

​
1. Understand subscription configuration

Before you create a subscription, collect these configuration details from your customer and system. Then, use the Create subscription API 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
    Important: 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 send a POST request to /v1/commerce/billing/subscriptions with the external ID and other request parameters. When you successfully create a subscription, PayPal returns a subscription id. 
curl -X POST --location '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.00,
              "currency_code": "USD"
          },
          "name": "Plan-Name-_1753840215",
          "trial_period": 14,
          "tax_codes": [
              "standard_vat"
          ],
          "charges": [
              {
                  "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113",
                  "properties": {
                      "amount": "1"
                  },
                  "min_amount": {
                      "value": 10.00
                  },
                  "tax_codes": [
                      "standard_vat"
                  ]
              }
          ],
          "minimum_commitment": {
              "amount": {
                  "value": 500.00
              },
              "invoice_display_name": "Negotiated Minimum Commitment",
              "tax_codes": [
                  "standard_vat"
              ]
          }
      }
  }'

​
Request body parameters

Parameter nameDescription
name
string		Human-readable name for the subscription. Used for display and identification.
external_customer_id
Required, string		External reference to the customer. Must contain only alphanumeric characters, underscores, and hyphens. This value links the subscription to a specific customer in your system.
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. Must reference an existing plan in your account.
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[].metric_id
Required, string		The ID of the metric this charge applies to. Required when including charges in plan_overrides.
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"].
Note: For the exhaustive list of request parameters, see API reference.

​
Response parameters

Note: 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
id
string		System-generated identifier for the created subscription. Use this ID for future operations, such as updating the subscription, tracking usage, or processing cancellations.
external_id
string		Your unique identifier for the subscription. Use this as the subscription ID when querying current and past usage data.
status
string		Current status of the subscription (ACTIVE, PENDING, CANCELED, or 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, call the Get subscription details 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
⌘I