# List a wallet's credit grants

> The credit_grants.list operation: GET /api/v1/wallets/{id}/grants in the REST API and the credit_grants_list tool in the MCP server.

Lists the credits behind a wallet's balance, newest first: purchases (top-ups and credit packs), subscription
credits, promo and adjustment grants and refund reversals. `remaining` is what is left of each grant (credits
held by open reservations count as left); `expiresAt` is when unused credits expire.

Credits are spent promo first, then subscription credits, then purchased ones, soonest expiry first within each
(spec §17.1, `priority`).

## At a glance

- **REST:** `GET /api/v1/wallets/{id}/grants`
- **MCP tool:** `credit_grants_list`
- **Operation ID:** `credit_grants.list`
- **Scope:** Brand
- **Permission:** `wallets:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `wallets:read` scope
- **Since:** M6

## Request

### Path parameters

| Field | Type       | Description           |
| ----- | ---------- | --------------------- |
| `id`  | `wal_…` ID | The wallet (`wal_…`). |

### Query parameters

| Field            | Type               | Required | Description |
| ---------------- | ------------------ | -------- | ----------- |
| `limit`          | integer (1 to 100) | No       |             |
| `starting_after` | `grant_…` ID       | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field              | Type                                                                        | Description                                                              |
| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `object`           | `"list"`                                                                    |                                                                          |
| `data`             | array of object                                                             |                                                                          |
| `data[].id`        | `grant_…` ID                                                                |                                                                          |
| `data[].object`    | `"credit_grant"`                                                            |                                                                          |
| `data[].brandId`   | `brd_…` ID                                                                  |                                                                          |
| `data[].livemode`  | boolean                                                                     |                                                                          |
| `data[].walletId`  | `wal_…` ID                                                                  |                                                                          |
| `data[].source`    | one of `purchase`, `subscription`, `promo`, `adjustment`, `refund_reversal` | `purchase`, `subscription`, `promo`, `adjustment` or `refund_reversal`.  |
| `data[].amount`    | money                                                                       | What was granted.                                                        |
| `data[].remaining` | money                                                                       | What is left: not yet spent or expired (reserved credits count as left). |
| `data[].priority`  | integer                                                                     | Spend tier (§17.1): 1 promo, 2 subscription, 3 purchased and the rest.   |
| `data[].expiresAt` | date-time or null                                                           |                                                                          |
| `data[].expired`   | boolean                                                                     | `expiresAt` has passed: the credits can't be spent any more.             |
| `data[].reason`    | string or null                                                              | The operator's reason, for promo and adjustment grants.                  |
| `data[].paymentId` | string or null                                                              |                                                                          |
| `data[].invoiceId` | string or null                                                              |                                                                          |
| `data[].createdAt` | date-time                                                                   |                                                                          |
| `has_more`         | boolean                                                                     |                                                                          |
| `next_cursor`      | string or null                                                              |                                                                          |

## Examples

### A promo grant and a purchase

```http
GET /api/v1/wallets/wal_01m4ty7w2a5qx7mhd9k8w6s0b1/grants
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "grant_01m4ty7w2a5qx7mhd9k8w6s0b3",
      "object": "credit_grant",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "walletId": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
      "source": "promo",
      "amount": {
        "amount": "5000000",
        "currency": "EUR"
      },
      "remaining": {
        "amount": "5000000",
        "currency": "EUR"
      },
      "priority": 1,
      "expiresAt": "2026-11-01T00:00:00.000Z",
      "expired": false,
      "reason": "Welcome credits",
      "paymentId": null,
      "invoiceId": null,
      "createdAt": "2026-10-16T10:15:00.000Z"
    },
    {
      "id": "grant_01m4ty7w2a5qx7mhd9k8w6s0b2",
      "object": "credit_grant",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "walletId": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
      "source": "purchase",
      "amount": {
        "amount": "80000000",
        "currency": "EUR"
      },
      "remaining": {
        "amount": "80000000",
        "currency": "EUR"
      },
      "priority": 3,
      "expiresAt": null,
      "expired": false,
      "reason": null,
      "paymentId": "pay_01m4ty7w2a5qx7mhd9k8w6s0b5",
      "invoiceId": null,
      "createdAt": "2026-10-14T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                         | HTTP status | When                                                                                   | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)       | 400         | `id` isn't a wallet ID, or a pagination value is invalid.                              | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)     | 404         | This brand has no such wallet in this mode (wallets belong to one brand and one mode). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)             | 400         | The request names no brand (an org or entity key without `Ownrecord-Brand`).           | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)       | 403         | You can't read this brand's wallets (`wallets:read`).                                  | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403         | You have no live-mode access, so you can't use live wallets.                           | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.                        |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).