Returns & RMAs
List Return Reasons
List all return reasons using the standard list interface. Supports filtering, sorting, search and pagination.
List RMAs
List all RMAs with pagination, filtering, and sorting via Spatie QueryBuilder.
Create RMA
Create a new RMA for a fulfilled sales order.
Get RMA
Get a single RMA with full detail including lines, return receipts, sales credits, and approved-by user.
Update RMA
Update an RMA's warehouse and/or notes.
Delete RMA
Delete an RMA. Only draft RMAs can typically be deleted. Returns 422 if the RMA cannot be deleted.
Approve RMA
Approve a draft RMA. Records the approving user and approval timestamp.
Cancel RMA
Cancel an RMA and keep it on record (the RMA is not deleted). Only RMAs in a cancellable status (draft, approved, in_transit) with zero return receipts can be canceled — `can_be_canceled` on the resource reflects this.
Close RMA
Close an approved or received RMA.
Reopen RMA
Reopen a closed RMA.
Uncancel RMA
Restore a canceled RMA back to draft status.
Revert to Draft
Revert an approved RMA back to draft status. Clears approved_at and approved_by_user_id.
Mark as Shipped
Mark an RMA as shipped by the customer.
Update Shipping Details
Update shipping details for an RMA. Automatically transitions status based on whether shipping info is added or removed:
Clear Shipping Details
Clear all shipping information from an RMA. If no receipts exist and the RMA is in IN_TRANSIT, it transitions back to APPROVED.
Add Line to RMA
Add a new line to an existing RMA. Cannot add lines to terminal (closed/canceled) RMAs.
Update RMA Line
Update an RMA line. Cannot update lines on closed or canceled RMAs.
Remove Line from RMA
Remove a line from an RMA. Returns 422 if the RMA is in a terminal state or if the line doesn't belong to the RMA.
Create Return Receipt from RMA
Record a return receipt against an RMA (items physically received at the warehouse).
Bulk Approve RMAs
Bulk approve multiple RMAs. Returns success and failed counts.
Bulk Cancel RMAs
Bulk cancel multiple RMAs.
Bulk Close RMAs
Bulk close multiple RMAs.
Bulk Delete RMAs
Bulk delete multiple RMAs.
Bulk Revert RMAs to Draft
Bulk revert approved RMAs back to draft status.
Bulk Generate RMAs from Orders
Dispatch a tracked background job that creates one RMA per selected (or all-matching) sales order, from each order's fulfilled, not-already-RMA'd lines. Returns a tracked_job_log_id immediately; progress shows via the tracked job log endpoints.
Get RMA Activity Log
Get the activity log for an RMA — every recorded change on the RMA itself, its lines, and its return receipts, newest first.
List RMA Inventory Movements
List the inventory movements created by an RMA's return receipts — the stock re-entering inventory as returned units are received.
List RMA FIFO Layers
List the inventory cost layers created by receiving this RMA's returned stock. Each layer records the received quantity, its unit cost, remaining availability, and lot details (batch number, expiry) when the product is lot-tracked.
List Return Receipts
List all return receipts with pagination. Supports filtering by RMA, warehouse, blind receipts (no RMA), and search by ID or RMA number.
Create Return Receipt
Create a new return receipt (blind or RMA-linked). Adjusts inventory based on each line's action.
Get Return Receipt
Get a single return receipt with full detail, including RMA and sales order, warehouse, received-by user, and all receipt lines with products, original products, RMA lines, and return reasons.
Delete Return Receipt
Delete a return receipt and all its lines. Reverses inventory adjustments.
Add Line to Return Receipt
Add a new line to an existing return receipt. Creates an inventory movement for the specified action.
Update Return Receipt Line
Update non-inventory-impacting fields on a return receipt line. Only notes and return_reason_id can be changed after creation. Fields that affect inventory (quantity, action, product_id) cannot be updated — delete and recreate the line to correct those.
Remove Line from Return Receipt
Remove a specific line from a return receipt. Reverses the inventory adjustment for that line. The line must belong to the specified return receipt.
Delete Return Receipt Line (standalone)
Delete a return receipt line directly by its ID (without specifying the parent receipt). If this is the last line on the return receipt, the entire return receipt is deleted automatically.
Bulk Set Disposition on Lines
Set the disposition (action + optional condition grade) on multiple lines of a return receipt at once. When a line's action changes, its prior inventory effect is reversed and the new action is re-applied so inventory stays consistent.
Resolve Scan
Resolve a scanned token for the Receive Returns Station. Resolution order: open RMA by number → open RMA by tracking number → sales order by number → product by SKU/barcode. Returns the match type plus staged lines whose dispositions are defaulted by the active return disposition policies (the matching policy id is included so the UI can show a 'policy applied' badge). Closed/canceled RMAs are excluded and fall through to 'none'.
Resolve Line Disposition
Re-resolve the policy-defaulted disposition for a single staged line once more criteria are known (e.g. after the operator selects a condition grade), so grade-specific disposition policies apply at the Receive Station.
Get Session Summary
Aggregate the return receipts the current authenticated user has committed since a timestamp, powering the station's running 'this session' totals (receipts, units, and units by disposition).
Preview Return Receipt Delete Impact
Read-only preview of the allocation-demotion impact of deleting this return receipt. Because deleting it removes the stock it added, this behaves like a manual negative adjustment and returns one row per affected product: how much of the removed quantity is unallocated vs soft-allocated vs hard-allocated, plus every sales-order allocation and fulfillment (printed shipping label) the removal would disturb. Use it to decide which fulfillments to authorize voiding via `void_confirmations` on the deleting call. Nothing is mutated. A removal that only re-adds stock returns an empty `data` array.
Preview Return Receipt Release Impact
Read-only preview of which back-ordered sales orders this return receipt would release, per restock-to-sellable line. Send the same payload you would POST to create the receipt; each line that restocks sellable stock is resolved to its product and the receive warehouse and evaluated against waiting back-ordered demand. Nothing is written.
List Return Reasons
List all return reasons with standard list query parameters. Supports filtering, sorting, search and pagination.
Create Return Reason
Create a new return reason.
Bulk Delete Return Reasons
Bulk delete multiple return reasons by ID.
Get Return Reason
Retrieve a single return reason by ID.
Update Return Reason
Update an existing return reason.
Delete Return Reason
Delete a return reason. Will fail if reason is linked to existing return receipt lines.
Check Return Reasons Deletable
Check which return reasons can be safely deleted. Returns deletability status per ID.
Archive Return Reason
Archive a single return reason.
Unarchive Return Reason
Unarchive a single return reason.
Bulk Archive Return Reasons
Bulk archive multiple return reasons.
Bulk Unarchive Return Reasons
Bulk unarchive multiple return reasons.
List Disposition Policies
List all return disposition policies, ordered by precedence (priority ascending, then id ascending).
Create Disposition Policy
Create a new return disposition policy.
Get Disposition Policy
Get a single disposition policy with its matched product, category, return reason, and warehouse summaries.
Update Disposition Policy
Update an existing disposition policy. Send the full set of fields (same shape as create).
Delete Disposition Policy
Delete a disposition policy. Already-received receipt lines retain their assigned disposition; only future return-receiving evaluation is affected.
Reorder Disposition Policies
Persist a new precedence order for the disposition policies. The position of each id in the ordered_ids array becomes its priority (first = priority 0, evaluated first).
Get Returns Summary KPIs
KPI summary: return rate, returned/shipped units, RMA count, restock recovery rate, recovered COGS value, discard rate, and average days to disposition.
Get Returns by Reason
Counts and units grouped by return reason, ordered by units desc.
Get Returns by Disposition
Units grouped by disposition action (added_to_stock / discarded / new_blemished_sku).
Get Top Returned Products
Top returned products by units (limit 20).
Get Returns Trend
Returns over time, grouped by week (Monday-start) or month.
List Returns Inbox
Paginated, enriched marketplace returns across channels. Each row has link status (an RMA already linked via external_source/external_return_id) and, when unlinked, a suggested order match.
Bulk Link Returns
Link the selected marketplace returns to RMAs (creating/linking per the match service; idempotent and conflict-safe).
Match Returns Now
Dispatch the tracked auto-match job for unlinked marketplace returns (optionally scoped to a source / integration). Returns a tracked_job_log_id; progress shows via the tracked job log endpoints. Job name: 'Match Marketplace Returns'.
List Unmatched Returns
Paginated list of received returns that are not yet linked to a return authorization (RMA) — returns received without a matching authorization, plus ambiguous matches flagged for review. Use it to reconcile or write off aged, unmatched returns. Filter by warehouse, reconciliation status, aging, received date, or product, and search by SKU/name.
List Recently Received Returns
Returns committed in a warehouse within the given window (today, or the last 7 days), across all operators — for confirming what has been received. Read-only.
Link Return Receipt to RMA
Link an unmatched return receipt to a return authorization (RMA), recording its received quantity without adding inventory a second time (the goods were already received). Provide exactly one of rma_id or sales_order_id; with sales_order_id the single open, unreceived RMA on that order is used. Fails with 422 if the target RMA is already received (which would double-count) or the order has zero/multiple open RMAs.