Balance history

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

GET /api/partner/v1/balance-history

cURL

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"

200

{
  "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" }
  ]
}

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	The order’s checkout_id: Get an order takes it
shipment	A shipping charge	The shipment’s id: Get a shipment takes it
withdrawal	A USDC withdrawal	The withdrawal’s id: Get a withdrawal 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.

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.

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.

Show 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, 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

cURL

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"

200

{
  "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" }
  ]
}