Stripe event: account.updated, re-read the Connect account, the event is a nudge not the state

TL;DR

For Connect platforms, this event fires when a connected account changes. Read charges\enabled, payouts\enabled, and details\submitted. Gate your platform logic on those three flags: - charges\enabled false: the account cannot take payments yet. Hold onboarding, show the next step. - payouts\_enabled false: money can come in but not out.

When to use

You are seeing this: Treat it as a notification to re-read the Account object, never as the state itself. Use this skill when you run into "Stripe event: account.updated, re-read the Connect account, the event is a nudge not the state".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

account.updated: re-fetch the account and re-evaluate gating

For Connect platforms, this event fires when a connected account changes. Treat it as a notification to re-read the Account object, never as the state itself.

What to do on receipt

1. Fetch the Account fresh from the API. Read charges_enabled, payouts_enabled, and details_submitted.

2. Gate your platform logic on those three flags:

   • charges_enabled false: the account cannot take payments yet. Hold onboarding, show the next step.
   • payouts_enabled false: money can come in but not out. Do not promise payout timing.
   • details_submitted false: they started onboarding and stopped. Nudge them.
3. Check requirements.currently_due and requirements.eventually_due. Newly due requirements with a current_deadline are the common reason an account that worked yesterday is restricted today.
4. Update your cached copy of the account. Return 200.

The trap

Caching the account once at onboarding and never re-reading it. Requirements change, capabilities get revoked, and your platform keeps treating a restricted account as healthy until a payout fails. This event is the refresh trigger; use it. The other trap: reading data.object from the event as current state. The event payload is a snapshot from delivery time; the fresh fetch is the truth.

Checklist

• capabilities on the account shows per-capability status (active, pending, inactive). Gate features on the specific capability you need, not on the account existing.
• Onboarding links expire. If details_submitted is false and your old onboarding link died, generate a new account link rather than resending the dead one.

Stripe's event reference lists account.updated as occurring whenever an external account is updated; in practice it is the Connect account change notification. Verified live at https://docs.stripe.com/api/events/types. chargesenabled, payoutsenabled, detailssubmitted, and requirements.currentlydue on the Account object are the documented gating fields.