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
name
string
required

Product name.

description
string | null

Product description.

images
string[]

Image URLs. Schemes javascript:, data:, and vbscript: are rejected.

metadata
object

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

unit_label
string | null

Unit displayed at checkout (e.g. seat, hour, license).

product_kind
enum<string>

Product kind. Defaults to other if omitted.

Available options:
digital,
physical,
service,
donation,
other
cross_sells
object[]

Cross-sell recommendations shown at checkout.

Response

The created product.

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.