SchedulePhase

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.

  • start_date
    Type: stringFormat: date-time
    required

    When this phase begins.

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

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

  • phase_index
    Type: integer

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

  • 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: "charge_automatically" or "send_invoice"enum

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

  • on_behalf_of
    Type: string | null

    Account ID for connected account scenarios.

  • trial_settings
    Type: TrialSettings

    Controls what happens when a trial period ends.

    Properties: 1
  • metadata
    Type: object | null

    Arbitrary key-value pairs for this phase.

    Properties: 1
  • items
    Type: 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.