charge.refunded: what it means and what to email

What it means

A charge was refunded, in full or in part. The event carries the updated Charge, not the refund itself. For the refund's own details Stripe points to refund.created, and recommends listening to that one at a minimum if you handle refunds.

For a subscription it means a charge on one of its invoices got a full or partial refund. Whether that also ends the subscription is a separate decision, and a separate event.

When Stripe sends it

Each time a refund is made on a charge, from the Dashboard or the API. A charge can be refunded more than once as long as the total stays within the original amount, so a partial refund followed by another sends the event twice.

A refund issued shortly after the charge can appear as a reversal, where the original charge drops off the customer's statement and no separate credit is issued. Otherwise the customer sees the credit about 5 to 10 business days later, depending on their bank.

Does Stripe email the customer?

Yes, if you turn it on, and only when three things are true: the original charge was made on a customer in your Stripe account, that customer has a stored email address, and Email customers for refunds is enabled. It is the Refunds toggle under Payments in Stripe's Customer emails settings. A customer who paid as a guest, with no Customer object, gets nothing from Stripe.

The email to send

Your own short note when you issue the refund. Say how much, when it should show up, and ask one thing. If Stripe's refund email is on, this is the human one beside it, so keep the numbers to the amount and the timing.

Subject: Your refund for [your app] is on its way

Hi {{first_name}},

I have refunded [amount] for [what they paid for]. Banks differ, but it can take 5 to 10 business days to show up on your statement.

If you have a minute, I would like to know what I could have done better. One line is plenty, and you can reply to this email.

[Your name]

If the refund came with a cancellation, the cancellation survey email template has other ways to ask, and win-back emails cover what to send weeks later.

Fields worth reading

• amount_refunded: the total refunded on the charge, in the smallest unit of the currency. It can be less than amount after a partial refund.
• amount and currency: what the charge was.
• refunded: true only when the charge is fully refunded. A partly refunded charge still reads false.
• customer, billing_details.email and receipt_email: who it was. Any of them can be empty.
• payment_intent: the PaymentIntent the charge belongs to, for finding the order or the invoice.
• receipt_url: Stripe's receipt page, kept up to date with the refunds.
• metadata: whatever you put on the payment when you made it.

if (event.type === "charge.refunded") {
  const charge = event.data.object;
  const refunded = charge.amount_refunded; // the total so far, smallest unit
  const whole = charge.refunded; // true only for a full refund
}

To see a real payload, run stripe trigger charge.refunded in a sandbox and read the event it sends.

What Kicklace does

With Stripe connected, the event lands on the person as a refund, refund, for the total refunded on that charge so far, so a second partial refund lands with the new total. Each total is kept once, and a repeat delivery does not land twice. It moves nobody on your Lifecycle map.

A side road with Refunded as its way in can start from it. The first-run setup offers one, and it stays off until you switch it on. Kicklace does not read refund.created, so the reason for the refund is not on the person.

Kicklace only reads Stripe. It never refunds anyone. Nothing sends until you switch a sequence on, and Kicklace shows who would have got it over the last 30 days first.

Write yours from your URL. Paste your site's address into the welcome email generator and it writes your first emails in your site's voice, ready to copy, with no sign-up. The refund note is one you add on the map, where Write for me drafts it in your voice.

Sources

• Types of events
• Stripe CLI: trigger
• Refund and cancel payments
• Receipts and paid invoices
• Using webhooks with subscriptions
• The Charge object