RMA

yui/craft-rma adds Return Merchandise Authorization (RMA) handling to a store running yui/craft-plugin. It gives support agents a control panel workflow for tracking product returns and gives customers a self-service "My Returns" area on the storefront.

Use it when you need a native way to collect, triage, and resolve return requests without routing everything through email or a spreadsheet.

What it does

• Adds an RMA section to the Craft control panel with a dashboard, a searchable request queue, and a request creation form for support agents.
• Adds shop/account/my-returns and shop/account/my-returns/new to the storefront so logged-in customers can request and track returns themselves.
• Stores request workflow definitions (statuses, return reasons, resolutions) in the database, editable from plugin settings — no code changes needed to add a new status or reason.
• Lets customers and agents attach files (photos, proof of damage, invoices) to a request.
• Surfaces return history and a "start a return" shortcut directly on the Craft customer edit page.
• Exports the request queue to CSV/XLSX for offline reporting.
• Exposes MCP tools so an AI agent can list, inspect, search, and update RMA requests.

Where admins work with this plugin

In Craft CP, open the RMA section (rma) from the primary navigation. It has four areas:

1. Dashboard (rma) — request and workflow metrics.
2. Requests (rma/requests) — searchable, filterable list of all return requests.
3. New request (rma/requests/new) — create a return on behalf of a customer.
4. Settings (rma/settings) — workflow definitions and plugin configuration. See Settings.

See Release Notes for what changed in each version.

A License page is also available under the plugin's CP navigation, consistent with other YUI plugins.

How a return request flows

1. A customer submits a return from shop/account/my-returns/new, or an agent creates one from rma/requests/new.
2. The requester picks the order, selects which purchased items (and quantities) to return, chooses a reason, and optionally attaches files.
3. The plugin looks up already-returned quantities per SKU for that order (via rma/requests/order-items in the CP, or shop/account/my-returns/order-items on the storefront) so the same item can't be over-returned across multiple open requests.
4. The request is created with the workflow's default status (Received out of the box).
5. An agent opens the request detail page (rma/requests/<id>), updates status/reason/resolution, adds an internal or customer-facing message, and attaches more files as needed.
6. The customer sees the current status and message thread on their "My Returns" page.

Default workflow

The install migration seeds a starting workflow, all editable afterwards in Settings:

• Statuses: Received (default), Awaiting Package, Approved, Rejected, Completed — all customer-visible.
• Return reasons: Damaged item, Wrong item received, Missing parts or accessories, Not as described.
• Resolutions: Replacement, Refund, Store credit.

Customer profile integration

When yui/craft-plugin customer editing is active, the RMA plugin adds a Return Requests tab to the customer edit page. It lists that customer's existing RMA requests and lets an agent start a new one, pre-filled with the customer's recent orders, without leaving the customer screen.

Dashboard widget

The plugin registers an RMA stats dashboard widget (RmaStatsWidget) that admins can add to their Craft CP dashboard, showing the same request/workflow metrics as the RMA dashboard page.

Requirements

• Craft CMS 5 project.
• yui/craft-plugin version 2, for customer and order data (order lookups, item lists, customer session). Without it, order/customer lookups return empty results and the plugin degrades gracefully rather than erroring.
• Composer access to https://packages.yui.sk/.

Installation

composer config repositories.yui composer https://packages.yui.sk/
composer require yui/craft-rma
php craft plugin/install rma
php craft migrate/all

Migrations create rma_statuses, rma_reasons, rma_resolutions, and rma_requests, and seed the default workflow described above.

Security notes

• File uploads are stored outside the webroot (storage/rma-uploads/) and served only through an authenticated controller action that streams the file — there is no direct public URL to an uploaded file.
• Upload handling blocks executable/script extensions outright (php, phtml, js, svg, html, …) regardless of the configured allowlist, and cross-checks the actual file MIME type against the declared extension before accepting it.
• If no file extensions are configured in Settings → Attachments, uploads are blocked entirely (default-deny) rather than silently allowing everything.

Developer / API reference

MCP tools

When the yui/mcp plugin is installed, RMA registers these tools so an AI agent can work with return requests directly:

Tool	Permission	Purpose
rma_list_requests	read	List requests, optionally filtered by status and a keyword search across order number, customer name/email, status, and reason. Supports limit (default 50).
rma_get_request	read	Get full detail for one request by id: items, message thread, attachments, order/customer CP links.
rma_get_stats	read	Aggregate dashboard data: totals, status/reason/resolution breakdowns, 30-day daily trend, top returned items.
rma_search_by_email	read	Find all requests for a given customer email — used for support lookups.
rma_update_status	write	Update status, reason, and/or resolution on a request by id, optionally appending an internal message.

Notable services (Yui\Rma\services)

• RmaService — CRUD and hydration for requests, dashboard aggregation (getDashboardData()), attachment upload handling, order-item mapping via yui\craft.
• DefinitionService — CRUD for the status/reason/resolution definition tables, including lookup maps and the default-status resolver used when a new request is created.

Routes

Control panel (rma/*): rma (dashboard), rma/requests, rma/requests/new, rma/requests/<id>, rma/requests/<id>/update, rma/requests/export, rma/settings, rma/license.

Storefront (registered only while the plugin is enabled): shop/account/my-returns, shop/account/my-returns/new, shop/account/my-returns/save, shop/account/my-returns/order-items.

Extending

The plugin registers its Twig template root as rma, so shop/account/my-returns and related templates can be overridden from a project's own templates/ directory the same way as any other Craft plugin templates.