---
title: "React to billing events"
description: "Run your own code when the billing provider reports an order, a subscription change or a refund, after the built-in refresh."
canonical_url: "https://nuxt-backend.dev/docs/billing/events"
---
# React to billing events

> Run your own code when the billing provider reports an order, a subscription change or a refund, after the built-in refresh.

The provider reports every change to `/billing/events` (see [Webhooks](https://nuxt-backend.dev/docs/ship/production/webhooks) for mounting it and its secret). The package handles each delivery first: it verifies the signature, drops a replay, refreshes the entity's cached plans, features and credits, and fulfils gifts. Your hooks run after that, keyed by the provider's own event names, so features and credits read fresh inside them.

```ts [backend/billing.ts]
const billing = setupBilling(components, {
  email,
  events: {
    'order.paid': async (ctx, payload) => {
      // entitlements are already refreshed here
    },
  },
})
```

## Which events refresh the cache

`customer.state_changed`, the `order.*` events (`created`, `paid`, `refunded`), every `subscription.*` event, `refund.created` and `refund.updated`, and the `benefit_grant.*` events (`created`, `updated`, `cycled`, `revoked`). A hook can listen to any event in the provider's catalog, these and the rest (`checkout.*`, `customer.*`, `product.*`, `benefit.*`).

## Events this package does not know

An authentic delivery whose type the installed provider SDK cannot parse, such as an event newer than the package, is acknowledged with `202` so it never loops in retries. To see it, pass `onUnknownEvent`:

```ts [backend/billing.ts]
const billing = setupBilling(components, {
  email,
  onUnknownEvent: async (ctx, { type, payload }) => {
    console.warn('unhandled billing event', type)
  },
})
```

## Test a hook

Buy something in the sandbox (`BILLING_ENVIRONMENT=sandbox`, the default) and watch the delivery land in the DevTools [Webhooks page](https://nuxt-backend.dev/docs/start/develop/devtools#webhooks). The provider's dashboard can resend any past delivery to the same endpoint.


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.