# List products

> The products.list operation: GET /api/v1/products in the REST API and the products_list tool in the MCP server.

Lists the brand's products in the request's mode, newest first. Filter with `active` (`true` or `false`) and
`kind` (`plan` or `standard`).

Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page).

## At a glance

- **REST:** `GET /api/v1/products`
- **MCP tool:** `products_list`
- **Operation ID:** `products.list`
- **Scope:** Brand
- **Permission:** `catalog: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 `catalog:read` scope
- **Since:** M4

## Request

### Query parameters

| Field            | Type                      | Required | Description                                          |
| ---------------- | ------------------------- | -------- | ---------------------------------------------------- |
| `active`         | string                    | No       | Only active (`true`) or archived (`false`) products. |
| `kind`           | one of `standard`, `plan` | No       |                                                      |
| `limit`          | integer (1 to 100)        | No       |                                                      |
| `starting_after` | `prod_…` 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`                        | `prod_…` ID                                                                                            |                                                                                   |
| `data[].object`                    | `"product"`                                                                                            |                                                                                   |
| `data[].brandId`                   | `brd_…` ID                                                                                             |                                                                                   |
| `data[].livemode`                  | boolean                                                                                                |                                                                                   |
| `data[].name`                      | string                                                                                                 |                                                                                   |
| `data[].description`               | string or null                                                                                         |                                                                                   |
| `data[].taxCategoryId`             | one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document) |                                                                                   |
| `data[].kind`                      | one of `standard`, `plan`                                                                              |                                                                                   |
| `data[].entitlements`              | array of object                                                                                        |                                                                                   |
| `data[].entitlements[].featureKey` | string                                                                                                 |                                                                                   |
| `data[].entitlements[].value`      | boolean or number or string                                                                            |                                                                                   |
| `data[].lifetimeEntitlements`      | boolean                                                                                                | A one-time purchase of the product grants its entitlements for good (spec §36.1). |
| `data[].displayOrder`              | integer or null                                                                                        |                                                                                   |
| `data[].highlighted`               | boolean                                                                                                |                                                                                   |
| `data[].active`                    | boolean                                                                                                |                                                                                   |
| `data[].images`                    | array of string                                                                                        |                                                                                   |
| `data[].metadata`                  | object                                                                                                 |                                                                                   |
| `data[].createdAt`                 | date-time                                                                                              |                                                                                   |
| `data[].updatedAt`                 | date-time                                                                                              |                                                                                   |
| `has_more`                         | boolean                                                                                                |                                                                                   |
| `next_cursor`                      | `prod_…` ID or null                                                                                    |                                                                                   |

## Examples

### Active plans

```http
GET /api/v1/products?active=true&kind=plan
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
      "object": "product",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "name": "Pro",
      "description": "For growing teams.",
      "taxCategoryId": "saas",
      "kind": "plan",
      "entitlements": [
        {
          "featureKey": "seats.max",
          "value": 10
        },
        {
          "featureKey": "feature.export",
          "value": true
        }
      ],
      "lifetimeEntitlements": false,
      "displayOrder": 2,
      "highlighted": true,
      "active": true,
      "images": [],
      "metadata": {},
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12: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         | A filter or pagination value is malformed. | Fix the fields listed in `details.issues` and send the request again.           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't see this brand's catalog.        | Ask an organization owner or admin for a role or scope that allows this action. |

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), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`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).