# Prices tools

> MCP tools for Prices: prices_archive, prices_create, prices_get, prices_list, prices_move_lookup_key, prices_update.

- `prices_archive`: Archive a price
- `prices_create`: Create a price
- `prices_get`: Get a price
- `prices_list`: List prices
- `prices_move_lookup_key`: Move a lookup key to a price
- `prices_update`: Update a price

## `prices_archive`

**Archive a price.** Operation [`prices.archive`](https://ownrecord.io/docs/reference/prices-archive.md) · Brand level · permission `catalog:write` · risk tier `write` · since M4

Archives a price: it can't be sold any more and leaves the pricing table. Subscriptions and invoices that use
it are unaffected. Its lookup key stays until you move it to the new price (`prices.move_lookup_key`).
Archiving an archived price changes nothing; reactivate it with `prices.update` and `active: true`.

`reason` is recorded in the audit log.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type           | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`price_…`) | yes      | –                                                                                                                                                                                                        |
| `reason`          | string         | no       | (1–500 characters)                                                                                                                                                                                       |
| `entity_id`       | ID (`ent_…`)   | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)   | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string         | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean        | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No price with this ID is visible to the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The price changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's catalog.

### Example

**Retire last year's price**

Arguments:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y2",
  "reason": "Replaced by the 2027 price",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "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": false,
  "used": false,
  "usedAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

## `prices_create`

