Update a Subscription Schedule

​

Updates schedule metadata or replaces phases. If phases is provided, all existing phase rows are deleted and recreated. The running workflow recalculates its next action time automatically.

Path Parameters
  • id
    Type: string
    required

    Subscription schedule ID (ULID).

Body·SubscriptionScheduleUpdateRequest
required
application/json

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.

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

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

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/subscription-schedules/{id}
curl https://api.paypercut.io/v1/subscription-schedules/01HD7M6DRKZ4Q4QEVWJB0RC1S6 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "end_behavior": "CANCEL"
}'

{
  "id": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "customer": "01KJQ34MWYH0TES77RDXA8T8TT",
  "status": "ACTIVE",
  "end_behavior": "CANCEL",
  "subscription": "01XXXXXXXXXXXXXXXXXXXXXXX",
  "released_subscription": null,
  "livemode": false,
  "start_date": "2026-03-01T00:00:00Z",
  "current_phase_index": 1,
  "current_phase": {
    "id": "sp_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
    "phase_index": 1,
    "start_date": "2026-04-01T00:00:00Z",
    "end_at": null
  },
  "next_action_at": null,
  "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,
      "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,
      "items": [
        {
          "price": "price_monthly",
          "unit_amount": 1000,
          "currency": "usd",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          }
        }
      ]
    }
  ],
  "created": "2026-02-28T12:00:00Z",
  "updated_at": "2026-03-15T09:00:00Z"
}

Subscription schedule updated successfully.