# Source: https://getlago.com/docs/guide/wallet-and-prepaid-credits/wallet-top-up-and-void.md

> ## Documentation Index
> Fetch the complete documentation index at: https://getlago.com/docs/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`).

<Info>
  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.
</Info>

<Tabs>
  <Tab title="Dashboard">
    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.

    <Info>Coupons **do not apply** to credit purchases and top-ups.</Info>
  </Tab>

  <Tab title="API">
    ```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"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="Dashboard">
    To top up a wallet 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.
  </Tab>

  <Tab title="API">
    ```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"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## 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`, `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).

<Tabs>
  <Tab title="Dashboard">
    To setup a `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);
  </Tab>

  <Tab title="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"
                }
              ]
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="Dashboard">
    To setup a `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);
  </Tab>

  <Tab title="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"
                }
              ]
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

### 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.