Subscription Plans

A subscription plan is a template that defines the pricing, billing frequency, and retry behavior for recurring payments.

What is a Subscription Plan?

Subscription plans allow you to:

• Define one-time or recurring payment structures

• Configure trial periods (free or paid)

• Set billing frequency and amounts

• Assign retry strategies for failed payments

Plan Types

Type	Description	Use Case
ONE_TIME	Single purchase, no recurring billing	Digital products, one-time services
SUBSCRIPTION_NO_TRIAL	Immediate billing at full price	Established services, returning customers
SUBSCRIPTION_FREE_TRIAL	Free trial period before billing	User acquisition, product demos
SUBSCRIPTION_PAID_TRIAL	Discounted trial before full price	Low-risk introduction, premium features

Configuration Fields

Basic Information

Field	Description	Required
name	Display name for the plan	Yes
description	Plan description	No
website_url	URL associated with the plan	No

Pricing

Field	Description	Required
currency	Three-letter currency code (e.g., USD, EUR)	Yes
full_price_amount	Regular billing amount	Yes
trial_price_amount	Amount charged during trial (for paid trials)	For SUBSCRIPTION_PAID_TRIAL

Billing Schedule

Field	Description	Required
billing_frequency_value	Number of time units between billings	For subscriptions
billing_frequency_unit	Time unit: DAYS, WEEKS, MONTHS, YEARS	For subscriptions
trial_period_value	Length of trial period	For trial plans
trial_period_unit	Trial period unit: DAYS, WEEKS, MONTHS, YEARS	For trial plans
settlement_interval_hours	Hours before automatic capture of authorized payments	No
trial_settlement_interval_hours	Hours before capture during paid trial period	For SUBSCRIPTION_PAID_TRIAL

Settlement Interval Limits:

• One-time purchases and paid trials: Maximum 239 hours

• Subscription renewals: Maximum 119 hours

Retry Configuration

Field	Description	Required
retry_strategy_id	ID of the retry strategy to use for failed payments	No

See Retry Strategies for available options.

Plan Lifecycle

Subscription plans have three possible statuses:

DRAFT -> ACTIVE <-> DEACTIVATED

Status	Description
DRAFT	Plan is being configured, cannot be used for subscriptions
ACTIVE	Plan is available for new subscriptions
DEACTIVATED	Plan is no longer available for new subscriptions (existing subscriptions continue)

Examples

Monthly Subscription (No Trial)

{
  "type": "SUBSCRIPTION_NO_TRIAL",
  "name": "Monthly Pro",
  "description": "Full access to all Pro features",
  "currency": "USD",
  "full_price_amount": 29.99,
  "billing_frequency_value": 1,
  "billing_frequency_unit": "MONTHS",
  "retry_strategy_id": 5,
  "status": "ACTIVE"
}

Annual Subscription with Free Trial

{
  "type": "SUBSCRIPTION_FREE_TRIAL",
  "name": "Annual Premium",
  "description": "Premium features with 14-day free trial",
  "currency": "USD",
  "full_price_amount": 199.99,
  "billing_frequency_value": 1,
  "billing_frequency_unit": "YEARS",
  "trial_period_value": 14,
  "trial_period_unit": "DAYS",
  "retry_strategy_id": 9,
  "status": "ACTIVE"
}

One-Time Purchase

{
  "type": "ONE_TIME",
  "name": "Lifetime Access",
  "description": "One-time purchase for lifetime access",
  "currency": "USD",
  "full_price_amount": 499.00,
  "status": "ACTIVE"
}

Creating Plans

You can create subscription plans through:

• Dashboard - Visual interface for creating and managing plans

• API - Programmatic creation via REST API

Next Steps

• Retry Strategies - Configure automatic retry behavior

• Create Plans via Dashboard - Step-by-step UI guide

• Create Plans via API - API integration guide