> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepaid Balance

> Top up a USD balance and keep using Appeeky after your plan's monthly credits run out, or pay per use for features without a plan quota.

Your **prepaid balance** is money you add to your Appeeky account up front. It pays for usage beyond your plan: API and MCP calls after your monthly credits are gone, extra UGC media, extra AI Visibility scans and extra Reddit subreddits. Some features, like [Creator Discovery](https://docs.appeeky.com/docs/creator-discovery.md), are paid from the balance only.

> [!NOTE]
>
> Every signed-in account can hold a balance, including free accounts. The balance never expires. Find it in **Settings → Billing**.

***

## How it works

1. **Top up.** Pick a pack in **Settings → Billing** and pay by card. The balance updates a few seconds after payment.
2. **Use your plan first.** Monthly plan credits are always spent before the balance.
3. **Pay from balance.** When a monthly quota runs out, a feature keeps working and is paid from your balance, as long as its switch is on and the balance covers the cost.
4. **Track it.** Every top-up, charge and refund shows in **Recent activity**.

When the balance can't cover a request, or you've switched a feature off, the request behaves as it would without a balance: the API returns `429` once your credits are used up. See [Rate Limits & Credits](https://docs.appeeky.com/docs/rate-limits.md).

***

## Top-up packs

| You pay | Bonus | Added to balance |
| - | -: | -: |
| \$10 | — | \$10.00 |
| \$25 | \$1.25 | \$26.25 |
| \$50 | \$4.00 | \$54.00 |
| \$100 | \$10.00 | \$110.00 |

The bonus is added as a separate entry in your activity, right after the top-up.

***

## What the balance pays for

| Feature | Price | When it's charged | Switch |
| - | - | - | - |
| **API & MCP** | \$0.005 per credit | After your monthly API/MCP credits run out. Only the credits your plan no longer covers are charged | API & MCP |
| **UGC media** | \$0.01 per media credit | When a generation needs more media credits than you have left this month | UGC media |
| **AI Visibility** | \$0.0015 per credit | After your monthly AI Visibility credits run out | AI Visibility |
| **Reddit subreddits** | \$0.01 per subreddit scan | Each time a subreddit beyond your plan's quota is scanned | Reddit subreddits |
| **Creator Discovery** | \$0.01 per analyzed creator | Every analyzed creator. There is no plan quota | None: you start each run yourself |

Current prices are also returned by `GET /v1/wallet`.

### Pay-from-balance switches

Under **Settings → Billing → Pay from balance**, each feature with a monthly quota has its own switch: *use balance when plan credits run out*. All switches are **on** by default. Turn one off to stop that feature from spending your balance. It then stops at its plan limit, just as it would without a balance.

Creator Discovery has no switch. It only spends when you start a search.

### Good to know

* **API & MCP.** A request is let through only when the balance covers its whole shortfall. The charge is made after the response succeeds. The response carries `X-Wallet-Overage-Units` and `X-Wallet-Overage-Feature` when the balance paid for part of it. `GET /v1/auth/usage` and the `get_api_usage` MCP tool show how many credits your balance can still buy (`walletCredits`) and your balance in USD.
* **Dashboard, desktop and mobile app use** doesn't spend API & MCP credits, so it never charges your balance for them.
* **UGC media.** Credits bought from your balance become media credits that don't expire. If a generation fails, its credits go back to your media credits, not to your balance.
* **AI Visibility.** Scan charges never take your balance below zero.
* **Creator Discovery.** Creators who fail to load, or don't make it into the results, are refunded automatically. See [Creator Discovery](https://docs.appeeky.com/docs/creator-discovery.md#billing).

***

## Refunds

* **Failed work.** When paid work fails, such as a Creator Discovery run, its charge is returned to your balance automatically and shows as **Refund** in your activity. Failed UGC generations return their media credits instead (see above).
* **Refunded payments.** If a top-up payment is refunded or disputed, that amount is removed from your balance, together with the matching share of its bonus. This shows as **Payment refunded**. If a dispute is decided in your favor, the amount is added back.

***

## Teams

In a [team workspace](https://docs.appeeky.com/docs/workspaces.md), all usage is paid from the **workspace owner's** balance. Only the owner can top up or change the switches.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/wallet` | Balance, switches, top-up packs and current prices |
| GET | `/v1/wallet/ledger` | Recent balance activity (`?limit=`, default 50, max 200) |
| PATCH | `/v1/wallet/settings` | Turn pay-from-balance switches on or off |
| POST | `/v1/wallet/topup` | Start a card payment for a top-up pack |

These endpoints work with an API key or a dashboard session, on every plan, and use 0 API credits.

### Get your balance

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/wallet \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "balanceMicros": 26250000,
    "settings": { "media": true, "api": true, "ai_visibility": true, "reddit": false },
    "packs": [
      { "amountCents": 1000, "bonusCents": 0 },
      { "amountCents": 2500, "bonusCents": 125 },
      { "amountCents": 5000, "bonusCents": 400 },
      { "amountCents": 10000, "bonusCents": 1000 }
    ],
    "prices": [
      { "feature": "api_credit", "unit": "API/MCP credit", "priceMicros": 5000 },
      { "feature": "creator_analysis", "unit": "analyzed creator", "priceMicros": 10000 }
    ]
  }
}
```

Fields ending in `Micros` are in millionths of a US dollar: divide by 1,000,000 for USD. In the example, `26250000` is \$26.25.

### Change switches

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH https://api.appeeky.com/v1/wallet/settings \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reddit": false }'
```

| Field | Type | Description |
| - | - | - |
| `api` | boolean | API & MCP credits |
| `media` | boolean | UGC media credits |
| `ai_visibility` | boolean | AI Visibility credits |
| `reddit` | boolean | Extra Reddit subreddit scans |

Send only the switches you want to change. The response returns all four.

### Top up

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/wallet/topup \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 2500 }'
```

`amountCents` must match one of the packs from `GET /v1/wallet`. The response holds a `url` to a secure card payment page. After you pay, you're sent back to **Settings → Billing** and the balance updates within a few seconds.

### Activity

`GET /v1/wallet/ledger` returns entries newest first. Each has an `entryType`:

| `entryType` | Meaning |
| - | - |
| `topup` | Money you added |
| `bonus` | Pack bonus |
| `charge` | Usage paid from the balance (`feature` and `units` say what for) |
| `refund` | Charge returned after failed work |
| `reversal` | Top-up payment refunded or disputed |
| `adjustment` | Manual or dispute correction |

`amountMicros` is positive for money in and negative for money out.

***

## Related

* [Rate Limits & Credits](https://docs.appeeky.com/docs/rate-limits.md): plans, monthly credits and `429` responses
* [Creator Discovery](https://docs.appeeky.com/docs/creator-discovery.md): pay-per-creator search
* [Workspaces](https://docs.appeeky.com/docs/workspaces.md): who pays in a team


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.