> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plans

> Define monthly plans in your catalog file, publish them, and change their terms safely with plan versions.

A plan grants `monthlyCredits` at the start of each monthly period, for `monthlyPriceCents` (US cents). A price of `0` makes it a [free plan](https://docs.integrateledger.com/configure-pricing/free-plans.md); anything else is a paid plan that syncs to Stripe and is bought through [Checkout](https://docs.integrateledger.com/getting-started/display-billing.md#sell-through-checkout).

## Define a plan

Add it to your catalog file, then publish with `npx integrateledger-cli push`:

```ts ledger.config.ts theme={"system"}
plans: [
	plan({ id: "free", name: "Free", monthlyCredits: 50, monthlyPriceCents: 0 }),
	plan({ id: "pro", name: "Pro", monthlyCredits: 1000, monthlyPriceCents: 2000 }),
	plan({ id: "scale", name: "Scale", monthlyCredits: 5000, monthlyPriceCents: 5000 }),
],
```

```json ledger.catalog.json theme={"system"}
"plans": [
  { "id": "free", "name": "Free", "monthlyCredits": 50, "monthlyPriceCents": 0 },
  { "id": "pro", "name": "Pro", "monthlyCredits": 1000, "monthlyPriceCents": 2000 },
  { "id": "scale", "name": "Scale", "monthlyCredits": 5000, "monthlyPriceCents": 5000 }
]
```

* **Credits last one period.** Unspent plan credits expire when the period ends; the next period starts with a fresh allowance. [Credits and balances](https://docs.integrateledger.com/concepts/credits.md) has the spend order.
* **Paid plans sync to Stripe** as a Product with a monthly Price. After a push the CLI reports each plan's sync: `synced`, `pending`, `failed`, or `awaiting_connection` until Stripe is connected. **Plans** in the dashboard has a retry for a plan that failed.
* **The `name` is what customers see** on Stripe Checkout and invoices.

## Change a plan

Edit the file and run `npx integrateledger-cli diff` before you push. Changing a plan's name, credits, price or overage creates a **new plan version**:

```
Plans
  ~ pro  Pro  new version · 1,000 credits/month, $29.00/month
      monthlyPriceCents  $20.00 → $29.00
      New plan version: customers who start this plan from now get these terms; current subscribers keep theirs
      Stripe: a new $29.00/month Price on the "Pro" Product
```

Current subscribers keep their terms. To move one onto different terms, [upgrade or downgrade](https://docs.integrateledger.com/configure-pricing/upgrades-and-downgrades.md) them to another plan.

Removing a plan from the file **archives** it: it can't be attached any more, and customers already on it keep it. Nothing is cancelled in Stripe. Adding the ID back restores it.

## Offer several tiers

Customers hold one plan at a time. List your plans on the billing page, sorted by price, and offer the pricier ones as upgrades and the cheaper ones as downgrades. [Display billing](https://docs.integrateledger.com/getting-started/display-billing.md) wires up the buttons.

To let customers keep working past their allowance, add [overage](https://docs.integrateledger.com/configure-pricing/overage.md). To sell credits without a subscription, add [credit packs](https://docs.integrateledger.com/configure-pricing/credit-packs.md).

> [!NOTE]
>
> **Other ways.** Plans can also be created in the dashboard under **Plans**, or with the [plan endpoints](https://docs.integrateledger.com/api-reference/plans/create.md). `npx integrateledger-cli pull` brings those edits back into your file.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.