Subscription

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

  • id
    Type: string
    required

    Unique identifier for the subscription (ULID).

  • customer
    required

    The customer ID, or the expanded customer object when expand=customer is requested.

    • Type: string

      Customer ID (ULID).

  • status
    Type: stringenum
    required

    Current lifecycle status of the subscription:

    • incomplete — subscription created but first payment not yet collected; charge attempts for default_incomplete, or inline charge failed for allow_incomplete
    • incomplete_expired — all dunning attempts exhausted on a default_incomplete subscription (terminal)
    • trialing — subscription is in a free trial period; no charge until trial ends
    • active — subscription is active and billing normally
    • past_due — the most recent charge failed; dunning retries in progress
    • canceled — subscription has been canceled (terminal)
    • unpaid — payment failed and all retries exhausted
    • paused — billing is temporarily paused
    values
    incompleteincomplete_expiredtrialingactivepast_duecanceledunpaidpaused
  • start_date
    Type: stringFormat: date-time
    required

    Date when the subscription was first created. May differ from created due to backdating.

  • next_billing_date
    Type: stringFormat: date-time
    required

    Next scheduled billing date for the subscription.

  • current_period_start
    Type: string | nullFormat: date-time

    Start of the current billing period.

  • current_period_end
    Type: string | nullFormat: date-time

    End of the current billing period.

  • cancel_at_period_end
    Type: boolean
    required

    Whether this subscription will cancel at the end of the current billing period.

  • 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.

  • paused_at
    Type: string | nullFormat: date-time

    If the subscription has been paused, the date it was paused.

  • trial_start
    Type: string | nullFormat: date-time

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

  • trial_end
    Type: string | nullFormat: date-time

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

  • trial_settings
    Type: TrialSettings

    Controls what happens when a trial period ends.

    Properties: 1
  • 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.

  • billing_cycle_anchor_config
    Type: BillingCycleAnchorConfig

    Advanced billing cycle configuration. Allows precise control over when billing cycles occur. All fields are optional integers with specific ranges.

    Properties: 5
  • collection_method
    Type: "charge_automatically" or "send_invoice"enum

    How payment is collected from the customer.

  • 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.

  • currency
    Type: string | null

    Three-letter ISO currency code (uppercase).

  • on_behalf_of
    Type: string | null

    The account (if any) on behalf of which charges are made.

  • livemode
    Type: boolean

    Whether this subscription exists in live mode (true) or test mode (false).

  • ended_at
    Type: string | nullFormat: date-time

    If the subscription has ended, the date it ended.

  • cancellation_details
    Type: CancellationDetails

    Details about why this subscription was cancelled.

    Properties: 2
  • billing_thresholds
    Type: object | null

    Thresholds at which an invoice is generated and billing period advances.

    Properties: 1
  • payment_behavior
    Type: string | nullenum

    The payment collection behavior configured at creation for this subscription:

    • default_incomplete — charge ran at creation or at the anchor date if one was set; success → active; failure → past_due; exhaustion → incomplete_expired
    • allow_incomplete — charge ran at creation or at the anchor date if one was set; success → active; failure → past_due; exhaustion → canceled
    • error_if_incomplete — charge ran before the subscription was created; subscription started as active
    • send_invoice — (coming soon) invoice-based billing
    values
    allow_incompletedefault_incompleteerror_if_incompletesend_invoice
  • pending_setup_intent
    Type: string | null

    ID of a pending SetupIntent for collecting payment credentials.

  • items
    Type: array of SubscriptionItem

    List of subscription items, each representing a product/price in the subscription.

    Properties: 10
  • metadata
    Type: object

    Set of key-value pairs attached to the subscription.

    Properties: 1
  • created
    Type: stringFormat: date-time
    required

    Time at which the subscription was created.

  • updated_at
    Type: stringFormat: date-time
    required

    Time at which the subscription was last updated.