List prices · Ownrecord docs

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`	400	A filter or pagination value is malformed.	Fix the fields listed in `details.issues` and send the request again.
`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: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The price behind a lookup key#

A product's active prices#

Errors#