Skip to main content

Overview

Credit bundles are one-time credit purchases that customers can buy as add-ons to their subscription. Each bundle defines:
  • Cost - The price customers pay
  • Credit amount - The credits added to their balance
  • Subscription config - Which subscription plan the bundle belongs to
Bundles are configured per subscription plan in the Lava dashboard. Customers purchase bundles through checkout sessions with checkout_mode: 'credit_bundle'.

Methods

list()

List all credit bundles for your merchant account. Signature
list(params?: {
  subscription_config_id?: string;
  cursor?: string;
  limit?: number;
}): Promise<ListResponse<RestCreditBundle>>
Parameters
NameTypeRequiredDescription
subscription_config_idstringNoFilter by subscription configuration ID
cursorstringNoPagination cursor from previous response
limitnumberNoNumber of results to return (max 100, default 20)
Returns
{
  data: Array<{
    credit_bundle_id: string;
    subscription_config_id: string;
    name: string;
    cost: string;
    credit_amount: string;
    created_at: string;
  }>;
  has_more: boolean;
  next_cursor: string | null;
}
Example: List All Bundles
const { data: bundles } = await lava.creditBundles.list();

for (const bundle of bundles) {
  console.log(`${bundle.name}: $${bundle.cost} for $${bundle.credit_amount} credits`);
}
Example: Filter by Subscription Config
const { data: proBundles } = await lava.creditBundles.list({
  subscription_config_id: 'subconf_pro123'
});

console.log(`Pro plan has ${proBundles.length} credit bundle options`);

retrieve()

Retrieve a specific credit bundle by ID. Signature
retrieve(id: string): Promise<RestCreditBundle>
Parameters
NameTypeRequiredDescription
idstringYesCredit bundle ID
Returns Single RestCreditBundle object. Example
const bundle = await lava.creditBundles.retrieve('cb_abc123');

console.log(`Bundle: ${bundle.name}`);
console.log(`Cost: $${bundle.cost}`);
console.log(`Credits: $${bundle.credit_amount}`);
console.log(`Subscription Config: ${bundle.subscription_config_id}`);

Type Reference

RestCreditBundle

type RestCreditBundle = {
  credit_bundle_id: string;
  subscription_config_id: string;
  name: string;
  cost: string;           // Price in dollars (e.g., "10.00")
  credit_amount: string;  // Credits granted (e.g., "15.00")
  created_at: string;     // ISO 8601 timestamp
};

Common Use Cases

Display Bundle Options to Customers

async function getBundleOptions(subscriptionConfigId: string) {
  const { data: bundles } = await lava.creditBundles.list({
    subscription_config_id: subscriptionConfigId
  });

  return bundles.map(bundle => ({
    id: bundle.credit_bundle_id,
    name: bundle.name,
    price: parseFloat(bundle.cost),
    credits: parseFloat(bundle.credit_amount),
    savings: parseFloat(bundle.credit_amount) - parseFloat(bundle.cost)
  }));
}

// Usage
const options = await getBundleOptions('subconf_pro123');
// Returns: [{ id: 'cb_...', name: '$10 Bundle', price: 10, credits: 15, savings: 5 }]

Create Bundle Purchase Checkout

async function purchaseBundle(connectionId: string, bundleId: string) {
  const session = await lava.checkoutSessions.create({
    checkout_mode: 'credit_bundle',
    origin_url: 'https://yourapp.com',
    connection_id: connectionId,
    credit_bundle_id: bundleId
  });

  return session.checkout_session_token;
}

Track Bundle Purchases via Webhooks

// Listen for bundle purchase completion
app.post('/webhooks/lava', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'credit_bundle.purchased') {
    const { credit_bundle_id, connection_id, credit_amount } = data;

    console.log(`Connection ${connection_id} purchased bundle ${credit_bundle_id}`);
    console.log(`Added $${credit_amount} in credits`);

    // Update your records
    await database.recordBundlePurchase({
      connectionId: connection_id,
      bundleId: credit_bundle_id,
      amount: credit_amount
    });
  }

  res.json({ received: true });
});