Return to origin

Trigger. In-process shipment.status.changed. Listener: ReturnShipmentListener.

This listener runs in the process that emitted the shipment event. Webhook and tracking processors run on the worker. An emit that stayed on the API would not reach a worker-only listener. See Shipment tracking.

Forward RTO

createFromForwardRto looks for an existing RTO return on that shipment.

• If one exists and the target rank is higher, it updates with force: true.
• If none exists, it builds lines from shipment items, capped by quantityOrdered - quantityReturned, and calls create with allowInternalRto.
• A unique conflict P2002 loads the winning row instead of failing.
• Target status is RETURN_RECEIVED when the shipment status is RETURN_DELIVERED or DELIVERED. Otherwise it is RETURN_SHIPPED.

Rank order used to decide whether to advance: REQUESTED, APPROVED, RETURN_LABEL_CREATED, RETURN_SHIPPED, RETURN_RECEIVED, INSPECTING, COMPLETED. A target that is not higher is left alone.

force: true skips isValidReturnTransition. The public return API cannot send type: RTO.

Errors from createFromForwardRto are logged. The listener does not rethrow. A failed RTO open does not fail the shipment status write that already happened. Nothing in this listener retries it.

Return shipments

If shipment.isReturn, linked ReturnRequest rows are updated with force: true:

Shipment status	Return status
RETURN_DELIVERED or DELIVERED	RETURN_RECEIVED
RETURN_IN_TRANSIT or IN_TRANSIT	RETURN_SHIPPED
LABEL_CREATED	RETURN_LABEL_CREATED
CANCELLED	CANCELLED

Other shipment statuses do not change the return. A per-return failure is logged and the loop continues.