ormuz
Business guides/Customer return

Handle a customer return

Open a Return case from an order, keep logistics facts and commercial decision separate, then explicitly create required credit notes and refunds before closing the case.

Business objective

The return is the durable Return case. It preserves what was requested, authorized, shipped, received, and inspected. The process decides how to obtain these facts and which commercial resolution to apply.

Return ≠ credit note ≠ refund

The Return case explains why a commercial correction is needed. A credit note corrects invoicing; a refund reverses a financial movement. These effects remain separate objects and steps.

Prerequisites

ElementRole
Source orderThe Return belongs to an existing order; its lines bound the items and quantities that can be returned.
Launcher returnAssociates the case with a process definition accepting an input platform.return named return.
Return policyDetermines what can be authorized, inspection checks, and the expected commercial resolution.
Financial contextActual order invoices and payments are required when the journey must produce a credit note or refund.

A return_url is useful only when the process exposes user actions in a User Journey. A journey operated entirely by your systems or teams can remain server-side.

Open the return

You can open the case from your backend with POST /v1/returns, or from a parent process with the Core node create_return. In both cases Ormuz creates the return then starts its owning process. The merchant is derived from the order: it is not a Return-creation parameter.

HTTP
POST /v1/returns
{5 items
"order_id":"ord_0123456789abcdef0123456789abcdef"
"reference":"RET-2026-0042"
"source_reference":"RMA-8472"
"return_url":"https://shop.example/orders/42/return"
"items":[1 item
0:{...}3 items
]
}
{
"order_id": "ord_0123456789abcdef0123456789abcdef",
"reference": "RET-2026-0042",
"source_reference": "RMA-8472",
"return_url": "https://shop.example/orders/42/return",
"items": [
  {
    "line_item_id": "li_0123456789abcdef0123456789abcdef",
    "quantity_requested": 2,
    "reason": "defective"
  }
]
}

While no authorization, shipment, receipt, or credit-note creation has frozen the case, the request may still be corrected without replacing existing lines. Once the journey is underway, treat changes as new facts rather than rewriting the past.

Return journey

StartOpen return
Autoriser
Ship
Recevoir
Inspecter
Resolve

Typical journey: logistics milestones are distinct facts; commercial resolution occurs explicitly after the necessary observations.

Authorize quantities

authorize_return sets the quantities genuinely eligible for return. Authorization is neither shipment nor final acceptance.

Observe physical movement

record_return_shipment records shipment; receive_return records quantities actually received. Do not synthesize these facts when your logistics operation did not observe them.

Inspecter

inspect_return qualifies received items and sets accepted quantities. An accepted quantity cannot exceed the received quantity.

Resolve

The final resolution expresses the commercial outcome: accepted, partially accepted, rejected, or withdrawn. It must be consistent with the selected quantity basis.

Human interactions : collecter puis appliquer

When authorization, receipt, or inspection is entered by an operator, use the dedicated user actions: collect_return_authorization, collect_return_receipt and collect_return_inspection. They produce a structured response but do not by themselves modify the case.

Always follow collection with the corresponding business node — authorize_return, receive_return or inspect_return — so the canonical fact is validated and persisted. This separation avoids confusing user input with a successful business transition.

Credit notes and refunds

When the resolution must correct invoicing, create_return_credit_note_drafts creates persisted credit notes in status draft from an explicit quantity basis: requested, authorized, received, or accepted. Once a basis is used for Return credit notes, keep the same convention for subsequent corrections.

A credit note does not return funds. If the sale has already been settled, then create refund intents from the credit notes and payments actually allocated: create_credit_note_psp_refunds for PSP payments or create_credit_note_payment_refunds for non-PSP receipts. External refund execution remains a separate step.

Do not close on an intent

A credit note in draft or a refund intent does not prove that a document was issued or funds were returned. When these objects explain the resolution, create and explicitly link them before finalizing the Return.

Resolve or cancel

finalize_return closes an open case open with an explicit resolution and may attach already-created objects explaining the outcome. For a resolution based on accepted quantities, inspection generally provides the quantity basis most faithful to the physical fact.

cancel_return is reserved for administrative abandonment of an open case before shipment or receipt. If the customer withdraws the request without physical movement, a resolution withdrawn may also be used while the Return has not been shipped or received. Do not use cancellation to erase an already-handled Return or already-produced financial effects.

Events and tracking

EventUsage
return.createdThe case is created and its owning process starts.
return.authorizedAuthorized quantities have been recorded.
return.shippedReturn shipment is observed for the first time.
return.receivedPhysically received quantities have been recorded.
return.inspectedInspection and accepted quantities have been recorded.
return.resolvedThe case is closed with an explicit commercial resolution.
return.cancelledThe case is canceled before normal resolution.

Use these events to synchronize systems around the case, but reread the return resource when your decision depends on current quantities or linked objects. Events describe milestones; the resource remains the complete case reference.

Implementation checklist

  • Configure a launcher return whose process accepts platform.return.
  • Open the Return from an existing order and reserve only quantities that can genuinely be returned.
  • Separate authorization, shipment, receipt, inspection, and resolution.
  • Use user actions only to collect facts requiring human input.
  • Choose an explicit quantity basis for credit notes and preserve it.
  • Create credit notes and refunds as effects separate from the Return case.
  • Treat a refund as executed only after confirmation in its own financial lifecycle.
  • Finalize the Return with a coherent resolution and linked objects useful for audit.