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

Path Parameters

id
string
required

The product id (prod_…).

Body

application/json
price_id
string
required

The price to set as default (price_…).

Response

The product with its new default price id set.

id
string
required

Product id (prod_…).

object
enum<string>
required
Available options:
product
merchant_id
string
required
name
string
required
description
string
required
active
boolean
required
images
string[]
required
metadata
object
required
livemode
boolean
required

true for live mode, false for test mode.

default_price_id
string | null
required

The product's default price (price_…), or null if none is set.

unit_label
string
required

Unit displayed at checkout.

product_kind
enum<string>
required
Available options:
digital,
physical,
service,
donation,
other
cross_sells
object[]
required
created_at
integer
required

Unix epoch seconds.

updated_at
integer
required

Unix epoch seconds.

default_price
object | null

Inline-expanded default price. Present on GET and list responses; omitted on mutation endpoints (create, update, set_default_price).

representative_price
object | null

Display-only fallback populated when no default is set but exactly one price exists. Present on GET and list responses; omitted on mutation endpoints. Must not be treated as the assigned default.

prices_count
integer | null

Total number of prices on this product. Present on GET and list responses; omitted on mutation endpoints.