Skip to main content

​
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

AttributeTypeDescription
idstringUnique subscription identifier
customer_idstringCustomer ID
statusenumSubscription status (see below)
product_idintegerAssociated product ID
merchant_product_idstringYour product reference ID
amount_centsintegerRecurring charge amount in cents
currencystringISO 4217 currency code
intervalenumBilling interval: daily, weekly, monthly, yearly
interval_countintegerNumber of intervals between billings
trial_period_daysintegerFree trial duration in days
trial_endtimestampWhen trial ends (null if no trial)
current_period_starttimestampStart of current billing period
current_period_endtimestampEnd of current billing period
next_billing_datetimestampNext scheduled charge date
cancel_at_period_endbooleanWhether subscription cancels at period end
cancelled_attimestampWhen subscription was cancelled (null if active)
ended_attimestampWhen subscription ended (null if active)
payment_methodobjectStored payment method details
metadataobjectCustom key-value pairs
created_attimestampWhen subscription was created
updated_attimestampWhen subscription was last updated

​
Subscription Status

StatusDescription
trialingIn free trial period
activeActive and billing normally
past_duePayment failed, retrying
cancelledCancelled, will end at period end
endedSubscription has ended
pausedTemporarily paused

​
Billing Intervals

Intervalinterval_countBilling Frequency
daily1Every day
daily7Every 7 days
weekly1Every week
weekly2Every 2 weeks (bi-weekly)
monthly1Every month
monthly3Every 3 months (quarterly)
yearly1Every 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
  }
}
TypeDescription
hsa_fsa_cardHSA/FSA debit card
credit_cardRegular credit card
debit_cardRegular 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:
  1. Status changes to past_due
  2. Automatic retry attempts (days 3, 7, 14)
  3. Customer receives notification
  4. 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"
}