Returns
Overview
Return requests, lines, and policies. Completion can restore stock and emit inventory sync.
Code map
| Piece | Path |
|---|---|
| Feature | src/modules/commerce/return |
| State machine | return-state-machine.ts |
| Shipment listener | return-shipment.listener.ts |
| Schema | 44-return.prisma |
Entities: ReturnRequest, ReturnLineItem, ReturnPolicy.
State machine
Null from allows any target, the same helper pattern as orders.
| From | To |
|---|---|
REQUESTED | APPROVED, REJECTED, CANCELLED |
APPROVED | RETURN_LABEL_CREATED, RETURN_SHIPPED, RETURN_RECEIVED, CANCELLED |
RETURN_LABEL_CREATED | RETURN_SHIPPED, CANCELLED |
RETURN_SHIPPED | RETURN_RECEIVED, CANCELLED |
RETURN_RECEIVED | INSPECTING, COMPLETED, REJECTED |
INSPECTING | COMPLETED, REJECTED |
COMPLETED, REJECTED, CANCELLED | none |
Events
| Name | Kind | Consumer |
|---|---|---|
return.status.changed | in-process | none found |
return.stock.restored | in-process | none found |
order.status.changed | outbox | produced by return command |
stock.sync.requested | outbox | inventory publish |
return.status.changed and return.stock.restored have no @OnEvent listener in the scan. Do not depend on them for a side effect.
Business rules
Unknown: whether restock on COMPLETED is mandatory or depends on ReturnItemGrade.
Order-level return statuses (RETURN_REQUESTED, RETURN_RECEIVED, and the rest) are the order state machine, not this one. Both can move in one flow. See Order state machine.
Workflows
API surface
POST /v1/commerce/returns requires RETURN:CREATE. PUT /v1/commerce/returns/:id requires RETURN:UPDATE. RTO type is rejected on the public create unless createFromForwardRto calls it with the internal flag. Return-policy controllers are separate.