Skip to main content
POST
Create Plan
Plans are immutableThere’s no update endpoint. A price change means creating a new plan — existing subscriptions stay on the plan (and price) they were created with until you move them or they cancel. To move them, use Change Subscription Plan (immediate replacement) or the plan_change object on Update Subscription (scheduled, same id).
Refer to the HTTP Response Codes section for details on possible error outcomes.

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Body

application/json
name
string
required

The plan name (MAX 255; MIN 3).

base_amount
object
required

The default price used for any country without an explicit entry in country_prices.

frequency
object
required

The billing frequency for the plan. Subscriptions created from this plan inherit it.

description
string

The plan description. No length limit is currently enforced.

merchant_reference
string

Your own identifier for the plan. No length limit is currently enforced.

country_prices
object[]

Optional explicit per-country prices. A country not listed falls back to base_amount.

allowed_payment_methods
string[]

Payment method types accepted for subscriptions on this plan.

metadata
object[]

Key-value pairs attached to the plan. Independent of any metadata set on a subscription created from it.

phases
object[]

Optional leading ladder (for example, a trial) before the plan's regular price. Omit for a flat plan. The last entry must be the terminal REGULAR phase with no duration.

Response

200

id
string
account_id
string
name
string
description
string
merchant_reference
string
status
string
Example:

"ACTIVE"

base_amount
object
frequency
object
country_prices
object[]
allowed_payment_methods
string[]
metadata
object[]
phases
object[]
created_at
string
updated_at
string