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

# List vouchers

> List vouchers in your tenant with filtering, sorting, and pagination.

**Required scope:** `vouchers:read`
**Rate limit:** 300 requests/minute

## Pagination

This endpoint supports both [cursor pagination (recommended)](/developer-api/pagination#cursor-pagination-recommended)
and [page pagination (deprecated)](/developer-api/pagination#page-pagination-deprecated).
The cursor shape wins if both are sent on the same request.

In cursor mode, results are ordered `created_at DESC, id DESC`, and the
`sort_by` / `sort_order` params are ignored.

## Query parameters

### Cursor shape (recommended)

| Parameter | Type    | Default | Notes                                                  |
| --------- | ------- | ------- | ------------------------------------------------------ |
| `cursor`  | string  | –       | Opaque cursor from a previous response's `next_cursor` |
| `limit`   | integer | `50`    | 1–100                                                  |

### Page shape (deprecated)

<Warning>
  The page shape is kept for back-compat. Use cursor pagination for new
  integrations – see [Pagination](/developer-api/pagination).
</Warning>

| Parameter  | Type    | Default | Notes                  |
| ---------- | ------- | ------- | ---------------------- |
| `page`     | integer | `1`     | 1-indexed page (min 1) |
| `per_page` | integer | `50`    | 1–100                  |

### Filters & sorting (both shapes)

| Parameter    | Type   | Default      | Notes                                                                                                                                                                                                                                                                 |
| ------------ | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`     | string | –            | One of `pending`, `completed`, `redeemed`, `expired`, `voided`, `refunded`                                                                                                                                                                                            |
| `search`     | string | –            | An email-shaped query searches `recipient_email` only. Any other query searches voucher `code` (prefix match) and `recipient_name` together – but not email. The two branches are exclusive. In cursor mode the in-process name fallback is skipped (SQL match only). |
| `sort_by`    | string | `created_at` | Page mode only. One of `code`, `amount`, `balance`, `status`, `created_at`. Ignored in cursor mode.                                                                                                                                                                   |
| `sort_order` | string | `desc`       | Page mode only. `asc` or `desc`. Ignored in cursor mode.                                                                                                                                                                                                              |
| `include`    | string | –            | Set to `customer` to embed the linked customer record on each row                                                                                                                                                                                                     |

## Response

Cursor shape:

```json theme={null}
{
  "vouchers": [
    {
      "id": "8d82f0d2-7f94-4a3b-8b55-1e2e3a4f5b6c",
      "code": "VG-EXAMPLE1",
      "amount": "100.00",
      "balance": "75.00",
      "status": "completed",
      "recipient_name": "Sam Recipient",
      "recipient_email": "sam@example.com",
      "expiry_date": "2029-04-26T00:00:00Z",
      "created_at": "2026-04-26T01:23:45Z",
      "updated_at": "2026-04-26T01:23:45Z",
      "location_id": null
    }
  ],
  "next_cursor": "cur_v1_eyJ2IjoxLCJ0Ijoi…uH8.QwR2…"
}
```

Page shape (deprecated):

```json theme={null}
{
  "vouchers": [/* …items… */],
  "total": 247,
  "page": 1,
  "per_page": 50
}
```

When `include=customer` is supplied, each voucher additionally carries a
`customer` field:

```json theme={null}
{
  "id": "...",
  "code": "VG-EXAMPLE1",
  "...": "...",
  "customer": {
    "id": "c0ffee00-...-...",
    "email": "buyer@example.com",
    "first_name": "Alex",
    "last_name": "Buyer"
  }
}
```

If a voucher has no linked customer, `customer` is `null`.

## Errors

* `400` – Invalid `status` value, or invalid/forged/cross-tenant `cursor`.
* `422` – `include` is set to anything other than `customer`.

## Examples

```bash theme={null}
curl \
  -H "X-API-Key: vg_live_EXAMPLEdoNotUseThis123456" \
  "https://api.vouchergrid.com/api/v1/developer/vouchers?status=completed&per_page=25"
```

```ts theme={null}
const params = new URLSearchParams({
  status: "completed",
  per_page: "25",
  sort_by: "created_at",
  sort_order: "desc",
});

const res = await fetch(
  `https://api.vouchergrid.com/api/v1/developer/vouchers?${params}`,
  { headers: { "X-API-Key": process.env.VOUCHERGRID_API_KEY! } },
);
const data = await res.json();
```