> ## 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.

# List orders

> Your account's order history, newest first: pack and card purchases, sell-backs and sales of your listings.

Scope: `read:account` · MCP tool: `list_orders`

Your pack and card purchases, sell-backs and listing sales, newest first. Shipment charges aren't here: read `cost` in [List shipments](https://catchbackcards.mintlify.site/partner-api/endpoints/list-shipments.md). Money in and withdrawals aren't here either. To reconcile your balance, use [Balance history](https://catchbackcards.mintlify.site/partner-api/endpoints/get-balance-history.md), which lists all of them. There are four kinds of order:

| `type` | What it is | Its `checkout_id` |
| - | - | - |
| `pack_purchase` | A [Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md) order | The `checkout_id` the purchase returned |
| `card_purchase` | A [Buy a card](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-card.md) order | The `checkout_id` the purchase returned |
| `sell_back` | One card [sold back](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md). A request that sells several cards makes one order per card | The sell-back's `transaction_id` |
| `listing_sale` | A sale of one of your listings to someone else, fixed price or Dutch auction | The sale's id |

The history belongs to the account, not the key: every key linked to the account sees the same orders. Purchases and sell-backs made in our app are left out. A sale of one of your listings is in, wherever you listed the card.

A key acts as one CatchBack account, so the history can't say which of your own customers an order was for. Keep that on your side, against the `order_id` you chose or the order's `pull_ids`.

To hear when an order finishes instead of polling, use a [webhook](https://catchbackcards.mintlify.site/partner-api/webhooks.md).

**type** `string`

Only orders of this kind: `pack_purchase`, `card_purchase`, `sell_back` or `listing_sale`. Leave it out for all four.

**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)

Orders 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 and type, so `since`, `until` and `type` are ignored when you send it. See [Pagination](https://catchbackcards.mintlify.site/partner-api/pagination.md#cursor-pages).

The window is capped at **31 days**, and a malformed or inverted window is a `400`, as on the [Purchase report](https://catchbackcards.mintlify.site/partner-api/endpoints/purchase-report.md). To read a longer stretch, ask for it a month at a time.

## Response

**since** `string`

The window's start, as used.

**until** `string`

The window's end, as used.

**type** `string | null`

The `type` filter, or `null` for all four.

**limit** `integer`

**has\_more** `boolean`

Whether there are more orders in the window.

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

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

**orders** `object[]`

Newest first, by `created_at`.

**order**

**checkout\_id** `string`

The order's id: see the table above. [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md) takes it.

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

The `Idempotency-Key` you sent with a purchase. `null` for a sell-back or a sale.

**type** `string`

`pack_purchase`, `card_purchase`, `sell_back` or `listing_sale`.

**status** `string`

`completed`, or `pending` while a purchase is still running, until we close an interrupted one ([how](https://catchbackcards.mintlify.site/partner-api/idempotency.md#timeouts-and-interrupted-orders)), or while one is held for review ([why](https://catchbackcards.mintlify.site/partner-api/errors-and-limits.md#when-a-purchase-needs-review)). A purchase that failed and refunded itself isn't listed, and neither is a held one once we've settled it. New values can be added, so don't fail on one you don't know.

**created\_at** `string`

**completed\_at** `string | null`

`null` while the order is pending.

**amount** `number | null`

What a purchase charged (a card buy includes its $1 buyer fee), what a sell-back paid, or what a listing sold for, in USD.</ResponseField>     <ResponseField name="fee" type="number | null">The $1 buyer fee on a card buy or the \$1 seller fee on a sale. `0` on a pack purchase or a sell-back.

**balance\_change** `number | null`

The order's effect on your balance: −`amount` for a purchase, +`amount` for a sell-back, +(`amount` − `fee`) for a sale. `null` until something shows the order was charged. A pending purchase whose packs or card have already landed shows its charge here before we close it.

**reconciled** `boolean`

`true` when the order went through but its response was lost, and we closed it from our own records.

**pack\_type** `string | null`

Pack purchases only.

**quantity** `integer | null`

Pack purchases only.

**pull\_ids** `string[]`

A pack purchase's pulls. For a sell-back of a card you pulled, the pull it sold. Empty otherwise.

**card\_id** `string | null`

The card a card buy, a sell-back or a sale was for. `null` on a pack purchase.

**listing\_id** `string | null`

The listing a card buy or a sale came from. `null` for a shop buy, a pack purchase or a sell-back.

**transaction\_id** `string | null`

For a card buy, the sale: the `purchase_id` that [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) and [Sell back](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md) use. For a sell-back or a sale, the same id as `checkout_id`. `null` on a pack purchase.

## Errors

| Status | When |
| - | - |
| `400` | An unknown `type`, 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/orders?since=2026-10-01T00:00:00Z&until=2026-10-31T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

```json 200 theme={null}
{
  "since": "2026-10-01T00:00:00.000Z",
  "until": "2026-10-31T00:00:00.000Z",
  "type": null,
  "limit": 50,
  "has_more": true,
  "next_cursor": "WyIyMDI2LTEwLTIwVDA0OjU0OjU3LjM3MzAwMVoiLC…",
  "orders": [
    {
      "checkout_id": "a0c3e7d1-…",
      "order_id": null,
      "type": "listing_sale",
      "status": "completed",
      "created_at": "2026-10-21T16:02:11.482+00:00",
      "completed_at": "2026-10-21T16:02:11.482+00:00",
      "amount": 45,
      "fee": 1,
      "balance_change": 44,
      "reconciled": false,
      "pack_type": null,
      "quantity": null,
      "pull_ids": [],
      "card_id": "0e94dc61-…",
      "listing_id": "5f1c2a90-…",
      "transaction_id": "a0c3e7d1-…"
    },
    {
      "checkout_id": "3e1ab17c-…",
      "order_id": "order-1042",
      "type": "pack_purchase",
      "status": "completed",
      "created_at": "2026-10-20T04:54:57.373+00:00",
      "completed_at": "2026-10-20T04:54:58.563+00:00",
      "amount": 25,
      "fee": 0,
      "balance_change": -25,
      "reconciled": false,
      "pack_type": "bronze",
      "quantity": 1,
      "pull_ids": ["e9d27918-…"],
      "card_id": null,
      "listing_id": null,
      "transaction_id": null
    }
  ]
}
```


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