Custom Plans and prices

Custom Plans and prices allow you to transition active Subscriptions between different Billing Plans. You can switch a customer's Subscription Item from one price to another while maintaining a smooth billing experience — whether you're upgrading them from free to paid, moving between paid tiers, or applying custom pricing.

Use cases

This Subscription management feature simplifies essential Billing workflows:

• Promotional offers - Apply special pricing to existing subscribers.
• Tiered upgrades and downgrades - Move customers between different paid Plans based on their needs or usage.
• Plan migrations - Transition customers to new pricing structures as your product evolves.
• Complimentary / employee access - Create a $0 complimentary price and transition employees or other non-paying accounts onto paid Features without a public Pricing Table offer.

Update Subscription Plans or prices

You can update the price or Plan of an existing Subscription Item in the Clerk Dashboard or using the Backend API.

Using the Clerk Dashboard

To change the price or Plan of an existing Subscription Item:

1. Navigate to the Billing⁠ page in the Clerk Dashboard.
2. Under Subscription activity, select the subscriber whose plan or pricing you want to update.
3. Select the ... menu next to the Subscription Item you want to update.
4. Choose Change price or Change plan as needed.

If none of the existing pricing options meet your needs, you can create a custom price:

1. When updating a Subscription Item, select Create new price.
2. Configure the pricing details.
3. Use the new price immediately for your Subscription transition.

This is useful for creating one-off pricing arrangements for specific customers.

Using the Backend API

Using the Backend API to transition Subscription Items is useful for automating Plan changes or building custom billing workflows.

The following example demonstrates how to transition a Subscription Item from one price to another using a cURL command.

curl 'https://api.clerk.com/v1/billing/subscription_items/{subi_123}/price_transition' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --data '{
  "from_price_id": "cprice_123",
  "to_price_id": "cprice_456"
}'

For complete API documentation, see the Create price transition endpoint⁠.

Complimentary prices

A complimentary price is a custom price set to $0 (monthly, annual, or both) that you create for specific Subscriptions. Use it when someone should have the Features of a paid Plan without being charged and without that price appearing as a public offer on your Pricing Table.

Complimentary prices are a good fit when:

• Employees or internal users need production Feature parity
• Partner or dogfood accounts should stay on paid Features indefinitely
• You want complimentary access to show up as its own price, not as a Discount sitting on top of a commercial price

They are a poor fit when you want self-serve evaluation that converts to paid. Use a free trial for that. If an existing subscriber should stay on their catalog price for a few free months, use a 100% Discount. See Free and complimentary access for the full comparison.

Example: employee Plan access

Your product has a public Pro Plan at $50/month. Your team needs the same Pro Features in production, but you do not want employee accounts on the public Pro price or listed on the Pricing Table.

1. Navigate to the Billing⁠ page in the Clerk Dashboard.
2. Select the employee (or the Organization that represents their account).
3. Select the ... menu next to their Subscription Item, then choose Change price (or Change plan if they are still on the default Plan).
4. Select Create new price.
5. Set the monthly and/or annual amount to $0. Optionally set the Price description to something like Employee - Pro so the price is easy to identify in Billing later.
6. Complete the transition onto that complimentary price.

The employee now has Pro Features at $0. The $50 Pro price remains your public commercial price; the complimentary price exists only for the Subscriptions you move onto it.

When an employee leaves, transition their Subscription Item back to the default Plan or cancel it. Both changes take effect at the end of the current billing period, so the paid Features remain available until then. If access must end immediately, revoke the account's application access separately as part of your offboarding process. See How transitions work.

How transitions work

When you create a price transition, Clerk handles all the timing and billing logic automatically. The behavior depends on the type of transition. Transitioning to a $0 complimentary price follows the same scheduling rules as any other target price. There is simply no charge when the amount is $0.

Free-to-paid transitions

New customers with no active Subscription

When transitioning a customer from free to a paid Plan with no other active Subscription, the paid Plan activates immediately and the customer is charged right away.

Example: Moving a customer on the default Plan to Pro ($50/month). Pro activates immediately, customer is charged $50.

Customers with a canceled Subscription

Canceled Subscriptions are active Subscriptions that are scheduled to end in the future. When transitioning from free to paid and the customer has a canceled Subscription, the new paid Plan is scheduled as upcoming to avoid billing conflicts.

Example: A customer has an active Pro Subscription (canceled, expires March 20) with the default Plan scheduled as upcoming. When you transition the upcoming default Plan to Enterprise, Enterprise becomes the new upcoming Plan and will activate on March 20 instead of the default Plan.

Paid-to-paid transitions

When a customer already has an active paid Subscription, the new Plan is scheduled to start when their current billing period ends to prevent double-billing.

Example: Upgrading a customer from Basic ($20/month, paid through Feb 15) to Enterprise ($35/month) on Jan 15:

• Basic remains active through Feb 15 (already paid for)
• Enterprise becomes upcoming and activates Feb 15 (customer is charged then)
• No double-billing for overlapping periods

Paid-to-free transitions

When transitioning from paid to free, the default Plan is scheduled as upcoming, allowing the customer's current paid Subscription to run through its paid period before automatically activating the default Plan.