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 (i.e. the status of the invoice must be succeeded).

If a paid top-up is made, Lago will automatically round the top-up credits to the nearest cent to comply with decimal rounding rules for amounts. However, this logic does not affect free credits.

To top up a wallet through the user interface:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Top up credit”;
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 credit” to confirm.

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

To top up a wallet through the user interface:

Open the “Wallets” tab and click “Edit wallet” on the right;
Select “Top up credit”;
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 credit” 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": "wallet_1234567890",
      "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 wallet’s balance. Note that this action is instantaneous and cannot be undone.

To top up a wallet 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.

To top up a wallet 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.

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": "wallet_1234567890",
      "voided_credits": "20.0",
      "metadata": [
        {
          "key": "top-up-type",
          "value" "manual-void"
        }
      ]
    }
  }'

Setup recurring top-ups

When creating or editing a wallet, you have the option to enable recurring top-ups. Two methods for recurring top-ups are available: fixed and target. These can be triggered either based on an interval or a threshold.

Fixed recurring top-up

A fixed recurring top-up allows you to add a predetermined number of credits to your wallet, either for purchasing or gifting.

Target recurring top-up

A target recurring top-up allows you to add a variable amount of credits to your wallet to reach a specific target balance. The top-up amount is determined by the ongoing balance at the trigger moment and the desired target balance.

Interval trigger

For an interval trigger, specify the frequency of the automatic top-up: weekly, monthly, quarterly or yearly.

Once the interval is defined, the system will automatically perform 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).
Yearly, on the same date every year (e.g., every 2nd of January).

To setup a interval recurring top-up through the user interface:

Create or edit a wallet;
Trigger on the option Activate recurring top-up;
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);

To setup a interval recurring top-up through the user interface:

Create or edit a wallet;
Trigger on the option Activate recurring top-up;
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",
      "expiration_at": "2022-07-07",
      "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 below the defined credit threshold, an automatic top-up is initiated.

To setup a interval recurring top-up through the user interface:

Create or edit a wallet;
Trigger on the option Activate recurring top-up;
Select threshold as recurring type;
Define the credits threshold; and
Define transaction metadata for the top-ups (optional & available only via API);

To setup a interval recurring top-up through the user interface:

Create or edit a wallet;
Trigger on the option Activate recurring top-up;
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",
      "expiration_at": "2022-07-07",
      "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 reached, the rule will be terminated and will no longer generate any top-ups.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Invoicing

Payments & Cash Collection

Data & Analytics

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

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Invoicing

Payments & Cash Collection

Data & Analytics

Resources

​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