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

# Snippet Events

> Listen to billing state transitions in your web app using CustomEvents.

The snippet dispatches `CustomEvent`s on `document` whenever the subscriber's billing status changes. Use these to trigger analytics, update your own UI, or log conversion events.

## Event reference

All events are dispatched on `document` (not `window`).

### `gatlio:lockout`

Fires when the subscriber transitions **to** `lockout` from any prior state. Also fires on first load if the subscriber is already in lockout (`null → lockout`).

```javascript theme={null}
document.addEventListener('gatlio:lockout', (event) => {
  console.log(event.detail)
  // { customerId: 'cus_xxx', status: 'lockout' }
})
```

### `gatlio:warning`

Fires when the subscriber transitions **to** `warning` from a non-null prior state. Suppressed on initial page load (`null → warning` does not fire).

```javascript theme={null}
document.addEventListener('gatlio:warning', (event) => {
  console.log(event.detail)
  // { customerId: 'cus_xxx', status: 'warning', card_update_url: 'https://...' }
})
```

### `gatlio:active`

Fires when the subscriber transitions **to** `active` from a non-null prior state. Suppressed on initial page load (`null → active` does not fire).

```javascript theme={null}
document.addEventListener('gatlio:active', (event) => {
  console.log(event.detail)
  // { customerId: 'cus_xxx', status: 'active' }
})
```

### `gatlio:recovered`

Fires when a subscriber in lockout completes the card update flow inside the gate overlay. This is distinct from `gatlio:active` and represents a **conversion event** — the subscriber upgraded their payment method in-session.

```javascript theme={null}
document.addEventListener('gatlio:recovered', (event) => {
  console.log(event.detail)
  // { customerId: 'cus_xxx', status: 'active' }

  // Good place to track a conversion:
  analytics.track('billing_recovered', { customerId: event.detail.customerId })
})
```

## Transition rules

Events fire on **status transitions only** — not on every poll tick when the status is unchanged.

| Transition                       | Event fired        |
| -------------------------------- | ------------------ |
| `null → lockout` (first load)    | `gatlio:lockout`   |
| `null → warning` (first load)    | *(suppressed)*     |
| `null → active` (first load)     | *(suppressed)*     |
| `active → warning`               | `gatlio:warning`   |
| `active → lockout`               | `gatlio:lockout`   |
| `warning → lockout`              | `gatlio:lockout`   |
| `lockout → active` (via polling) | `gatlio:active`    |
| `warning → active` (via polling) | `gatlio:active`    |
| card update completed in gate    | `gatlio:recovered` |
| status unchanged between polls   | *(nothing)*        |

## `gatlio:active` vs `gatlio:recovered`

Both events signal that the subscriber is now active. The difference:

* `gatlio:active` — the server resolved the issue (e.g. a retry succeeded or an operator reinstated the subscriber)
* `gatlio:recovered` — the subscriber **completed the card update flow** in the current session

Use `gatlio:recovered` to attribute revenue recovery to the enforcement gate.