Subscription Object

Subscriptions enable recurring payments for memberships, services, or product deliveries. They automatically charge customers at specified intervals using their stored HSA/FSA or regular payment method.

The Subscription Object

{
  "id": "sub_abc123xyz",
  "customer_id": "cus_xyz789",
  "status": "active",
  "product_id": 12345,
  "merchant_product_id": "MEMBERSHIP-PREMIUM",
  "amount_cents": 9900,
  "currency": "USD",
  "interval": "monthly",
  "interval_count": 1,
  "trial_period_days": 7,
  "trial_end": "2025-10-25T14:30:00Z",
  "current_period_start": "2025-10-18T14:30:00Z",
  "current_period_end": "2025-11-18T14:30:00Z",
  "next_billing_date": "2025-11-18T14:30:00Z",
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "ended_at": null,
  "payment_method": {
    "type": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa"
  },
  "metadata": {
    "tier": "premium",
    "features": "unlimited_access,priority_support"
  },
  "created_at": "2025-10-18T14:30:00Z",
  "updated_at": "2025-10-18T14:30:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique subscription identifier
`customer_id`	string	Customer ID
`status`	enum	Subscription status (see below)
`product_id`	integer	Associated product ID
`merchant_product_id`	string	Your product reference ID
`amount_cents`	integer	Recurring charge amount in cents
`currency`	string	ISO 4217 currency code
`interval`	enum	Billing interval: `daily`, `weekly`, `monthly`, `yearly`
`interval_count`	integer	Number of intervals between billings
`trial_period_days`	integer	Free trial duration in days
`trial_end`	timestamp	When trial ends (null if no trial)
`current_period_start`	timestamp	Start of current billing period
`current_period_end`	timestamp	End of current billing period
`next_billing_date`	timestamp	Next scheduled charge date
`cancel_at_period_end`	boolean	Whether subscription cancels at period end
`cancelled_at`	timestamp	When subscription was cancelled (null if active)
`ended_at`	timestamp	When subscription ended (null if active)
`payment_method`	object	Stored payment method details
`metadata`	object	Custom key-value pairs
`created_at`	timestamp	When subscription was created
`updated_at`	timestamp	When subscription was last updated

Subscription Status

Status	Description
`trialing`	In free trial period
`active`	Active and billing normally
`past_due`	Payment failed, retrying
`cancelled`	Cancelled, will end at period end
`ended`	Subscription has ended
`paused`	Temporarily paused

Billing Intervals

Interval	`interval_count`	Billing Frequency
`daily`	1	Every day
`daily`	7	Every 7 days
`weekly`	1	Every week
`weekly`	2	Every 2 weeks (bi-weekly)
`monthly`	1	Every month
`monthly`	3	Every 3 months (quarterly)
`yearly`	1	Every year

Subscription Lifecycle

A subscription moves through these states:

trialing - Subscription created with trial period
active - Subscription is active and billing normally (can come from trialing or be created without trial)
past_due - Payment failed, retrying (can come from trialing or active)
cancelled - Cancel requested, will end at period end
ended - Subscription has ended (can come from cancelled, past_due after max retries, or active for immediate cancellation)

Trial Periods

Subscriptions can include a free trial period:

{
  "trial_period_days": 7,
  "trial_end": "2025-10-25T14:30:00Z",
  "status": "trialing",
  "next_billing_date": "2025-10-25T14:30:00Z"
}

During trial:

Customer is not charged
Payment method is verified
First charge occurs when trial ends

Payment Method

{
  "payment_method": {
    "type": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2026
  }
}

Type	Description
`hsa_fsa_card`	HSA/FSA debit card
`credit_card`	Regular credit card
`debit_card`	Regular debit card

Cancellation Behavior

Cancel at Period End

{
  "status": "cancelled",
  "cancel_at_period_end": true,
  "current_period_end": "2025-11-18T14:30:00Z",
  "cancelled_at": "2025-10-20T10:00:00Z",
  "ended_at": null
}

Customer retains access until period end.

Immediate Cancellation

{
  "status": "ended",
  "cancel_at_period_end": false,
  "cancelled_at": "2025-10-20T10:00:00Z",
  "ended_at": "2025-10-20T10:00:00Z"
}

Access ends immediately.

Past Due Handling

When a payment fails:

Status changes to past_due
Automatic retry attempts (days 3, 7, 14)
Customer receives notification
After max retries, subscription ends

{
  "status": "past_due",
  "next_billing_date": "2025-10-21T14:30:00Z",
  "retry_count": 2,
  "max_retries": 3
}

Examples

Monthly Membership

{
  "id": "sub_membership_001",
  "amount_cents": 9900,
  "interval": "monthly",
  "interval_count": 1,
  "status": "active",
  "trial_period_days": 14
}

Quarterly Subscription

{
  "id": "sub_quarterly_001",
  "amount_cents": 24900,
  "interval": "monthly",
  "interval_count": 3,
  "status": "active"
}

Annual Plan with Trial

{
  "id": "sub_annual_001",
  "amount_cents": 99900,
  "interval": "yearly",
  "interval_count": 1,
  "status": "trialing",
  "trial_period_days": 30,
  "trial_end": "2025-11-18T14:30:00Z"
}

Create Subscription - POST /api/v2/subscriptions
Get Subscription - GET /api/v2/subscriptions/
List Subscriptions - GET /api/v2/subscriptions
Cancel Subscription - POST /api/v2/subscriptions//cancel
Update Subscription - PUT /api/v2/subscriptions/

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

Subscription Object

Subscription Object

The Subscription Object

Attributes

Subscription Status

Billing Intervals

Subscription Lifecycle

Trial Periods

Payment Method

Cancellation Behavior

Cancel at Period End

Immediate Cancellation

Past Due Handling

Examples

Monthly Membership

Quarterly Subscription

Annual Plan with Trial

​Subscription Object

​The Subscription Object

​Attributes

​Subscription Status

​Billing Intervals

​Subscription Lifecycle

​Trial Periods

​Payment Method

​Cancellation Behavior

​Cancel at Period End

​Immediate Cancellation

​Past Due Handling

​Examples

​Monthly Membership

​Quarterly Subscription

​Annual Plan with Trial

​Related Endpoints

Subscription Object

The Subscription Object

Attributes

Subscription Status

Billing Intervals

Subscription Lifecycle

Trial Periods

Payment Method

Cancellation Behavior

Cancel at Period End

Immediate Cancellation

Past Due Handling

Examples

Monthly Membership

Quarterly Subscription

Annual Plan with Trial

Related Endpoints