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

    Properties: 10
  • default_settings
    Type: ScheduleDefaultSettings

    Default settings applied to the subscription created by this schedule.

    Properties: 3
  • end_behavior
    Type: 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
    RELEASECANCELNONE
  • metadata
    Type: object | null

    Arbitrary key-value pairs for storing additional information.

    Properties: 1
  • livemode
    Type: boolean

    Whether this schedule is in live mode or test mode.

  • billing_mode
    Type: object | null

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

    Properties: 1