Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lava.so/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Problem

You want to show customers their remaining credits, subscription plan, and prompt them to add funds when their balance is low.

​
Solution

Use customers.getSubscription() to fetch the full credit breakdown, then render it in your UI. 
import { Lava } from '@lavapayments/nodejs';

const lava = new Lava();

async function getBalanceDisplay(customerId: string) {
  const result = await lava.customers.getSubscription(customerId);

  if (!result.subscription) {
    return { status: 'no_subscription', credits: null, plan: null };
  }

  const { credits, plan, pending_change } = result.subscription;
  const total = parseFloat(credits.total_remaining);
  const LOW_BALANCE_THRESHOLD = 2.0; // $2.00

  return {
    status: total <= 0 ? 'empty' : total < LOW_BALANCE_THRESHOLD ? 'low' : 'ok',
    credits: {
      total: total.toFixed(2),
      fromPlan: parseFloat(credits.cycle_remaining).toFixed(2),
      fromBundles: parseFloat(credits.bundle_remaining).toFixed(2),
    },
    plan: {
      name: plan.name,
      price: `$${plan.period_amount}/${plan.billing_interval}`,
      included: `$${plan.included_credit}`,
      rollover: plan.rollover_type,
    },
    pendingChange: pending_change
      ? {
          type: pending_change.type,
          effectiveAt: pending_change.effective_at,
          newPlan: pending_change.name ?? null,
        }
      : null,
  };
}

​
API Route

app.get('/api/balance', async (req, res) => {
  const balance = await getBalanceDisplay(req.user.customerId);

  if (balance.status === 'empty') {
    return res.status(402).json({
      ...balance,
      message: 'No credits remaining. Please add funds to continue.',
    });
  }

  res.json(balance);
});

​
Pre-Request Check

Gate AI requests on credit availability: 
async function ensureCredits(customerId: string) {
  const result = await lava.customers.getSubscription(customerId);

  if (!result.subscription || parseFloat(result.subscription.credits.total_remaining) <= 0) {
    throw new Error('No credit balance — prompt user to add funds');
  }

  return result.subscription;
}

​
Next Steps

Checkout

Embed a checkout flow for subscriptions and credit bundles

Plans & Subscriptions

Configure included credits and rollovers