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

# Show Credit Balance

> Display a customer's credit balance, subscription details, and low-balance warnings in your UI

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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Checkout" icon="credit-card" href="/monetize/checkout">
    Embed a checkout flow for subscriptions and credit bundles
  </Card>

  <Card title="Plans & Subscriptions" icon="repeat" href="/monetize/plans">
    Configure included credits and rollovers
  </Card>
</CardGroup>