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

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

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

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