charge.dispute.created — the window to act

What the event means

charge.dispute.created fires when a buyer opens a dispute. Nothing has been lost yet — the outcome is undecided — but Stripe has already withheld the disputed amount pending resolution.

Why timing matters

Once the connected account's payout clears, reversing a transfer leaves them with a negative balance that Stripe recovers from future volume. If they have no future volume, the platform never recovers it.

Reversing while the dispute is open, against a balance that has not yet paid out, is the difference between a bookkeeping entry and a write-off.

The trade-off

Reversing early penalises a connected account that may have done nothing wrong, on a dispute that may be won. Most platforms hold rather than reverse on created, and treat the event as a watch-list entry.

Fraud-reason disputes are the exception — they are rarely won, so an early reversal is closer to inevitable than premature.

What Stripe has already done by the time you see this

When charge.dispute.created fires, Stripe has already withheld the disputed amount from the platform balance. That money is unavailable pending the outcome.

The dispute fee is typically debited at the same time. On destination charges both hit the platform, not the connected account.

What has *not* happened is any movement on the transfer. The connected account still holds their share, and their payout schedule continues running as normal on that balance.

So the position at this moment is: your money is frozen, their money is liquid and leaving. That asymmetry is the entire argument for acting now rather than at close.

The payout race

Most connected accounts are on a daily or two-day automatic payout schedule. A dispute typically takes 60 to 75 days to resolve.

Over that window the connected account will have paid out dozens of times. The specific dollars from the disputed order left long ago; what remains is whatever their current balance happens to be, which is a function of their recent volume rather than of anything to do with this dispute.

A reversal on day 3 draws against funds Stripe is still holding. The same reversal on day 70 draws against a balance that may be near zero. Nothing about the reversal API changes between those two days — only the probability that it collects anything.

Weighing the trade-off honestly

Reversing on created is not free. The dispute may be won, and a seller debited for a transaction they fulfilled correctly has a legitimate grievance.

Reason code is the strongest signal. fraudulent disputes are rarely won — the cardholder did not authorise the transaction, and no amount of shipping evidence changes that. product_not_received and product_unacceptable are frequently won with tracking or correspondence.

Seller history matters. A first dispute against a long-standing account is noise. A cluster against a new one is a pattern, and recovery there is usually secondary to offboarding.

Amount matters. The conversation costs the same whether you are recovering $40 or $4,000. Most platforms set a floor below which they simply absorb it.

A defensible default: hold on created for most reason codes, reverse immediately on fraudulent, and always reverse above a dollar threshold your finance team sets.

A middle path: hold, do not reverse

Reversing is not the only lever. Stripe lets a platform pause payouts on a connected account, which freezes the balance without taking anything from it.

This preserves the recovery option without penalising a seller who may be vindicated. If the dispute is won, release the hold and nothing happened. If it is lost, the funds are still there to reverse.

It costs the seller liquidity rather than money, which is a far easier conversation than a debit — and for platforms with a small number of high-value disputes it is often the right default.

What FeeGuard does with it

FeeGuard raises a lower-severity finding on charge.dispute.created, flagged in metadata as an early warning rather than a realised loss. The dashboard shows the amount at risk and the evidence deadline.

These findings are excluded from automated clawback by design. Reversing funds from a seller over a dispute that may still be won is exactly the kind of decision that should require a human, and building an automation that does it silently would be a mistake regardless of how the numbers look.

Building the watch list

A dispute opened today needs revisiting when it closes, which may be ten weeks away. Holding that context is the practical work of handling this event.

At minimum, record the dispute id, the charge, the connected account, the amount at risk, the reason code, and the evidence deadline from evidence_details.due_by. That deadline is the one date with a hard consequence — miss it and the dispute is lost by default regardless of the evidence you had.

The transfer position is worth snapshotting too. Knowing what the connected account held when the dispute opened, versus what they hold when it closes, tells you immediately whether the recovery window has already shut.

const dispute = event.data.object as Stripe.Dispute;

await recordWatchItem({
  disputeId: dispute.id,
  chargeId: dispute.charge as string,
  amountAtRisk: dispute.amount,
  reason: dispute.reason,
  evidenceDueBy: dispute.evidence_details?.due_by ?? null,
  transferOutstandingAtOpen: outstanding,
});

Disputes that are not disputes

Not everything arriving here is a chargeback, and treating them identically produces both false alarms and missed losses.

Inquiries and retrievals are requests for information. No funds are withdrawn and no loss has occurred.

Early fraud warnings signal that a network flagged the transaction before any dispute exists. Nothing has been debited. Many platforms proactively refund at this point — which, done without reverse_transfer, creates exactly the leak the companion articles describe.

Check status rather than assuming the event type implies a loss. Acting on every dispute-family event as though money has gone is the fastest route to a queue nobody trusts.