Subscription

A subscription object representing a recurring billing agreement with a customer.

billing_cycle_anchor
Type: string | nullFormat: date-time
required

The reference point that aligns future billing cycle dates. Sets the day of week for weekly intervals, day of month for monthly/yearly, etc.
cancel_at_period_end
Type: boolean
required

Whether this subscription will cancel at the end of the current billing period.
created
Type: stringFormat: date-time
required

Time at which the subscription was created.
customer
required
Type: string

Customer ID (ULID).
id
Type: string
required

Unique identifier for the subscription (ULID).
next_billing_date
Type: stringFormat: date-time
required

Next scheduled billing date for the subscription.
start_date
Type: stringFormat: date-time
required

Date when the subscription was first created. May differ from created due to backdating.
status
Type: stringenum
required
Current lifecycle status of the subscription:
- INCOMPLETE — initial payment attempt failed
- INCOMPLETE_EXPIRED — initial payment not received within 23 hours (terminal)
- TRIALING — subscription is in a free trial period
- ACTIVE — subscription is active and billing normally
- PAST_DUE — payment required but could not be collected
- CANCELED — subscription has been canceled (terminal)
- UNPAID — payment failed and all retries exhausted
- PAUSED — trial ended without a payment method
values
- INCOMPLETE
- INCOMPLETE_EXPIRED
- TRIALING
- ACTIVE
- PAST_DUE
- CANCELED
- UNPAID
- PAUSED
updated_at
Type: stringFormat: date-time
required

Time at which the subscription was last updated.
billing_cycle_anchor_config
Type: object | null · BillingCycleAnchorConfig

Advanced billing cycle configuration. Allows precise control over when billing cycles occur. All fields are optional integers with specific ranges.
- day_of_month
  Type: integer
  min:
  1
  max:
  31
  required
  
  Day of month for billing (1–31).
- hour
  Type: integer | null
  min:
  0
  max:
  23
  
  Hour of day for billing in UTC (0–23).
- minute
  Type: integer | null
  min:
  0
  max:
  59
  
  Minute of hour for billing (0–59).
- month
  Type: integer | null
  min:
  1
  max:
  12
  
  Month of year for billing (1–12).
- second
  Type: integer | null
  min:
  0
  max:
  59
  
  Second of minute for billing (0–59).
billing_thresholds
Type: object | null

Thresholds at which an invoice is generated and billing period advances.
- propertyName
  Type: anything
cancel_at
Type: string | nullFormat: date-time

If set, the date on which the subscription will be canceled.
canceled_at
Type: string | nullFormat: date-time

If the subscription has been canceled, the date of that cancellation.
cancellation_details
Type: object · CancellationDetails

Details about why this subscription was cancelled.
- comment
  Type: string | null
  max length:
  5000
  
  Free-form text comment explaining the cancellation reason.
- feedback
  Type: string | nullenum
  
  Predefined cancellation reason category provided by the customer.
  
  values
  customer_service
  low_quality
  missing_features
  other
  switched_service
  too_complex
  too_expensive
  unused
collection_method
Type: stringenum

How payment is collected from the customer.
values
- charge_automatically
- send_invoice
currency
Type: string | null

Three-letter ISO currency code (uppercase).
current_period_end
Type: string | nullFormat: date-time

End of the current billing period.
current_period_start
Type: string | nullFormat: date-time

Start of the current billing period.
days_until_due
Type: integer | null

Number of days a customer has to pay invoices. Null for charge_automatically.
default_payment_method
Type: string | null

ID of the default payment method for this subscription.
ended_at
Type: string | nullFormat: date-time

If the subscription has ended, the date it ended.
items
Type: array object[] · SubscriptionItem[]

List of subscription items, each representing a product/price in the subscription.
A subscription item representing a product/price combination active on the subscription.
- billing_interval
  Type: stringenum
  
  Resolved billing interval for this item (e.g. monthly).
  
  values
  daily
  weekly
  monthly
  yearly
- created_at
  Type: stringFormat: date-time
  
  Timestamp when the item was created.
- currency
  Type: string | null
  
  Three-letter ISO 4217 currency code (uppercase). Resolved from item.currency → subscription.currency.
- id
  Type: string
  
  Subscription item ID (ULID format with si_ prefix).
- price
  Type: string
  
  Price ID from the product catalog.
- product
  Type: string
  
  Unique identifier for the product.
- quantity
  Type: integer
  
  Quantity of the subscription item.
- recurring
  Type: object · RecurringConfig
  
  Recurring billing configuration.
- unit_amount
  Type: number | null
  
  Unit price in the smallest currency unit (e.g. cents).
- updated_at
  Type: stringFormat: date-time
  
  Timestamp when the item was last updated.
livemode
Type: boolean

Whether this subscription exists in live mode (true) or test mode (false).
metadata
Type: object

Set of key-value pairs attached to the subscription.
- propertyName
  Type: anything
on_behalf_of
Type: string | null

The account (if any) on behalf of which charges are made.
paused_at
Type: string | nullFormat: date-time

If the subscription has been paused, the date it was paused.
pending_setup_intent
Type: string | null

ID of a pending SetupIntent for collecting payment credentials.
trial_end
Type: string | nullFormat: date-time

If the subscription has a trial, the end of that trial.
trial_settings
Type: object · TrialSettings

Controls what happens when a trial period ends.
- end_behavior
  Type: object
  
  Behavior when the trial ends.
trial_start
Type: string | nullFormat: date-time

If the subscription has a trial, the start of that trial.