Return ( return )
Durable customer Return case: preserves what was requested, authorized, physically shipped, received, and inspected, then the final commercial resolution and objects created to apply it.
Role
A return concerns exactly one order and its buyer. It replaces neither the credit note, refund, nor process orchestrating handling. Its role is to preserve the Return business case and successive facts that must remain readable after process completion.
Accepting a Return does not yet mean a credit note was issued or a cash refund executed. These financial effects are separate objects linked to the Return when created.
Two axes not to confuse
| Axis | Field / facts | Question |
|---|---|---|
| Case lifecycle | status : open, resolved, cancelled | Is the case still active? |
| Commercial resolution | resolution_status : pending, accepted, partially_accepted, rejected, withdrawn | What share of the request does the merchant ultimately accept? |
| Physical facts | authorized, received, accepted quantities + timestamps | What actually happened to the goods? |
This separation allows, for example, a case to remain open while some lines have already been received, or to resolve a Return as partially_accepted when only part of inspected quantities is commercially accepted.
Operational lifecycle
The graph shows the typical operational journey. `authorized_at`, `shipped_at`, `received_at`, and `inspected_at` preserve physical milestones; commercial resolution occurs explicitly at the end.
The Return starts with requested lines and reasons. It may then be authorized, associated with a return shipment, recorded as received, and inspected. The process may omit a step only when its business journey allows it; it must not invent a physical fact that did not occur.
A different quantity at each stage
Each return_item may carry several quantities so case history is not overwritten:
| Quantity | Meaning | Step |
|---|---|---|
quantity_requested | Quantity requested by the buyer. | Return creation. |
quantity_authorized | Quantity authorized to be returned. | authorize_return |
quantity_received | Quantity physically received. | receive_return |
quantity_accepted | Quantity accepted after inspection. | inspect_return |
Nodes creating credit notes or finalizing the Return use a quantity_basis is explicit:
requested, authorized, received, or accepted. Ormuz verifies that the selected milestone actually exists and that no used quantity exceeds the quantity originally requested.
Once credit notes linked to the Return are created with a given basis, do not silently change basis for later credit notes. The Return → credit-note link preserves this convention to avoid inconsistent compensation.
Commercial resolution
finalize_return closes the case with a final resolution: accepted, partially_accepted,
rejected or withdrawn. The result must be consistent with quantities retained for the selected basis.
- accepted — the reference quantity is accepted in full.
- partially_accepted — only part of that quantity is accepted.
- rejected — no quantity is commercially accepted.
- withdrawn — the request is withdrawn without normal resolution.
resolution_detail may explain the outcome and related_objects explicitly links objects created to apply it: credit note, refund, replacement order, or supporting document.
Credit notes and refunds
create_return_credit_note_drafts turns selected quantities into credit-note proposals against source invoices. Credit notes remain separate invoicing objects.
If the sale had already been paid, a PSP or bank refund may then be created from credit notes and payments actually allocated. The Return must therefore not itself fabricate a cash movement: it exposes the commercial fact justifying the financial steps.
In a process
Core nodes cover the lifecycle without locking the journey into one UX:
create_return— opens the case and requested lines.collect_return_authorization+authorize_return— collects and persists authorization.record_return_shipment— records carrier, tracking, and optional label.collect_return_receipt+receive_return— records received quantities.collect_return_inspection+inspect_return— records physical acceptance and item condition.finalize_returnorcancel_return— completes the case.
Events
The lifecycle is observable through platform events:
return.created → return.authorized → return.shipped → return.received → return.inspected → return.resolved, with return.cancelled as an alternative ending.