Add a new subscription tier to your project. Define the plan name, price, currency, and billing duration to offer members different membership options. You can also configure whether the plan supports recurring payments, one-time purchases, or both.
POST/v2/projects/{project_id}/plans
Authorization
Bearer API KeyRequired
API key access: Unrestricted project API key required. Restricted keys cannot call this endpoint.
Path Parameters
project_idstringrequired
The unique identifier of the project.
Request Body
plan_namestringrequired
Display name (3–50 characters). Supports letters in any language, numbers, spaces, hyphens, underscores, parentheses, square brackets, dot, comma, percent, plus, supported currency symbols and emojis.
plan_pricestring|numberrequired
Nonnegative price within the currency's decimal limit. Prefer a decimal string such as 29.99; JSON numbers must also satisfy the numeric precision limits.
plan_currencystringrequired
A supported currency code (e.g., USD, EUR).
plan_price_formattedstringrequired
Formatted display price, for example $29.99. Required separately from the numeric price.
plan_durationstringrequired
Duration of the plan (e.g., '1 hour', '1 day', '1 month').
plan_targetsarray
Target selections, for example [{"kind":"role","external_id":"123456789012345678"}]. Each kind is role, channel or group; external_id is the platform numeric ID as a string.
plan_dataobject
Additional plan configuration options.
plan_data.plan_recurringboolean
Whether the plan supports recurring payments.
plan_data.plan_one_timeboolean
Whether the plan supports one-time payments.
plan_data.plan_trialstring
Trial duration, for example '1 day'. Use a positive relative duration for a trial; do not use an absolute date or the lifetime value '0'. Applies to recurring and nonrecurring trial plans.
To configure a recurring trial, send plan_data: {"plan_recurring": true, "plan_one_time": false, "plan_trial": "1 day"} with a positive plan price and a finite plan_duration, such as "1 month". For a nonrecurring trial, set plan_recurring to false and plan_one_time to true. See Automatic Trials for Named Members for project-key checkout behavior.
Trial eligibility is per customer and plan within the project. A completed checkout on that plan consumes eligibility; terminating its membership does not reset it. Omitted or empty plan_targets makes a plan universal across the project's applicable targets.
Prices follow the decimal input rules and the selected currency's precision. USD allows 2 decimal places, JPY 0, BTC 8, and ETH 18. Trailing zeroes do not count: "10.000" USD is accepted; "10.006" USD returns 422 VALIDATION_ERROR instead of being rounded. The 18-digit input limit still applies to the fractional part of a decimal string.
Recurring plans require a finite duration; lifetime "0" is not supported for recurring billing. plan_price_formatted is a separate display string; "1" is valid without a currency symbol. A display string does not override the numeric price or its precision checks.
A universal plan can return expanded applicable targets with is_universal: true; a populated plan_targets array does not make it a restricted plan.
