# Plans, the default plan, and plan fees

> Plans group entitlements and credit packs. Plan fields, the default plan, how customers get a plan (directly or through refs), plan changes, and subscription fees.

# Plans

A **plan** is a named set of [entitlements](./entitlements) (what customers on it can do) and
[topups](./grants-and-topups) (credit packs they can buy). Every customer is on one plan, either its own or one it
gets through its refs.

```stof
policy: {
    credits: {
        request: { label: 'Request' }
        pro_month: { label: 'Pro, monthly', price: { amount: 49 } }
    }
    plans: {
        free: {
            label: 'Free'
            default: true
            entitlements: {
                api: {
                    limit: {
                        credit: 'request', value: 1000
                        resets: true, reset_inc: 1day
                    }
                }
            }
        }
        pro: {
            label: 'Pro'
            period: 'monthly'
            trial_period: 14days
            entitlements: {
                subscription: {
                    limit: {
                        credit: 'pro_month', mode: 'soft', value: 0
                        resets: true, reset_sch: 'monthly:1'
                    }
                }
                api: {
                    limit: {
                        credit: 'request', value: 100_000
                        resets: true, reset_sch: 'monthly:1'
                    }
                }
                sso: {}
            }
        }
    }
}
```

## Fields

| Field | Type | Default | Notes |
|---|---|---|---|
| `label` | str | `''` | Name for people. |
| `default` | bool | false | The plan for customers created without one (and without refs that have one). |
| `entitlements` | obj | `{}` | Entitlement name to [Entitlement](./entitlements). |
| `topups` | obj | `{}` | Topup name to [Topup](./grants-and-topups). |
| `period` | str | `'monthly'` | Billing period: `yearly`, `monthly`, `weekly`, or `daily`. Informational for your billing. |
| `subscription` | str | `'subscription'` | The entitlement that charges the plan's fee (below). |
| `trial_period` | duration | null | How long after a customer starts on the plan before the fee is charged (Ex. `14days`). |
| `hidden` | bool | false | Not used by the engine. A flag for your own pricing page, Ex. plans for one-off deals. |

The plan's name is its field name, and the engine fills `name` in for you.

## How a customer gets a plan

1. **Its own plan**, set when it's created (`createCustomer(id, 'pro')`) or changed (`setCustomerPlan`).
2. **Its refs' plan.** A customer with no plan of its own (`''`) uses the plan of the first customer in its refs that
   has one. This is how users get their org's plan.
3. **The default plan**, when neither gives one. With no default plan and no plan to inherit, the customer isn't
   created (`createCustomer` returns nothing), and calls for that ID are denied.

Gives and takes (custom deals) follow the same path: a user on its org's plan also gets the org's gives and takes.
See [Customers](./customers#gives-and-takes).

## Changing plans

<Tabs groupId="lang" queryString>
<TabItem value="typescript" label="TypeScript">

```ts
await limitr.setCustomerPlan('acme', 'pro', false);
```

</TabItem>
<TabItem value="python" label="Python">

```python
limitr.set_customer_plan('acme', 'pro', False)
```

</TabItem>
</Tabs>

`setCustomerPlan(id, plan, overwrite_meters)` moves a customer to another plan and sends `customer-plan-changed`.

- **`overwrite_meters: false`** keeps the usage counted so far, so an upgrade mid-month doesn't hand out a fresh
  allowance. A kept meter moves to the new plan's credit when the new plan prices the entitlement on another one
  (0.8.1). The engine (`set_customer_plan` in Stof) defaults to `false`.
- **`overwrite_meters: true`** starts the meters over. The TypeScript SDK defaults to `true`, so pass `false` to keep
  usage.

Gives, takes, overrides, purchased grants, and caps stay on the customer through a plan change. Included topup
balances move to the new plan's included topups by their `plan_change`, and are removed when the new plan has none
in that credit ([Plan changes](./grants-and-topups#plan-changes)). See [Change plans](../how-to/change-plans).

## Plan fees

Limitr meters usage; a plan's fixed fee is charged through an entitlement too, so it shows up in the same events and
invoices:

1. Add a credit priced at the fee (`pro_month` above, $49).
2. Add a `subscription` entitlement metered in it, soft, with `value: 0` and a monthly reset.
3. Call `ensureCustomerPlanQuantity(id)` (`ensure_plan_subscription` in Stof) for the customers who pay for the plan,
   Ex. the org, not each user. It's never called for you.

It counts one unit (sending `meter-overage` with `overage_price: 49`) at most once per period, and returns false
when there's nothing to charge: already charged this period, still in the trial, or the customer's own plan has no
`subscription` meter. The trial is measured from when the customer's subscription meter started.

## Changing a plan's definition

Plans can be added, replaced, or removed while the engine runs: `setPlan(id, stof)` and `deletePlan(id)` (they send
`plan-set` and `plan-removed`). Customers on a replaced plan keep their meters, and the next call uses the new limits.

## Reads

| Call | Returns |
|---|---|
| `plan(id, def = true)` | A plan by plan ID or customer ID, falling back to the default plan. |
| `defaultPlan()` | The default plan. |
| `planPeriod(id)` / `planTrialPeriod(id)` | The period, and the trial in milliseconds. |
| `planSubEntitlementName(id)` | The subscription entitlement's name. |
| `limit(planId, entitlement)` / `cost(planId, entitlement)` | A plan's limit and standard increment for an entitlement. |
