Skip to main content
POST
Create a product
Authenticate with an API key that belongs to the target organization and has Full access or the products:products:write permission. Only the Owner and Admin roles can grant it.
  • Takes the same inputs as creating a product in the dashboard: one product with one price.
  • Unlike the dashboard, it doesn’t create a payment link. To get a shareable URL, create a payment link for the product, or sell the price with a checkout session (see below).
  • Send a unique Idempotency-Key header (required; 1–255 ASCII characters from 0x21 to 0x7E, no spaces), the same rule as checkout sessions. The same key with the same body returns the product created the first time (201) and creates nothing new. The same key with a different body returns 409. If the product created with that key was later deleted, a retry also returns 409; send a new key.
  • pricingType is ONE_TIME or SUBSCRIPTION. pricing is a string in major units, such as "19.99". Omit pricing for a flexible “pay what you want” price; this works for ONE_TIME only, and minAmount and maxAmount are then optional.
  • A SUBSCRIPTION price needs billingInterval (DAY, MONTH or YEAR). billingIntervalCount is optional and defaults to 1.
  • status is PUBLISHED (default), DRAFT or ARCHIVED. A DRAFT product can’t be published or archived later. To keep a product off sale for now, create it as ARCHIVED and publish it when ready.
  • Unknown fields are rejected with 400.
  • To sell a fixed price, pass the returned pricing.pricingId as pricingId to Create a checkout session. Checkout sessions can’t sell a flexible amount; for that, create a payment link.

Authorizations

X-API-Key
string
header
required

Merchant API key (format: ak_BASE64)

Headers

Idempotency-Key
string
required

Unique creation request key: 1-255 ASCII characters in the range 0x21-0x7E (no spaces or control characters)

Required string length: 1 - 255

Body

application/json

Product and price

name
string
required

Product name

pricingType
enum<string>
required
Available options:
SUBSCRIPTION,
ONE_TIME
currency
string
required

Currency code, for example USD

description
string
pricing
string

Price in major units, for example "19.99". Omit for a flexible (pay what you want) price, which is ONE_TIME only.

minAmount
number

Optional minimum for a flexible price (ONE_TIME only)

maxAmount
number

Optional maximum for a flexible price (ONE_TIME only)

pricingName
string

Name of the price

billingInterval
enum<string>
Available options:
DAY,
MONTH,
YEAR
billingIntervalCount
integer

Number of intervals between charges (SUBSCRIPTION). Defaults to 1.

status
enum<string>
default:PUBLISHED
Available options:
PUBLISHED,
DRAFT,
ARCHIVED

Response

Created

data
object
error
object
message
string
success
boolean