Skip to main content
Credit packs (bundles) are add-on products you attach to a subscription configuration. They let subscribers buy extra credits in fixed amounts (e.g., “$10 for 15 credits”) without changing their plan. Bundles are only available to customers who are already on a subscription that includes those bundles.

​
How Bundles Relate to Subscription Configs

  • Each subscription config (plan) can have zero or more credit bundles.
  • A bundle belongs to exactly one subscription config.
  • When you open checkout in credit_bundle mode, you pass a credit_bundle_id and a connection_id. The connection must already be on a subscription that includes that bundle (same subscription config).
Example: You have a plan “Pro Monthly” with two bundles: “10 Credits (9)"and"50Credits(9)" and "50 Credits (39)”. A customer on Pro Monthly can buy either bundle. A customer on a different plan that has no bundles cannot use credit_bundle checkout for these bundle IDs.

​
Finding Bundle IDs (Dashboard / Frontend)

Bundle IDs are not exposed on the public REST API—they are available in the Lava dashboard and via the tRPC API used by the frontend when you manage subscription configs.
  • In the dashboard: go to Monetize → Subscription configs. When you create or edit a plan, you add credit bundles and see their names and pricing. The frontend uses the config’s creditBundles (including creditBundleId) from the subscription configs list/edit flows.
  • For the test checkout or any in-dashboard flow: the dashboard calls merchantSubscription.listConfigs, which returns each config with its creditBundles array. Each bundle has creditBundleId, name, cost, creditAmount. Use creditBundleId when triggering a credit_bundle checkout (e.g. test checkout or your own embedded flow that already has the config/bundle data from the dashboard).

​
When to Use credit_bundle Checkout Mode

Use credit_bundle when:
  • The customer already has a subscription (you have their connection_id).
  • You want them to buy a fixed credit pack (one of the bundles attached to their plan).
  • You want a single payment for that pack (no free-form amount).
Flow:
  1. Customer is on a plan that has credit bundles.
  2. In your app, you show available packs (from the config’s credit_bundles).
  3. Customer picks a pack; you have the credit_bundle_id from the config response.
  4. Create a checkout session with checkout_mode: 'credit_bundle', connection_id, and credit_bundle_id.
  5. Customer pays; credits are added to their current subscription cycle.
The connection must be on an active subscription for the same subscription config that owns the bundle. Otherwise checkout will fail.

​
Subscription Info and Credits

The connection subscription endpoint returns subscription details for a connection, including which plan they’re on and their remaining credits:
  • subscription.name, subscription.period_amount, subscription.included_credit — plan details.
  • subscription.credits.total_remaining, subscription.credits.cycle_remaining, subscription.credits.bundle_remaining — credit breakdown showing cycle credits vs purchased bundle credits.
  • subscription.pending_change — when present, shows scheduled cancellation or downgrade at end of cycle.
Use this to show “You’re on the Pro Monthly plan with $25 in credits remaining” and to decide which bundles to offer (only show bundles for that subscription_config_id).

​
Next Steps

Checkout Modes

Subscription, topup, credit_bundle, and onboarding

How Lava Billing Works

Plans, meters, and the billing flow