# Credits & billing

> The prepaid credit wallet — available vs held credits, bonus tiers, top-ups, auto-recharge, what happens without enough credits, and refunds.

Source: https://swaglists.com/docs/billing

Orders are paid from a **prepaid credit wallet**: you buy credits, and each order spends credits. There are no invoices to chase and no card charge per order — your integration only needs to keep the wallet funded. One credit cent = one US cent.

## The wallet

```bash title="cURL"
curl https://swaglists.com/api/v1/wallet -H "Authorization: Bearer $API_KEY"
```

```json title="Response"
{
  "object": "wallet",
  "mode": "live",
  "livemode": true,
  "currency": "usd",
  "available": 482550,
  "held": 12480,
  "total": 495030,
  "low_balance_threshold": 10000
}
```

| Field | Meaning |
| --- | --- |
| `available` | Spendable credits, in cents. New orders reserve from here. Can be negative after a payment dispute. |
| `held` | Credits reserved for confirmed orders that have not been accepted for production yet. |
| `total` | `available` + `held`. |
| `low_balance_threshold` | You get a `wallet.low_balance` event (and an email) when `available` drops below it. Set it in Settings → Orders. |

Live and test mode have separate wallets. Test credits are free — see [Test mode](https://swaglists.com/docs/test-mode.md#test-credits).

## How an order uses credits

1. **Confirm** — the order total is moved from `available` to `held` (a `hold` transaction).
2. **Accepted for production** — the held credits are spent (`capture`). An order produced in several parts captures each part separately.
3. **Canceled or failed before that** — the held credits go back to `available` (`release`). Canceled after capture? The spent credits are refunded (`refund`).

Every change is an immutable [transaction](https://swaglists.com/docs/objects.md#transaction) — list them with `GET /wallet/transactions` (filter by `type` or `order_id`):

| Transaction `type` | Meaning |
| --- | --- |
| `topup` | Credits you bought (the paid amount). |
| `bonus` | Bonus credits of a top-up (a separate entry). |
| `hold` | Credits reserved for an order (`amount` −X, `held_delta` +X). |
| `release` | Reserved credits returned to available (canceled/failed order). |
| `capture` | Reserved credits spent when production of (part of) an order was accepted (`held_delta` −X). |
| `charge` | Credits spent directly, without a reservation. |
| `refund` | Credits refunded for an order. |
| `adjustment` | A correction by support (positive or negative), with a reason. |
| `reversal` | Credits taken back after a top-up was refunded or disputed (can make `available` negative). |
| `test_credit` | Free test credits (test mode only). |

## Bonus tiers

Bigger top-ups earn bonus credits on top of what you pay:

| You pay | Bonus | Example: credits you receive |
| --- | --- | --- |
| Less than $1,000 | 0% | $500 → $500 |
| $1,000 – $2,499.99 | 3% | $1,000 → $1,030 |
| $2,500 – $4,999.99 | 4% | $2,500 → $2,600 |
| $5,000 and above | 5% | $5,000 → $5,250 |

For example, paying **$5,000** gives **$5,250** in credits. The bonus is added as a separate `bonus` transaction. Tiers can change; the **Buy credits** page always shows the current ones before you pay. Bonus credits are not refundable.

## Buying credits (top-ups)

Top-ups are made in the dashboard (**Wallet → Buy credits**) by owners, admins and finance members. Pay by card or US bank account (ACH); bank transfer may also be available. The minimum top-up is $100.

- **Card** — credits arrive within seconds.
- **US bank account (ACH)** — cheaper for large amounts; credits arrive when the payment clears (usually a few business days). The top-up is `processing` meanwhile.

You receive `topup.succeeded` and `wallet.credited` events when credits arrive (`topup.failed` if a payment fails). List top-ups with `GET /topups`.

**Invoices.** Every card or bank purchase comes with an invoice (download it from the purchase in the wallet). It shows the legal name, billing address and tax ID (VAT, EIN, GST…) from **Settings → Billing** — fill them in before buying. Reselling? Upload your resale or exemption certificate on the same page; once our team approves it, no sales tax is added to your orders.

## Auto-recharge

Turn on **Wallet → Recharge automatically**: when `available` falls below your threshold, we charge your saved card or bank account for the amount you chose (bonus tiers apply). Failed recharges notify you and auto-recharge pauses after repeated failures. With auto-recharge on, orders rarely wait for credits.

## When credits run out

What happens to an order your available credits cannot cover is a setting (**Settings → Orders → When credits run out**):

| Setting | Result |
| --- | --- |
| **Hold** (default) | The order is created `on_hold` with `hold_reason: insufficient_funds` and `funds_status: awaiting`. You get `order.on_hold`. As soon as credits arrive (top-up, auto-recharge, refund), held orders continue automatically, **oldest first**, and you get `order.processing`. |
| **Hold, release manually** (`hold_manual`) | The order is created `on_hold` / `insufficient_funds` like *Hold*, but adding credits does **not** release it. You release held orders yourself: one at a time or in bulk from **Orders** in the dashboard, or with `POST /orders/{id}/confirm` from the API. Releasing reserves the order total first; if your credits still don't cover it, it stays on hold (the API answers `402 insufficient_funds`). New orders your credits cover are not blocked by held ones. |
| **Reject** | `POST /orders` (and `POST /orders/{id}/confirm`) fail with `402 insufficient_funds`; nothing is created. The error includes `required_amount` and `available_amount`. |

Whatever the setting, **nothing is ever sent to production unless its credits are reserved in your wallet first.** With *Hold* you can also release a held order early (after a top-up, before the automatic retry runs) the same way: dashboard **Release** or `POST /orders/{id}/confirm`.

Holding is friendlier when your customer has already paid you; rejecting suits integrations that want to retry themselves. When you retry a rejected request after adding credits, send it with a **new** `Idempotency-Key` (for example `order-1042:2`): the 402 is stored under the original key for 24 hours, so reusing that key returns the same error. `external_id` still prevents a duplicate order. Check `GET /account` → `settings.insufficient_funds_behavior` to see which applies.

`POST /orders/estimate` returns `wallet_available` and `sufficient_funds` so you can check before ordering.

## Refunds

- **Order refunds go to your wallet.** Canceling an order releases or refunds its credits automatically. If support refunds an order (for example a damaged item), the credits are added to `available` (`refund` transaction, `order.refunded` and `wallet.credited` events).
- **Unused credits** can be refunded to the original payment method on request — use **Settings → Billing → Refund unused credits** (or contact support). Only the paid portion of unused credits is refundable; bonus credits from that top-up are removed proportionally. Owners can also ask to close the account there.
- **Payment disputes** (chargebacks) on a top-up remove its credits, which can make `available` negative; new orders wait until the balance is positive again.

## Credits API

| Request | Returns |
| --- | --- |
| `GET /wallet` | The [wallet](https://swaglists.com/docs/objects.md#wallet) of the key's mode. |
| `GET /wallet/transactions` | Every balance change, newest first (`type`, `order_id` filters). |
| `GET /topups`, `GET /topups/{id}` | Credit purchases (live mode). |
| `POST /test/wallet/fund` | Free test credits (test mode). |

All need the `wallet:read` scope (the test helper needs full access).