Proposal: Stable Post-Purchase Lifecycle Hooks for Returns, Refunds, and Line-Level Add-Ons

[tazzytazzy]

I’m looking at building a reusable Returns / RMA package for Lunar, as well as subscription and credit packages. I chatted briefly about this on Discord, and as much as I want to wait for version 2.x in hopes these features will be available, I need to get the e-commerce portion going sooner than later.

The main gap I’m hitting is post-purchase extensibility. Lunar already has good extension points around carts, orders, and payment drivers, but add-ons still need to duplicate some lifecycle logic once an order has been paid, refunded, cancelled, or handled at the line level.

What would help most is a small set of stable lifecycle hooks/contracts that packages can build on. I'm willing to code these and update the docs repo, but I just want some guidance if these would be accepted into the mainline. I'm also willing to contribute the returns / RMA package, credit package, and subscriptions package too, but as separate PRs.

If this seems reasonable, I can put together a concrete proposal for the hooks, events, contracts, and listener flow before I start implementation.

---

Sleepy time details

Requested hooks/contracts:

• OrderPaid / OrderLinePaid: a reliable signal that payment actually succeeded, so add-ons can start post-purchase behavior from the correct lifecycle point.
• RefundRequested: fires before refund execution, so add-ons can run approval checks, eligibility logic, and prepare their own accounting/workflow state.
• RefundCompleted: fires after a successful refund, so add-ons can finalize workflow state and link their records to the Lunar refund transaction.
• RefundFailed: fires when refund execution fails, so packages can keep state accurate and recover cleanly.
• Order-line lifecycle hooks such as created, paid, cancelled, refunded, and completed: this would let packages react to purchased lines directly instead of inferring everything from the order aggregate.
• Refund allocation hook/contract: some way to pass or resolve per-line allocations for an order-level refund, since Lunar refunds at the transaction level, but returns/refund packages still need line-level refund truth.
• Order-line capability contract: lets admin/storefront code ask things like isRefundable, isCancellable, requiresPhysicalReturn, createsEntitlement, supportsEndOfTerm, or allowsAccountCredit without hardcoding package-specific rules.
• Credit application / order-adjustment contract: some way for a credits package to apply account balance against eligible order amounts before external payment is authorized/captured, without pretending credits are a payment driver.
• Credit eligibility/allocation contract: lets checkout/admin layers determine which lines can consume account credit and how applied credit should be allocated, especially if recurring renewal charges should remain ineligible.

DB / migrations:

• I do not think this requires core DB changes.
• A returns package can own its own tables, e.g. return_requests, return_lines, refund_allocations, plus optional audit/receipt records.
• A subscription package addon and credits package addon can also own their own tables, e.g. subscription, credit-account, credit-entry, and credit-application tables.
• The main ask from core is lifecycle hooks/contracts, not built-in returns, subscriptions, or credit tables.

[glennjacobs]

Hey there, thanks for the comprehensive write-up.

This is a big part of what v2 is looking to solve, so the timing I guess is unfortunate.

Some of the events proposed would be fairly straightforward. The order line logic I think is a problem as it simply doesn't exist in v1. Refunds etc are not linked in any way to order lines. So I'm not sure how that would be solved.

We also have to consider v2, so that any v1 updates don't go in a different direction. Luckily it's still WIP so we have flexibility there.

I don't think we'd want the additional packages in the monorepo, they would be best as community add-ons I think right now for v1. However, some of the concepts may well be appreciated for v2, eg. I wanted the v2 core to have the concept of customer credit and a basic ledger for it.

Perhaps if you can propose your approach and we can see what might work?

[truelost]

Thanks for the thoughtful response, and for the time you all are putting into both v1 and v2.

That all makes sense. I definitely do not want to push v1 in a direction that fights what you are planning for v2, and I also agree the add-ons themselves are better as community packages for now rather than going into the monorepo.

My goal on the v1 side is not to make core own returns, subscriptions, or credits. The goal is to add a small, general-purpose extension surface that lets community add-ons integrate cleanly with checkout, payment success, refunds, and post-purchase line behavior.

