customer.state_changed

{
  "event": "customer.state_changed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "customerId": "user_123",
    "trigger": "subscription_activated",
    "status": "active",
    "subscriptionId": "sub_1a2b3c4d",
    "plan": {
      "id": "pln_pro_monthly",
      "name": "Pro"
    },
    "billingInterval": "monthly",
    "consumptionModel": "metered",
    "features": [
      {
        "code": "api_calls",
        "name": "API Calls",
        "unitName": "request",
        "type": "usage",
        "allowed": true,
        "consumption": {
          "model": "metered",
          "period": {
            "start": "2026-07-01T00:00:00.000Z",
            "end": "2026-08-01T00:00:00.000Z"
          },
          "unitsUsed": 120,
          "includedUnits": 1000,
          "remainingUnits": 880,
          "unlimited": false,
          "overage": {
            "enabled": true,
            "units": 0,
            "unitPrice": {
              "amount": 50,
              "currency": "usd",
              "scale": 10000
            }
          }
        }
      },
      {
        "code": "editors",
        "name": "Editors",
        "unitName": "seat",
        "type": "seats",
        "allowed": true,
        "usage": {
          "period": {
            "start": "2026-07-01T00:00:00.000Z",
            "end": "2026-08-01T00:00:00.000Z"
          },
          "unitsUsed": 3,
          "includedUnits": 5,
          "remainingUnits": 2,
          "unlimited": false,
          "overage": {
            "enabled": false,
            "units": 0
          }
        }
      }
    ],
    "seats": [
      {
        "code": "editors",
        "current": 3,
        "included": 5,
        "remaining": 2,
        "unlimited": false
      }
    ],
    "credits": null,
    "balance": null
  }
}

{
  "event": "customer.state_changed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "customerId": "user_123",
    "trigger": "subscription_activated",
    "status": "active",
    "subscriptionId": "sub_1a2b3c4d",
    "plan": {
      "id": "pln_pro_monthly",
      "name": "Pro"
    },
    "billingInterval": "monthly",
    "consumptionModel": "metered",
    "features": [
      {
        "code": "api_calls",
        "name": "API Calls",
        "unitName": "request",
        "type": "usage",
        "allowed": true,
        "consumption": {
          "model": "metered",
          "period": {
            "start": "2026-07-01T00:00:00.000Z",
            "end": "2026-08-01T00:00:00.000Z"
          },
          "unitsUsed": 120,
          "includedUnits": 1000,
          "remainingUnits": 880,
          "unlimited": false,
          "overage": {
            "enabled": true,
            "units": 0,
            "unitPrice": {
              "amount": 50,
              "currency": "usd",
              "scale": 10000
            }
          }
        }
      },
      {
        "code": "editors",
        "name": "Editors",
        "unitName": "seat",
        "type": "seats",
        "allowed": true,
        "usage": {
          "period": {
            "start": "2026-07-01T00:00:00.000Z",
            "end": "2026-08-01T00:00:00.000Z"
          },
          "unitsUsed": 3,
          "includedUnits": 5,
          "remainingUnits": 2,
          "unlimited": false,
          "overage": {
            "enabled": false,
            "units": 0
          }
        }
      }
    ],
    "seats": [
      {
        "code": "editors",
        "current": 3,
        "included": 5,
        "remaining": 2,
        "unlimited": false
      }
    ],
    "credits": null,
    "balance": null
  }
}

Un solo evento para sincronizar el acceso

En lugar de gestionar cada evento del ciclo de vida (subscription.activated, subscription.canceled, trial.expired, …) para mantener tus flags de acceso sincronizados, gestioná este único evento. Cada transición de permisos lo dispara con el estado actual del cliente, calculado en el momento de la entrega:

trigger	Cuándo
`subscription_created`	Se creó una suscripción (estado `pending_payment`: todavía sin acceso).
`subscription_activated`	Un pago confirmó la suscripción.
`trial_started`	Comenzó una prueba.
`trial_converted`	Un cliente en prueba se convirtió a pago mediante un cambio de plan.
`trial_expired`	Una prueba se agotó y comenzó la facturación regular.
`plan_change`	Se ejecutó un cambio de plan (inmediato o programado).
`cancellation_scheduled`	Se programó una cancelación: el acceso continúa hasta el fin del período.
`cancellation_revoked`	Se revirtió una cancelación programada.
`subscription_canceled`	La suscripción terminó: `status` pasa a `none`.
`past_due`	Un pago recurrente falló: empieza una ventana de gracia — el uso y los asientos siguen funcionando, las compras nuevas se bloquean.
`seats_updated`	El conteo de asientos del cliente cambió.
`addon_activated`	Se activó un complemento en la suscripción.
`addon_deactivated`	Se desactivó un complemento de la suscripción.
`credits_depleted`	La suscripción se quedó sin créditos.
`balance_depleted`	La suscripción se quedó sin saldo prepago.
`quota_exceeded`	El uso superó la cantidad incluida de una función.
`plan_access_granted`	Un Plan Grant amplió temporalmente el acceso del customer sin cambiar la facturación de la suscripción.
`plan_access_ended`	Un Plan Grant venció o fue revocado; el payload contiene el estado actual resultante.

Cómo manejar el payload

Usá status como la barrera de acceso (trialing y active otorgan acceso), features para los límites por feature, y credits/balance para el margen de consumo en planes de créditos/balance. El payload refleja el estado en el momento de la entrega: si dos transiciones ocurren una tras otra, el evento posterior siempre lleva el estado final, así que procesar los eventos en orden de timestamp converge al resultado correcto. Consultá Plan Grants para ver el ciclo de acceso temporal.

Cuerpo

application/json

string

requerido

event

string

requerido

Allowed value: "customer.state_changed"

timestamp

string

requerido

organizationId

string

requerido

mode

enum<string>

requerido

Opciones disponibles:

live,

sandbox

apiVersion

string

requerido

data

object

requerido

Show child attributes

Respuesta

200

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

Introducción

Eventos

customer.state_changed

Un solo evento para sincronizar el acceso

Cómo manejar el payload

Cuerpo

Respuesta

​Un solo evento para sincronizar el acceso

​Cómo manejar el payload

Cuerpo

Respuesta

Un solo evento para sincronizar el acceso

Cómo manejar el payload