Refund tax/amount split misallocates across stacked partial refunds (refunded_amount can exceed net_amount)

Refund tax/amount split misallocates across stacked partial refunds (refunded_amount can exceed net_amount)

Summary

In Order.calculate_refunded_tax_from_total the tax side is capped at refundable_tax_amount but the amount side is not capped at refundable_amount. Across stacked partial refunds each refund's tax rounds down and the shortfall spills into refunded_amount, so cumulative refunded_amount creeps past net_amount. Total cash refunded is conserved (the tax side is under by the same amount), so this is a ledger misallocation, not a customer over-refund — but it skews merchant payout, under-remits tax, and can strand residual tax.

Location

server/polar/models/order.py (Order.calculate_refunded_tax_from_total):

refunded_tax_amount = abs(round((self.tax_amount * total_refund_amount) / self.total_amount))
refunded_tax_amount = min(refunded_tax_amount, self.refundable_tax_amount)   # tax IS capped
refunded_amount = total_refund_amount - refunded_tax_amount                  # amount NOT capped

Minimal reproduction

# Order: net_amount = 52, tax_amount = 10  (~19% tax)
# Stripe partial refunds (dashboard, arbitrary amounts): [32, 9, 8, 3, 6, 3]  (sum = 61 = full charge)
# Feeding each through calculate_refunded_tax_from_total + update_refunds yields:
#   refunded_amount = 53  >  net_amount = 52     (over by 1)
#   refunded_tax    = 8   <  its proportional share
# amount + tax = 61 is conserved — the overage on the amount side equals the shortfall on tax.

A sweep of ~500k realistic random orders (3–27% tax, up to 15 stacked partial refunds each ≤ remaining charge) ends with refunded_amount > net_amount in ~115 cases, overage up to +4 minor units.

Reachability

The API refund path (RefundService.create) is safe — it bounds the total to remaining_balance. The affected path is Stripe-dashboard refunds: they carry no refund_id in metadata, so the refund.created webhook falls through to create_from_stripe, which splits an arbitrary stripe_refund.amount via from_total with no upstream bound, and Stripe allows multiple partial refunds per charge.

Impact

• payout_amount = net − fee − refunded_amount is skewed against the merchant by the overage.
• The MoR reverts the same amount less tax to the authority (tax under-remitted).
• Once refunded_amount ≥ net_amount the order flips to status = refunded while refundable_tax_amount is still positive, so a later RefundService.create raises RefundedAlready and the residual tax can never be refunded through the API.

Magnitude is small (1–4 minor units per affected order), but it is a ledger-integrity/tax-remittance correctness issue.

Suggested fix

Mirror the tax cap on the amount side. Caveat: a naive refunded_amount = min(refunded_amount, self.refundable_amount) restores the refunded_amount ≤ net_amount bound but drops the capped minor unit, so refunded_amount + refunded_tax_amount no longer equals the Stripe refund on the overflowing step. The correct fix should keep the split summing to total_refund_amount — e.g. cap the amount and route the freed unit back to tax only up to refundable_tax_amount, or (cleaner) special-case the final refund that closes out the order to return refundable_amount, refundable_tax_amount (the same pattern the function already uses for the == remaining_balance case).

Note on discovery

Found by an automated invariant check ("cumulative refunded_amount ≤ net_amount") over the refund kernel, reproduced with the real function, and confirmed reachable via the Stripe-dashboard webhook path. Machine-checked in Lean: the current split violates the bound on the witness above; adding the amount cap provably restores it for all refund sequences. The asymmetry was introduced in 63c054858 (PR #11894), which added the tax cap without the mirror amount cap.