Refund, cancel and return are three separate actions. None of them does another's job.
- Refund sends money back to one payment on the order. It never changes stock, and it never cancels the order.
- Cancel stops an order that hasn't shipped. It never refunds card, cash or gift card money, and it never puts stock back.
- Return (an RMA,
sf_return) tracks goods coming back: requested, approved, received, inspected, completed. Only store credit and gift card refunds move value by themselves. A refund to the original payment is made on the order first, and the return then records it.
Studio does them in that order. Its Cancel with Also refund refunds each payment first, then cancels with refund: false (websitemint order-details.tsx 391–444). Do the same.
Ask first
- Which order? Its order number. Read the order back (customer, lines, total, how it was paid) before doing anything.
- Refund, cancel, or a return of goods? If goods are coming back, use a return (step 5). If the order hasn't shipped and they don't want it, cancel (step 4), refunding first if money was taken.
- How much? The full amount left, or a part. A partial refund is just a smaller amount. There is no per-line refund that works out the price for you.
- Which payment? Only when the order was paid more than one way (gift card plus card, cash plus check). The server refuses to guess.
- Cash? Has the cash been handed back to the customer? A cash refund is refused until a person says yes.
- Put the goods back in stock? Nothing restocks by itself.
Which refunds really send money back
The order refund (POST storefront/order/refund/<orderNumber>) sends the money back to the payment it came from. What happens depends on that payment's gateway (appengine finance/payment.service.ts processRefund 205–228):
| Paid with | What the refund does | Money really moves? |
|---|---|---|
| Stripe (card) | stripe.refunds.create on the payment intent, with an idempotency key from operationKey (616–660). A pending Stripe refund counts as made. | Yes. If the bank later fails it, Stripe's webhook marks the refund failed, puts the order back to paid or partially refunded and reverses its books entry (markOrderRefundFailed, storefront.order.service.ts 2890). |
| PayPal | A stub: // TODO: Implement PayPal refund returns paypal_pending, success: false (771–774). | No. Answer: "Payment refund was not confirmed. Nothing was refunded." A failed refund row is still written to Payments. |
| Helcim | A stub returning helcim_pending (803–806). | No. Same answer as PayPal. |
| Cash, check, offline, manual | No gateway. A refund row (gateway: manual, status: refunded) is written as the record that money went back (storefront.order.service.ts 549–567). | Only by hand. For cash, cashReturned: true is required, otherwise: "This payment was cash. Hand the cash back first, then tick "Cash handed back" to record the refund. Nothing was refunded." Tested. |
| Gift card | The value goes back onto the card that paid (giftCardRefund 557–584). A fully spent card becomes active again. | Yes, onto the card. Tested: a $30 card paid $20, then a $5 refund and a $15 refund put it back to $30. |
| Store credit or reward points | Back to the customer's wallet balance (walletRefund 590–614). | Yes, onto the wallet. |
| Anything else | unsupported_gateway, success: false. | No. |
PayPal and Helcim orders can't be refunded from Appmint. Refund them in PayPal's or Helcim's own dashboard. Nothing then records that refund on the order: Appmint keeps showing it as paid. Say so to the person. If they want the order to read refunded, a person can use Set status directly on the Actions tab (POST storefront/order/set-status/<n> with { status }), which records no refund and no books entry.
Steps
1. Orders: read the order and its payments
Open the order (/order?view=orders&openId=<order sk>). Its Payments tab lists every payment and refund. call_appengine GET storefront/order/<orderNumber>/payments returns the same: orderTotal, totalPaid, totalRefunded, netRetained, refundHistory[], paymentStatus and payments[]. Each payment row has its gateway and ref, which the table above works from.
Check the status (data.status):
| Status | Refund? | Cancel? |
|---|---|---|
new, awaiting-payment (nothing paid) | No: "Order has no verified collected payment to refund" | Yes |
paid, processing, paid-partial, partially_refunded | Yes | Yes |
shipped, in_transit, delivered | Yes | No: "Cannot cancel order with status "shipped"…" |
refunded | No: "Order has already been fully refunded" | Yes |
cancelled | Yes, and it stays cancelled | No |
(storefront.order.service.ts 552–600, 787–793.) Studio's buttons are stricter: Cancel Order is hidden once an order is shipped, partially shipped, delivered, completed, refunded or returned (order-details.tsx 677).
An order paid at the till (POS) is refunded the way its tab is: the same route hands it to the POS refund (storefront.service.ts 128–131). An order made from an invoice may have its money on the invoice, not the order. If its Payments tab lists no payment, refund on the invoice instead: POST storefront/invoices/<invoice sk>/refund with { amount?, reason, transactionId?, operationKey } (see Phone order for a customer).
Hands on: the order number, its status, and each payment's gateway, ref and amount. Check: the person agrees this is the right order and the right payment.
2. Orders: refund
Stop: a refund sends money back. Show the order, the amount, and the payment it goes back to (card ending, gift card, cash). Say whether the money will really move (the table above). Wait for yes. For cash, also ask: has the cash been handed over?
On screen: the order's Actions tab, Process Refund. Enter the amount (it starts with what is left) and a reason. With more than one payment, pick Refund to which payment?. For cash, tick Cash handed back.
Real action: call_appengine POST storefront/order/refund/<orderNumber>:
| Field | What it is |
|---|---|
amount | In money, not cents (5 is $5.00). Leave it out to refund everything left on that payment. |
reason | Shown on the order's refund history and, for a gift card, on the card's timeline. |
paymentRef | The payment's ref from step 1. Required when the order has more than one payment, otherwise: "This order was paid with more than one payment. Choose which payment to refund: … Nothing was refunded." |
cashReturned | true only after a person confirms the cash went back. Required for a cash payment. |
operationKey | 8–100 letters, digits, - or _. The same key sent twice is one refund: the second call answers alreadyRecorded: true. Always send one. Tested. |
items | Saved on the refund line as a note. It doesn't price the refund and doesn't restock. |
The answer carries summary: { orderAmount, thisRefund, totalRefunded, remainingRefundable }. An amount over what is left is refused: "Invalid refund amount: at most 15.00 can go back on the gift-card GCT-… payment" (tested).
What the refund changes:
- The order: a line in
refundHistory,totalRefundedup, statuspartially_refunded, orrefundedonce everything is back. A cancelled order stayscancelled(tested). - Payments: a
refundedrow on the order. - Books: the refund's share of sales and sales tax is reversed (
postOrderRefundToLedger). Tested: onerefundjournal entry per refund. - Reward points the order earned come back off the customer's share.
- Stock: nothing. Tested: stock stayed where the sale left it.
- Email: none to the customer for a card or cash refund. A gift card refund sends
gift-card-creditedto the card's holder, if the card has an email or phone (giftcard.service.ts1148).
Hands on: the refund id (refund.id) and summary.remainingRefundable.
Check: the Payments tab shows the refund. For Stripe, the refund shows in Stripe's dashboard.
3. Payments: a refund started from the payment
Payments (/payment, open the payment, Refund) refunds one payment directly: POST finance/payments/refund with { gateway, paymentRef, amount, reason }. Here the amount is in cents. It records the refund on the order or invoice it belongs to and books it, like the order refund (finance/payment.controller.ts 37–48, 97–104). Prefer the order refund (step 2): it checks cash, split payments and what is left. Studio's Refund box here offers the payment's full amount even after earlier partial refunds.
4. Orders: cancel
Stop: cancelling emails the customer and can't be undone. If money was taken and the customer gets it back, refund first (step 2), payment by payment. Show the reason and wait for yes.
On screen: the order's Actions tab, Cancel Order, with a reason. Leave Also refund off if you already refunded.
Real action: call_appengine POST storefront/order/cancel/<orderNumber> with { reason, refund: false }.
What cancelling changes (storefront.order.service.ts 763–931):
- Status
cancelled,cancelledAt,cancellationReason; the order workflow moves to Cancelled. - Kitchen or fulfilment tickets fired for it are voided.
- Store credit and reward points that paid for it go back to the customer's wallet.
- Email:
order-cancellation, "Order #… cancelled", to the order's email (tested). It mentions a refund only when the cancel itself made one. - Not changed: card, cash and gift card payments. Tested: a gift card that paid $20 stayed at $10 after cancelling; refunding the cancelled order afterwards put the $20 back.
- Not changed: stock. Tested: two units sold stayed off stock after the cancel.
Don't rely on refund: true. It refunds only an order with a gateway paymentRef in status paid, processing or confirmed, and it asks the gateway for the whole order amount, ignoring earlier partial refunds. Its refund isn't added to the refund history. For anything else it silently refunds nothing: a cash-paid order cancelled with refund: true answered just "Order cancelled", with all $32 still collected (tested). Refund first with step 2, then cancel with refund: false, as Studio does.
Hands on: the cancelled order's number. Check: the order reads Cancelled, and its Payments tab shows each refund you made.
5. Returns: take goods back (RMA)
A return is its own record (sf_return, numbered RMA-…). Staff open it from the order (Return items) or Returns (/return?tab=returns), which calls POST storefront/returns/request. A signed-in customer opens one from My Account › Orders › Request a return, then sees it at /account/returns.
The request names lines by SKU and quantity: { orderNumber, type: 'return', reasonCategory, reason, items: [{ sku, name, quantity, returnQuantity, condition, reason }] }.
reasonCategory:defective,damaged_shipping,wrong_item,not_as_described,changed_mindorother.otherneeds a reason.condition:unopened,opened,damaged,defectiveorwrong_item.typemay also beexchange,warrantyorrepair.
Prices come from the order, never the request. Tested: a line sent at $999 was saved at the order's $20. The window is 30 days from the order (returns.service.ts 286). It can't be changed. Later: "Return window has expired for order …".
Every move is staff-only, on the return's ⋮ menu, PUT storefront/returns/<rmaNumber>/<action>:
| Step | Action and body | From status | Email to the customer |
|---|---|---|---|
| Requested | POST storefront/returns/request | — | return_request_confirmation, "Return request received (RMA-…)" |
| Approve | approve { notes?, returnAddress?, shippingLabel? }. With no full address, the selling location's address is used, else the first location that has one. | requested | return_approved, with where to send it |
| Reject | reject { reason } | requested | return_rejected, with the reason |
| Customer ships | PUT storefront/returns/rma/<rma>/ship { carrier, trackingNumber } (customer side) | approved | none |
| Receive | receive { receiptMethod: 'shipment' | 'in_store', notes? }. In store skips the shipping step. | shipped, or approved for in store | none |
| Inspect | inspect { items: [{ sku, itemIndex, approved, condition, notes? }], overallNotes? }, one decision per line. Only accepted lines count toward the refund. | received | none |
| Complete | complete (below) | received or inspecting | return_completed |
| Cancel | cancel { reason }. No refund. Stock held for it is released. | not completed | none |
(returns.controller.ts 223–350, returns.service.ts. The whole path, from request to complete, was tested, and the three emails were queued.)
Stop: completing gives value back and emails the customer. Show the amount and how it is given, and wait for yes.
Complete takes { amount, method, transactionId?, giftcardSerial?, notes? }. The amount can't exceed what the accepted lines sold for: "Refund amount exceeds the inspected and accepted return value (…)". GET storefront/returns/<rma>/refund-options lists the refunds already made on the order that it can name (read-only).
method | What really happens |
|---|---|
original_payment | Moves no money. Refund the order first (step 2, reason Return <rma>), then complete with transactionId set to that refund's id. Tested: the return was "Settled by refund refund-… of $20.00 made on order …", and that refund now names the RMA. Any other reference is written down with "this did not move money — make the refund itself on the order or with the payment provider." |
store_credit, no giftcardSerial | Credits the customer's store credit wallet (needs a customer email), booked as owed. |
store_credit or giftcard with giftcardSerial | Puts the value onto that existing gift card. |
giftcard, no serial | Issues a new gift card for the amount and emails it to the customer (gift-card-issued). |
exchange | Amount 0. No money moves. Send the replacement as a new order. |
When completed returns cover every unit sold, the order becomes returned, unless it is already refunded or cancelled (tested: a refunded order stayed refunded).
Studio's Complete dialog labels store credit as "Store credit (issue a new gift card)". The server credits the wallet instead when no card is named (returns.service.ts 710). Choose Onto an existing gift card, or giftcard with no serial, when the customer should get a card.
Hands on: the RMA number and how it was settled. Check: the return reads Completed, and its timeline's last line says what was given back.
6. Inventory: put the goods back in stock
Nothing puts stock back by itself: not refund, not cancel, not return. Tested: six units sold across test orders stayed off a product's stock through refunds, cancels and a completed return.
- Products whose stock is kept in Inventory (
sf_inventoryrows): on a completed return, ⋮ › Restock items callsPOST storefront/inventory/returnwith{ sku, locationId, quantity, returnId: <rma>, condition: 'restockable' | 'damaged' }. - Products that count their own stock (
data.stockon the product, "Track inventory"): a sale counted it down when the order was placed (storefront.order.service.ts2145). Raise it again by editing the product's stock, only after the person says the goods are resellable.
Stop: ask before changing stock.
Check: the product or inventory row shows the new count.
When it's done
Tell the person:
- the order number and its status now;
- each refund: amount, which payment, and whether the money really went back (Stripe, gift card, store credit), was only recorded (cash), or must still be made by hand (PayPal, Helcim);
- for a return: the RMA number and how it was settled;
- what the customer was emailed (cancellation, return emails; nothing for a plain card or cash refund);
- that stock was not changed, unless they asked and you restocked.
Open the order's Payments tab, or the return.
What it can't do yet
- PayPal and Helcim refunds, and voids and captures, are stubs. Refund in their dashboards. The order then still reads paid.
- No stock goes back on cancel, refund or return. It is a manual step (step 6).
- No per-line refund.
itemson a refund is a note. The amount is what you type. - No refund email for card or cash refunds. Cancellation and return emails are the only order emails here.
- The cancellation email isn't on the order's Messages tab. It is saved with the order id
undefined(tested), so look for it by the customer's email. - Cancel's
refund: trueis unreliable (step 4). - The return window is fixed at 30 days.
- Returns accept gift card lines. The site's return form doesn't leave them out.
Refunds are staff only. A signed-in customer may cancel their own order (window.appmint.order.cancel), but not refund it or cancel with refund: true: both answer 403 "A refund is made by the business…". Anyone not signed in gets 401 "Sign in to change this order.", and another customer's order 403 "This order is not yours to change." (storefront.controller.ts orderRefund, orderCancel, assertMayActOnOrder). The customer asks the business, and staff refund it here.
Don'ts
- Don't refund or cancel without a yes, and never twice: always send an
operationKey. - Don't tick
cashReturnedfor the person. They confirm the cash was handed back. - Don't tell a customer a PayPal or Helcim refund was made from Appmint.
- Don't cancel to give money back. Cancel gives nothing back.
- Don't complete a return as
original_paymentbefore refunding the order. - Don't call
StorefrontOrderService.orderRefundthroughcall_service. It skips the till check and who-refunded that the route adds. Use the route. - Don't change stock without asking.