Tutorial

A short book on usage-based billing with Limitr. Each chapter is one small program you can paste into a file and run. Start at chapter 1, or jump to the one you need.

Limitr policies are written in Stof, a superset of JSON, and the tutorial introduces it along the way: how a policy is written (chapter 2), units (chapter 4), functions in a policy (chapter 7), the document underneath it all (chapter 14), and rules shared across a policy (chapter 15). No Stof knowledge is needed to start.

npm i @formata/limitr

The examples are TypeScript, and every one shows exactly what it prints. Save one as example.mts and run it with npx tsx example.mts, or with Bun or Deno. Limitr runs the same way in the browser.

1. Why Limitr: where usage-based billing gets hard, and what Limitr does about it
2. Your first policy: plans, features, and the allow call
3. Customers and plans: default plans, orgs and their users, upgrades
4. Limits and resets: units, daily and monthly periods
5. Hard, soft, and observe: deny, bill the overage, or just watch
6. Pricing and margins: prices, costs, tiers, and the margin of every call
7. AI calls: reserve and settle: costs that change per call, and usage you only know afterwards
8. Stacking entitlements: one action, several meters
9. Control and monetize: rate limits that protect you, next to the usage you sell
10. Seats, top-ups, and spend caps: org seats, prepaid credits, and budgets
11. Running it in your app: one engine per server, middleware, and saving state
12. Validation and errors: policy formats and what happens when something's wrong
13. Going to Cloud: the same code, with managed policies, billing, and analytics
14. The language underneath: Stof: reading a policy from your app, and asking it questions
15. Feature flags and custom deals: rollouts, kill switches, and giving or taking features per customer

The reference covers every policy field, engine function, and event. The same material ships with the npm package as skills for AI coding agents.