Concepts
The records Revenue keeps and how they relate.
Features are bundled into plans. Attaching a plan to a customer creates a subscription and gives them balances. Your app checks and tracks against those balances. Revenue bills the subscription each period with an invoice.
Feature
One thing your app gates or counts. Its id is what your code sends.
| Kind | Use it for | Example |
|---|---|---|
metered, used up | Usage that refills each cycle | videos, messages, tokens |
metered, kept | Counts that stay until removed | seats, projects, workspaces |
credit_system | One balance that several features spend from | credits, where a video costs 10 and a script 2 |
boolean | Access with no count | SSO, custom branding |
A metered feature can listen to event names, so one track call can drain several features at once, such as a daily and a monthly message limit. A credit system can carry a credit value in USD and a markup, so balances.track_tokens turns AI tokens into credits by the model's price.
Plan
A price plus what it grants. Prices are set per currency in minor units (pesewas, kobo, cents). Each plan item grants an amount of one feature and says how it is charged:
| Charged as | Meaning |
|---|---|
| Included | Comes with the plan, resets on its own interval |
| Prepaid | Bought up front in packs, such as 500 credits or 5 seats |
| Pay as you go | Customers keep going past the included amount and the extra is billed at the end of the period, in packs, flat or in tiers |
Items can also roll unused amounts over, reset every few intervals, cap how much a customer can use, and choose whether usage starts fresh when the plan begins.
- Default plans are attached free to every new customer.
- Groups make plans replace each other. Upgrading is immediate and prorated; downgrading is scheduled for the end of the period.
- Add ons stack on top of a main plan. One off plans are purchases, such as credit packs, and stack every time they are bought.
- Trials run a number of days, with or without asking for a card first, once per customer.
- Versions go up when you change the price or contents of a plan that has customers. Current customers keep their version until you move them.
Customer
Your app's own user or account, keyed by your id. Create them with customers.get_or_create the first time you see them; it is safe to call on every sign in.
Entity
A seat, workspace or project under a customer. An entity can count against a feature (creating one uses a seat), and can have its own plans, balances and limits. Checks with an entity_id use the entity's balance first and fall back to the customer's.
Subscription
A customer's place on a plan: trialing, active, past_due, scheduled (a downgrade waiting for renewal) or ended. Revenue renews it itself: at the end of each period it builds an invoice and charges the saved card.
Balance
What a customer can still use of one feature. Grants from plans, add ons, top ups, rewards and rollovers stack; the breakdown lists every source. Resetting grants are used first, then grants that expire soonest, then grants that never expire. A pay as you go balance can go below zero; that part is billed at the end of the period.
Limits and alerts
Per customer, per entity or as plan defaults: allow or block going past the included amount, a spend limit on how far past, usage limits per day, week, month or year, usage alerts, and auto top ups. See Limits and alerts.
Invoice
Why money moved: the lines of a new plan, a renewal, a plan change, extra seats, a top up or a card check, with discounts and account credit applied. Unpaid invoices retry on day 1, 3 and 5 and have a hosted page the customer can pay on.
Reward
A coupon (percent or amount off, once, for a few invoices or forever), free usage or a free add on. Customers apply it with a promo code or earn it through a referral program.
Event and cost
Every track call is an event, with the value, the credits it spent and whether it was capped. A cost is what a provider charged you to serve a customer, in US dollars. Revenue joins costs with payments to give margin. See Cost tracking.