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

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

    • 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 — subscription created but first payment not yet collected; Temporal owns 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
    • 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

    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

    • 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

      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.

  • payment_behavior
    Type: string | nullenum

    The payment collection behavior configured for this subscription:

    • default_incomplete — created as incomplete; Temporal owns all charge attempts; exhaustion → incomplete_expired
    • allow_incomplete — inline charge at creation; success → active; failure → past_due; exhaustion → canceled
    • error_if_incomplete — pre-flight charge before creation; failure → 402, nothing created; success → active
    • send_invoice — (coming soon) invoice-based billing
    values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • send_invoice
  • 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

    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.