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.

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

    • Phase item referencing an existing catalog price.

      One-time charge: omit recurring (or set null) — the item is charged once on phase creation and excluded from all future billing cycles.

      • price
        Type: string
        required

        Price ID from your product catalog.

      • currency
        Type: string | null
        min length:  
        3
        max length:  
        3

        Currency override. Falls back to schedule default_settings or subscription currency.

      • metadata
        Type: object | null

        Arbitrary key-value pairs for this item.

      • quantity
        Type: integer
        min:  
        1

        Quantity of this item.

      • recurring
        Type: object · RecurringConfig

        Recurring billing configuration.

      • unit_amount
        Type: number | null
        min:  
        0

        Unit amount override in cents. Falls back to the catalog price if omitted.

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

    • propertyName
      Type: anything
  • 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.

    • end_behavior
      Type: object

      Behavior when the trial ends.