# Create a price > The prices.create operation: POST /api/v1/prices in the REST API and the prices_create tool in the MCP server. 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: "", 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`). ## At a glance - **REST:** `POST /api/v1/prices` - **MCP tool:** `prices_create` - **Operation ID:** `prices.create` - **Scope:** Brand - **Permission:** `catalog:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `catalog:write` scope - **Since:** M4 ## Request ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | -------------------------------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `productId` | `prod_…` ID | 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. | | `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). | | `amount.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `amount.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `customAmount` | object | No | One-time and credit-pack prices: let the buyer choose an amount in this range instead. | | `customAmount.min` | object | Yes | The smallest amount the buyer may choose. | | `customAmount.min.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `customAmount.min.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `customAmount.max` | object | Yes | The largest amount the buyer may choose. | | `customAmount.max.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `customAmount.max.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `customAmount.preset` | object | No | The amount suggested to the buyer. | | `customAmount.preset.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `customAmount.preset.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `creditPack` | object | No | Credit packs: the credit terms. | | `creditPack.credits` | object | No | The pack's nominal credits; equals the amount (the default). Custom-amount packs have none. What the wallet receives follows the brand's credit basis (net by default). | | `creditPack.credits.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `creditPack.credits.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `creditPack.bonusCredits` | object | No | Promo credits granted on top of the purchase. | | `creditPack.bonusCredits.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `creditPack.bonusCredits.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `creditPack.expiresAfterDays` | integer | No | Days until the credits expire (1–3650). | | `recurring` | object | No | Recurring prices: the billing period and scheme. | | `recurring.interval` | one of `day`, `week`, `month`, `year` | Yes | The billing period's unit. | | `recurring.intervalCount` | integer | No | Periods per billing cycle (default 1). | | `recurring.usageType` | one of `licensed`, `metered` | No | `licensed`: the quantity is seats or units; `metered`: the quantity comes from usage events of `metered.meter`, billed in arrears. | | `recurring.billingScheme` | one of `per_unit`, `tiered` | No | `per_unit`: unitAmount × quantity; `tiered`: priced by tiers. | | `recurring.unitAmount` | object | No | Per-unit prices: the price of one unit per period. | | `recurring.unitAmount.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `recurring.unitAmount.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `recurring.tiersMode` | one of `graduated`, `volume` | No | Tiered prices: `graduated` (each tier priced separately) or `volume` (all units at the reached tier). | | `recurring.tiers` | array of object | No | Tiered prices: the tiers, lowest first. | | `recurring.tiers[].upTo` | integer or `"inf"` | Yes | The last unit of the tier (inclusive); `"inf"` for the last tier. | | `recurring.tiers[].unitAmountMicros` | string | Yes | Price per unit in micros, as a string; sub-minor precision allowed (2500 = 0.0025). | | `recurring.tiers[].flatAmount` | object | No | A fixed amount added once when the tier is reached. | | `recurring.tiers[].flatAmount.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `recurring.tiers[].flatAmount.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `recurring.trialDays` | integer | No | Free trial days for new subscriptions (1–730). | | `recurring.includedCredits` | object | No | Credits included every period (spec §17). | | `recurring.includedCredits.amount` | object | Yes | Credits granted into the wallet each period. | | `recurring.includedCredits.amount.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `recurring.includedCredits.amount.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `recurring.includedCredits.expiresAfterDays` | integer | No | | | `recurring.metered` | object | No | Metered prices (`usageType: metered`): the meter and how its usage is aggregated and priced. | | `recurring.metered.meter` | string | Yes | The meter usage events name, e.g. `api.calls` or `payments.volume`. | | `recurring.metered.aggregation` | one of `sum`, `max`, `last` | No | How a period's usage is aggregated: `sum` of quantities, `max` (the largest), or `last` (the latest event's). | | `recurring.metered.pricing` | one of `per_unit`, `percent_of_amount` | No | `per_unit`: the price's `unitAmount` or tiers per unit of usage; `percent_of_amount`: the quantity is an amount in micros of the price's currency, charged at `ratePpm`. | | `recurring.metered.ratePpm` | string | No | `percent_of_amount` only: the rate in parts per million (0.4% = `"4000"`). | | `recurring.metered.includedQuantity` | string | No | Free usage per period, subtracted first (micros of the currency for `percent_of_amount`). | | `recurring.metered.minimumCharge` | object | No | The least the price charges per period, usage or not. | | `recurring.metered.minimumCharge.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `recurring.metered.minimumCharge.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `recurring.metered.maximumCharge` | object | No | The most the price charges per period. | | `recurring.metered.maximumCharge.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `recurring.metered.maximumCharge.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `metadata` | object | No | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced. | ## Response `201 Created` with a JSON object: | Field | Type | Description | | -------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- | | `id` | `price_…` ID | | | `object` | `"price"` | | | `brandId` | `brd_…` ID | | | `livemode` | boolean | | | `productId` | `prod_…` ID | | | `nickname` | string or null | | | `lookupKey` | string or null | | | `type` | one of `one_time`, `recurring`, `credit_pack` | | | `currency` | string | | | `taxBehavior` | one of `inclusive`, `exclusive` | | | `amount` | money or null | Fixed one-time or credit-pack amount. | | `customAmount` | object or null | The range a buyer may choose from (custom-amount prices). | | `creditPack` | object or null | | | `recurring` | object or null | | | `active` | boolean | | | `used` | boolean | A checkout session or payment referenced the price: what it charges can no longer change. | | `usedAt` | date-time or null | | | `metadata` | object | | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### Monthly per-seat price, graduated tiers, 14-day trial ```http POST /api/v1/prices Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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 } } ``` Response (`201`): ```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 ```http POST /api/v1/prices Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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" } } } } ``` Response (`201`): ```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 ```http POST /api/v1/prices Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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" } } } ``` Response (`201`): ```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 ```http POST /api/v1/prices Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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 } } ``` Response (`201`): ```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 ```http POST /api/v1/prices Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1", "type": "one_time", "currency": "EUR", "taxBehavior": "inclusive", "amount": { "amount": "49000000", "currency": "EUR" } } ``` Response (`201`): ```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" } ``` ## Errors | Code | HTTP status | When | What to do | | ------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | [`org_restricted`](https://ownrecord.io/docs/reference/errors.md#org_restricted) | 403 | Live mode, while the organization's Ownrecord subscription is unpaid (§37.5). | Pay the open Ownrecord invoice in Organization → Billing; the restriction lifts as soon as it is paid. Test mode keeps working. | | [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required) | 403 | A recurring price without the plan's subscriptions, or a metered one without its usage billing. | Upgrade the organization's plan, or remove something to get back under the limit. | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A field is missing or malformed, or the price's terms break a rule (`details.issues` names each field). | Fix the fields listed in `details.issues` and send the request again. | | [`meter_definition_conflict`](https://ownrecord.io/docs/reference/errors.md#meter_definition_conflict) | 409 | Another metered price of the meter uses another aggregation, pricing or (percent of amount) currency. | Use the meter's existing aggregation and pricing (and, for percent of amount, its currency), or choose another meter key. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No product with this ID is visible to the request. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`product_archived`](https://ownrecord.io/docs/reference/errors.md#product_archived) | 409 | The product is archived. | Reactivate the product first (`active: true`), or use an active product. | | [`lookup_key_taken`](https://ownrecord.io/docs/reference/errors.md#lookup_key_taken) | 409 | Another price of the brand already has the lookup key. | Move the key explicitly with `prices.move_lookup_key` (POST /prices/{id}/move_lookup_key), or choose another key. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change 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), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`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), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).