Skip to main content
A plan governs a customer’s access and billing. Plans specify:
  • Recurring charge — how much and how often (e.g., $25/month)
  • Included credits — usage allowance per billing cycle
  • Rollover rules — whether unused credits carry to the next cycle
  • Linked meters — which meters can draw from plan credits
  • Credit bundles — one-time credit packs customers can purchase
Plans and subscriptions are used interchangeably — in the SDK and API, plan templates are called subscription configs (subscription_config_id), and a customer’s enrollment is an active subscription. Despite the name, a plan doesn’t require a recurring charge — set the period amount to $0 for pure pay-as-you-go pricing where customers only pay for what they use.

​
Plan configuration

​
Recurring charge

The period amount is what the customer pays each billing cycle. This becomes their usage credit by default.
  • Billing interval: day, week, month, or year
  • Maximum: $10,000 per cycle
  • Period amount and billing interval are immutable after creation

​
Included credit

The dollar amount of usage allowance included each cycle. Three modes:
ModeIncluded creditUse case
Full credit (default)Equals period amountStandard plan — $25/month plan gives $25 in credits
Partial creditCustom amount ≤ period amountPlatform fee model — $25/month but only $20 in credits
No credit$0Access fee — subscription grants access, usage billed separately

​
Rollover

Control whether unused credits carry to the next cycle:
Rollover typeBehavior
noneUnused credits expire at cycle end
fullAll unused credits carry to the next cycle
Example with full rollover: 
Month 1: $25 credit, $15 used → $10 remaining
Month 2: $25 new + $10 rollover = $35 available
Example with none rollover: 
Month 1: $25 credit, $15 used → $10 forfeited
Month 2: $25 credit (fresh start)
Cycle credits and bundle credits have independent rollover settings. See Credit bundles below.

​
Linked meters

Select which meters can draw from this plan’s included credits. Only linked meters consume plan credits — unlinked meters bill separately. A plan can link multiple meters (e.g., one for chat, one for image generation), all drawing from the same credit balance.

​
Overage

When a customer exceeds their plan credits, Lava auto-charges their payment method for the overage at the meter’s rate. Service continues uninterrupted.

​
Credit bundles

Credit bundles are one-time credit packs that customers can purchase. Each bundle specifies:
  • Cost — what the customer pays (e.g., $10)
  • Credit amount — credits received (e.g., $15 for a 50% bonus)
Bundles are only available to customers on the plan that owns those bundles. Bundle credits have their own rollover setting, independent of cycle credit rollover. Checkout flow:
  1. Customer is on a plan with credit bundles
  2. Your app shows available packs
  3. Customer picks a pack → create a checkout session with checkout_mode: 'credit_bundle'
  4. Customer pays → credits added to their current cycle
const session = await lava.checkoutSessions.create({
  checkout_mode: 'credit_bundle',
  origin_url: 'https://yourapp.com',
  connection_id: 'conn_existing_subscriber_id',
  credit_bundle_id: 'cb_pack_id'
});
The connection must have an active subscription for the plan that owns the bundle.

​
Subscription lifecycle

​
Renewal

Subscriptions renew automatically at the end of each billing cycle. On renewal:
  • The customer is charged the period amount
  • A new cycle begins with fresh included credits
  • Rolled-over credits (if rollover is full) are added to the new cycle’s balance

​
Upgrades

When a customer upgrades to a higher-priced plan:
  • The new plan takes effect immediately
  • Customer is charged the full new plan amount
  • Current cycle updates with the new plan’s included credit
  • Unused credits (both cycle and bundle) carry over

​
Downgrades

When a customer switches to a lower-priced plan:
  • The current plan continues until the end of the billing cycle
  • The new plan takes effect at the next cycle boundary
  • Shows as pending_change.type: 'downgrade' in the API

​
Cancellation

Scheduled cancellation (customer-initiated):
  • Subscription stays active until the current cycle ends
  • Customer retains access to remaining credits
  • Shows as pending_change.type: 'cancellation' in the API
  • No further charges after the cycle ends
Immediate cancellation (merchant-initiated):
  • Subscription terminates immediately
  • Use for fraud, disputes, or refund scenarios

​
Querying subscription status

The connection subscription endpoint returns a customer’s plan details and remaining credits: 
const sub = await lava.subscriptions.getByConnection('conn_abc123');

console.log(`Plan: ${sub.plan.name}`);
console.log(`Credits remaining: ${sub.credits.total_remaining}`);
console.log(`Cycle ends: ${sub.cycle_end_at}`);

if (sub.pending_change) {
  console.log(`Pending ${sub.pending_change.type} at ${sub.pending_change.effective_at}`);
}
Credit breakdown:
  • credits.total_remaining — total available credits
  • credits.cycle_remaining — from included credit + cycle rollover
  • credits.bundle_remaining — from bundle purchases + bundle rollover

​
Next steps

Meters

Configure pricing rules that attach to your plans

Checkout

Embed checkout to onboard paying customers