# customer.subscription.updated: read what changed, especially cancel_at_period_end

This event fires on any subscription change: plan switches, quantity changes, trial to active transitions, billing tweaks. Most receipts are routine. One field is not.

## What to do on receipt

1. Compare against your stored copy of the subscription. What actually changed? New price id means a plan change: adjust entitlements. New quantity means a seat change: adjust seats.
2. Check `cancel_at_period_end`. If it just flipped to `true`, the customer canceled. They keep access until `current_period_end`, but this is your churn moment: log it, trigger your save flow or exit survey now, not at period end.
3. Check `status` transitions. `active` to `past_due` means the renewal payment failed; the dunning events (`invoice.payment_failed`) carry the detail, but this is where your entitlements logic should notice.
4. Persist the new subscription snapshot. Return 200.

## The trap

Ignoring this event as noise. Then `customer.subscription.deleted` arrives weeks later and you wonder why a paying customer vanished. The cancellation happened here, weeks ago, when you could still have done something. The other trap: deprovisioning when you see `cancel_at_period_end: true`. They paid through period end; cutting them off early is a support ticket and a chargeback risk.

## Checklist

- `deleted` is the terminal event. `updated` with cancellation flags is the warning. Handle them as a pair.
- Quantity and price changes can also arrive here from the Customer Portal. If you let customers self-serve plan changes, this handler is your entitlement sync.