Spec 0028 - Line-item refunds, return outcomes, and optional store credit integrations

[tazzytazzy]

I like the direction of 0028. Moving refunds from a flat amount to line allocations solves a real reporting and support problem. Being able to answer which line was refunded, how many units were refunded, and how much value was allocated to that line is a big improvement.

One thing I would love to see kept clear in the design is that “returns” should not imply only physical goods.

We have both physical and digital products and subscriptions. In those cases, the resolution is not always “customer ships item back, merchant receives item, merchant restocks item.” Sometimes the correct path is:

• refund only
• revoke access
• cancel future access
• issue partial value
• issue no refund with a recorded reason
• issue store credit instead of a card refund
• handle a mixed order where one line is physical and another line is digital

The current spec already separates payment truth from line allocation truth, which feels like the right foundation. Money should still come from the transaction ledger, while line allocations explain what the refund was for. I think that same shape could also leave room for a richer return or resolution layer later without forcing that layer into core refunds immediately.

A few suggestions:

1. Keep refund_lines focused on allocation, not physical return workflow.

   refund_lines should answer what value and quantity were refunded against an order line. It probably should not try to answer whether the item was received, inspected, restocked, access-revoked, or subscription-cancelled.

2. Add enough metadata or extension surface for line resolution context.

   Even if core only ships line-item refunds, it would be helpful if packages can associate their own workflow records with the refund allocation. For example, a package might need to link a refund line to a return request line, a digital access revocation, or a store-credit issuance.

3. Treat physical return, refund-only, and digital/virtual resolution as separate workflows.

   Physical items may need authorization, shipment, receipt, inspection, and restock later. Digital or virtual items may need no shipment at all. They may need a different action, such as revoking access or recording why a refund is not available.

4. Use the discounted paid amount as the refund basis.

   The open question around discounted lines is important. For support and customer trust, the refundable ceiling should reflect the amount actually paid for that line after discounts, not the catalog price. If discounts are spread across multiple lines, the allocation should be deterministic so later partial refunds cannot over-refund one line.

5. Consider a stable way for add-ons to participate in refund decisions.

   A line may be technically refundable from a payment perspective, but still blocked by business policy, expired access, prior refund allocations, subscription state, or a return workflow. It would help if packages had a supported way to provide line capability or refundability checks before the refund is executed.

We are also working on a credits add-on for Lunar. The idea is to keep it separate from returns and refunds, since account credit can come from several places: goodwill adjustments, support recovery, returns, subscription downgrades, or other store policies.

That package will own the credit account, ledger, issuance history, and checkout application rules. Returns or refund workflows could optionally issue credit through it instead of sending money back to the card.

One common use case would be:

• customer has a $100 approved refund value
• merchant offers a 5% bonus if the customer keeps it as store credit
• customer receives $105 store credit instead of a $100 payment refund
• the original line allocation still records the returned or refunded value
• the credit ledger records the issued credit and bonus separately

We plan to make that credits package available for release through the future Lunar app store once it is ready.

So from my side, the main thing I would hope 0028 preserves is a clean boundary:

• Lunar core records payment refunds and line allocations
• line allocations stay tied to the transaction
• optional packages can own return workflows, digital resolution workflows, credit issuance, and other business-specific handling
• physical goods do not become the only mental model for refunds or returns

That would make 0028 useful on its own while also giving package authors enough room to build more complete return, credit, and digital-resolution flows on top.

We also plan to make a Returns/RMA package available to allow users to request physical returns of products; they can get the authorization information (RMA number, shipping address, return directions) from this add-on. Then, the add-on tracks whether we received it, the item's condition, and completes the refund (or a portion of it).