Skip to main content
In this quickstart, you’ll set up a complete monetization flow: create a plan, embed checkout, and generate forward tokens for customer billing.
Prerequisites: Complete the Track Usage Quickstart 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 (sub_xxxxx) — you’ll need it for checkout.
2

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',
  subscription_config_id: 'sub_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.
'use client';

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

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

  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

Generate Forward Tokens

After checkout, retrieve the connection and generate forward tokens for the customer:
const connection = await lava.connections.retrieve(connectionId);

const forwardToken = lava.generateForwardToken({
  connection_id: connection.connection_id,
  meter_slug: 'my-meter'
});
Use this token in API requests exactly like the Create Your First Request flow — but now balance checks and usage billing will apply to your customer as well.
5

Check the Dashboard

Go to Monetize > Customers to see your customer’s connection, 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: topup mode, credit bundles, and completion handling

Webhooks

Receive notifications for connection and balance events

Forward Proxy

Token generation, multi-provider routing, and error handling

​
Troubleshooting

Verify @lavapayments/checkout is installed, the session token hasn’t expired (60-minute limit), and the component is in a client component ('use client').
Decode the token to inspect contents: echo "token" | base64 -d. Verify the secret key, connection ID, and meter slug are all valid and active in the dashboard.