Create a price · Ownrecord docs

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

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`	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`	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`	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`	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`	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`	409	The product is archived.	Reactivate the product first (`active: true`), or use an active product.
`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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

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

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

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

A €10 credit pack with €2 bonus credits#

A one-time price#

Errors#

At a glance

Request

Body

Response

Examples

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

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

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

A €10 credit pack with €2 bonus credits

A one-time price

Errors