SubscriptionSchedule

A subscription schedule manages the lifecycle of a subscription through a series of phases, allowing you to configure billing changes at specific future dates.

  • id
    Type: string
    required

    Unique identifier for the subscription schedule (ULID).

  • account
    Type: string

    Merchant account ID.

  • customer
    Type: string
    required

    ID of the customer this schedule belongs to.

  • status
    Type: SubscriptionScheduleStatusenum
    required

    Current lifecycle state of a subscription schedule:

    • NOT_STARTED — created but waiting for the first phase start date
    • ACTIVE — currently running; a phase is active
    • COMPLETED — all phases have ended (via end_behavior: CANCEL)
    • CANCELED — manually canceled before completion
    • RELEASED — released from the subscription; billing continues independently
    values
    NOT_STARTEDACTIVECOMPLETEDCANCELEDRELEASED
  • end_behavior
    Type: ScheduleEndBehaviorenum
    required

    What happens when the last phase ends:

    • RELEASE — schedule becomes RELEASED; the subscription continues billing on its own cadence
    • CANCEL — the subscription is immediately canceled; schedule becomes COMPLETED
    • NONE — no action taken; schedule remains active
    values
    RELEASECANCELNONE
  • subscription
    Type: string | null

    ID of the subscription created when the schedule was activated. Null until the first phase is applied.

  • released_subscription
    Type: string | null

    ID of the subscription that was released from this schedule.

  • default_settings
    Type: ScheduleDefaultSettings

    Default settings applied to the subscription created by this schedule.

    Properties: 3
  • metadata
    Type: object | null

    Set of key-value pairs attached to the schedule.

    Properties: 1
  • livemode
    Type: boolean
    required

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

  • start_date
    Type: stringFormat: date-time
    required

    Derived from phases[0].start_date. When the workflow begins watching.

  • current_phase_index
    Type: integer
    required

    Zero-based index of the currently active phase.

  • current_phase
    Type: object | null

    Summary snapshot of the currently active phase (id, phase_index, start_date, end_at).

    Properties: 1
  • next_action_at
    Type: string | nullFormat: date-time

    When the workflow will next fire (next phase transition or schedule end).

  • canceled_at
    Type: string | nullFormat: date-time

    If the schedule was canceled, the date of cancellation.

  • completed_at
    Type: string | nullFormat: date-time

    If the schedule completed (all phases ended), the completion date.

  • released_at
    Type: string | nullFormat: date-time

    If the schedule was released, the date of release.

  • phases
    Type: SchedulePhases 1…20
    required

    Ordered list of schedule phases. Applied sequentially by the workflow. The first phase's start_date determines when the subscription is created.

    Properties: 10
  • application
    Type: string | null

    Application ID if created via a connected application.

  • customer_account
    Type: string | null

    Customer account ID for connected account scenarios.

  • billing_mode
    Type: object | null

    coming soon — Reserved for future billing mode configuration. Currently accepted and stored but has no effect on billing behavior.

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

    Time at which the schedule was created.

  • updated_at
    Type: stringFormat: date-time
    required

    Time at which the schedule was last updated.