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

<Info>
  **Building with an AI agent?** See the [Agents billing guide](/agents/bill-customers) for how to set up customer billing programmatically.
</Info>

<Info>
  **Prerequisites:** Complete the [Track Usage Quickstart](/get-started/quickstart-track) first.
</Info>

<Steps>
  <Step title="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.
  </Step>

  <Step title="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 };
    ```
  </Step>

  <Step title="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>;
    }
    ```
  </Step>

  <Step title="Make Billed Requests">
    After checkout, use the customer ID to make requests that bill the customer:

    <Tabs>
      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>

    Balance checks and usage billing will apply to your customer automatically.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Meters" icon="gauge" href="/monetize/meters">
    Configure usage-based pricing rules for your meters
  </Card>

  <Card title="Checkout Guide" icon="credit-card" href="/monetize/checkout">
    Advanced checkout: credit bundles, completion handling, and more
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Receive notifications for customer and balance events
  </Card>

  <Card title="Forward Proxy" icon="route" href="/gateway/forward-proxy">
    Token generation, multi-provider routing, and error handling
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Checkout component not displaying" icon="window">
    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>

  <Accordion title="401 on forward token" icon="lock">
    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.
  </Accordion>
</AccordionGroup>