SubscriptionListResponse

Paginated list of subscriptions.

  • items
    Type: array object[] · Subscription[]
    required

    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.

    • billing_thresholds
      Type: object | null

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

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

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

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

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

    • trial_start
      Type: string | nullFormat: date-time

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

  • last_key
    Type: string | null

    Cursor for the next page in format: {ISO_timestamp}_{ULID}. Pass as last_key in the next request. Null when there are no further pages.