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

# Balance history

> Every change to your balance, newest first: orders, shipments, withdrawals and money in.

Scope: `read:account` · REST only, no MCP tool

Every change to your CatchCoins balance in a window, newest first, in one list: what your orders cost or paid, shipping charges, USDC withdrawals, and the money that came in. Use it to explain your balance line by line, for example to match it against your own books at the end of a month.

| `type` | What it is | Its `id` |
| - | - | - |
| `pack_purchase`, `card_purchase`, `sell_back`, `listing_sale` | An order, as in [List orders](https://catchbackcards.mintlify.site/partner-api/endpoints/list-orders.md) | The order's `checkout_id`: [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md) takes it |
| `shipment` | A shipping charge | The shipment's `id`: [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) takes it |
| `withdrawal` | A [USDC withdrawal](https://catchbackcards.mintlify.site/partner-api/funding.md#withdraw) | The withdrawal's `id`: [Get a withdrawal](https://catchbackcards.mintlify.site/partner-api/endpoints/get-withdrawal.md) takes it |
| `deposit` | Money in: a USDC or other crypto deposit, a wire we credited, or a card deposit | The deposit's id |

Only what moved your balance is listed:

* An order still running, before anything shows it charged, isn't listed yet. A failed order or a failed withdrawal is never listed, since the amount went back to your balance.
* There is no running balance on each line. The response carries your `balance` now.
* What the account did in our app is left out, as in List orders.

**since** `string`

ISO 8601 with a time zone, e.g. `2026-10-01T00:00:00Z`. Inclusive. Defaults to `until` minus 7 days.

**until** `string`

ISO 8601 with a time zone. Inclusive. Defaults to now. At most 31 days after `since`.

**limit** `integer` (default: 50)

Entries per page, 1–100. A higher value is treated as 100.

**cursor** `string`

`next_cursor` from the previous page, unchanged. It carries that page's window, so `since` and `until` are ignored when you send it. See [Pagination](https://catchbackcards.mintlify.site/partner-api/pagination.md#cursor-pages).

> [!NOTE]
>
> A page can come back with fewer entries than `limit`, even none, while `has_more` is `true`. Keep following `next_cursor` until it is `null`.

## Response

**since** `string`

The window's start, as used.

**until** `string`

The window's end, as used.

**balance** `number`

Your balance now, in USD. The same as `balance` in [Get account](https://catchbackcards.mintlify.site/partner-api/endpoints/get-account.md).

**limit** `integer`

**has\_more** `boolean`

Whether there may be more entries in the window.

**next\_cursor** `string | null`

Send it as `cursor` for the next page. `null` on the last page.

**entries** `object[]`

Newest first, by `created_at`.

**entry**

**id** `string`

See the table above.

**type** `string`

`pack_purchase`, `card_purchase`, `sell_back`, `listing_sale`, `shipment`, `withdrawal` or `deposit`. New values can be added, so don't fail on one you don't know.

**amount** `number`

The change to your balance in USD: negative when it took from it. A sale's is net of the \$1 seller fee.

**created\_at** `string`

**order\_id** `string | null`

The `Idempotency-Key` you sent with a purchase, shipment or withdrawal. `null` otherwise.

**method** `string | null`

Deposits only: `crypto` (a USDC deposit to your [deposit address](https://catchbackcards.mintlify.site/partner-api/funding.md#deposit), or another crypto deposit), `wire`, `card` or `other`. `null` on every other type.

## Errors

| Status | When |
| - | - |
| `400` | A `since` or `until` we can't read as a date, `since` not before `until`, a window wider than 31 days, or a `cursor` that wasn't passed back unchanged |
| `403` | The key lacks `read:account` or isn't linked to an account |
| `500` | We couldn't read your history. Retry with backoff: you never get a partial page |

```bash cURL theme={null}
curl "https://catchbackcards.com/api/partner/v1/balance-history?since=2026-10-01T00:00:00Z&until=2026-10-31T00:00:00Z" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

```json 200 theme={null}
{
  "since": "2026-10-01T00:00:00.000Z",
  "until": "2026-10-31T00:00:00.000Z",
  "balance": 4930,
  "limit": 50,
  "has_more": false,
  "next_cursor": null,
  "entries": [
    { "id": "7b0f2c4e-…", "type": "withdrawal", "amount": -5000, "created_at": "2026-10-03T15:20:41.118+00:00", "order_id": "withdraw-2026-10-03-001", "method": null },
    { "id": "a0c3e7d1-…", "type": "sell_back", "amount": 180, "created_at": "2026-10-02T18:09:12.904+00:00", "order_id": null, "method": null },
    { "id": "3e1ab17c-…", "type": "pack_purchase", "amount": -250, "created_at": "2026-10-02T18:05:57.373+00:00", "order_id": "order-1042", "method": null },
    { "id": "c71d09a2-…", "type": "deposit", "amount": 10000, "created_at": "2026-10-02T17:41:03.552+00:00", "order_id": null, "method": "crypto" }
  ]
}
```


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