Prices tools · Ownrecord docs

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 · 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: No price with this ID is visible to the request.
version_conflict: The price changed at the same time; retry.
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 · 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: Live mode, while the organization's Ownrecord subscription is unpaid (§37.5).
entitlement_required: A recurring price without the plan's subscriptions, or a metered one without its usage billing.
validation_failed: A field is missing or malformed, or the price's terms break a rule (details.issues names each field).
meter_definition_conflict: Another metered price of the meter uses another aggregation, pricing or (percent of amount) currency.
resource_not_found: No product with this ID is visible to the request.
product_archived: The product is archived.
lookup_key_taken: Another price of the brand already has the lookup key.
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 · 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: No price with this ID is visible to the request.
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 · 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: A filter or pagination value is malformed.
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 · 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: The lookup key is malformed.
price_archived: The price is archived.
price_lookup_key_conflict: The price already has another lookup key.
resource_not_found: No price with this ID is visible to the request.
version_conflict: One of the prices changed at the same time; retry.
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 · 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: No field to change was sent, one is malformed, or the new terms break a rule.
price_immutable: The price has been used and the request changes what it charges.
meter_definition_conflict: New metered terms disagree with another metered price of the meter (aggregation, pricing or currency).
lookup_key_taken: Another price of the brand already has the lookup key.
price_archived: A lookup key was set on an archived price.
resource_not_found: No price with this ID is visible to the request.
version_conflict: The price changed at the same time; retry.
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"
}

prices_archive#

Arguments#

Errors#

Example#

prices_create#

Arguments#

Errors#

Examples#

prices_get#

Arguments#

Errors#

Example#

prices_list#

Arguments#

Errors#

Examples#

prices_move_lookup_key#

Arguments#

Errors#

Example#

prices_update#

Arguments#

Errors#

Example#

`prices_archive`

Arguments

Errors

Example

`prices_create`

Arguments

Errors

Examples

`prices_get`

Arguments

Errors

Example

`prices_list`

Arguments

Errors

Examples

`prices_move_lookup_key`

Arguments

Errors

Example

`prices_update`

Arguments

Errors

Example