SubscriptionScheduleCreateRequest

Request body for creating a subscription schedule.

The first phase's start_date determines when the workflow activates and creates the subscription. If start_date is in the past, the subscription is created immediately.

Use this endpoint (not POST /v1/subscriptions) when:

  • You have a one-time charge (e.g. setup fee) on the first invoice
  • Billing should stop after N months (end_behavior: CANCEL)
  • Prices or items change at a future date
  • The subscription start date is in the future
  • customer
    Type: string
    required

    ID of the customer for whom the schedule is created.

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

    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.

  • billing_mode
    Type: object | null

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

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

    Whether this schedule is in live mode or test mode.

  • metadata
    Type: object | null

    Arbitrary key-value pairs for storing additional information.

    • propertyName
      Type: anything