Pricing models

Every model below is configuration. Your app code stays the same: check, track, attach.

Credits and top upsCopy Anchor Link

One balance that several features spend from.

1. Create metered features basic_message and premium_message.
2. Create a credit system credits with credit_schema 1 for basic and 10 for premium.
3. Plan pro: USD 20.00 a month with credits included 2,000, resetting monthly.
4. Plan top_up: interval one_off, item credits with usage_model: "prepaid", USD 1.00 per 100 credits (billing_units: 100), no reset.

await revenue.check({ customerId, featureId: "premium_message" });
await revenue.track({ customerId, featureId: "premium_message", value: 1 });
await revenue.attach({ customerId, planId: "top_up", featureQuantities: [{ featureId: "credits", quantity: 500 }] });

Checks and tracks name the underlying feature; Revenue spends the credits. Top ups stack and never reset, and the monthly grant is used first. Add an auto top up to refill without asking.

AI credits priced by tokensCopy Anchor Link

Give the credit system credit_value_usd: 0.01 and markup: 0.3, then report tokens:

await revenue.balances.trackTokens({ customerId, modelId: "anthropic/claude-haiku-4-5", inputTokens: 1200, outputTokens: 400 });

Revenue prices the tokens, adds 30 percent, spends credits and records the real provider cost, so the margin view shows exactly what you kept. Use locks when you need to reserve before a long completion.

Free trialsCopy Anchor Link

trial_days: 14 on a paid plan. With trial_card_required: false the trial starts on attach with no checkout and ends unless they pay. With true the card is checked first, and the plan bills automatically when the trial ends. One trial per customer per plan, and per device when you send fingerprint.

Subscriptions with tiersCopy Anchor Link

Plans in one group replace each other: free, pro, business. Upgrades are immediate and prorated; downgrades wait for the end of the period. Annual pricing is a separate plan in the same group, such as pro_annual at interval: "year".

Pay as you goCopy Anchor Link

An item with usage_model: "usage_based", included: 1000, USD 1.00 per 1,000 calls. Customers keep going past 1,000; the balance goes below zero and the extra is on the next renewal invoice. Cap it with max_purchase on the plan or a spend limit per customer. For volume discounts use tiers with tier_behavior: "graduated" or "volume".

A plan with no base price and only pay as you go items asks for a card on attach, so usage can be billed later.

SeatsCopy Anchor Link

A metered feature seats with consumable: false. Either:

• Prepaid seats: item usage_model: "prepaid", USD 10.00 per seat. Buy with feature_quantities on attach; add more with billing.update (charged now for the days left) or fewer (from renewal).
• Seats as they are used: item usage_model: "usage_based", included: 3, USD 5.00 per extra seat, proration: "prorate_immediately". Create an entity per member with feature_id: "seats"; the fourth seat is charged for the days left, and renewals bill every seat past three.

Per seat allowancesCopy Anchor Link

Attach a plan to each entity (billing.attach with entity_id) to give every member their own 50 credits a month, while the company keeps a shared pool on the customer. Checks with entity_id use the member's balance first.

HybridCopy Anchor Link

Mix the above in one plan: a base price, included credits that roll over, pay as you go API calls, seats with included members, and an on and off feature like SSO.

Rollovers and expiring grantsCopy Anchor Link

rollover: { "max": 500, "duration_cycles": 2 } on an item carries up to 500 unused units into the next two periods. balances.create with expires_at gives grants that vanish on a date. Revenue always spends resetting grants first, then the ones expiring soonest.

Custom dealsCopy Anchor Link

Pass customize to attach for one customer: a different price, more included units, a different overage price. The deal stays on their subscription through renewals and plan versions.

Changing prices laterCopy Anchor Link

Edit the plan. If it has customers, Revenue saves a new version: new customers get it, current customers keep their version and price. Move them when you are ready with plans.migrate or the Move them button on the plan.