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
connection_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 credits.
- Handle overages: When credits run out, Lava auto-charges the customer’s card or requires a credit bundle purchase
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, Lava either auto-charges their card at the meter’s rate (overage) or requires them to purchase a credit bundle — a prepaid block of credits with its own pricing.In the SDK and API, plans are called subscription configs (
subscription_config_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 & Connections
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 connection — the billing relationship between that customer and your merchant account. The connection’s ID (connection_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 connection_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 |