subscription.plan_change_scheduled

{ "event": "subscription.plan_change_scheduled", "timestamp": "2026-06-23T14:30:00.000Z", "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f", "mode": "live", "apiVersion": "2026-08-27", "data": { "subscriptionId": "sub_1a2b3c4d", "customerId": "user_123", "status": "active", "currentPlan": { "id": "pln_pro", "name": "Pro" }, "scheduledPlan": { "id": "pln_starter", "name": "Starter" }, "billingInterval": "monthly", "scheduledBillingInterval": null, "effectiveAt": "2026-04-25T00:00:00.000Z" } }

Scheduled plan change lifecycle

Interval direction takes precedence: a shorter interval is scheduled for the end of the paid period and a longer interval changes immediately. When the interval is unchanged, Plan Groups use sortOrder: lower-ordered plans are scheduled and higher-ordered plans change immediately. Paid-to-free changes are always scheduled.

Moment	Event	What to do
Downgrade requested	`subscription.plan_change_scheduled`	Show “changing to {scheduledPlan.name} on {effectiveAt}”. Keep current plan access.
A different change replaces it	`subscription.plan_change_revoked` + `subscription.plan_change_scheduled`	Update the notice to the new target plan.
Billing period ends	`subscription.plan_changed`	Apply the new plan’s entitlements.

Immediate upgrades skip this event entirely — they fire subscription.plan_changed right away.

Body

application/json

string

required

event

string

required

Allowed value: "subscription.plan_change_scheduled"

timestamp

string

required

organizationId

string

required

mode

enum<string>

required

Available options:

live,

sandbox

apiVersion

string

required

data

object

required

Show child attributes

Response

200

Return any 2xx status code to acknowledge receipt of the event.

Overview

Events

subscription.plan_change_scheduled

Scheduled plan change lifecycle

Body

Response

​Scheduled plan change lifecycle

Body

Response

Scheduled plan change lifecycle