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

# Quickstart: Charge Your First Customer

> Set up pricing and checkout to charge customers for AI usage

In this quickstart, you'll set up a complete monetization flow: create a plan, embed checkout, and generate forward tokens for customer billing.

> [!NOTE]
>
> **Building with an AI agent?** See the [Agents billing guide](https://lava.so/docs/agents/bill-customers.md) for how to set up customer billing programmatically.

> [!NOTE]
>
> **Prerequisites:** Complete the [Track Usage Quickstart](https://lava.so/docs/get-started/quickstart-track.md) first.

**1. Create a Plan**

Go to **Monetize > Plans** and click **New Plan**. Configure:

* **Name**: e.g. "Pro Plan" (customers see this)
* **Monthly Amount**: e.g. `$25.00`
* **Rollover**: Whether unused balance carries over

Copy the **Plan ID** (`sc_xxxxx`) — you'll need it for checkout.

**2. Create a Checkout Session (Backend)**

Install the SDK and create a checkout session on your backend:

```bash theme={null}
npm install @lavapayments/nodejs @lavapayments/checkout
```

```typescript theme={null}
import { Lava } from '@lavapayments/nodejs';

const lava = new Lava();

// POST /api/checkout/create-session
const session = await lava.checkoutSessions.create({
  checkout_mode: 'subscription',
  origin_url: 'https://yourapp.com',
  plan_id: 'sc_your_plan_id'
});

// Return to frontend
return { checkoutSessionToken: session.checkout_session_token };
```

**3. Embed Checkout (Frontend)**

Use the `useLavaCheckout` hook to open the checkout modal. It handles phone verification, payment setup, and subscription creation in one flow.

```tsx theme={null}
'use client';

import { useLavaCheckout } from '@lavapayments/checkout';

export function PricingPage() {
  const { open } = useLavaCheckout({
    onSuccess: async ({ customerId }) => {
      // Save customerId to your database, linked to your user
      await fetch('/api/save-customer', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ customerId })
      });
    }
  });

  async function handleCheckout() {
    const res = await fetch('/api/checkout/create-session', { method: 'POST' });
    const { checkoutSessionToken } = await res.json();
    open(checkoutSessionToken);
  }

  return <button onClick={handleCheckout}>Subscribe Now</button>;
}
```

**4. Make Billed Requests**

After checkout, use the customer ID to make requests that bill the customer:

> [tab] SDK
>
> ```typescript theme={null}
> const customer = await lava.customers.retrieve(customerId);
>
> // gateway() handles forward token generation automatically
> const data = await lava.gateway('https://api.openai.com/v1/chat/completions', {
>   body: { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] },
>   customer_id: customer.customer_id,
>   meter_slug: 'my-meter',
> });
> ```

> [tab] Forward Token
>
> ```typescript theme={null}
> const customer = await lava.customers.retrieve(customerId);
>
> const forwardToken = lava.generateForwardToken({
>   customer_id: customer.customer_id,
>   meter_slug: 'my-meter'
> });
>
> // Use this token in the Authorization header of your API requests
> ```

Balance checks and usage billing will apply to your customer automatically.

**5. Check the Dashboard**

Go to **[Monetize > Customers](https://lava.so/dashboard/monetize/customers)** to see your customer's billing details, balance, and usage. Go to **[Analytics > Requests](https://lava.so/dashboard/monetize/explore)** to see individual requests with cost breakdowns.

## What's Next?

> [card] [Meters](https://lava.so/docs/monetize/meters.md)
>
> Configure usage-based pricing rules for your meters

> [card] [Checkout Guide](https://lava.so/docs/monetize/checkout.md)
>
> Advanced checkout: credit bundles, completion handling, and more

> [card] [Webhooks](https://lava.so/docs/integration/webhooks.md)
>
> Receive notifications for customer and balance events

> [card] [Forward Proxy](https://lava.so/docs/gateway/forward-proxy.md)
>
> Token generation, multi-provider routing, and error handling

## Troubleshooting

> [accordion] Checkout component not displaying
>
> Verify `@lavapayments/checkout` is installed, the session token hasn't expired (60-minute limit), and the component is in a client component (`'use client'`).

> [accordion] 401 on forward token
>
> Decode the token to inspect contents: `echo "token" | base64 -d`. Verify the secret key, customer ID, and meter slug are all valid and active in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.