Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json
product_id
string
required

The product this price belongs to (prod_…).

unit_amount
integer<int64>
required

Billing amount in minor units (e.g. cents for USD).

currency
string
required

Three-letter ISO currency code (e.g. USD).

type
enum<string>

Price type. Inferred from whether recurring is present when omitted.

Available options:
one_time,
recurring
nickname
string

Display label for this price variant.

metadata
object

Custom key-value metadata. Max 50 keys; keys up to 40 characters; values up to 500 characters.

make_default
boolean

If true, atomically set this price as the product's default after creation.

recurring
object | null

Cadence for recurring prices. Omit for one-time prices.

Response

The created price.

id
string
required

Price id (price_…).

object
enum<string>
required
Available options:
price
product_id
string
required

Parent product (prod_…).

merchant_id
string
required
unit_amount
integer<int64>
required

Billing amount in minor units.

currency
string
required

Three-letter ISO currency code.

type
enum<string>
required

Price type.

Available options:
one_time,
recurring
active
boolean
required
nickname
string
required

Display label for this price variant.

metadata
object
required
livemode
boolean
required

true for live mode, false for test mode.

created_at
integer
required

Unix epoch seconds.

updated_at
integer
required

Unix epoch seconds.

recurring
object | null

Cadence for recurring prices; null for one-time prices.