The main thing I want to avoid is package authors having to bypass Lunar internals or duplicate payment/refund orchestration just to build common commerce add-ons.

Without being able to see v2, it's hard to plan from my side or write code for it. I know you're planning a grand reveal, but for open-source and code contributions, it makes it a bit harder. I would like to contribute to the core in a way that doesn't duplicate work or cause headaches for you for v2.

Here is the approach I had in mind.

---

1. Payment success hooks

This is the most broadly useful and seems like the safest starting point for v1.

Proposed idea

Add a stable event when an order is actually considered paid / financially complete.

Why

Packages need one reliable place to react when payment has succeeded:

• returns may need to determine refundability windows from the paid date
• subscriptions may need to activate service
• credits or other add-ons may need to create follow-up records

Suggested shape

• OrderPaid
• optional OrderLinePaid

I understand the concern around order-line logic in v1. I am not imagining line payment state stored separately in core. For v1, OrderLinePaid could simply mean: "this line belongs to an order that has now been paid", not "this line has its own financial lifecycle in core."

So this would be a convenience lifecycle event, not a new persistence model.

Example payload:

• order id
• transaction id if available
• payment driver
• paid amount
• timestamp
• for line event: order line id

If OrderLinePaid feels like too much for v1, I think OrderPaid alone is still valuable, and packages can derive the lines from the order. I would like to have this for subscription items.

---

2. Refund authorization + refund lifecycle hooks

This is the biggest need for a returns / RMA package.

Proposed idea

Add:

• a pre-refund authorization contract / guard
• refund lifecycle events around execution

Why

A returns package needs to be able to require an approved return workflow before money is actually refunded.

An event after the refund is useful, but it does not solve the main workflow problem. The key missing piece is a clean veto point before the payment driver is called.

Suggested surface

Contract / guard

• RefundAuthorization
• or similar naming if you prefer

Purpose:

• given an order / transaction / amount / actor, decide whether the refund may proceed

This would let a returns package say:

• if there is no approved return request, deny the refund
• if the request is approved, allow it

That avoids having packages override admin behavior or throw from listeners.

Events

• RefundRequested: refund is about to execute, after authorization has passed
• RefundCompleted: refund succeeded
• RefundFailed: refund attempt failed

Payload could include:

• order id
• source transaction id
• refund amount
• notes
• actor / user id if available
• refund transaction id on success
• failure message on failure

This part seems useful regardless of whether v2 later changes the deeper refund model.

---

3. Refund allocation as a contract, not core refund persistence

I agree with the concern that v1 does not link refunds to order lines. I am not proposing that core suddenly implement native line-item refunds in v1.

Proposed idea

Keep Lunar’s refund truth at the transaction level, but optionally expose a line-allocation contract / payload shape for packages.

Why

Returns packages still need line-level refund truth, even if the actual payment refund is order-level.

For example:

• customer returns 1 of 2 units on one line
• refund amount must be tracked against that line
• package needs to record how much of the order-level refund maps to each affected line

Suggested shape

• RefundAllocationResolver
• or allow an optional line_allocations payload on refund-related events / request DTOs

Important point:

• core would not need to store this
• core would not need to pretend refunds are line-native
• this would just give packages a stable integration point for passing and reacting to allocation data

So in v1, Lunar could still refund at the transaction level exactly as it does now, while packages own their own ledger tables and line-allocation truth.

---

4. Order-line capability contract rather than full line lifecycle state

I think this may be the better fit for v1 than trying to force deeper order-line lifecycle into core.

Proposed idea

Expose a capability resolver contract for order lines.

Why

Admin/storefront code often needs to ask:

• is this line refundable?
• is this line cancellable?
• does this require physical return?
• does this create an entitlement / ongoing service?
• should account credit be allowed on this line?

That is a real need for returns, subscriptions, and credits, but it does not necessarily require core to model a full line lifecycle state machine.

Suggested shape

• OrderLineCapabilities

Purpose:

• packages can answer capability questions for a line
• UI and orchestration code can use one contract instead of hardcoded checks

This feels v1-compatible because it is additive and does not require changing Lunar’s data model.

---

5. Credits as a secondary concern for v1, but important for v2 direction

