Upgrade or downgrade a subscription

Subscription services usually offer different plans, often with different price points, to cater to a wide variety of consumers. For example, a music streaming service might have different these plans:

A subscriber might start with the basic plan and then decide to upgrade to the premium plan to enjoy their music with no advertisements.

Change subscription plan

You can upgrade or downgrade to subscription plans under the same product. To change a plan, copy the following code and modify it.

Sample request

API endpoint used: Revise plan or quantity of subscription

curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/revise
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS-TOKEN" \
-d '{
  "plan_id": "P-5ML4271244454362WXNWU5NQ"
}'

Modify the code

After you copy the code in the sample request, modify the following:

Subscriptions using PayPal require the user to login and re-consent to the change using the approve HATEOAS URL returned in the response. If re-consent is not done or if it fails, the subscription continues to be billed on the existing plan. Subscriptions using direct card payment do not need re-consent.

Billing changes

The new price is effective starting on the next billing cycle. Proration and one-time fees aren't automatically supported. If you want to prorate the difference at the time the plan changes or charge one-time fees, you need to do these manually.

In the following example, a subscriber's billing cycle is at the beginning of the month, and they upgrade their plan mid-cycle.

See also