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 plans (plan_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.

​
Default free plan

Every merchant account starts with a Free plan ($0/month, no included credit). Customers are automatically placed on this plan until they complete checkout for a paid plan. You can customize the free plan from Monetize > Plans in the dashboard, for example to include a small credit allowance for free-tier users. The free plan works like any other plan: you can rename it, add included credit, link meters, and attach credit bundles.
Use the free plan to offer a trial experience. For example, set included credit to $1.00 so free-tier users can try your product before upgrading.

​
Plan configuration

const plan = await lava.subscriptions.createPlan({
  // Required
  name: 'Pro Plan',
  period_amount: '25.00',
  billing_interval: 'month', // 'day' | 'week' | 'month' | 'year'

  // Optional — defaults to period_amount
  included_credit: '20.00',

  // Optional — 'full' | 'none' (default: 'none')
  rollover_type: 'full',

  // Optional — 'full' | 'none' (default: 'full')
  bundle_rollover_type: 'full',

  // Optional — restrict which meters can draw from plan credits
  meter_ids: ['meter_abc123', 'meter_def456'],

  // Optional — one-time credit packs customers can purchase
  credit_bundles: [
    { name: 'Small Pack', cost: '5.00', credit_amount: '5.00' },
    { name: 'Large Pack', cost: '20.00', credit_amount: '25.00' },
  ],

  // Optional — auto top-up bundle (by index into credit_bundles array above)
  default_auto_top_up_bundle_index: 0,
});

​
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.

​
Credit bundles

When a customer’s cycle credits are depleted, the next request returns a 402 error (forward_token_customer_limit_reached). To keep service running, customers can upgrade to a new plan or make a one time credit purchase with credit bundles. Each credit bundle specifies:
  • Cost — what the customer pays (e.g., $10)
  • Credit amount — credits received (e.g., $15 for a 50% bonus)
Credit bundles are scoped to each plan. Bundle credits always rollover by default and can be configured independently 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',
  customer_id: 'conn_existing_subscriber_id',
  credit_bundle_id: 'cb_pack_id'
});
The customer must have an active subscription for the plan that owns the bundle.

​
Auto top-up

You can specify a credit bundle to be automatically purchased when a customer’s cycle credits are depleted. Auto top-up has two levels: Plan default — set default_auto_top_up_bundle_id on the plan. New subscriptions inherit this setting automatically. 
const plan = await lava.subscriptions.createPlan({
  name: 'Pro Plan',
  period_amount: '25.00',
  billing_interval: 'month',
  credit_bundles: [
    { name: 'Top-up Pack', cost: '10.00', credit_amount: '10.00' }
  ],
  default_auto_top_up_bundle_index: 0 // index into credit_bundles array
});
Per-subscription override — once a customer subscribes, you can change or disable auto top-up on their individual subscription. Use the customer’s active subscription ID (as_...): 
// Enable or change auto top-up bundle
await lava.subscriptions.update('as_abc123', {
  auto_top_up_bundle_id: 'cb_pack_id'
});

// Disable auto top-up (manual purchases only)
await lava.subscriptions.update('as_abc123', {
  auto_top_up_bundle_id: null
});
Set a plan default so customers get uninterrupted service out of the box. Customers who prefer manual control can disable auto top-up on their subscription.

​
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 via Lava dashboard):
  • Subscription terminates immediately
  • Customer is blocked from further requests
  • Use for fraud, disputes, or refund scenarios

​
Querying subscription status

The customer subscription endpoint returns a customer’s plan details and remaining credits: 
const { subscription } = await lava.customers.getSubscription('conn_abc123');

if (subscription) {
  subscription.plan.name;                  // plan name
  subscription.credits.total_remaining;    // total available credits
  subscription.credits.cycle_remaining;    // from included credit + rollover
  subscription.credits.bundle_remaining;   // from bundle purchases + rollover
  subscription.cycle_end_at;               // current cycle end date
  subscription.pending_change;             // null, or { type: 'cancellation' | 'downgrade', 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