Since you mentioned v2 may include customer credit and a basic ledger, I think this is worth at least framing now, even if it is not all implemented in v1.

Proposed idea

A credit application / eligibility surface that lets stored value reduce the remaining external payment amount without acting like a fake payment driver.

Why

A credits package needs to:

• determine what order amounts are eligible for credit
• apply some or all available balance
• reduce the remaining charge before external payment completes
• keep recurring renewal scenarios ineligible if needed

Suggested shape

• CreditEligibilityResolver
• CreditApplicationResolver

I see this as more directional for v2 and possibly optional for v1. I would not expect the whole customer-credit system to land in v1 core, but if there is a preferred direction for how v2 wants to think about credits, I would like to avoid building the add-on in a way that conflicts with that.

---

6. What I think core should own vs package should own

Core

A small generalized extension surface:

• OrderPaid
• refund authorization / guard
• refund lifecycle events
• optional refund allocation payload/contract
• optional order-line capability contract

Packages

All package-specific workflow and persistence:

• returns / RMA tables and states
• subscription tables and lifecycle
• credit ledger / balance tables
• package-specific domain events

So I am not asking core to own the business domains, only to expose the commerce lifecycle points that packages need in order to integrate cleanly.

---

7. My v1 preference

If it helps to keep scope tight, I think the most practical v1 subset is:

1. OrderPaid
2. RefundAuthorization
3. RefundRequested
4. RefundCompleted
5. RefundFailed

That alone would unlock a lot for a returns package and would also help subscription activation.

Then, if it still feels aligned with v2 direction, the next layer would be:

• refund allocation contract / payload
• order-line capability contract

And credits can stay mostly in community-package land for v1 unless there is a specific core direction you already know you want to preserve for v2.

---

If this overall direction seems sensible, I can follow up with a tighter proposal showing:

• suggested event names
• example payloads / DTOs
• a proposed refund flow
• where the authorization contract would be called in v1

I am happy to follow your lead on naming and shape. My main goal here is to propose a framework that is small enough to fit v1, but not so narrow that community add-ons have to work around core.

[glennjacobs]

I know you're planning a grand reveal

Not so much a grand reveal, just that we may still make fundamental changes and don't want to reveal something that ultimately is not what we deliver.

I am happy to see a PR for the first subset, and then we can consider how the order line side of things would work after.

[tazzytazzy]

I've broken this down into 3 PRs:

1. OrderPaid + refund orchestration + refund authorization + refund lifecycle events + admin refund integration + order-line capabilities + refund allocation passthrough.

This first PR is intentionally the largest, because it needs to be enough to unblock a reusable returns/RMA package. Refund hooks alone are not sufficient for that. Returns also needs a generalized way to ask line-level questions like isRefundable / requiresPhysicalReturn, and a clean way to attach package-owned allocation data to the order-level refund flow without introducing line-level refund persistence into core.

2. OrderLinePaid as a convenience order-line lifecycle hook.

This is mainly for subscriptions and other line-oriented post-purchase activation use cases. It stays additive and explicitly does not introduce independent line-level financial state in core.

3. Credit checkout hooks.
   This would cover generalized contracts for credit application, credit eligibility, and credit allocation, so a credits package can reduce the remaining external payable amount without acting like a payment gateway or pushing credit-ledger logic into Lunar core.

I think this split gives us the best balance of usefulness and reviewability:

• PR 1 delivers immediate value and is sufficient to build returns/RMA cleanly.
• PR 2 adds the missing line-oriented purchase hook for subscriptions.
• PR 3 isolates the most opinionated checkout-related surface, which is likely the highest-risk part to review.

Across all 3 PRs, the boundary stays the same:

• no returns, subscriptions, or credits tables in core
• no native line-item refund persistence in core
• no package-specific business workflow in core
• only generalized extension points that reusable add-ons can build on

Once i get the 1st PR working along with my returns / RMA package, then I'll post the 1st PR.

[tazzytazzy]

I've made PR #2443 as a start. Let me know what you think and if i should change any of the elements / function calls.

[tazzytazzy]

Any feedback on #2443? Thanks. @glennjacobs