Prepaid credits and wallets: bill usage against a balance

Prepaid credits increase predictability. You collect payments in advance, then monitor how the balance of your customers’ wallets evolves.

Create wallets

You can create up to 6 active wallets per customer, each with its own settings. A wallet can be scoped to specific fees or billable metrics, include usage limitations, and define its own recurring top-up rules. When a subscription or progressive billing invoice is generated, Lago automatically applies available wallet credits to reduce the invoice total. Wallet priority controls the order in which wallets are applied, from 1 to 50, where 1 is applied first and 50 last. When several wallets share the same priority, the wallet that expires soonest is applied first, and wallets without an expiration date are applied after those with one. Wallets with the same priority and expiration date are applied in creation order, oldest first.

Dashboard
API

To create a wallet for one of your customers through the user interface:

Access the “Customers” section via the side menu;
Select a customer from the list;
Open the “Wallets” tab and click “Add wallet & credits” on the right;
Choose a name for the wallet (optional);
Set the credit value (e.g. 1 credit = $5);
Define the wallet priority;
Enter the number of credits to be purchased and/or granted for free;
Determine whether the wallet transaction generates an invoice after a top-up or only following a successful payment;
Define a PO number to be used on invoices generated from this wallet;
Set the expiration date (optional); and
Click “Add wallet & credits” to confirm.

The currency of the wallet can differ from the default currency of the customer. Prepaid credits only apply to invoices sharing the same currency as the wallet.

Create a credit wallet

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/wallets" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "wallet": {
      "external_customer_id": "hooli_1234",
      "name": "Prepaid credits",
      "rate_amount": "1.0",
      "paid_credits": "100.0",
      "granted_credits": "50.0",
      "currency": "USD",
      "expiration_at": "2022-07-07T23:59:59Z",
      "invoice_requires_successful_payment": false,
      "transaction_metadata": [
        {
          "key": "top-up-type",
          "value": "manual"
        }
      ]
    }
  }'

Creation of a wallet via the user interface

Free credits are added to the customer’s wallet instantly, while purchased credits are added to the wallet when payment is confirmed (see below).

Payment terms

A wallet’s payment terms determine when invoices for its purchased credits are due. They apply to credit purchases, including manual and recurring top-ups. They do not set the payment terms of subscription invoices that use those credits. When creating or editing the wallet, open Invoicing settings. Keep the inherited customer term, or choose a payment-term type and its days or month settings, then save. If the customer has no term of their own, the billing entity’s default applies. To return to the default later, choose inheritance. For example, your customer uses Net 30 for subscriptions, but you set their wallet to Due on receipt. A top-up invoice dated April 10, 2026 is due April 10; a subscription invoice dated the same day is due May 10. See Payment terms for all six options and examples. Changes apply to future invoices; existing invoices retain their stored term. From the API, send payment_term when you create or update the wallet.

Giving a customer more time to pay does not make purchased credits available before payment. For example, a Net 15 top-up invoice dated April 10 is due April 25, but the credits are added only when payment is confirmed. The invoicing after successful payment option separately controls when the invoice is issued.

Real-time wallet balance

PREMIUM FEATURE ✨This feature is only available to users with a premium license. Please contact us to get access to Lago Cloud and Lago Self-Hosted Premium.

Keep track of the real-time balance of your customers’ wallets. Lago provides two types of balance:

Balance: the invoiced balance, which reflects the prepaid credits left in the wallet. It updates each time an invoice is finalized for the customer.
Ongoing balance: the balance that accounts for current usage, including taxes and draft invoices. It estimates the consumption of the balance close to real time, and also updates each time an invoice is finalized for the customer.

Application scope

Prepaid credits settled in a wallet are applied to upcoming subscription invoices. They are deducted from the post-tax subtotal, after any credit notes have been applied.

## EXAMPLE OF INVOICE

All subscriptions fee    $50.00
All usage-based fees     $20.00
Coupons                 -$10.00
-------------------------------
Subtotal (excl. tax)     $60.00
Tax (10%)                $ 6.00
-------------------------------
Subtotal (incl. tax)     $66.00
Credit notes            -$20.00
Prepaid credits         -$30.00
-------------------------------
Total                    $16.00

Prepaid credits do not apply to one-off invoices.

By default, prepaid credits apply to every fee type. You can refine this behavior by configuring limitation rules directly in the wallet. The create a wallet endpoint lists the fee types a wallet can be restricted to.

Dashboard
API

To limit the scope of prepaid credits through the user interface:

Create or edit an existing wallet;
In the “Limit wallet credits to specific objects” section, add one or more object limitations; and
Limit the prepaid credits to specific billable metrics, if you need to.

Selecting every item has the same effect as selecting none. Leave the options unselected unless you need a restriction.

Wallet form section limiting prepaid credits to specific objects — Limit wallet prepaid credits to specific objects

Scope wallet to specific fee

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/wallets" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "wallet": {
      "external_customer_id": "hooli_1234",
      "name": "Prepaid credits",
      "rate_amount": 1.0,
      "paid_credits": 100.0,
      "granted_credits": 50.0,
      "currency": "USD",
      "applies_to": {
        "fee_types": ["charge", "commitment", "subscription"]
      }
    }
  }'

Invoicing after successful payment option

When enabled, this option delays issuing an invoice for a wallet top-up until a successful payment is made. If disabled, the invoice is issued immediately upon the wallet top-up, whatever the payment status. This setting applies to all the transactions of the wallet, and you can override it on individual transactions or on recurring rules. With this option enabled, the invoice is issued on the day the payment succeeds and is due that same day, whatever the wallet’s payment term.

Wallet transaction limits

Dashboard
API

For each wallet, you can set minimum and maximum limits per paid transaction. When these limits are defined, any top-up attempt must fall within the specified range. Transactions below the minimum or above the maximum are rejected.

Wallet form section with the minimum and maximum amounts per paid top-up — Wallet transaction limits

Add wallet min and max limits

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/wallets" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "wallet": {
      "external_customer_id": "hooli_1234",
      "name": "Prepaid credits",
      "rate_amount": 1.0,
      "paid_top_up_min_amount_cents": 1000,
      "paid_top_up_max_amount_cents": 100000
    }
  }'

You can ignore these limits on a top-up by adding the ignore_paid_top_up_limits flag to the payload, or by enabling “Skip top-up limits for this transaction” in the dashboard. It works on single top-ups and on automatic ones (recurring wallet transactions).

Top-up form with the option to skip the top-up limits for this transaction — Skip wallet limits for a single transaction

Expiration date and termination

If you don’t set an expiration date, prepaid credits are carried over to the next billing period until the wallet balance is zero. If you define an expiration date, all the remaining credits are automatically voided when that date is reached. To modify the expiration date of the prepaid credits through the user interface:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Edit information”;
Modify the expiration date; and
Click “Edit information” to confirm.

The expiration date displayed in the app is based on the organization’s timezone. You can also terminate a wallet manually, before its expiration date:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Terminate wallet”; and
Click again to confirm.

Terminating a wallet instantly voids all the remaining credits. This action cannot be undone.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Prepaid credits and wallets: bill usage against a balance

Create wallets

Payment terms

Real-time wallet balance

Application scope

Invoicing after successful payment option

Wallet transaction limits

Expiration date and termination

​Create wallets

​Payment terms

​Real-time wallet balance

​Application scope

​Invoicing after successful payment option

​Wallet transaction limits

​Expiration date and termination

Create wallets

Payment terms

Real-time wallet balance

Application scope

Invoicing after successful payment option

Wallet transaction limits

Expiration date and termination