Skip to main content
Version: 2.0.0

Settings

This page explains every RMA setting and where to find it. Open settings in Craft CP:

RMA -> Settings (rma/settings).

Settings are split into four tabs: General, Workflow, Attachments, Notifications.

General tab​

  • Enable RMA: turns the plugin on. When off, the storefront routes (shop/account/my-returns*) are not registered and the customer-facing "My Returns" nav link disappears — the control panel section stays available either way.
  • Allow guest requests: intended to permit return requests from customers without an account. At present the storefront controller requires an active YUI Craft customer session for both viewing and submitting returns, so treat this switch as forward-looking configuration rather than an already-wired guest checkout path.
  • Return policy: free text describing eligibility rules, timelines, and packaging requirements. Not rendered automatically anywhere by default — wire it into your own storefront template if you want to display it to customers.
  • Customer instructions: free text describing the step-by-step process after a request is submitted. Same as above: available as data, not auto-rendered.

Workflow tab​

Three editable tables define the request lifecycle. Changes take effect immediately across the CP and storefront — no redeploy needed, since definitions are stored in the rma_statuses, rma_reasons, and rma_resolutions tables.

Request statuses​

Columns: Label, Code, Default (lightswitch), Visible to customer (lightswitch).

  • Exactly one status should be marked Default — it's assigned to every new request (CP-created or customer-submitted). If none is marked, the plugin falls back to the first status in sort order.
  • Visible to customer controls whether that status label is shown on the customer's "My Returns" page rather than hidden as an internal-only stage.
  • Code is normalized to kebab-case on save (for example Awaiting Package → awaiting-package).

Default seed: Received (default), Awaiting Package, Approved, Rejected, Completed.

Return reasons​

Columns: Label, Code. Presets a customer or agent chooses from when creating a request.

Default seed: Damaged item, Wrong item received, Missing parts or accessories, Not as described.

Resolutions​

Columns: Label, Code. The outcome offered once a request is approved.

Default seed: Replacement, Refund, Store credit.

::: tip Saving any of the three tables replaces the entire table content (delete + re-insert in one transaction). Don't remove a row that's still referenced by existing requests unless you're fine with that request showing the raw code instead of a label — the request itself is not migrated to a new code. :::

Attachments tab​

  • Allow attachments: lets customers and agents upload files (photos, invoices, proof of damage) with a request. When off, the upload field is skipped everywhere the request form is rendered.
  • Attachment limit: maximum files per request, 1–10.
  • Allowed file types: table of accepted extensions (extension column). Default seed: jpg, jpeg, png, pdf.

If this table is left empty, uploads are blocked entirely (default-deny), even though the Allow attachments switch is on. This is intentional — see Security notes.

Regardless of what's configured here, these extensions are always rejected: php, php3–php8, phtml, phar, shtml, cgi, pl, py, rb, sh, bash, htaccess, htpasswd, exe, bat, cmd, com, js, jsx, ts, tsx, html, htm, svg, xml, xsl, xslt. Accepted files are also checked against a MIME-type allowlist per extension; a mismatch (for example a .pdf that isn't actually PDF) is rejected.

Notifications tab​

  • Staff notification email: the address that should be notified when a new return request comes in.

This field only stores the address — the plugin does not send an email itself. Wire an actual notification (Craft system message, queue job, automation) to this setting in your project if you need one; the settings page notes this explicitly ("Wire Craft email templates or automations here").

Validation and save behavior​

  • Attachment limit must be between 1 and 10.
  • Staff notification email must be a valid email address if set.
  • Saving redirects back to rma/settings and shows a Craft success/error notice as usual.
  1. Review the seeded statuses/reasons/resolutions in the Workflow tab and adjust labels/codes to match your actual return process before going live.
  2. Decide whether attachments are required for your process; if so, confirm Allowed file types covers what customers will realistically upload (photos, PDFs).
  3. Set Staff notification email and connect it to an actual notification mechanism if your team needs a push alert per request.
  4. Fill in Return policy and Customer instructions if your storefront theme surfaces them.
  5. Create one test request from the storefront and one from the CP (rma/requests/new) to confirm the flow end-to-end before customers see it.

Troubleshooting​

New requests all get the wrong status​

Check the Workflow tab — confirm exactly one status row has Default switched on.

Uploads are silently rejected​

  1. Confirm Allow attachments is on and Allowed file types is not empty.
  2. Confirm the uploaded file's extension is in the allowlist and isn't one of the permanently blocked extensions.
  3. Confirm the file's actual content matches its extension (a renamed file will fail the MIME check).

A request shows a raw code instead of a status/reason/resolution label​

The definition row for that code was deleted from the Workflow tab after the request was created. Re-add a row with the same Code to restore the label, or update the request's status/reason/resolution to a currently defined code.