# List prices > The prices.list operation: GET /api/v1/prices in the REST API and the prices_list tool in the MCP server. Lists the brand's prices in the request's mode, newest first. Filter with `productId`, `type`, `currency`, `active` (`true` or `false`) and `lookupKey` (at most one price has it). Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/prices` - **MCP tool:** `prices_list` - **Operation ID:** `prices.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 | | ---------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------ | | `productId` | `prod_…` ID | No | | | `type` | one of `one_time`, `recurring`, `credit_pack` | No | | | `currency` | string | No | | | `active` | string | No | Only active (`true`) or archived (`false`) prices. | | `lookupKey` | string | No | A stable name for the price, unique in the brand and mode, e.g. `pro_monthly`. | | `limit` | integer (1 to 100) | No | | | `starting_after` | `price_…` 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` | `price_…` ID | | | `data[].object` | `"price"` | | | `data[].brandId` | `brd_…` ID | | | `data[].livemode` | boolean | | | `data[].productId` | `prod_…` ID | | | `data[].nickname` | string or null | | | `data[].lookupKey` | string or null | | | `data[].type` | one of `one_time`, `recurring`, `credit_pack` | | | `data[].currency` | string | | | `data[].taxBehavior` | one of `inclusive`, `exclusive` | | | `data[].amount` | money or null | Fixed one-time or credit-pack amount. | | `data[].customAmount` | object or null | The range a buyer may choose from (custom-amount prices). | | `data[].creditPack` | object or null | | | `data[].recurring` | object or null | | | `data[].active` | boolean | | | `data[].used` | boolean | A checkout session or payment referenced the price: what it charges can no longer change. | | `data[].usedAt` | date-time or null | | | `data[].metadata` | object | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `price_…` ID or null | | ## Examples ### The price behind a lookup key ```http GET /api/v1/prices?lookupKey=pro_monthly Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "price_01m4tx5nj8emwbyf7y9vcf47y2", "object": "price", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0", "nickname": "Pro monthly, per seat", "lookupKey": "pro_monthly", "type": "recurring", "currency": "EUR", "taxBehavior": "inclusive", "amount": null, "customAmount": null, "creditPack": null, "recurring": { "interval": "month", "intervalCount": 1, "usageType": "licensed", "billingScheme": "tiered", "unitAmount": null, "tiersMode": "graduated", "tiers": [ { "upTo": 10, "unitAmountMicros": "12000000", "flatAmount": null }, { "upTo": "inf", "unitAmountMicros": "9000000", "flatAmount": null } ], "trialDays": 14, "includedCredits": null, "metered": null }, "active": true, "used": false, "usedAt": null, "metadata": {}, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ### A product's active prices ```http GET /api/v1/prices?productId=prod_01m4tx5nj8emwbyf7y9vcf47y0&active=true Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "price_01m4tx5nj8emwbyf7y9vcf47y2", "object": "price", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0", "nickname": "Pro monthly, per seat", "lookupKey": "pro_monthly", "type": "recurring", "currency": "EUR", "taxBehavior": "inclusive", "amount": null, "customAmount": null, "creditPack": null, "recurring": { "interval": "month", "intervalCount": 1, "usageType": "licensed", "billingScheme": "tiered", "unitAmount": null, "tiersMode": "graduated", "tiers": [ { "upTo": 10, "unitAmountMicros": "12000000", "flatAmount": null }, { "upTo": "inf", "unitAmountMicros": "9000000", "flatAmount": null } ], "trialDays": 14, "includedCredits": null, "metered": null }, "active": true, "used": false, "usedAt": null, "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).