Stripe event: charge.refunded fires on partial refunds too, check how much

Not specified by the original author.

TL;DR

For per-refund detail (who, when, exact amount, reason), listen to refund.created instead. The other trap: issuing a refund and then waiting for this event to update your books.

Steps

1. Read data.object.amount_refunded and data.object.amount on the Charge. If they are equal, the charge is fully refunded. If amount_refunded is smaller, it is partial.
2. For per-refund detail (who, when, exact amount, reason), listen to refund.created instead. That event carries the Refund object. This one carries the Charge.
3. Full refund: reverse fulfillment (revoke access, restock, mark the order refunded). Partial refund: adjust the order total, keep fulfillment, note the credit.
4. Return 200.
5. A single charge.refunded handler that deprovisions on any receipt. A partial refund is customer service, not cancellation. The other trap: issuing a refund and then waiting for this event to update your books. Update your books when you issue the refund; treat the event as confirmation, not as the trigger.

When to use

You are seeing this: Stripe's own reference says it plainly: this event occurs whenever a charge is refunded, including partial refunds. Use this skill when you run into "Stripe event: charge.refunded fires on partial refunds too, check how much".

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.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Stripe's event reference says charge.refunded occurs whenever a charge is refunded, including partial refunds, and advises listening to refund.created for information about the refund. Verified live at https://docs.stripe.com/api/events/types.