Allow Learners to Change Their Subscription (Upgrade and Downgrade) Using API

    Plan Availability
    Legacy Plans
    Platform

The changeSubscriptionProduct API lets you, as a developer, build a self-serve flow where learners upgrade or downgrade their Thinkific Payments subscription to a different product. Learners can switch tiers on your site without contacting you or Thinkific Support.

This guide explains how to find a learner's subscription, preview a change, make the change, and cancel a scheduled downgrade using the API.

Applies to:

How Subscription Changes Work

Thinkific doesn't offer a built-in page where learners can switch their subscription to a different product. With the changeSubscriptionProduct API, you can build that experience on your own site.

Here's how it works:

  1. A learner chooses the product they want to move to.
  2. You call the changeSubscriptionProductPreview query with the learner's subscription ID and the target price ID.
  3. You show the learner the amount due today and their next billing amount and date.
  4. When the learner confirms, you call the changeSubscriptionProduct mutation.
  5. Thinkific updates the learner's billing and moves their course access to the new product.

You don't need to choose whether a change is an upgrade or a downgrade. Thinkific compares the two prices and decides for you. The preview response includes a timing field that tells you which one it is.

Target price timing What happens
Higher than the current price IMMEDIATE The learner is charged the prorated difference now. Their renewal date stays the same, and the change applies once the payment succeeds.
The same or lower PERIOD_END Nothing is charged now. The change is scheduled for the end of the current billing period, and the learner keeps their current product until then.

When access moves to the new product, learners keep their progress. Courses included in both the old and new product aren't affected, and any coupon on the subscription carries over to the new product.

Getting Started

Before you begin, you'll need an API Access Token or OAuth 2.0 application and familiarity with Thinkific's GraphQL API. Your credentials need these scopes:

  • read:subscriptions or write:subscriptions to preview a change
  • write:subscriptions to make or cancel a change
  • read:products if you request product details on a scheduled change

Site admins can change any subscription on the site. A learner who is signed in can change only their own subscription.

You'll need two IDs for each change:

  • Subscription ID: Query recurringPayments through userByEmail (for one learner) or site (for all subscriptions on the site), and use the id field. This is a Thinkific ID, not the payment processor's subscription ID. Both queries are available in beta only.
  • Target price ID: In your Thinkific admin, open the target product's pricing page. The price ID is in the link for that price.

Resources:

Previewing a Change

The preview shows the learner exactly what they'll pay before they confirm, and it doesn't change anything.

  • amountDueToday already includes the credit for unused time on the current product, so don't subtract the credit again when you display it.
  • For upgrades, keep the prorationDate value from the response and pass it to the mutation. This makes the charge match the quote.
  • A quote expires after one hour. After that, preview again before making the change.

All amounts are whole numbers in the currency's smallest unit. For example, 14600 means $146.00 in USD.

Making the Change

Call changeSubscriptionProduct with the subscription ID and target price ID. For upgrades, also pass prorationDate. The response tells you what happened:

  • paymentConfirmation is returned: The learner needs to verify their card before the upgrade can complete. See Handling Card Authentication below.
  • scheduledChange is returned: A downgrade is booked. The response includes the date it takes effect, the new price, and the new product.
  • Both are empty, with no errors: The upgrade was charged and has already taken effect.

When an upgrade completes, a new order for the new product appears in your admin. The order's line item and subtotal show the prorated amount charged, not the new product's full renewal price. The learner receives a receipt for the same prorated amount. The original order isn't changed. For a downgrade, the new order is created when the first renewal at the new price is paid. Thinkific doesn't send an email when a downgrade is scheduled. The new order email is sent when the downgrade takes effect, so consider showing or sending your own confirmation when a learner schedules one.

If a learner requests a new change while an earlier one is still pending, the new request replaces the earlier one. For example, an upgrade replaces a scheduled downgrade.

Handling Card Authentication

Some upgrades require the learner to verify their card, for example with 3-D Secure. When that happens, the mutation returns a paymentConfirmation object, and the change hasn't happened yet. A declined card on an upgrade is returned the same way, so your flow needs to handle declines as well as card verification. Downgrades can't be declined, because nothing is charged when they're scheduled.

To complete the payment, load Stripe.js with the publishableKey from the same response, then call stripe.handleNextAction with the clientSecret. Use handleNextAction, not confirmCardPayment, because the payment has already been submitted.

If the learner doesn't finish verifying before expiresAt (about one day), the change is discarded, and the subscription stays on its current product. You won't receive a notification when this happens.

Cancelling a Scheduled Downgrade

A downgrade can be cancelled any time before it takes effect. Call cancelScheduledSubscriptionProductChange with the subscription ID. The subscription keeps its current product and price, and the next renewal bills as normal.

Once the downgrade has taken effect, it can't be cancelled. Make a new change to move the learner back instead.

Handling Errors

When a change can't be made, nothing is charged. The mutations return userErrors with a code that explains why. The preview returns the same codes as top-level GraphQL errors, in extensions.code.

For example, INTERVAL_MISMATCH means the target price bills on a different interval than the subscription, and PRORATION_DATE_STALE means the quote is more than an hour old.

Important Considerations

  • Only Thinkific Payments subscriptions can change product. Subscriptions processed through Stripe or  PayPal aren't supported.
  • The target must be a recurring price for a different product on the same site, in the same currency, and on the same billing interval.
  • Payment plans and phased subscriptions cannot be adjusted (upgraded or downgraded).
  • Subscriptions that are paused, in a trial, set to cancel, or not active cannot be adjusted (upgraded or downgraded).
  • A subscription can have only one pending change at a time.
  • Downgrades always take effect at the end of the billing period. No refund or credit is issued for the remaining time on the current product.
  • These operations are in beta and aren't part of the stable API schema.

Frequently Asked Questions

Can learners see what they'll be charged before they upgrade? 

Yes. The changeSubscriptionProductPreview query returns the amount due today, the next billing amount, and the next billing date, without making any changes. Show these to the learner before they confirm.

Do learners lose their course progress when they change products?

No. Learners keep their progress when their subscription moves to a new product. Access to courses that are in both the old and new product isn't interrupted.

Will the learner get a receipt when they upgrade?

Yes. The learner receives a receipt for the prorated amount charged, and a new order for the new product appears in your admin showing that same amount.

What happens if a learner changes their mind after scheduling a downgrade?

Call cancelScheduledSubscriptionProductChange before the downgrade takes effect, and the subscription keeps its current product and price. To move to a different product instead, call changeSubscriptionProduct again. The new change replaces the scheduled one.

Related Articles:

Was this article helpful?
0 out of 0 found this helpful