# Credits

**Credits** are a prepaid balance on your Wren account. You can top up your credit balance via Stripe, then use credits to pay for offset orders without a per-transaction charge. Credits also allow offset purchases below the $1.00 Stripe minimum.

## POST /api/credits/top-up — Add credits

Charges your payment method on file and adds the amount to your credit balance.

POST`/api/credits/top-up`Copy Path

### Authentication

Required. Use a **team API token** (recommended; tops up the team wallet) or legacy personal API token (tops up the user wallet). Account required for personal tokens. **Test tokens** (`wren_test_…`) return a canned response without charging Stripe — see [Test mode](https://www.wren.co/docs/api#test-mode).

### Headers

- `Content-Type: application/json` or `application/x-www-form-urlencoded`

### Request body

| Attribute | Type | Description & Constraints |
| --- | --- | --- |
| `amountInUsdCents` | integer | **Required.** Amount to add in USD cents. Must be a positive integer and at least 100 ($1.00). |

### Example request

### Success response

HTTP `200`

- `amountCharged` — In the user currency's smallest denomination (e.g. 10000 = $100.00 USD)
- `id` — Stripe charge ID
- `creditBalance` — Updated credit balance in USD cents

### Error responses

- **400** — Missing or invalid `amountInUsdCents`, amount below minimum, or payment failure
- **403** — Missing/invalid auth or not an account user

* * *

## GET /api/credits/balance — Get your credit balance

Returns the authenticated user's current credit balance.

GET`/api/credits/balance`Copy Path

### Authentication

Required. Use a team API token (returns the team wallet) or legacy personal API token (returns the user wallet). Test tokens return a canned $1,000.00 balance.

### Request

No body. No query parameters.

### Example request

### Success response

HTTP `200`

- `creditBalanceUsdCents` — Current balance in USD cents (e.g. 10000 = $100.00)

### Error responses

- **403** — Missing or invalid authentication

* * *

## GET /api/credits/ledger — List credit transactions

Returns the authenticated user's credit transaction history, sorted by most recent first.

GET`/api/credits/ledger`Copy Path

### Authentication

Required. Use a team API token (returns the team ledger) or legacy personal API token (returns the user ledger). Test tokens return a small canned sample ledger.

### Query parameters

| Parameter | Type | Description & Constraints |
| --- | --- | --- |
| `limit` | integer | Optional. Number of entries to return. Default `50`, max `200`. |
| `offset` | integer | Optional. Number of entries to skip. Default `0`. |

### Example request

### Success response

HTTP `200`

- `entries` — Array of ledger entries for the current page
- `total` — Total number of entries across all pages
- `limit` — Page size used for this request
- `offset` — Offset used for this request
- `amount_usd_cents` — Positive for top-ups, negative for deductions
- `type` — One of `top_up`, `deduction`, or `refund`
- `order_group_id` — Links deductions to offset orders (null for top-ups)
- `stripe_charge_id` — Links top-ups to Stripe charges (null for deductions)

### Error responses

- **403** — Missing or invalid authentication