invoice.paid: what it means and what to email

What it means

An invoice has been paid. Stripe sends the event when a payment attempt on the invoice succeeds, and also when you mark an invoice as paid outside Stripe. Every subscription payment is an invoice, so this is the event that says a customer paid for their first period, paid again at renewal, or finally paid after a card failed.

Stripe's advice is to give access when you receive it and the subscription's status is active. A paid invoice does not always make a subscription active, so fetch the subscription and check before you extend anything.

When Stripe sends it

Once for each paid invoice: the first payment of a subscription, every renewal, a payment collected on a retry, and an invoice you mark paid by hand. The invoice's billing_reason says which kind it is. subscription_create is the first invoice, subscription_cycle is a renewal, subscription_update follows a change to the subscription, and manual is an invoice that has nothing to do with a subscription.

An attempt_count above 1 means automatic retries were needed, so a card that failed before has now worked.

Events can be delivered more than once, so keep the ids of the ones you have handled. Stripe does not promise any order either, which means a renewal's invoice.paid can arrive before the subscription update that goes with it.

Does Stripe email the customer?

A receipt, if you turn it on. In Stripe's Customer emails settings, the Successful payments toggle under Payments makes Stripe email a receipt after an invoice is paid, and for an invoice that charges automatically the email carries a PDF of the invoice and of the receipt, unless you turn that off in your invoice settings. With that toggle off, a customer who is charged automatically gets no receipt email.

Stripe's email is a receipt, so the thank-you, and the call on which payment deserves a note, are still yours.

The email to send

Not on every one. A thank-you on the first invoice, a short note after failed attempts, and for an ordinary renewal nothing at all unless something changed. Read billing_reason and attempt_count to choose.

The one worth writing first is the note after a failure, because it closes the loop on the failed payment email. Send it as soon as the event arrives.

Subject: Your payment went through

Hi {{first_name}},

The payment for [your app] that didn't go through earlier has now gone through, so there is nothing left for you to do.

Thanks for sorting it out. If anything looks off on your account, reply to this email.

[Your name]

For the first invoice, the SaaS welcome email template covers what a thank-you to a new customer says, and the failed payment email template is the email this one follows.

Fields worth reading

• customer_email, customer_name and customer: who paid.
• amount_paid and currency: what was paid, in the smallest unit of the currency.
• billing_reason: why the invoice exists, as above.
• attempt_count: above 1 when a retry cleared the payment.
• hosted_invoice_url and invoice_pdf: the invoice, to link or to attach.
• number: the number printed on the invoice and on the emails Stripe sends for it.
• parent.subscription_details.subscription: the subscription to fetch and check. Before API version 2025-03-31.basil this was subscription, which later versions removed.

if (event.type === "invoice.paid") {
  const invoice = event.data.object;
  const first = invoice.billing_reason === "subscription_create";
  const recovered = invoice.attempt_count > 1;
}

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

What Kicklace does

With Stripe connected, the event lands on the person as a purchase, purchase, for the amount paid, and the first one moves them to Paying on your Lifecycle map. The invoice's id is the purchase's key, so the same invoice never lands twice, and the payment that paid it takes the same key.

When attempt_count is above 1 it lands as payment_recovered instead, because a retry cleared a card that had failed. That ends the person's time on a Payment failed side road, so the failed payment emails stop.

A sequence on the Paying stage answers a purchase, and the first-run setup puts a short thank-you there. Nothing sends until you switch it 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 the thank-you email in your site's voice, ready to copy, with no sign-up.

Sources

• Types of events
• Stripe CLI: trigger
• Using webhooks with subscriptions
• Receipts and paid invoices
• Send customer emails
• The Invoice object
• Invoicing resources now specify how they were generated