Quickstart: Charge Your First Customer

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

Building with an AI agent? See the Agents billing guide for how to set up customer billing programmatically.

Prerequisites: Complete the Track Usage Quickstart first.

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.

Create a Checkout Session (Backend)

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

npm install @lavapayments/nodejs @lavapayments/checkout

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 };

Embed Checkout (Frontend)

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

'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>;
}

Make Billed Requests

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

SDK
Forward Token

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',
});

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.

Check the Dashboard

Go to Monetize > Customers to see your customer’s billing details, balance, and usage. Go to Analytics > Requests to see individual requests with cost breakdowns.

What’s Next?

Meters

Configure usage-based pricing rules for your meters

Checkout Guide

Advanced checkout: credit bundles, completion handling, and more

Webhooks

Receive notifications for customer and balance events

Forward Proxy

Token generation, multi-provider routing, and error handling

Troubleshooting

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').

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.

Get Started

AI Gateway

AI Spend

Monetize

Integration

SDK

Cookbook

Comparisons

Quickstart: Charge Your First Customer

What’s Next?

Meters

Checkout Guide

Webhooks

Forward Proxy

Troubleshooting

​What’s Next?

Meters

Checkout Guide

Webhooks

Forward Proxy

​Troubleshooting

What’s Next?

Troubleshooting