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:

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)

Annual Subscription with Free Trial

One-Time Purchase

Creating Plans

You can create subscription plans through:

  • Dashboard - Visual interface for creating and managing plans

  • API - Programmatic creation via REST API

Next Steps

Last updated