Dispatch Tracking, Cancellations & Returns¶
What happens to an order after it's placed: dispatching it with a tracking number, cancelling it before it ships, and taking items back after it has shipped. Each is available in the admin, the REST admin API and over MCP, and runs through the same service code in all three.
Dispatch tracking¶
When an order is dispatched you can record how it's being delivered:
| Field | Limit | Notes |
|---|---|---|
carrier |
100 characters | e.g. Royal Mail |
trackingNumber |
100 characters | |
trackingUrl |
500 characters | Must be a full http:// or https:// link, because it's rendered as a link in the email |
All three are optional, so an order can still be dispatched without tracking. Values are trimmed, and an invalid value stops the dispatch with a message naming the field.
Where it's stored. Order.dispatchTracking (DispatchTracking, with a recordedAt date). Tracking a fulfiller records in the portal is also held per line (LineItem.dispatchTracking), because an order split between fulfillers goes out as several parcels; it goes on the order only when one fulfiller is sending everything. When an order has no order-level tracking, the dispatch emails show each item's own tracking beside it (see Fulfilment).
The admin order view, orders get over MCP and the REST Order model all show it; the REST per-line fulfilment status (LineFulfilmentStatus.dispatchTracking) shows each line's own tracking.
How it's recorded. OrderService.dispatchOrder(order, user, siteContext, tracking) passes the
values to the site's dispatchOrder pipeline as additionalParameters (carrier,
trackingNumber, trackingUrl). The recordDispatchTrackingProcessor step (priority
CORE + 200, after setOrderToDispatchedProcessor) saves them on the order and writes
DISPATCH_TRACKING_RECORDED <carrier> <number> to the activity log. The dispatch email step runs
after it, so the email includes the tracking. setOrderToDispatchedProcessor doesn't email the
customer itself: if it did, the email would be queued before the tracking was saved. The
effective pipeline is:
orderStateValidationProcessor(the order must be PACKING)conditionalCaptureProcessor(captures if the site captures at dispatch)setOrderToDispatchedProcessor(marks every outstanding lineFULFILLED, digital ones included; the order's state rolls up to DISPATCHED from them, see Fulfilment. If the order still isn't DISPATCHED it stops the pipeline witherror, so nobody is told it was dispatched)recordDispatchTrackingProcessorsendOrderDispatchEmailProcessor(does nothing if the dispatch email has already been sent)redirectToOrderPageProcessor
The email. email/orderDispatched (and its -text variant) shows a "Tracking info"
block with the carrier, the tracking number and a link, when the order has tracking. It and
orderPartialDispatched use the order confirmation's (orderPlaced) layout: the branded banner
with the logo, order number and date, the items in the parcel, and where it ships to. The
wording comes from the orderNotificationEmail.tracking* message keys (English and Dutch).
Resending the dispatch email¶
OrderEmailResendService.resendDispatchEmail queues the customer's dispatch email again, with the
order's current tracking, and logs DISPATCH_EMAIL_RESEND_QUEUED. Every route that sends the
dispatch email builds it with OrderDispatchEmailSender, so they all use the same site settings
(orderDispatchTemplate, orderDispatchSubjectPattern, orderNotificationFrom*). Those routes
are the dispatchOrder pipeline, a fulfiller finishing the last lines in the portal, and the resend. Apart from a resend, the email goes once per order:
CustomerDispatchNotifier records DISPATCH_EMAIL_QUEUED and won't send it again. A resend is
refused if the order isn't DISPATCHED or DELIVERED, and nothing is sent if the order has no
customer email address.
Where to find it¶
| Dispatch with tracking | Resend dispatch email | |
|---|---|---|
| Admin | Order view → Dispatch Order opens a form for the tracking (orders with one fulfiller; see below) | Order view → Resend Dispatch Email (admins only) |
| REST | POST /v1/admin/orders/{orderId}/dispatch with an optional DispatchOrderRequest body |
POST /v1/admin/orders/{orderId}/dispatch/resend-email (409 if not dispatched, 422 if no customer email) |
| MCP | manageFulfilment dispatch with carrier, trackingNumber, trackingUrl |
manageOrderEmails resendDispatch |
| Fulfiller portal | /fulfilment → an order → Dispatch, with optional tracking for that fulfiller's items |
— |
Over MCP the resend is refused if the dispatch email was sent for the order in the last 15 minutes, whether by the dispatch itself or by an earlier resend.
An order split between fulfillers has no Dispatch Order button. Each fulfiller's items are dispatched separately (Advancing an order in admin), and that action doesn't take tracking. The REST and MCP dispatch don't look at fulfillers: they dispatch every outstanding physical line on the order.
On the customer's order page¶
The order page (/o/{orderId}/{confirmationCode}, the orderSummaryExtension) shows the order
number and the date it was placed, the message for its state (order.confirmation.status.<STATE>,
reworded in Site Text; see below for DISPATCHED), and a Tracking panel listing every parcel's carrier, tracking number and
Track your parcel link (trackingUrl). The parcels are the order's own tracking and each line's
(an order split between fulfillers goes out as several parcels), each listed once
(OrderSummaryExtension.trackingOf); with none recorded the panel isn't shown. Nova, Brock and the
themes built on them show it. When the order's
parcels went with parcel labels, a Where your order is panel replaces it:
each parcel's status, carrier link and a timeline of status, date and town (see
Parcel Tracking). Each line shows its
picture, and the page has Continue shopping and Print receipt buttons. Printing the page (the
button, or the browser's own print) gives a plain black-and-white receipt from a print-only
stylesheet (order-print.css): only the order goes on the paper, without the shop's header, footer,
other blocks on the page, buttons, pictures or coloured backgrounds; status pills print as outlined
boxes, tracking links print their web address, and the details sit side by side. The receipt starts
with the shop's name and web address, and ends with the business behind it from Settings > Store and
storefront > Legal entity (legal name, registered address, company number and VAT number, each only when it's filled
in); neither shows on screen. It's a receipt, not a VAT invoice. Nova and Brock pages (and the themes
built on them) print this way, including the account order page.
An order reaches DISPATCHED when all its lines are fulfilled, which means different things depending
on what it holds, so the page and the order confirmation email pick the message from the order
(Order.confirmationStatusKey):
| The order holds | Key | Message |
|---|---|---|
| Something posted or delivered | order.confirmation.status.DISPATCHED |
Your order has been sent and is on its way. |
| Something collected (click & collect) | order.confirmation.status.DISPATCHED.collected |
Your order has been collected. |
| Nothing to send: donations, tickets, digital products (fulfilled as soon as it is placed) | order.confirmation.status.DISPATCHED.complete |
Your order is complete. |
Each can be reworded in Site Text. The state badge beside the order heading, and in the customer's
order history (Account overview and Orders), follows the same rule
(generic/order/customerStatusBadge, keys order.status.badge.<status>): Received, Being packed,
Sent, Collected, Complete, Delivered, Cancelled, Payment failed, in the shopper's language. Admin
screens keep orderStateBadges, which shows the raw state. The Shipping Address card only appears
when something on the order ships.
The page doesn't show a step-by-step tracker: which steps an order goes through will depend on the items in it, so a tracker belongs with that work rather than a fixed list of order states.
Nova draws all of this for every Nova-based theme in the theme's own colours.
Delivered¶
DELIVERED follows DISPATCHED when the carrier says every parcel on the order has arrived: when
every live outbound parcel label on a DISPATCHED order reaches the
DELIVERED tracking status, TrackingService calls OrderService.markDelivered, which records the
change on the order's state history like any other. Only DISPATCHED orders move; nothing moves an
order to DELIVERED without labels. Tracking describes the carrier's work, so the lines' fulfilment
states (PACKING, FULFILLED) are left alone. See Parcel Tracking.
Order cancellation¶
A SUBMITTED or PACKING order can be cancelled. Cancelling gives the customer their money back, marks the order CANCELLED, puts its stock back and emails the customer. A DISPATCHED or DELIVERED order can't be cancelled; it needs a return.
What happens to the payment¶
OrderCancellationService.plan(order, siteContext) works this out before anything changes. The
admin modal, the REST dry run and the MCP dry run all show the plan.
| Payment state | What cancelling does |
|---|---|
CAPTURED, PARTIAL_REFUND (or legacy PAID) |
REFUND: what's left (captured amount minus refunds so far) is refunded by running the site's refundOrder pipeline |
| Paid in cash at the till, in full or in part | CASH_REFUND (cash only) or REFUND (with a card too): any card part is refunded through the gateway, and the cash part is recorded as given back on the order's cash payment (activity POS_CASH_REFUND:<id>:<amount>) for staff to hand over the counter. The admin's cancel dialog says how much cash to hand back |
AUTHORISED (not captured yet, e.g. a site that captures at pack or dispatch) |
VOID: the Stripe PaymentIntent is cancelled, releasing the hold on the card; the payment becomes VOIDED |
No payment, INITIAL, REFUNDED, VOIDED |
NONE |
Anything else (PENDING_REFUND, DISPUTED, FAILED...) |
Refused: sort the payment out with the provider first |
Cancelling is also refused when:
- the order is a table's bill with money taken: it is refunded from the table, whose own record of refunds a cancellation here would leave out;
- the order has a line that cancelling can't undo: a subscription, a virtual gift card, a gift card top-up or a donation (their side effects happen at checkout);
- the order was paid partly by another payment intent (a gift card or split tender), because
the
refundOrderpipeline only refunds the main card payment (cash taken at the till is the exception above: it is recorded, not sent to a gateway); - part of the order has already been dispatched. An order split between fulfillers stays PACKING until the last one finishes, and cancelling it would refund and restock goods that have gone. Dispatch the rest, then record a return for anything coming back.
The cancelOrder pipeline¶
OrderCancellationService.cancel(order, user, siteContext, reason, restock) checks the plan, then
runs the site's cancelOrder pipeline through OrderService.cancelOrder. The pipeline gets the
reason and restock values as additionalParameters:
orderStateValidationProcessor: the order must be SUBMITTED or PACKING (validStatesconfig, defaulting to those two).releaseOrderPaymentProcessor: refunds or releases the payment as above, and recordscancellationPaymentAction/cancellationPaymentAmounton the order. If the provider refuses, it stops the pipeline witherror, so the order is left as it was.setOrderToCancelledProcessor: sets the state to CANCELLED, marks the lines still to be fulfilledCANCELLED(see Fulfilment), and stores the reason in thecancellationReasonorder property and the activity log.restockCancelledOrderProcessor: puts the stock back (see below), unlessrestockisfalse.releasePromotionUsesProcessor: gives back the promotion uses the order took at checkout, so they count again towards "first N" and per-customer limits (see Marketing tools).sendOrderCancellationEmailProcessor: emails the customer.
The pipeline is annotation-driven (@PipelineStep), so it reaches every site on deploy.
defaultProcessors.json has rows for it, and system update 84.json adds the
orderStateValidationProcessor / cancelOrder config row to existing installs, so the valid
states can be changed per site in the pipeline admin.
Stock is taken when the card is held¶
Unified checkout (including direct checkout) takes an order's stock at the
moment of payment, so two shoppers can't both buy the last one. When the shopper pays, Stripe holds
the amount on their card (the intent waits at requires_capture).
First, checkout checks the hold is for the basket as it is now: the intent's amount and currency
against the order's total. A basket changed after the card was held (an edit from the basket page
or another tab while the payment was in flight) would otherwise be placed for its new total while
capture takes only what Stripe holds. On a mismatch the hold is cancelled (or the payment refunded,
for a wallet that captured straight away), any stock the order still holds is put back, the cached
intent is dropped so the next attempt pays the new total, and the shopper is told
checkout.msg.basketChangedDuringPayment: their basket changed while they were paying and their
card hasn't been charged. No order is placed.
Then, before the order is placed, StockAllocationService.allocate takes every line's stock
atomically:
- All of it is there: the order goes ahead. What was taken is recorded on the order.
- Something has just sold out: what was taken is put back, the card hold is cancelled (or the
payment refunded, for the few wallets that capture straight away), and the shopper is told
checkout.msg.soldOut: the item sold out and their card hasn't been charged. No order is placed. - The payment then fails to authorise, or the order fails to go through:
releaseputs the stock back.
A site with allowOOSAddToOrder on still takes orders for items it is short of, as before: what
can be taken is taken and the order goes ahead.
With multiple stock locations on, each line is taken at the location sourcing chose for it. If another order takes that stock between the plan and the taking, what was taken goes back, the order is planned once more against what's left, and a second miss counts as sold out. Without them every line comes from the default location.
The legacy checkout, POS sales and REST baskets don't have this step yet. updateInventory in the
submitOrder pipeline takes their stock, and only logs a shortfall. It skips an order checkout has
already allocated (orderProperties.stockAllocated), so stock is never taken twice. With multiple
stock locations on, it sources web orders the same way (StockAllocationService.takeAvailable,
which keeps what it can get and never fails the order); till sales still take stock at the default
location.
Stock held by an order that was never placed¶
Checkout saves the hold on the order as soon as it takes the stock
(orderProperties.stockAllocationPendingSince), and placing the order removes that marker. If a
checkout stops between the two (the server restarts mid-confirm, say), the worker's
StockHoldReleaseJob puts the stock back after the site's stock-hold-release-minutes (default
30, never less than 5). It only ever releases a basket: an order that was submitted or placed, has
a PaymentV2 intent or a paid payment state, or whose checkout lock says the card is held or charged,
keeps its stock. Each release claims the hold atomically on the stored order, so two workers can't
put the same stock back twice. A payment_intent.payment_failed webhook for a basket releases its
hold too, once the hold is two minutes old (a younger one may belong to a confirm placing the order
that moment; the job picks it up later).
The hold also records what it was taken for (orderProperties.stockAllocationBasis: each line's
id, SKU, quantity and collect or deliver choice, and the delivery and collection options and
slots). If the basket changes while it still holds stock (a line added, a quantity raised, a line
moved between collect and deliver, another option or slot), the next confirm hands the hold back
and takes the stock again for the basket as it is, and so does placing the order by any other
route (UpdateInventory). Until then the stock it holds still counts as its own when checkout and
the basket read a store's stock.
Restocking¶
Stock taken at checkout is recorded in the order's stockTaken property
([{skuId, quantity, location}], location being the location code it came from).
A SKU that was already out of stock isn't decremented, so it isn't recorded. Restocking puts back
exactly that list with InventoryService.increaseStock, each entry at the location it came from;
older entries without a location go back to the default location. Orders placed before the record
existed use their line quantities instead. Untracked SKUs (unlimited stock) are left alone, and
quantitySold isn't reduced.
Event ticket lines are the exception at checkout: reserveTicketStockProcessor takes their stock
earlier, in the validate phase, and refuses the order if any ticket type is sold out (an event has
a fixed capacity, so it can't oversell). Its stockTaken entries carry the lineItemId, and
updateInventory skips those lines. Cancelling voids the order's tickets
(voidTicketsProcessor) before the restock.
A refused order stays a basket and the card hold is released. Checkout then hands it to
SoldOutTicketsService.returnToBasket: each sold-out ticket line is cut to the tickets still left
(a line with none left keeps its quantity and shows as out of stock, for the buyer to remove), the
order is repriced, and the buyer goes back to the basket page, where the line says Sorry, Adult
tickets for Summer Gala sold out while you were checking out. Only 2 are left, so your basket
now has 2. You have not been charged. (or that the payment will be refunded, when the hold
couldn't be released automatically). The single-page checkout, the step checkout's payment step and
Apple Pay quick pay all do this; a direct-checkout (/buy) order has no basket, so its checkout
reloads with the same message. The wording is the basket.stockNotice.ticketsSoldOut* Site Text keys.
The customer email¶
email/orderCancelled (HTML and text) tells the customer the order was cancelled and whether they
were refunded or had the hold on their card released, with the amount. A click & collect order is
told there's nothing to collect (orderCancelledEmail.body.collection) rather than that it won't be
sent. The cancellation reason is internal and isn't included.
Config key (order-cancellation-emails) |
Default | |
|---|---|---|
order-cancellation-email-enabled |
true |
Send the email |
order-cancellation-email-subject |
Order #{0} has been cancelled |
{0} is the order number |
order-cancellation-email-template |
orderCancelled |
Template under email/ |
The From and BCC addresses are the same orderNotificationFrom* settings the dispatch email uses.
Where to find it¶
| Admin | Order view → Cancel Order (admins only) opens a confirmation showing what will be refunded or released and how much stock goes back, with a required reason and a restock checkbox. Manage Orders → Cancelled Orders lists them. |
| REST | POST /v1/admin/orders/{orderId}/cancel with {reason, restock, dryRun}. 409 if the order can't be cancelled or the provider refused (the order is unchanged). |
| MCP | manageCancellations (mcp:admin): reason and idempotencyKey are required, dryRun previews, and a refund is capped by mcp-refund-limit. Releasing an authorisation moves no money, so the limit doesn't apply to it. |
| Customer | The order page's Cancel order button, on a shop that allows it: see below. |
Customers cancelling their own order¶
With customer-cancellation-enabled on (off by default, under Settings → Orders and email → Customer returns and cancellations),
the order page (/o/{id}, reached from the order email or the account) has a Changed your mind? panel
(orderCustomerCancel, between the order summary and the returns panel). Cancel order opens a second
step that says what happens to the money ("We'll release the £42.10 hold on your card, so you won't be
charged", or the refund and how long it takes) before Yes, cancel my order. Afterwards the panel says
the order has been cancelled and what happened to the payment.
It's offered until the shop starts on the order (CustomerCancellationService):
- the order is SUBMITTED, placed online (not a till or dine-in sale, not a kitchen order) and has no subscription (which has its own cancel);
- no line is being packed or has been fulfilled. Digital lines are fulfilled as soon as they're paid for, so an order with a delivered ticket, gift card or donation isn't offered;
- nothing has been picked for collection and the collection hasn't been made ready;
- no shipping label has been bought;
- it was placed within
customer-cancellation-window-minutes(0, the default, means no limit); - the cancellation itself would be allowed (above).
Once the shop has started (the order is PACKING, or any of the above), the panel says so and suggests
getting in touch. The rules are checked again when the customer confirms, on the order as stored then,
so a fulfiller who starts the order in the meantime wins and the customer is told it can no longer be
cancelled here. Confirming first claims the order (customerCancellationClaimedAt in its properties, a
single conditional update while it is SUBMITTED), so a double-submit can't refund or restock twice; the
claim is given back if the cancellation doesn't go ahead and lapses after 15 minutes. A fulfiller who
starts the order during the refund itself (about a second) still isn't stopped: orders have no version,
so the last save wins, as it already does for an admin cancel. The same people
see it as see returns: the signed-in owner, or anyone with the confirmation code from the email.
It cancels as the admin does, with the reason "Cancelled by the customer": the hold released or the payment refunded, the stock put back, and the cancellation email sent if the site has it on.
Sites get the panel by applying the Customers cancel their own orders platform upgrade
(CustomerCancellationUpgrade), which adds it to their order page; new installs have it already.
Cancelling one part of a split order¶
An order that is partly collected and partly delivered (see
Partly collected, partly delivered) has two parts (OrderPart.COLLECTION and OrderPart.DELIVERY), and either can be cancelled on its
own while the other carries on: the drill nobody came for, or the pallet of screws the warehouse
can't send. OrderCancellationService.planPart(order, part, siteContext) works it out and
cancelPart(order, user, siteContext, part, reason, restock) does it. The plan is the same
CancellationPlan, with part and the lineIds it cancels.
A part can be cancelled when:
- the order is SUBMITTED or PACKING;
- none of the part's lines has been handed over or dispatched. A collection partly handed over, or a delivery partly dispatched, needs a return for what has gone;
- something else on the order is still open or has been fulfilled. If cancelling the part would leave nothing (the other part was cancelled already, and there is no donation or download), cancel the whole order instead;
- none of the part's lines is a subscription, gift card or donation, and the payment isn't held by a second card intent, as for a whole order. A donation elsewhere on the order doesn't block it, because it isn't in either part;
- the payment has been captured. A split order is captured when it is placed, whatever the site's capture point, so this holds for every new split order. One that is still only authorised (placed before that rule) is refused: Stripe captures a payment once and capturing less than was authorised isn't built, so there is no way to give back just this part before the money is taken. Cancel the part once the payment has been captured, or cancel the whole order.
The money. The part's value is its lines' discounted totals (a promotion's share is already in
each line's price), as a return values a line, plus the delivery charge after any delivery
discount for the delivery part. It is capped at what is left to refund on the order and refunded
through the site's refundOrder pipeline with that amount, so the payment becomes
PARTIAL_REFUND.
The cancelOrderPart pipeline (annotation-driven, so on every site with no config or system
update; the service has checked the plan, so it has no state-validation step). Its parameters are
part, amount, reason and restock:
refundCancelledPartProcessor: refundsamount. If the refund doesn't go through it stops witherrorand nothing is cancelled.setPartToCancelledProcessor: marks the part's open linesCANCELLEDand rolls the order up: it stays open while the other part is still to go, and becomes DISPATCHED if the other part is done. For the collection part,collectionDetails.statebecomesCANCELLED(withcancelledAt). The reason goes in the activity log (PART_CANCELLED COLLECTION: ...).restockCancelledPartProcessor: puts back exactly the part'sstockTakenentries (matched by theirlineItemId; an entry without one by SKU), each to the location it came from, and takes them off the record so a later whole-order cancel doesn't put them back twice. It gives back the part's capacity booking:CLICK_AND_COLLECTfor the collection,SHIP_FROM_STOREandSTORE_DELIVERYfor the delivery.sendPartCancellationEmailProcessor: theorderPartCancelledemail (below).
What each part cancellation did is kept in the order's cancelledParts property, keyed by part:
reason, paymentAction, paymentAmount, lineIds and cancelledAt.
The email. email/orderPartCancelled (HTML and text) lists only the cancelled items, says
whether and how much was refunded, and ends "The rest of your order isn't affected." Its text is
the orderNotificationEmail.partCancelled* keys (subject partCancelledSubject). It is sent only
when order-cancellation-email-enabled is on.
| Admin | On a split order, Cancel collection and Cancel delivery sit next to Cancel order (admins only, while that part has something open). Each opens the same kind of dialog: the items it cancels, what is refunded, how much stock goes back, a required reason and a restock checkbox, or why it can't be cancelled. |
| REST | POST /v1/admin/orders/{orderId}/cancel with part: COLLECTION or DELIVERY. dryRun previews; the response adds part and lineIds. 409 when the part can't be cancelled. |
| MCP | manageCancellations with part. The same dryRun, idempotencyKey (a key names one part of one order) and mcp-refund-limit rules apply. |
| Hold job | Cancels the uncollected part of a split order (see Collection handover). |
Cancelling some units of some lines¶
The same pipeline cancels any set of line quantities (OrderCancellationService.cancelLines), as
the till does when a picker can't find an item. It is
part cancellation generalised, not a separate path:
- Whole lines. A line carries one whole quantity, so cancelling 2 of a line of 5 first splits
the 2 off into a line of their own, with their share of every money figure on the line's price
(total, net, tax, fee, discount and each promotion's or manual discount's source), rounded
half-up for the split-off units, the rest staying on the original. The two lines add up to what
the one did, so the order's price still equals the sum of its lines, its tax is unchanged, and
everything that refunds, restocks, emails or reports goes on working in whole lines. The order's
stockTakenentries follow the units. If the money can't be moved the split is joined back. - The pipeline runs with
lines(the cancelled line ids) in place ofpart, and records the cancellation under the order'scancelledLinesproperty, keyed by its id. A part's capacity booking stays (the rest of the part still needs it) and the part email isn't sent: the caller tells the customer. The collection is marked cancelled only when nothing of it is left. - The money goes by the payment's state: a captured payment is refunded the units' discounted
value (
REFUND); an authorised one keeps its authorisation and is captured that much less (REDUCE_CAPTURE:PaymentDetails.releasedBeforeCaptureand each card intent'samountToRelease, which the Stripe capture passes asamount_to_capture; Stripe releases the rest). A gift card holds nothing until capture, so only card authorisations are reduced; a reduction they can't absorb is refused. Cash taken at the till is refunded as the till refunds cash (CASH_REFUND, recorded on the cash payments with aPOS_CASH_REFUNDactivity entry). - Nothing left. Cancelling every remaining unit is refused (
planLinessays to cancel the whole order instead), so the order is cancelled whole and never rolls up to dispatched. - A difference without a line.
planRefund/giveBackmove just an amount the same way (refund, release from the authorisation, or cash), with nothing cancelled: the till uses them for the difference when a cheaper substitute is picked in place of what was ordered.
Effect on the rest of the platform¶
OrderStates.CANCELLEDcounts as placed (isPlaced()), so a cancelled order can't be deleted, used as a basket or resubmitted (BasketAlreadySubmittedError.stateincludesCANCELLED).- The revenue, statistics, export and gift-aid queries list
SUBMITTED,PACKINGandDISPATCHEDexplicitly, so a cancelled order drops out of them. Figures already calculated for past periods aren't recalculated. - It also drops out of the admin's Active and All Orders lists and appears under Cancelled Orders. The customer still sees it in their order history, with the status "Your order has been cancelled".
Returns (RMA)¶
A return records items coming back from a DISPATCHED or DELIVERED order. Staff record returns in the admin, API or MCP; customers can ask for one from their order page (see Customer return requests). It moves through:
PENDING_APPROVAL ──approve──▶ REQUESTED ──receive──▶ RECEIVED ──refund──▶ REFUNDED
│ │ │
└──────────reject──────────┴─────────────────────┴──────▶ REJECTED
Staff-recorded returns start at REQUESTED. REFUNDED and REJECTED are final. An order that hasn't been dispatched yet should be cancelled instead.
Data¶
Returns live in their own orderReturns collection (OrderReturn), scoped by siteId (and
carrying catalogueId), with indexes on siteId + state + created, siteId + orderId and
siteId + number. Only ReturnServiceImpl touches OrderReturnRepository; everything else goes
through ReturnService, which takes the caller's SiteContext, so a return on another site is
reported as not found. The old, unused ReturnOrder class was removed.
| Field | |
|---|---|
number |
<orderNumber>-R<n>, e.g. 1001-R1 |
lines |
order line id, SKUs, quantity and amount (the line's share of its discounted price, pro rata by quantity) |
refundAmount |
sum of the line amounts: what a refund pays by default |
refundedAmount |
what was actually refunded |
restocked |
whether the units went back into stock on receipt |
reason / rejectionReason |
why it came back / why it was turned down (sent to the customer) |
source |
STAFF or CUSTOMER |
customerReason / customerComments |
the reason the customer picked (DOES_NOT_FIT, FAULTY_OR_DAMAGED, NOT_AS_DESCRIBED, WRONG_ITEM, CHANGED_MIND, OTHER) and what they wrote |
history |
every step, with who did it and an optional note |
Each step is also written to the order's activity log (RETURN_REQUESTED, RETURN_RECEIVED,
RETURN_REFUNDED, RETURN_REJECTED).
Rules¶
- Create: quantities per order line, each at most what was ordered less what earlier returns (other than rejected ones) already cover. Subscriptions, virtual gift cards, gift card top-ups, donations and event tickets can't be returned (a ticket is refunded, which voids it). A reason is required.
- Receive: optionally restocks each returned SKU (variant SKU where there is one) with
InventoryService.increaseStockat the location it was sent from: the order line'ssourceLocationCode, else the location the order'sstockTakenrecord gives for that SKU, else the default location (orders placed before locations existed). - Refund: only from RECEIVED. Runs the order's
refundOrderpipeline for the return's value, or a different amount (e.g. less for damaged goods). The amount can't exceed what's left to refund on the order, and the payment must be CAPTURED, PARTIAL_REFUND or PAID. An atomicrefundInProgressclaim on the return stops two refunds of the same return running at once. If the provider doesn't refund, the return stays RECEIVED. Once everything taken has been refunded,releasePromotionUsesProcessor(the last core step ofrefundOrder) gives back the order's promotion uses; a partial refund keeps them. - Reject: from REQUESTED or RECEIVED, with a reason that's sent to the customer. Rejected quantities become returnable again.
Emails¶
One template, email/orderReturnUpdate (HTML and text), switches on returnState. It's sent when
a return is requested, refunded or rejected, and lists the returned items and the amount.
Return labels. With parcel labels and shipping-return-labels-enabled on, approving a return
also buys a prepaid return label and emails it to the customer with a 30-day download link
(email/returnLabel); Send a return label on the return's page does the same for a return
accepted another way. See Parcel Labels.
Config key (order-return-emails) |
Default | |
|---|---|---|
order-return-emails-enabled |
true |
Send return emails |
order-return-email-subject |
Your return {1} for order #{0} |
{0} order number, {1} return number |
order-return-email-template |
orderReturnUpdate |
Template under email/ |
Where to find it¶
| Admin | Manage Orders → Returns lists returns with a state filter (customer requests are marked). A dispatched order's page has a Returns panel and a Create return form (quantity per line, reason). Each return has a page with its lines, history and the Mark as received (with restock), Refund (admins only) and Reject actions. Fulfillers can do everything except refund. |
| REST | GET/POST /v1/admin/returns, GET /v1/admin/returns/{returnId}, and POST .../receive, .../refund (with dryRun) and .../reject. Errors are 409 with a ReturnError message. |
| MCP | returns (mcp:read: list, get; the customer's name and email need mcp:write) and manageReturns (mcp:write: create, receive, reject; refund also needs mcp:admin, an idempotencyKey, respects mcp-refund-limit and supports dryRun). opsInbox counts returns to receive and to refund. |
Customer return requests¶
Customers can ask to return items from the order page (/o/{orderId}/{code}, reached from their
order emails, or from their account order history when logged in). It's off until a shop turns it
on.
Turning it on for a shop
- Apply the Customer return requests upgrade under Platform Upgrades. It adds the
orderReturnRequestextension to the order confirmation page, below the order summary. New installs have it already. - Set the site config (category
customer-returns):
| Key | Default | |
|---|---|---|
customer-returns-enabled |
false |
Show the "Return items" form |
customer-cancellation-enabled |
false |
Show Cancel order on the order page until the shop starts on the order |
customer-cancellation-window-minutes |
0 |
Only for this many minutes after the order is placed (0: until the shop starts) |
customer-return-window-days |
30 |
Days after dispatch a customer can ask; 0 for no limit |
customer-returns-require-approval |
true |
Requests wait for staff approval; when off they're accepted straight away |
customer-return-instructions |
empty | What to do once accepted, e.g. where to post the items; in the email and on the order page |
customer-return-staff-email |
none | Address to email when a customer asks |
What the customer sees. The orderReturnRequest extension checks the visitor may see the
order (the confirmation code from the link, or the logged-in owner; anyone else sees nothing). It
lists the order's returns and their progress, shows the return instructions once a return is
accepted, and, when the order is eligible, offers a "Return items" form: a quantity per line (up to
what's left to return), a reason and optional comments. The form uses a native <details>
element, so it works in every theme without Bootstrap JS. Posting it creates the return and
redirects back to the order page with ?returnRequested=<number>, so a refresh doesn't send it
twice. An order is eligible when customer returns are on, it's DISPATCHED or DELIVERED, it's within
the window (counted from the order's DISPATCHED status change, or its dispatch tracking, or failing
that its submission), and something is left to return. Otherwise the panel says the window has
closed or everything is already being returned.
What staff see.
- A
returnRequestedEventin the admin notifications feed, linking to the return. It holds no personal data. Turn it off withsupressedAdminNotifications. - An email to
customer-return-staff-email, if set (email/orderReturnRequestedStaff). - The return under Manage Orders → Returns, marked Customer, showing the reason and comments. Approve and send instructions moves it to REQUESTED and emails the customer the return instructions. Decline rejects it with a reason that's emailed to the customer.
opsInboxcounts returns to approve; MCPmanageReturns approve; RESTPOST /v1/admin/returns/{returnId}/approve.
Emails to the customer. The orderReturnUpdate template covers each step: request received
(PENDING_APPROVAL), accepted with the instructions (REQUESTED), refunded and declined.
Split orders¶
On an order partly collected and partly delivered, each part is returnable on its own, once it is done: all its lines finished and at least one handed over. The drill collected on Monday can come back while the screws are still waiting for a van, so such an order takes returns while it is still SUBMITTED or PACKING. Lines of a cancelled part were refunded when it was cancelled and are never returnable. A line in neither part (a download, say) is returnable once the whole order is dispatched, as on any order.
The customer's return window counts from when each part was done (the latest fulfilment update on its lines, else the order's dispatch), so the two parts can close on different days. Lines whose window has closed drop out of the form, and the deadline shown is the soonest one still open. Whole orders work exactly as before.
Not covered yet¶
- Customers can't cancel their own request; staff decline it.
- The request form isn't in the customer REST API, only on the storefront page.
- The delivery charge isn't included in a return's value; refund it by passing an
amount. - Revenue reports still count the original sale; the refund shows on the payment.
Pipeline validation¶
orderStateValidationProcessor and paymentStateValidationProcessor return validationFailed
when the order or payment is in the wrong state. The annotated pipeline executor stops on that
result, just as it does on error. So dispatching an order that isn't PACKING, or refunding a
payment that isn't captured, changes nothing and reports failure.
If a site has no validStates configured for a pipeline, the processors fall back to the
defaults in defaultProcessors.json: packOrder accepts SUBMITTED, dispatchOrder accepts
PACKING, cancelOrder accepts SUBMITTED or PACKING, and refunds accept PAID, CAPTURED or
PARTIAL_REFUND.