Skip to main content

Refunds and credit notes

Routes: /org/ecom/orders and /org/ecom/credit-notes Permissions: Manage Refund Request of Customer · Approve Refund Request · View Storefront Credit Notes

1. What a refund is here​

Money going back, in two steps by two different permissions: someone raises it, someone else approves it. A processed refund produces a credit note — the document that records it.

StepPermissionWho typically holds it
Raise on a customer's behalfManage Refund Request of CustomerSupport
ApproveApprove Refund RequestFinance or a manager
View the credit noteView Storefront Credit NotesFinance
Credit notes are a Finance module, not an e-Commerce one

/org/ecom/credit-notes sits under the storefront's route prefix, but its RBAC module is finance_storefront_creditnotes in the Finance category — so View Storefront Credit Notes is granted through a Finance role, not through the storefront ones.

A storefront manager with every org.ecom.orders.* permission can approve a refund and still not be able to open the credit note it produced.

2. How a refund flows​

3. Working the refund queue​

Step 1 · Find them​

The Refund pending toggle on the orders workbench scopes the list to orders with a refund "awaiting admin decision or gateway settlement".

Pending covers two very different waits

One is waiting for a human — nobody has decided. The other is waiting for a gateway — decided, and the money is in transit. The toggle shows both; only the first is actionable.

Step 2 · Decide​

Approval needs Approve Refund Request.

Step 3 · Check the credit note​

Figure 1 — Credit notes.

4. Field reference​

FilterScopes to
Refund pendingA refund in REQUESTED or APPROVED — decided or not, not yet settled
Refunded pillOrders with a processed refund

Partial refunds​

Refunds are recorded per item, so an order can be partly refunded. Such an order matches the Refunded pill while its own status may still read DELIVERED — see order lifecycle.

5. The admin contract​

PrerequisiteWithout it
refund.request_for_customerSupport cannot raise one
refund.approveNothing is ever approved
View Storefront Credit Notes (Finance)The credit note cannot be opened
A payment gatewayCard refunds have no route back

6. Downstream​

EffectWhere
Credit note/org/ecom/credit-notes
Order matches RefundedThe workbench
Shopper sees itMy orders

7. Don't confuse this with…​

ThingWhy it differs
RefundMoney returned on an order
Credit noteThe document recording it
CancellationNo fulfilment; may involve no money at all
CouponA discount before payment

8. Troubleshooting​

SymptomCause
Cannot approveMissing refund.approve
Cannot open a credit noteView Storefront Credit Notes is a Finance permission
Refund stuck pendingWaiting on gateway settlement, not on a person
Order still says DeliveredPartial refunds do not change the order status