# Custom Plans and prices

> Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend [pinning](https://clerk.com/docs/pinning.md) your SDK and `clerk-js` package versions.

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](#using-the-clerk-dashboard) or [using the Backend API](#using-the-backend-api).

### Using the Clerk Dashboard

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

1. Navigate to the [**Billing**](https://dashboard.clerk.com/~/billing/subscriptions) 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.

- Your Secret Key is already injected into the code snippet.
- Replace the `subi_123` with the ID of the Subscription Item you want to transition.
- Replace the `cprice_123` with the ID of the price you want to transition from.
- Replace the `cprice_456` with the ID of the price you want to transition to.

* Replace `YOUR_SECRET_KEY` with your Clerk Secret Key.
* Replace the `subi_123` with the ID of the Subscription Item you want to transition.
* Replace the `cprice_123` with the ID of the price you want to transition from.
* Replace the `cprice_456` with the ID of the price you want to transition to.

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

For complete API documentation, see the [Create price transition endpoint](https://clerk.com/docs/reference/backend-api/tag/billing/POST/billing/subscription_items/%7Bsubscription_item_id%7D/price_transition){{ target: '_blank' }}.

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

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)