---
title: "Returns / RMA Module"
module_id: "returns"
version: "1.0.0"
category: "data"
autonomy: "view-required"
generated: true
generated_at: "2026-05-04"
---

# Returns / RMA

> Return-merchandise-authorization flow with line-item tracking, approval, restock-on-receive, and refund processing. Customers see their own returns; staff manages all.

Ships with **5 agent skills**, an **admin UI**.

## Quick Facts

| Property | Value |
|----------|-------|
| **Module ID** | `returns` |
| **Version** | 1.0.0 |
| **Category** | data |
| **Autonomy** | view-required |
| **Core** | No |
| **Capabilities** | `data:read`, `data:write` |
| **MCP-exposed skills** | 5 |
| **Owns tables** | — |

## Skills

These skills are seeded into `agent_skills` when the module is enabled and exposed via MCP.
External operators (FlowPilot, OpenClaw, Claude Desktop, custom MCP clients) can call them directly.

| Skill | Scope | Description |
|-------|-------|-------------|
| `create_return` | internal | Create a new return (RMA) for an order. Use when: customer or support agent requests a return/refund. NOT for: approving (use approve_return) or processing the refund (use refund_return). |
| `manage_return_item` | internal | Add/edit/remove line items on an existing return. Use when: specifying which order items are being returned and in what condition. |
| `approve_return` | internal | Approve a requested return so the customer can ship it back. Use when: support/admin signs off on the RMA. NOT for: actually receiving goods (use receive_return). |
| `receive_return` | internal | Mark an approved return as received. Auto-emits stock.movement event for items flagged restock=true. Use when: warehouse confirms the package arrived. |
| `refund_return` | internal | Process the refund for a received return. Use when: payment is being returned to the customer (Stripe, manual, or store-credit). |

## Module API Contract

**Actions:** `create`, `approve`, `receive`, `refund`, `list`, `get`

**Input fields:** `action`, `return_id`, `order_id`, `reason`, `refund_cents`, `refund_method`, `notes`

## File Map

| Purpose | Path |
|---------|------|
| Module definition | `src/lib/modules/returns-module.ts` |
| Admin page | `src/pages/admin/ReturnsPage.tsx` |

## Contributing

To enhance this module, see [Contributing Guide](../contributing/contributing.md).

Key rules:
- Follow `ModuleDefinition<I, O>` contract pattern
- All schema changes require idempotent migrations
- Skills must be self-describing ([Law 2](../concepts/openclaw-law.md))
- Blocks are interfaces, not pipelines ([Law 3](../concepts/openclaw-law.md))
- New skills must pass the [Agent Contract Integrity](../architecture/agent-contract-integrity.md) checklist (`bun run lint:skills`)

---

*This file is auto-generated by `scripts/generate-module-docs.ts`. Do not edit manually — re-run the script after changing the module definition.*