Order#outstanding_balance implementation limits Refund usage

[jordan-brough]

Executive Summary

The current implementation of Order#outstanding_balance limits Refund usage to certain use cases. This is mostly the fault of one person who shall remain nameless, but his initials are J.B. and it is me.

In a nutshell, Refunds are being treated as "Order adjustment + Return of money on a payment", and they probably should only be "Return of money on a payment". That was the original intention of Refund.

Long-winded explanation

Currently Order#outstanding_balance is defined as:

total - payment_total - refund_total

where payment_total is defined as payments.completed.sum(:amount) - refund_total.

So outstanding_balance expands to:

total - (payments.completed.sum(:amount) - refund_total) - refund_total

which reduces to:

total - payments.completed.sum(:amount)

This means that "outstanding balance" is "the order total minus your completed payment total, regardless of whether those payments have been refunded or not".

Another way to think of it is that a Refund effectively adjusts the order total. It is saying that you got returned X amount of money and the order should consider it as counting toward the payment total.

This works fine for common scenarios like:

• User completes an order for widget A ($10) and widget B ($20) and submits payment
• User receives their shipment and reports that widget B is broken
• Admin provides a refund for the broken widget B

In this case outstanding_balance is correctly $0.

It does not work for scenarios where the order is modified after payment is complete:

• User completes an order for widget A ($10) and widget B ($20) and submits payment
• User asks to have widget B cancelled, and admin deletes widget B's line item from the order and grants a refund for widget B.

In this case the outstanding balance will end up being -$20 (it appears that we owe them money) because the raw payment total is $30 but the order total has gone down to $10.

It also does not work for scenarios where a refund is issued for some other reason:

• User completes an order for widget A ($10) and submits payment
• User says "oops, I need to pay using a different account. Can you refund me and let me pay with a different card?"
• Admin grants a refund and the user submits a new payment

In this case the outstanding balance will end up being -$10 (it appears that we owe them money) because the raw payment total is $20 (the sum of both completed payments) but the order total is still only $10.

Potential solution

It feels like the right fix could be:

1. Change outstanding_balance to be simply total - payment_total
2. When generating a refund for scenarios like "widget is broken", we also generate a negative adjustment on the order (or line item) to represent the order total .

That would allow Refund to just represent the return of money on a payment, and allow it to be used in various scenarios. That might be a hard thing to do and maintain backward compatibility, however. :(

Thoughts? Have others run into this and solved it in different ways?

[fredericboivin]

I opened a related issue #1107 a while ago about the same thing (and I think we reach pretty much the same conclusion).

I'd be in favor of changing outstanding_balance. Unless I'm missing a use case, the issue that this behavior is addressing is only about presentation. (not showing completed orders with refunds as balance_due in the admin) so this could be solved in a different way (properly updating orders through adjustments or promotions)

What is core opinion on this?

[Senjai]

Can we go with #1 here? I don't see an immediate problem if payment_total also takes into account the refund total. We currently fix this with an adjustment at the moment because refunds don't put the order into the payment state we expect it to be in.

[jasonfb]

I was just going over this point on someone else's PR .... a direct "Refund" as implement (from the Admin payment screen, issued directly against an order OUTSIDE of the Returns Auth process) is kind of a bad news feature.

Our Cust Service team can't give it up, although I am trying to get them to process all refunds through the RA process. The problem with the refunds the way they are is that essentially you can't issue Refund Tax transactions against them, which is appropriate in all cases when you give $ back to someone (this is basically impossible AFAIK because there is not relationship from the refund to the return item that it is refunding, thus making the TAX CODE impossible to know)

To your scenarios:

User completes an order for widget A ($10) and widget B ($20) and submits payment
User receives their shipment and reports that widget B is broken
Admin provides a refund for the broken widget B

this should be treated as a return, even if the thing doesn't come back, and thus go through the RA process which will issue a Refund tax transaction correctly

User completes an order for widget A ($10) and widget B ($20) and submits payment
User asks to have widget B cancelled, and admin deletes widget B's line item from the order and grants a refund for widget B.

We actually can't support this with our 3PL, since they are too good at what they do. Our products ship within 2 hours most of the time, making it actually impossible for us to change orders once they are submitted to our 3PL.

But again, it should be considered a finished transaction and refunds should go through RA. Also, in your scenario, what's the accounting? Is that revenue for the business or not? According to what I understand of GAAP-- which is really important here -- you should consider it two transactions: A sale & a return (the sale is revenue and the return is expense).

Again, if you issue refunds directly, you get no ability to do that Refund Tax transaction

User completes an order for widget A ($10) and submits payment
User says "oops, I need to pay using a different account. Can you refund me and let me pay with a different card?"
Admin grants a refund and the user submits a new payment

This seems to me to be the only actually valid use case for Refunds (outside of RAs). In this case, it is a transactional matter only, you'd simply putting that order back into "limbo" while you take away 1 payment and then add another payment. In this case, we don't care about the Return Tax transactions so it seems to be to be a clean use case.

I agree that the existing logic doesn't make sense. I think one thing we should strive for is separating transaction records conceptually (and I mean all entites) into two categories:

1. transaction records that happen at the time of sale or in fulfillment.
2. transaction records that happen at a later time, and constitute new entries into the Bookkeeper's ledger

Moving in this direction will make things cleaner. And bookkeepers like new entries, not old ones that change values.

[jrochkind]

My thought has been that it's crazy spree/solidus lets you modify a complete order at all. I think the case:

• User completes an order for widget A ($10) and widget B ($20) and submits payment
• User asks to have widget B cancelled, and admin deletes widget B's line item from the order and grants a refund for widget B.

Probably not even to be possible. Instead, an adjustment cancelling out that item would be the way to go. But now I realize that leads to it's own problems with taxes, calculated promotions, etc.

So I don't really know.

[jhawthorn]

Fixed by #2002 🎉