**Create a price.** Operation [`prices.create`](https://ownrecord.io/docs/reference/prices-create.md) · Brand level · permission `catalog:write` · risk tier `write` · since M4

Creates a price for one of the brand's products. Types:

- `one_time`: a fixed `amount`, or a `customAmount` range the buyer chooses from;
- `credit_pack`: like one-time, plus `creditPack` (`bonusCredits` granted as promo credits,
  `expiresAfterDays`). A fixed pack's `credits` equal its amount; what the wallet receives follows the brand's
  credit basis (net by default);
- `recurring`: `per_unit` (`unitAmount` × quantity) or `tiered` (`graduated` or `volume` tiers, each with an
  optional `flatAmount`), with optional `trialDays` and `includedCredits`. Recurring prices are sold with
  subscriptions.

A recurring price with `usageType: metered` takes its quantity from usage events (`usage_events.create`),
billed in arrears. `recurring.metered` names the `meter` (e.g. `api.calls`), its `aggregation` per period
(`sum`, `max` or `last`) and its `pricing`: `per_unit` uses the price's `unitAmount` or tiers per unit of usage;
`percent_of_amount` reads the quantity as an amount in micros of the price's currency and charges `ratePpm`
(0.4% = `"4000"`), with no unit amount or tiers. Optional: `includedQuantity` (free per period),
`minimumCharge` and `maximumCharge` (per period). Every metered price of a meter uses the same aggregation and
pricing (and, for percent of amount, the same currency).

Money is `{ amount: "<integer micros>", currency }` (12.50 EUR = `"12500000"`). Charged amounts use whole
minor units of the currency; unit prices may be finer (`unitAmountMicros` `"2500"` = 0.0025).
`taxBehavior` says whether the amounts include tax (`inclusive`, required for consumer prices in the EU and
UK) or not (`exclusive`).

Once a checkout session or payment uses the price, what it charges can't change: create a new price and move
the lookup key to it (`prices.move_lookup_key`).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type                                          | Required | Description                                                                                                                                                                                              |
| ----------------- | --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productId`       | ID (`prod_…`)                                 | yes      | The product the price belongs to.                                                                                                                                                                        |
| `type`            | one of `one_time`, `recurring`, `credit_pack` | yes      | `one_time`, `credit_pack` or `recurring` (licensed or metered: per unit or tiered).                                                                                                                      |
| `currency`        | string                                        | yes      | ISO 4217 currency code; every amount of the price uses it.                                                                                                                                               |
| `taxBehavior`     | one of `inclusive`, `exclusive`               | yes      | `inclusive`: the amount includes tax (consumer prices in the EU and UK); `exclusive`: tax is added.                                                                                                      |
| `nickname`        | string                                        | no       | An internal label, never shown to customers. (1–120 characters)                                                                                                                                          |
| `lookupKey`       | string                                        | no       | A stable name for the price, unique in the brand and mode, e.g. `pro_monthly`.                                                                                                                           |
| `amount`          | object                                        | no       | One-time and credit-pack prices: the fixed amount (whole minor units).                                                                                                                                   |
| `customAmount`    | object                                        | no       | One-time and credit-pack prices: let the buyer choose an amount in this range instead.                                                                                                                   |
| `creditPack`      | object                                        | no       | Credit packs: the credit terms.                                                                                                                                                                          |
| `recurring`       | object                                        | no       | Recurring prices: the billing period and scheme.                                                                                                                                                         |
| `metadata`        | object                                        | no       | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.                                                                                                                        |
| `entity_id`       | ID (`ent_…`)                                  | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)                                  | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string                                        | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                                       | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`org_restricted`](https://ownrecord.io/docs/reference/errors.md#org_restricted): Live mode, while the organization's Ownrecord subscription is unpaid (§37.5).
- [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required): A recurring price without the plan's subscriptions, or a metered one without its usage billing.
- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is missing or malformed, or the price's terms break a rule (`details.issues` names each field).
- [`meter_definition_conflict`](https://ownrecord.io/docs/reference/errors.md#meter_definition_conflict): Another metered price of the meter uses another aggregation, pricing or (percent of amount) currency.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No product with this ID is visible to the request.
- [`product_archived`](https://ownrecord.io/docs/reference/errors.md#product_archived): The product is archived.
- [`lookup_key_taken`](https://ownrecord.io/docs/reference/errors.md#lookup_key_taken): Another price of the brand already has the lookup key.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's catalog.

### Examples

**Monthly per-seat price, graduated tiers, 14-day trial**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "type": "recurring",
  "currency": "EUR",
  "taxBehavior": "inclusive",
  "nickname": "Pro monthly, per seat",
  "lookupKey": "pro_monthly",
  "recurring": {
    "interval": "month",
    "billingScheme": "tiered",
    "tiersMode": "graduated",
    "tiers": [
      {
        "upTo": 10,
        "unitAmountMicros": "12000000"
      },
      {
        "upTo": "inf",
        "unitAmountMicros": "9000000"
      }
    ],
    "trialDays": 14
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "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"
}
```

**Metered: 0.4% of the processed volume, at least €5 a month**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "type": "recurring",
  "currency": "EUR",
  "taxBehavior": "exclusive",
  "nickname": "Volume fee",
  "lookupKey": "volume_monthly",
  "recurring": {
    "interval": "month",
    "usageType": "metered",
    "metered": {
      "meter": "payments.volume",
      "pricing": "percent_of_amount",
      "ratePpm": "4000",
      "minimumCharge": {
        "amount": "5000000",
        "currency": "EUR"
      }
    }
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y8",
  "object": "price",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "nickname": "Volume fee",
  "lookupKey": "volume_monthly",
  "type": "recurring",
  "currency": "EUR",
  "taxBehavior": "exclusive",
  "amount": null,
  "customAmount": null,
  "creditPack": null,
  "recurring": {
    "interval": "month",
    "intervalCount": 1,
    "usageType": "metered",
    "billingScheme": "per_unit",
    "unitAmount": null,
    "tiersMode": null,
    "tiers": null,
    "trialDays": null,
    "includedCredits": null,
    "metered": {
      "meter": "payments.volume",
      "aggregation": "sum",
      "pricing": "percent_of_amount",
      "ratePpm": "4000",
      "includedQuantity": null,
      "minimumCharge": {
        "amount": "5000000",
        "currency": "EUR"
      },
      "maximumCharge": null
    }
  },
  "active": true,
  "used": false,
  "usedAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

**Metered: €0.002 per API call after 10,000 free calls a month**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "type": "recurring",
  "currency": "EUR",
  "taxBehavior": "exclusive",
  "nickname": "API calls",
  "lookupKey": "api_calls_monthly",
  "recurring": {
    "interval": "month",
    "usageType": "metered",
    "unitAmount": {
      "amount": "2000",
      "currency": "EUR"
    },
    "metered": {
      "meter": "api.calls",
      "aggregation": "sum",
      "includedQuantity": "10000"
    }
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y9",
  "object": "price",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "nickname": "API calls",
  "lookupKey": "api_calls_monthly",
  "type": "recurring",
  "currency": "EUR",
  "taxBehavior": "exclusive",
  "amount": null,
  "customAmount": null,
  "creditPack": null,
  "recurring": {
    "interval": "month",
    "intervalCount": 1,
    "usageType": "metered",
    "billingScheme": "per_unit",
    "unitAmount": {
      "amount": "2000",
      "currency": "EUR"
    },
    "tiersMode": null,
    "tiers": null,
    "trialDays": null,
    "includedCredits": null,
    "metered": {
      "meter": "api.calls",
      "aggregation": "sum",
      "pricing": "per_unit",
      "ratePpm": null,
      "includedQuantity": "10000",
      "minimumCharge": null,
      "maximumCharge": null
    }
  },
  "active": true,
  "used": false,
  "usedAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

**A €10 credit pack with €2 bonus credits**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1",
  "type": "credit_pack",
  "currency": "EUR",
  "taxBehavior": "inclusive",
  "lookupKey": "credits_10",
  "amount": {
    "amount": "10000000",
    "currency": "EUR"
  },
  "creditPack": {
    "bonusCredits": {
      "amount": "2000000",
      "currency": "EUR"
    },
    "expiresAfterDays": 365
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y4",
  "object": "price",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1",
  "nickname": null,
  "lookupKey": "credits_10",
  "type": "credit_pack",
  "currency": "EUR",
  "taxBehavior": "inclusive",
  "amount": {
    "amount": "10000000",
    "currency": "EUR"
  },
  "customAmount": null,
  "creditPack": {
    "credits": {
      "amount": "10000000",
      "currency": "EUR"
    },
    "bonusCredits": {
      "amount": "2000000",
      "currency": "EUR"
    },
    "expiresAfterDays": 365
  },
  "recurring": null,
  "active": true,
  "used": false,
  "usedAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

**A one-time price**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1",
  "type": "one_time",
  "currency": "EUR",
  "taxBehavior": "inclusive",
  "amount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y5",
  "object": "price",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1",
  "nickname": null,
  "lookupKey": null,
  "type": "one_time",
  "currency": "EUR",
  "taxBehavior": "inclusive",
  "amount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "customAmount": null,
  "creditPack": null,
  "recurring": null,
  "active": true,
  "used": false,
  "usedAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

## `prices_get`

**Get a price.** Operation [`prices.get`](https://ownrecord.io/docs/reference/prices-get.md) · Brand level · permission `catalog:read` · risk tier `read` · since M4

Returns one price of the brand's catalog in the request's mode, archived or not. `used` says whether a
checkout session or payment has referenced it (then what it charges can't change).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument    | Type           | Required | Description                                                                                                                              |
| ----------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | ID (`price_…`) | yes      | –                                                                                                                                        |
| `entity_id` | ID (`ent_…`)   | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`  | ID (`brd_…`)   | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No price with this ID is visible to the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this brand's catalog.

### Example

**A monthly per-seat price**

Arguments:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y2",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "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"
}
```

## `prices_list`

**List prices.** Operation [`prices.list`](https://ownrecord.io/docs/reference/prices-list.md) · Brand level · permission `catalog:read` · risk tier `read` · since M4

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).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type                                          | Required | Description                                                                                                                              |
| ---------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `productId`      | ID (`prod_…`)                                 | 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                                       | no       | (1–100)                                                                                                                                  |
| `starting_after` | ID (`price_…`)                                | no       | –                                                                                                                                        |
| `entity_id`      | ID (`ent_…`)                                  | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`       | ID (`brd_…`)                                  | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or pagination value is malformed.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this brand's catalog.

### Examples

**The price behind a lookup key**

Arguments:

```json
{
  "lookupKey": "pro_monthly",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```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**

Arguments:

```json
{
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "active": "true",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```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
}
```

## `prices_move_lookup_key`

**Move a lookup key to a price.** Operation [`prices.move_lookup_key`](https://ownrecord.io/docs/reference/prices-move-lookup-key.md) · Brand level · permission `catalog:write` · risk tier `write` · since M4

Moves a lookup key to this price, taking it from the price that has it (if any) in the same step. Use it when
a new price replaces an old one: integrators that look prices up by key (`prices.list?lookupKey=…`, checkout
sessions) get the new price at once, and nothing references a price ID that changed.

The price must be active and have no other lookup key (remove that first). Moving a key to the price that
already has it changes nothing. Both prices get a `price.updated` event.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type           | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`price_…`) | yes      | The price that gets the key.                                                                                                                                                                             |
| `lookupKey`       | string         | yes      | A stable name for the price, unique in the brand and mode, e.g. `pro_monthly`.                                                                                                                           |
| `entity_id`       | ID (`ent_…`)   | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)   | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string         | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean        | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The lookup key is malformed.
- [`price_archived`](https://ownrecord.io/docs/reference/errors.md#price_archived): The price is archived.
- [`price_lookup_key_conflict`](https://ownrecord.io/docs/reference/errors.md#price_lookup_key_conflict): The price already has another lookup key.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No price with this ID is visible to the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): One of the prices changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's catalog.

### Example

**Point pro_monthly at the new price**

Arguments:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y3",
  "lookupKey": "pro_monthly",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y3",
  "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-14T09:30:00.000Z"
}
```

## `prices_update`

**Update a price.** Operation [`prices.update`](https://ownrecord.io/docs/reference/prices-update.md) · Brand level · permission `catalog:write` · risk tier `write` · since M4

Changes a price's nickname, lookup key, metadata or `active` (false archives it, true reactivates it). Send
only the fields to change; `null` clears an optional value; `metadata` replaces the whole map.

While no checkout session or payment has used the price (`used: false`), its tax behaviour and amounts can
change as well: each of `amount`, `customAmount`, `creditPack` and `recurring` replaces the stored value.
Once used, those are fixed (`price_immutable`): create a new price, move the lookup key to it with
`prices.move_lookup_key`, and archive this one. The type and currency never change.

A lookup key held by another price isn't moved silently (`lookup_key_taken`); use `prices.move_lookup_key`.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type                            | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`price_…`)                  | yes      | –                                                                                                                                                                                                        |
| `nickname`        | string or null                  | no       | –                                                                                                                                                                                                        |
| `lookupKey`       | string or null                  | no       | Set a free lookup key, or null to remove it. To take one from another price, use prices.move_lookup_key.                                                                                                 |
| `metadata`        | object                          | no       | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.                                                                                                                        |
| `active`          | boolean                         | no       | false archives the price, true reactivates it.                                                                                                                                                           |
| `taxBehavior`     | one of `inclusive`, `exclusive` | no       | Unused prices only.                                                                                                                                                                                      |
| `amount`          | object or null                  | no       | Unused prices only: the fixed amount; null removes it.                                                                                                                                                   |
| `customAmount`    | object or null                  | no       | Unused prices only: the custom amount range; null removes it.                                                                                                                                            |
| `creditPack`      | object                          | no       | Unused credit packs only: the credit terms.                                                                                                                                                              |
| `recurring`       | object                          | no       | Unused recurring prices only: the billing period and scheme.                                                                                                                                             |
| `entity_id`       | ID (`ent_…`)                    | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)                    | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string                          | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                         | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): No field to change was sent, one is malformed, or the new terms break a rule.
- [`price_immutable`](https://ownrecord.io/docs/reference/errors.md#price_immutable): The price has been used and the request changes what it charges.
- [`meter_definition_conflict`](https://ownrecord.io/docs/reference/errors.md#meter_definition_conflict): New metered terms disagree with another metered price of the meter (aggregation, pricing or currency).
- [`lookup_key_taken`](https://ownrecord.io/docs/reference/errors.md#lookup_key_taken): Another price of the brand already has the lookup key.
- [`price_archived`](https://ownrecord.io/docs/reference/errors.md#price_archived): A lookup key was set on an archived price.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No price with this ID is visible to the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The price changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's catalog.

### Example

**Rename a price**

Arguments:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y2",
  "nickname": "Pro monthly (2026)",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "price_01m4tx5nj8emwbyf7y9vcf47y2",
  "object": "price",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "nickname": "Pro monthly (2026)",
  "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-14T09:30:00.000Z"
}
```