Overview
Lava Monetize currently operates on a prepaid credit system. Customers subscribe to a plan, receive usage credits, and each request draws down their balance based on meter pricing.What happens on every request
- Identify: Lava resolves the
customer_id(who to bill) andmeter_slug(which pricing to apply) - Price: The meter calculates a fee based on its rate structure and the request’s usage (tokens, characters, seconds, or request count)
- Charge: The meter fee is deducted from the customer’s plan cycle credits
- Handle depleted credits: When credits run out, the request is blocked. If auto top-up is configured, Lava automatically purchases the configured credit bundle so the next request can succeed
Key concepts
Plans
A plan governs a customer’s access and billing. Plans specify the recurring charge (e.g. $25/month), how much of that becomes usage credits, which meters are active, and whether unused credits roll over. When a customer’s credits run out, requests are blocked until credits are replenished. You can configure auto top-up with a credit bundle so Lava automatically purchases more credits when the balance is depleted.In the SDK and API, plan templates are called plans (
plan_id).Meters
A meter represents a billable dimension of usage (e.g. image generations, documents processed). You choose the unit (tokens, characters, seconds, or requests) and the fee model (fixed rate, percentage markup, or tiered pricing). Each meter has a meter slug you include in forward tokens or post-request calls to apply that pricing. Meters attach to plans. A single plan can link multiple meters (e.g. one for chat and one for image generation), all drawing from the same credit balance. A meter can also be shared across multiple plans.Checkout & Customers
Checkout is the hosted payment flow you embed in your app. It handles phone verification, payment setup, and subscription creation. When a customer completes checkout, Lava creates a customer — the billing relationship between that customer and your merchant account. The customer’s ID (customer_id) is what you pass in every request to bill that customer. Store it in your database alongside your internal user ID.
A customer completes checkout once to subscribe — after that, you use the customer_id for all billing. Checkout is needed again only to switch plans or purchase credit bundles.
Reporting usage to Lava
There are two ways to get usage into Lava: routing requests through the AI Gateway (recommended), or reporting usage after the fact via the API.| Gateway | Post-request reporting | |
|---|---|---|
| How it works | Route AI requests through Lava’s AI Gateway. Usage is tracked automatically. | Report usage to Lava via POST /v1/requests after each operation. |
| Best for | AI APIs (OpenAI, Claude, Gemini, etc.) | Any billable operation — API calls, compute, storage, or AI with your own keys |
| Setup | Swap your base URL to Lava’s proxy | Add a reporting call after each operation |
| Balance enforcement | Pre-request — blocks if insufficient credits | Post-request only — request already ran |
| Products | Gateway + Monetize | Monetize only |