system-events: Add balance.{order,refund,refund_reversal,dispute} events

[Yopi]

These can be used to build balance metrics in the correct currency

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
polar	Ignored	Preview	Jan 5, 2026 0:39am
polar-sandbox	Ignored	Preview	Jan 5, 2026 0:39am

[frankie567]

A few things there and there, but that's the right approach :)

On another level, I'm wondering if we should add tax_amount in the events metadata as well: merchants indeed only care about the raw amount, but I'm wondering if we might need the tax amount in the future. That said, it can be a rabbit hole as it'll also require to add tax_country/tax_state to fully make sense 🤔

[Yopi]

A few things there and there, but that's the right approach :)

Thank you for the good feedback!

On another level, I'm wondering if we should add tax_amount in the events metadata as well: merchants indeed only care about the raw amount, but I'm wondering if we might need the tax amount in the future. That said, it can be a rabbit hole as it'll also require to add tax_country/tax_state to fully make sense 🤔

That's a good question. If we think that it would be useful we might as well add it now I guess.

I also realised that we do revert_refund transactions which we might want to have an event for. Either as a negative amount with the same refund event, or a new event.

[frankie567]

That's a good question. If we think that it would be useful we might as well add it now I guess.

I gotta feeling (woohooo) that it'll be useful in the future. So I would say let's add it (+tax country/state).

I also realised that we do revert_refund transactions which we might want to have an event for. Either as a negative amount with the same refund event, or a new event.

Yeah let's do balance.refund_reversal. It's quite rarely used (6 transactions as of today!), but let's be complete.

[Yopi]

That's a good question. If we think that it would be useful we might as well add it now I guess.

I gotta feeling (woohooo) that it'll be useful in the future. So I would say let's add it (+tax country/state).

Perfect, I'll add it.

I also realised that we do revert_refund transactions which we might want to have an event for. Either as a negative amount with the same refund event, or a new event.

Yeah let's do balance.refund_reversal. It's quite rarely used (6 transactions as of today!), but let's be complete.

Should we do the same with the balance.dispute_reversal as well? 😅

[frankie567]

Should we do the same with the balance.dispute_reversal as well? 😅

So, the trick is that we only write the transaction when the dispute is closed (won or lost). If it's won, we write a Dispute + Dispute Reversal. If it's lost, just a Dispute. So I would be tempted to say that we only create an event balance.dispute when it's lost (because the merchant lost money) and be silent about won disputes.

EDIT: Actually, if we want to be clear about fees (see below), we probably need to have balance.dispute_reversal as well (because fees are applied even in case of won dispute).

---

Now that I think of it, there is also the fees dimension 😅 In this implementation, we store the amounts before Polar fees. If we want to show graphs with "net" amounts, we probably also need to store balance.fees events ☺️☺️

[Yopi]

I think this is good to go now!