Se dispara cuando se programa un downgrade o cambio de intervalo para el fin del período de facturación.

Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

subscriptionIdstring

The subscription ID.

customerIdstring

The customer ID. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.

statusstring

Current status — the subscription stays usable.

currentPlanobject

The plan currently in effect (id and name).

scheduledPlanobject

The plan that takes effect at effectiveAt (id and name).

billingIntervalstring | null

The current billing interval.

scheduledBillingIntervalstring | null

The new billing interval, if the change includes one. Null when only the plan changes.

effectiveAtstring

ISO 8601 datetime when the change executes (the billing period end).

{
  "event": "subscription.plan_change_scheduled",
  "timestamp": "2026-04-15T12:00:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-05-25",
  "data": {
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "status": "active",
    "currentPlan": {
      "id": "plan_pro",
      "name": "Pro"
    },
    "scheduledPlan": {
      "id": "plan_starter",
      "name": "Starter"
    },
    "billingInterval": "monthly",
    "scheduledBillingInterval": null,
    "effectiveAt": "2026-04-25T00:00:00.000Z"
  }
}

Ciclo de vida del cambio de plan programado

Commet es justo por defecto: los cambios que benefician al cliente (upgrades) se aplican de inmediato, los cambios que reducen lo que recibe (downgrades, intervalos más cortos) se aplican al final del período que ya pagó.

Momento	Evento	Qué hacer
Se solicita un downgrade	`subscription.plan_change_scheduled`	Mostrá "cambia a {scheduledPlan.name} el {effectiveAt}". Mantené el acceso del plan actual.
Un cambio distinto lo reemplaza	`subscription.plan_change_revoked` + `subscription.plan_change_scheduled`	Actualizá el aviso al nuevo plan objetivo.
Termina el período de facturación	`subscription.plan_changed`	Aplicá los permisos del nuevo plan.

Los upgrades inmediatos se saltan este evento por completo: disparan subscription.plan_changed de inmediato.