Top-up and void credits

Credit purchases and top-ups

Lago automatically generates an invoice for each purchase. Taxes do not apply to credit purchases, which are considered as advance payments. Payment must be made in order for credits to be added to the customer’s wallet (the payment status of the top-up invoice must be succeeded).

On a paid top-up, Lago rounds the top-up credits to the nearest cent, to comply with the decimal rounding rules for amounts. This does not affect free credits.

Dashboard
API

To top up a wallet through the user interface:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Top up credits”;
Enter the number of credits to be purchased and/or granted for free;
Define transaction metadata (optional & available only via API);
Determine whether the wallet transaction generates an invoice after a top-up or only following a successful payment; and
Click “Top up credits” to confirm.

Coupons do not apply to credit purchases and top-ups.

Top up a credit wallet

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

curl --location --request POST "$LAGO_URL/api/v1/wallet_transactions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "wallet_transaction": {
      "wallet_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "paid_credits": "20.0",
      "granted_credits": "10.0",
      "invoice_requires_successful_payment": false,
      "metadata": [
        {
          "key": "top-up-type",
          "value": "manual"
        }
      ]
    }
  }'

Invoicing top-up 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, regardless of the payment status. This setting can be applied to individual transactions.

Void credits

You can deduct an exact number of credits from the balance of a wallet. This action is instantaneous and cannot be undone.

Dashboard
API

To void credits through the user interface:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Void credits”;
Enter the number of credits to void;
Define transaction metadata (optional & available only via API); and
Click “Void credits” to confirm.

Void credits from a wallet

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

curl --location --request POST "$LAGO_URL/api/v1/wallet_transactions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "wallet_transaction": {
      "wallet_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "voided_credits": "20.0",
      "metadata": [
        {
          "key": "top-up-type",
          "value": "manual-void"
        }
      ]
    }
  }'

Setup recurring top-ups

Recurring top-up rules require Lago Premium. For automatic collection of paid top-ups through Stripe, connect Stripe and collect a payment method for the customer. Purchased credits become available only after the purchase invoice is marked succeeded.

When you create or edit a wallet, you can enable recurring top-ups. Two methods are available, fixed and target. Both are triggered either by an interval or by a threshold. The start date of a recurring top-up is ignored when it is the same as the creation date of the wallet. For example, if you create a wallet on Jan 1st, 2026, and set a monthly recurring top-up to start on Jan 1st, 2026, the top-up does not trigger until Feb 1st, 2026.

Fixed recurring top-up

A fixed recurring top-up adds a predetermined number of credits to the wallet, either purchased or granted for free.

Target recurring top-up

A target recurring top-up adds a variable number of credits to the wallet to reach a target balance. The number of credits comes from the gap between the ongoing balance at the moment of the trigger and the target balance. Set the target with target_ongoing_balance. It must be greater than or equal to threshold_credits when the rule is triggered by a threshold.

Set a target recurring top-up on creation

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": "0.0",
      "currency": "USD",
      "recurring_transaction_rules": [
        {
          "method": "target",
          "trigger": "threshold",
          "threshold_credits": "20.0",
          "target_ongoing_balance": "100.0",
          "invoice_requires_successful_payment": false
        }
      ]
    }
  }'

Interval trigger

For an interval trigger, specify the frequency of the automatic top-up: weekly, monthly, quarterly, semiannual or yearly. Once the interval is defined, Lago performs a top-up:

Weekly, on the same day each week (e.g., every Monday).
Monthly, on the same date each month (e.g., every 2nd of the month).
Quarterly, on the same date every three months (e.g., every 2nd of the quarter).
Semiannual, on the same date every six months (e.g., every 2nd of the semester).
Yearly, on the same date every year (e.g., every 2nd of January).

Dashboard
API

To set up an interval recurring top-up through the user interface:

Create or edit a wallet;
Click “Add a recurring top-up rule”;
Select interval as recurring type;
Define your interval;
Define when the rule should start; and
Define transaction metadata for the top-ups (optional & available only via API);

Setup an interval recurring top-up

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": "0.0",
      "granted_credits": "0.0",
      "currency": "USD",
      "recurring_transaction_rules": [
        {
          "method": "fixed",
          "trigger": "interval",
          "interval": "weekly",
          "started_at": null,
          "paid_credits": "100.0",
          "granted_credits": "0.0",
          "invoice_requires_successful_payment": false,
          "transaction_metadata": [
            {
              "key": "top-up-type",
              "value": "automatic"
            }
          ]
        }
      ]
    }
  }'

Threshold trigger

With a threshold trigger, set a specific number of credits that will trigger an automatic top-up. Lago monitors the ongoing balance, and if it falls to or below the defined credit threshold, an automatic top-up is initiated.

Dashboard
API

To set up a threshold recurring top-up through the user interface:

Create or edit a wallet;
Click “Add a recurring top-up rule”;
Select threshold as recurring type;
Define the credits threshold; and
Define transaction metadata for the top-ups (optional & available only via API);

Set a recurring top-up on creation

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",
      "recurring_transaction_rules": [
        {
          "method": "fixed",
          "trigger": "threshold",
          "threshold_credits": "100.0",
          "paid_credits": "100.0",
          "granted_credits": "0.0",
          "invoice_requires_successful_payment": true,
          "transaction_metadata": [
            {
              "key": "top-up-type",
              "value": "automatic"
            }
          ]
        }
      ]
    }
  }'

Expiration date

Define an expiration date for your recurring transaction rule. Once that date is reached, the rule is terminated and generates no further top-up.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Top-up and void credits

Credit purchases and top-ups

Invoicing top-up after successful payment option

Void credits

Setup recurring top-ups

Fixed recurring top-up

Target recurring top-up

Interval trigger

Threshold trigger

Expiration date

​Credit purchases and top-ups

​Invoicing top-up after successful payment option

​Void credits

​Setup recurring top-ups

​Fixed recurring top-up

​Target recurring top-up

​Interval trigger

​Threshold trigger

​Expiration date

Credit purchases and top-ups

Invoicing top-up after successful payment option

Void credits

Setup recurring top-ups

Fixed recurring top-up

Target recurring top-up

Interval trigger

Threshold trigger

Expiration date