Create a Subscription Schedule

​

Creates a subscription schedule. A workflow starts immediately and waits until phases[0].start_date, at which point the subscription is created and the first phase is applied.

Use this endpoint instead of POST /v1/subscriptions when:

  • You need a one-time charge (e.g. setup fee) on the first invoice only
  • 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

Phase-based trials: Set trial_end on phases[0] to start the subscription in TRIALING status. No charge is taken until trial_end elapses. The billing schedule startAt is set to trial_end, not the phase start_date.

Body
required
application/json

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.

  • billing_mode
    Type: object | null

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

  • default_settings
    Type: object · ScheduleDefaultSettings

    Default settings applied to the subscription created by this schedule.

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

Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/subscription-schedules
curl https://api.paypercut.io/v1/subscription-schedules \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "customer": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "default_settings": {
    "default_payment_method": "pm_xyz"
  },
  "end_behavior": "RELEASE",
  "phases": [
    {
      "start_date": "2026-03-01T00:00:00Z",
      "items": [
        {
          "price": "price_setup_fee",
          "unit_amount": 5000,
          "currency": "usd"
        },
        {
          "price": "price_monthly",
          "unit_amount": 1000,
          "currency": "usd",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          }
        }
      ]
    },
    {
      "start_date": "2026-04-01T00:00:00Z",
      "items": [
        {
          "price": "price_monthly",
          "unit_amount": 1000,
          "currency": "usd",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          }
        }
      ]
    }
  ]
}'

{
  "id": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "account": "01XXXXXXXXXXXXXXXXXXXXXXX",
  "customer": "01KJQ34MWYH0TES77RDXA8T8TT",
  "status": "NOT_STARTED",
  "end_behavior": "RELEASE",
  "subscription": null,
  "released_subscription": null,
  "default_settings": {
    "default_payment_method": "pm_xyz",
    "collection_method": "charge_automatically",
    "billing_cycle_anchor_config": null
  },
  "metadata": null,
  "livemode": false,
  "start_date": "2026-03-01T00:00:00Z",
  "current_phase_index": 0,
  "current_phase": null,
  "next_action_at": "2026-03-01T00:00:00Z",
  "canceled_at": null,
  "completed_at": null,
  "released_at": null,
  "phases": [
    {
      "start_date": "2026-03-01T00:00:00Z",
      "end_date": "2026-04-01T00:00:00Z",
      "phase_index": 0,
      "collection_method": "charge_automatically",
      "items": [
        {
          "price": "price_setup_fee",
          "unit_amount": 5000,
          "currency": "usd"
        },
        {
          "price": "price_monthly",
          "unit_amount": 1000,
          "currency": "usd",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          }
        }
      ]
    },
    {
      "start_date": "2026-04-01T00:00:00Z",
      "phase_index": 1,
      "collection_method": "charge_automatically",
      "items": [
        {
          "price": "price_monthly",
          "unit_amount": 1000,
          "currency": "usd",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          }
        }
      ]
    }
  ],
  "application": null,
  "customer_account": null,
  "billing_mode": null,
  "created": "2026-02-28T12:00:00Z",
  "updated_at": "2026-02-28T12:00:00Z"
}

Subscription schedule created successfully.