> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Top-up and void credits
> Add and void credits, to the customer's wallet.
## Credit purchases and top-ups[](#credit-purchases-and-top-ups "Direct link to heading")
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:
1. Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
2. Select **"Top up credit"**;
3. Enter the number of credits to be purchased and/or granted for free;
4. Define transaction metadata (optional & available only via API);
5. Determine whether the wallet transaction generates an invoice after a top-up or only following a successful payment; and
6. Click **"Top up credit"** to confirm.
Coupons **do not apply** to credit purchases and top-ups.
```bash Top up a credit wallet theme={"dark"}
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[](#void-credits "Direct link to heading")
You can deduct an exact number of credits from the wallet's balance. Note that this action is instantaneous and cannot be undone.
To void credits through the user interface:
1. Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
2. Select **"Void credits"**;
3. Enter the number of credits to void;
4. Define transaction metadata (optional & available only via API); and
5. Click **"Void credits"** to confirm.
```bash Top up a credit wallet theme={"dark"}
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`.
Be advised that when setting a start date for a recurring top-up, it will be ignored if it is the same as the date the wallet was created. 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 will not trigger until Feb 1st, 2026.
### 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`, `semiannual` 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).
* 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).
To set up an `interval` recurring top-up through the user interface:
1. Create or edit a wallet;
2. Trigger on the option `Activate recurring top-up`;
3. Select `interval` as recurring type;
4. Define your interval;
5. Define when the rule should start; and
6. Define transaction metadata for the top-ups (optional & available only via API);
```bash Setup an interval recurring top-up theme={"dark"}
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 set up an `interval` recurring top-up through the user interface:
1. Create or edit a wallet;
2. Trigger on the option `Activate recurring top-up`;
3. Select `threshold` as recurring type;
4. Define the credits threshold; and
5. Define transaction metadata for the top-ups (optional & available only via API);
```bash Set a recurring top-up on creation theme={"dark"}
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.