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

> List voucher product designs configured in your tenant.

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

A "product" is a voucher design / SKU configured in the VoucherGrid Design
Centre – for example, a `$50 Birthday` voucher or a `Custom Amount` voucher.

## Pagination

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 supplied. Cursor mode forces
`ORDER BY created_at DESC, id DESC` and ignores the legacy `sort_order`
column on the underlying table.

## Query parameters

### Cursor shape (recommended)

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

### Page shape (deprecated)

<Warning>
  Use cursor pagination for new integrations – see [Pagination](/developer-api/pagination).
</Warning>

| Parameter  | Type    | Default | Notes     |
| ---------- | ------- | ------- | --------- |
| `page`     | integer | `1`     | 1-indexed |
| `per_page` | integer | `20`    | 1–100     |

### Filters (both shapes)

| Parameter | Type   | Default | Notes                                                                                                                                                        |
| --------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`  | string | –       | One of `ready`, `internal`, `live`, `archived`. `internal` products are staff-only – they appear in the in-app sale drawer but never on a public storefront. |

## Response

Cursor shape:

```json theme={null}
{
  "products": [
    {
      "id": "0e1d2c3b-4a59-6788-9aab-bcdef0123456",
      "name": "birthday-50",
      "display_name": "Birthday Voucher",
      "description": "$50 birthday voucher with festive design",
      "pricing_type": "fixed",
      "fixed_amount": "50.00",
      "min_amount": null,
      "max_amount": null,
      "status": "live",
      "location_id": null,
      "created_at": "2026-04-26T01:23:45Z"
    }
  ],
  "next_cursor": "cur_v1_eyJ2IjoxLCJ0Ijoi…uH8.QwR2…"
}
```

Page shape (deprecated):

```json theme={null}
{
  "products": [/* …items… */],
  "total": 4,
  "page": 1,
  "per_page": 20
}
```

`pricing_type` is one of:

* `fixed` – single set price (shown as **Face Value** in the Design Centre), in `fixed_amount`.
* `range` – price between `min_amount` and `max_amount`.
* `custom` – price entered by the buyer (no preset bounds).

## Errors

* `400` – Invalid `status` value, or invalid/forged/cross-tenant `cursor`.

## Examples

```bash theme={null}
curl \
  -H "X-API-Key: vg_live_EXAMPLEdoNotUseThis123456" \
  "https://api.vouchergrid.com/api/v1/developer/products?status=live"
```

```ts theme={null}
const res = await fetch(
  "https://api.vouchergrid.com/api/v1/developer/products?status=live",
  { headers: { "X-API-Key": process.env.VOUCHERGRID_API_KEY! } },
);
const data = await res.json();
```