> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# customer.state_changed

> Aggregate entitlement event — what can this customer access right now.

## One event to sync access

Instead of handling every lifecycle event (`subscription.activated`, `subscription.canceled`, `trial.expired`, ...) to keep your access flags in sync, handle this single event. Every entitlement transition fires it with the customer's **current** state, computed at delivery time:

| trigger | When |
| - | - |
| `subscription_created` | A subscription was created (status `pending_payment` — no access yet). |
| `subscription_activated` | A payment confirmed the subscription. |
| `trial_started` | A trial began. |
| `trial_converted` | A trialing customer converted to paid via plan change. |
| `trial_expired` | A trial ran out and regular billing began. |
| `plan_change` | A plan change executed (immediate or scheduled). |
| `cancellation_scheduled` | A cancellation was scheduled — access continues until period end. |
| `cancellation_revoked` | A scheduled cancellation was reverted. |
| `subscription_canceled` | The subscription terminated — `status` becomes `none`. |
| `past_due` | A recurring payment failed — a grace window begins: usage and seats keep working, new purchases are blocked. |
| `seats_updated` | A customer's seat count changed. |
| `addon_activated` | An add-on was activated on the subscription. |
| `addon_deactivated` | An add-on was deactivated from the subscription. |
| `credits_depleted` | The subscription ran out of credits. |
| `balance_depleted` | The subscription ran out of prepaid balance. |
| `quota_exceeded` | Usage passed a feature's included quantity. |
| `plan_access_granted` | A Plan Grant temporarily expanded the customer's access without changing subscription billing. |
| `plan_access_ended` | A Plan Grant expired or was revoked; the payload contains the resulting current state. |

## Handling the payload

Use `status` as the access gate (`trialing` and `active` grant access), `features` for per-feature limits, and `credits`/`balance` for consumption headroom on credits/balance plans. The payload reflects the state at delivery time — if two transitions happen back to back, the later event always carries the final state, so processing events in `timestamp` order converges to the correct result.

See [Plan Grants](https://commet.co/docs/plan-grants.md) for the temporary access lifecycle.


## OpenAPI

````yaml /openapi/en/webhooks/2026-08-27.json webhook customer.state_changed
openapi: 3.1.0
info:
  title: Commet Webhooks
  version: '2026-08-27'
  description: >-
    Outbound webhook events emitted by the Commet API. Each event is delivered
    as a signed POST to your configured endpoints.
servers: []
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.