Skip to main content
POST
Create a plan for a product

Authorizations

Authorization
string
header
required

Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer token.

Path Parameters

productRef
string
required

Product reference or ID

Example:

"prd_1A2B3C4D"

Body

application/json
name
string
required
Required string length: 2 - 200
Pattern: ^[\p{L}\p{N} .,'"&\/()+:\-]*$
options
object[]
required
accessExpiryDays
integer
Required range: x > 0
currency
string
Required string length: 3
description
string
Maximum string length: 500
Pattern: ^[\p{L}\p{N}\s.,'"&\/()+:%;?!@#_[\]\-]*$
features
object
maxActiveUsers
integer
Required range: x > 0
metadata
object
status
enum<string>
Available options:
active,
inactive,
archived
taxBehavior
enum<string>
Available options:
auto,
inclusive,
exclusive

Response

Plan created successfully

createdAt
string
required

Creation timestamp

isActive
boolean
required

Whether the plan is active (derived from status)

Example:

true

options
object[]
required

Composable pricing options (money as integer minor units)

reference
string
required

Plan reference

Example:

"pln_1A2B3C4D"

status
string
required

Plan status

Example:

"active"

type
enum<string>
required

Derived plan type (read from options)

Available options:
recurring,
one-time,
usage-based,
hybrid
Example:

"recurring"

updatedAt
string
required

Last update timestamp

accessExpiryDays
number

Access expiry in days

currency
string

Currency code (ISO 4217)

Example:

"USD"

currencySymbol
string

Currency symbol (derived from currency)

Example:

"$"

description
string

Plan description

Example:

"Best for teams getting started"

features
object

Plan features

maxActiveUsers
number

Maximum number of active users

name
string

Plan name

Example:

"Starter"

price
number

Derived headline price in minor units (the base or one-time charge)

Example:

2999

requiresPayment
boolean

Whether payment is required

Example:

true