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.

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⁠.

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:

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.