Plans

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

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.
`topups`	obj	`{}`	Topup name to Topup.
`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

Its own plan, set when it's created (createCustomer(id, 'pro')) or changed (setCustomerPlan).
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.
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.

Changing plans

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

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. 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). See 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:

Add a credit priced at the fee (pro_month above, $49).
Add a subscription entitlement metered in it, soft, with value: 0 and a monthly reset.
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.

Fields​

How a customer gets a plan​

Changing plans​

Plan fees​

Changing a plan's definition​

Reads​