SubscriptionSchedule

A subscription schedule manages the lifecycle of a subscription through a series of phases, allowing you to configure billing changes at specific future dates.

created
Type: stringFormat: date-time
required

Time at which the schedule was created.
current_phase_index
Type: integer
required

Zero-based index of the currently active phase.
customer
Type: string
required

ID of the customer this schedule belongs to.
end_behavior
Type: string · ScheduleEndBehaviorenum
required
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
id
Type: string
required

Unique identifier for the subscription schedule (ULID).
livemode
Type: boolean
required

Whether this schedule exists in live mode (true) or test mode (false).
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.
start_date
Type: stringFormat: date-time
required

Derived from phases[0].start_date. When the workflow begins watching.
status
Type: string · SubscriptionScheduleStatusenum
required
Current lifecycle state of a subscription schedule:
- NOT_STARTED — created but waiting for the first phase start date
- ACTIVE — currently running; a phase is active
- COMPLETED — all phases have ended (via end_behavior: CANCEL)
- CANCELED — manually canceled before completion
- RELEASED — released from the subscription; billing continues independently
values
- NOT_STARTED
- ACTIVE
- COMPLETED
- CANCELED
- RELEASED
updated_at
Type: stringFormat: date-time
required

Time at which the schedule was last updated.
account
Type: string

Merchant account ID.
application
Type: string | null

Application ID if created via a connected application.
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
canceled_at
Type: string | nullFormat: date-time

If the schedule was canceled, the date of cancellation.
completed_at
Type: string | nullFormat: date-time

If the schedule completed (all phases ended), the completion date.
current_phase
Type: object | null

Summary snapshot of the currently active phase (id, phase_index, start_date, end_at).
- propertyName
  Type: anything
customer_account
Type: string | null

Customer account ID for connected account scenarios.
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.
metadata
Type: object | null

Set of key-value pairs attached to the schedule.
- propertyName
  Type: anything
next_action_at
Type: string | nullFormat: date-time

When the workflow will next fire (next phase transition or schedule end).
released_at
Type: string | nullFormat: date-time

If the schedule was released, the date of release.
released_subscription
Type: string | null

ID of the subscription that was released from this schedule.
subscription
Type: string | null

ID of the subscription created when the schedule was activated. Null until the first phase is applied.