SchedulePhases

  • Type: array object[] · SchedulePhase[] 1…20

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

    A single phase in a subscription schedule. Phases are applied sequentially. When a phase is applied, subscription items are updated to match the phase's items.

    • items
      Type: array · SchedulePhaseItems 1…
      required

      Items active during a phase. At least one item is required per phase. Items without recurring are one-time charges (captured at phase creation, excluded from all future billing cycles).

      For the terminal phase with end_behavior: CANCEL, repeat the previous phase's items. The subscription is canceled immediately when the last phase is applied, so the repeated items are never charged again.

    • start_date
      Type: stringFormat: date-time
      required

      When this phase begins.

    • billing_cycle_anchor
      Type: string | null

      Billing anchor for the subscription created by this phase:

      • "phase_start" (default) — use start_date as the billing anchor
      • "automatic" — inherit the subscription's existing anchor (no change on transition)
      • ISO 8601 datetime string — use a specific date
    • collection_method
      Type: stringenum

      How to collect payment during this phase. send_invoice is (coming soon).

      values
      • charge_automatically
      • send_invoice
    • end_date
      Type: string | nullFormat: date-time

      When this phase ends. Omit for an open-ended (last) phase. When reached and no further phases exist, end_behavior determines what happens to the subscription.

    • metadata
      Type: object | null

      Arbitrary key-value pairs for this phase.

    • on_behalf_of
      Type: string | null

      Account ID for connected account scenarios.

    • phase_index
      Type: integer

      Zero-based index. Auto-assigned from array position if omitted.

    • trial_end
      Type: string | nullFormat: date-time

      Trial end date for the subscription created by this phase (Phase 0 only). When set, the subscription starts in TRIALING status and no charge is taken until trial_end. The billing schedule startAt is set to this date.

    • trial_settings
      Type: object · TrialSettings

      Controls what happens when a trial period ends.