SubscriptionScheduleUpdateRequest

Request body for updating a subscription schedule. All fields are optional.

If phases is provided, all existing phase rows are deleted and replaced. The running workflow recalculates its next action time.

  • default_settings
    Type: object · ScheduleDefaultSettings

    Default settings applied to the subscription created by this schedule.

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

    • collection_method
      Type: string | nullenum

      How to collect payment. Defaults to charge_automatically. send_invoice is (coming soon).

      values
      • charge_automatically
      • send_invoice
    • default_payment_method
      Type: string | null

      Payment method ID used when the schedule activates and creates the subscription.

  • end_behavior
    Type: string · ScheduleEndBehaviorenum

    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
    • RELEASE
    • CANCEL
    • NONE
  • metadata
    Type: object | null

    Updated metadata key-value pairs.

    • propertyName
      Type: anything
  • phases
    Type: array object[] · SchedulePhases 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.