Automate a weekly Stripe refund report with reasons and failures

Stripe lets you refund all or part of a payment from the Dashboard or the Refunds API. In the Dashboard you can select several payments and refund them together, but as full refunds; partial refunds must be issued individually. Refunds therefore scatter across weeks, reasons and payment methods. A single monthly number hides what matters: whether one product drives most of them, whether duplicates are creeping up, and whether a refund failed and left a customer unpaid.

Stripe's API reference lists refund statuses of pending, requires_action, succeeded, failed and canceled. For card refunds, Stripe holds a refund as pending when your available balance cannot cover it, until the balance is sufficient. A requires_action refund carries a note on what it needs to continue processing. A failed refund can carry a failure_reason such as lost_or_stolen_card, expired_or_canceled_card or insufficient_funds. Stripe says the bank returns a failed refund to Stripe, and you then need to arrange another way to pay the customer. The report lists each of these with its reason so nothing sits unnoticed.

You add the job and grant read access to your Stripe refunds; the team requests the access when you add it. Each week a scheduled agent lists refunds created in the last seven days through the list endpoint, which accepts a created date range and returns up to 100 refunds per page. It groups them by status and reason, totals amounts by currency so currencies are never mixed, and compares the week with the one before. A partial refund counts as its own refund, so the report shows amounts as well as counts.

The COO agent, as department head, reviews the report before it goes out: do totals match the refund list, is each currency kept apart, is any failed refund missing. Stripe says customers see a refund as a credit approximately 5-10 business days later, so the report also helps you answer "where is my refund" with a real status rather than a guess. Then you approve, edit or skip it, and nothing is sent until you do.