Billing events
Checkout
The session a customer moves through to pay. Useful for analytics, abandoned-checkout recovery, and pre-filling your own records before the order lands.checkout.created
A checkout session was opened.
checkout.updated
A checkout session changed status (e.g. confirmed or expired).
Customers
Track the people and organizations buying from you.customer.state_changed is the one to reach for when you need a single source of truth.
customer.created
A new customer record exists.
customer.updated
Customer details were edited.
customer.deleted
A customer was removed.
customer.state_changed
A consolidated snapshot whenever anything material changes — active
subscriptions and currently granted benefits included.
For provisioning access,
customer.state_changed is usually all you need: the
payload tells you exactly what the customer is entitled to right now, so you can
reconcile your own access table in one place instead of stitching together
subscription and benefit events.Subscriptions
Recurring billing has the most moving parts, so it has the most events. Start here when implementing any subscription logic.subscription.created
A subscription was created.
subscription.active
The subscription is active and billing.
subscription.uncanceled
A scheduled cancellation was reversed.
subscription.canceled
The subscription is set to cancel (or has canceled).
subscription.past_due
A renewal payment failed. The customer can recover by updating their payment
method — we retry automatically.
subscription.updated
Catch-all that fires alongside every other subscription event
(
active, canceled, uncanceled, past_due, revoked). Handy when you
want one handler for all state transitions.order.created
Inspect the
billing_reason field to tell renewals apart: purchase,
subscription_create, subscription_cycle, or subscription_update.
subscription_cycle means a renewal.subscription.revoked
Billing has stopped and benefits are gone — cut off access here.
Cancellation flow
What fires on cancellation depends on whether it takes effect at the end of the billing period (the default) or immediately.- End of period (default)
- Immediate revocation
A customer cancels from the portal, or you cancel via the dashboard or API.
Two events fire right away:
subscription.updatedsubscription.canceled
active
status, but cancel_at_period_end is now true — so keep access on until
the period ends.When the current period closes, the subscription is revoked for good: billing
cycles stop and benefits are withdrawn. Two more events fire:subscription.updatedsubscription.revoked
canceled.Renewal flow
Each renewal cycle emits events in a fixed order so you can track the cycle from invoice to payment.1
Cycle opens
At the renewal date, these fire immediately (if enabled on your endpoint):
subscription.updatedorder.created
current_period_start and
current_period_end. The order is the invoice for the upcoming cycle with a
pending status. If the plan uses usage-based billing, the customer’s
metered consumption for the prior period is already rolled into the total.2
Payment clears
We charge the new order shortly after. On success:
order.updatedorder.paid
paid. Treat order.paid as
the green light to extend service for the new period.Metered, outcome, and agent-based plans settle through this same renewal flow.
The
order.created total for a usage plan already includes everything ingested
through your meters during the period — including AI usage billed by tokens,
activity, or verified outcome — so there is no separate “usage” event to
reconcile. See usage-based billing
for how that consumption is aggregated.Orders
A one-time purchase or a subscription invoice. These are your canonical revenue events.order.created
An order (invoice) was created.
order.paid
Payment cleared — recognize revenue and fulfill here.
order.updated
An order’s status or details changed.
order.refunded
An order was fully or partially refunded.
Refunds
Standalone refund lifecycle events, complementingorder.refunded.
refund.created
A refund was initiated.
refund.updated
A refund’s status changed.
Benefit grants
A grant is one customer’s access to one benefit — a license key, file download, Discord role, GitHub repo, or prepaid credits. These are your provisioning hooks.benefit_grant.created
A benefit was granted to a customer — provision access.
benefit_grant.updated
A grant changed.
benefit_grant.revoked
A benefit was revoked — tear down the access you provisioned.
Organization events
These track changes to your own catalog and account rather than a customer transaction — useful for keeping internal dashboards, caches, or read models in step with the dashboard and API.Benefits
benefit.created
A benefit definition was created.
benefit.updated
A benefit definition changed.
Products
product.created
A product was created.
product.updated
A product’s details or pricing changed.
Organization
organization.updated
Your organization’s settings changed.