Subscription upgrade and downgrade methods

Customers will eventually want to change the plan they are on and you need a way to alter their subscription.

How to upgrade or downgrade a plan subscription

Link to this section

• Set up the self-serve portal and allow customers to manage their own subscriptions. See self-serve portal for orgs and self-serve portal for users. In this scenario, the user selects the new plan from the pricing table. If any displayed plan offers annual pricing, they can turn on Pay annually to see and select yearly (or mixed yearly + monthly) prices — the same toggle used at sign-up. See How customers choose annual pricing. Self-serve changes stay within the pricing table’s plan group.
• Manually upgrade or downgrade via the Kinde UI (see below). The Change plan dialog lists published plans by plan group, so you can move a customer to a plan in a different group of the same type (organization or user). Choosing annual pricing when an admin assigns or changes a plan is not available in this flow yet.
• Overwrite the current agreement (subscription) by creating a new one via the Management API. The new plan can be in a different plan group. The current agreement is cancelled even if it belongs to a different group. The new plan must be the same customer type as the customer (organization or user).

Self-serve Pay annually applies when moving to a different plan. Customers cannot switch monthly ↔ annual on their current plan from the portal plan selection screen.

Change a plan subscription for an organization (B2B) or user (B2C)

Link to this section

1. Open the organization or user record in Kinde.
2. Go to Organizations and locate the org, or go to Users and locate the user.
3. Select Billing in the side menu. Details of the org’s or user’s plan are shown.
4. Select Change plan.
5. In the Choose plan dialog, plans are listed under their plan group. Select the new plan.
   • The customer’s current plan is labeled Current plan and cannot be selected.
   • A plan whose prices are not ready is labeled Prices are still syncing and cannot be selected.
6. Select Save. The customer’s plan is now updated.

Depending on the billing policies you have set, this information will be synced to Stripe and an invoice credit or bill will be issued.

Change to a plan in a different plan group

Link to this section

When you change a plan in the Kinde admin, you can select any published plan of the same customer type whose prices have finished syncing — including a plan in a different plan group. You can also assign a published plan of the same customer type in a different plan group by creating a new billing agreement via the Management API.

For example, you can move an organization from a plan in your default organization group to a plan in another organization group.

When you do this:

• The customer’s current agreement is cancelled, even if it belongs to a different plan group.
• A new agreement is created for the selected plan.

You cannot assign an organization plan to a user, or a user plan to an organization.

Customers who change their own plan in the self-serve portal still choose from the pricing table, which includes plans from one plan group only.

On the billing details page, the subscription card shows Plan and Next invoice in the same way as the customer portal (amount and date, including usage recorded so far when the plan has metered features). Agreement ID, Customer ID, and feature counts remain admin-only. See Billing and invoice cycles.

One-time purchases when changing plan

Link to this section

Changing plan starts a new subscription (a new billing agreement). One-time purchases on the previous agreement are not carried over.

When a plan is changed interactively in the self-serve portal or the Kinde admin, Kinde shows a confirmation dialog listing any active one-time purchases the customer will lose—for example credit packs or add-on unlocks.

After the change:

• Those purchases are no longer available on the new agreement.
• Amounts already paid are not refunded.
• If the same one-time purchase is available on the new plan, the customer must buy it again as a new purchase.

These forfeiture rules also apply when you change a plan via the Management API. Because the API overwrites the agreement directly without a Kinde confirmation dialog, API callers must check active purchases (for example with Get billing one-time purchases) and warn the customer before creating the new agreement.

See One-time purchases.