Order Return

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

OrderReturn is the operational return aggregate that groups returned fulfillment-request items, return fees, return shipping lines, transfer routing, confirmation and approval state, and completion or refund context.

Parent hierarchy:

• Order Lifecycle
• Return Processing
• Order Return

Primary implementation paths:

• packages/framework/src/Models/OrderReturn.php
• packages/framework/src/Http/Controllers/Api/Admin/OrderReturnsController.php
• packages/framework/src/Actions/OrderReturn
• packages/framework/src/Actions/OrderReturn/Requests/Admin

What Users Can Do With It

Direct capabilities

Operators can:

• create, show, update, and delete order returns
• attach return items from fulfillment-request items
• attach return shipping lines
• manage transfer locations and transport details
• send the return to supplier
• confirm items
• approve items
• complete the return
• send drop-off details
• download the return PDF
• review linked payments and activity logs

Indirect capabilities

Other workflows use OrderReturn to:

• revise order amount due
• drive refund calculations
• generate return PDFs and communications
• log sale activities for returned items, fees, and shipping lines

Things users cannot do directly

This pass did not find a packaged Livewire return-management page in packages/admin. The shared package defines a rich admin API and return lifecycle, but the exact operator screen can be host-app specific.

Where It Is Managed

Channel	Role	Notes
Admin API	Direct	Main CRUD and lifecycle surface
Host-specific operations UI	Direct or parent-owned	Expected consumer of the return API
Payments and refunds	Indirect	Return completion and refunds are related but not identical
Storefront	Indirect	No packaged shopper return-management UI found in this pass

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/OrderReturnsController.php
• packages/framework/src/Actions/OrderReturn/Requests/Admin/Index.php
• packages/framework/src/Actions/OrderReturn/Requests/Admin/Show.php

Channel-Level Field Coverage

Create flow

Creating an order return requires:

• order_id
• fulfillment_request_id
• customer_id
• current_location_id
• product_inventory_location_id
• type
• optional internal_reason
• fulfillment_request_items
• optional fulfillment_request_confirmation_number
• optional order_shipping_line_id

Sources:

• packages/framework/src/Actions/OrderReturn/CreateOrderReturn.php

Update flow

The update action supports:

• location and transfer fields
• notes
• shipping carrier, method, and type details
• tracking numbers
• shipping-booked and delivered-at-location toggles
• revise_order_amount_due
• additional fulfillment-request items to return

Source:

• packages/framework/src/Actions/OrderReturn/UpdateOrderReturn.php

Confirm, approve, and complete

The lifecycle actions require:

• required shipping and restocking fees before confirm, approve, or complete
• confirmation numbers
• item-level confirmed and approved quantities

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/OrderReturnsController.php
• packages/framework/src/Actions/OrderReturn/ConfirmOrderReturnItems.php
• packages/framework/src/Actions/OrderReturn/ApproveOrderReturnItems.php
• packages/framework/src/Actions/OrderReturn/CompleteOrderReturn.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• UUID-based
• searchable
• action-request aware
• flag-aware

Important relationships:

• order()
• fulfillmentRequest()
• productInventoryLocation()
• currentLocation()
• transferLocations()
• orderReturnItems()
• feeLines()
• shippingLines()
• orderPayments()
• orderRefunds()

Source:

• packages/framework/src/Models/OrderReturn.php

Relationships

OrderReturn directly connects:

• order recovery
• returned fulfillment-request items
• return-specific fees and shipping
• payment/refund context
• supplier and customer communications

Practical dependents:

• refund workflows
• operational return handling
• order amount-due recalculation
• customer and supplier communication

Rules And Downstream Effects

Quantity validation

The create and update flows block returning more quantity than a fulfillment-request item still has left to return.

Sources:

• packages/framework/src/Actions/OrderReturn/CreateOrderReturn.php
• packages/framework/src/Actions/OrderReturn/UpdateOrderReturn.php

Fee requirement

Returns must have both:

• a shipping fee
• a restocking fee

before confirm, approve, or complete can proceed.

Sources:

• packages/framework/src/Models/OrderReturn.php
• packages/framework/src/Http/Controllers/Api/Admin/OrderReturnsController.php

Quantity-stage math

Refundable item amounts change with the lifecycle stage:

• before confirmation, amount is based on requested quantity
• after confirmation, amount is based on confirmed quantity
• after approval, amount is based on approved quantity

Source:

• packages/framework/src/Models/OrderReturnItem.php

Order recalculation

If revise_order_amount_due is enabled or changed, updating the return recalculates the parent order.

Source:

• packages/framework/src/Actions/OrderReturn/UpdateOrderReturn.php

Completion side effects

Completing a return:

• stamps completed_at
• saves the confirmation number
• logs sale activities for return items, fee lines, and shipping lines
• dispatches OrderReturnCompleted

Source:

• packages/framework/src/Actions/OrderReturn/CompleteOrderReturn.php

Integrations And Automation

Supplier and customer email

Order returns can:

• send supplier return emails
• send customer drop-off details
• send confirmation email when the feature is enabled
• attach return PDFs to communication workflows

Sources:

• packages/framework/src/Actions/OrderReturn/SendOrderReturn.php
• packages/framework/src/Actions/OrderReturn/SendDropOffDetails.php
• packages/framework/src/Actions/OrderReturn/ConfirmOrderReturnItems.php

Payment and refund context

The return surface exposes linked payments, while refund execution remains an adjacent financial workflow.

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/OrderReturnsController.php
• packages/framework/src/Models/OrderReturn.php

Where It Appears To End Users

OrderReturn is primarily an operator-facing concept.

The shared package shows it through API resources, email outputs, and related operational actions. Shoppers do not get a packaged self-serve return portal in the inspected storefront routes.

Current Documentation Takeaways

1. OrderReturn is a first-class recovery workflow, not just a refund note.
2. The shared package defines a strong return lifecycle, but not a packaged admin return screen.
3. Fee requirements, quantity-left-to-return checks, and lifecycle-stage math are central to whether the workflow can move forward cleanly.
4. Customer communication exists, but it is email-driven rather than storefront self-service in the shared package.

Open Questions

• This first pass did not inspect host-specific return UI layers that may consume the shared return API in downstream applications.