Returns & RMA

Let customers and guests request returns from their orders, and handle every return in the Magento admin: approve, receive, refund or close, with a conversation, a status history and emails at every step. This guide covers installation, configuration and day-to-day use.

• Demo, guest returns (Luma): https://demo.softawarecommerce.com/returns/guest/
• Demo, guest returns (Hyvä): https://demo.softawarecommerce.com/hyva/returns/guest/
• Admin demo: https://demo.softawarecommerce.com/try-admin/returns
• Changelog: Release notes · Questions: FAQ

1. Requirements

The return pages do not touch the checkout. On Adobe Commerce, which has its own returns feature, use one of the two workflows so customers see one way to return items.

2. Installation

With Composer. Use the Composer keys from your account on softawarecommerce.com (see https://softawarecommerce.com/shop/composer-access/):

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-returns
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

On Hyvä, the module's templates are picked automatically and the module registers itself for Tailwind source scanning. Run your usual Hyvä CSS build after installing so the return pages are styled.

To update later: composer update softaware/module-returns, then the same bin/magento commands.

3. Quick start

1. Open Stores > Configuration > Softaware > Returns & RMA (also Softaware > Returns & RMA > Settings).
2. General > Enabled is Yes by default. Check Return Window (Days) and Order Statuses That Allow Returns.
3. Processing > Default Return Instructions: add your returns address. This text is sent to the customer with every approval.
4. Optional: create a returns policy CMS page and select it in General > Returns Policy Page. Customers then have to tick "I have read the returns policy" before they send a return.
5. Emails > Staff Email Addresses: who is told about new returns and customer messages.
6. Save and flush the cache. Customers now see My Returns in their account and a Return Items button on their orders, and guests can use /returns/guest.

4. Settings

All settings are under Stores > Configuration > Softaware > Returns & RMA. Most can be set per website or store view.

General

Reasons, Conditions and Resolutions

Three lists of code and label pairs. Customers choose one reason and one condition per item, and one resolution per return. Codes (lower-case letters, digits and underscores) are stored with each return and used in reports, so keep them stable; change and translate the labels per store view freely.

• Return Reasons (default): Wrong size or fit, Not as described, Faulty or damaged on arrival, Wrong item sent, Quality not as expected, Changed my mind, Other.
• Item Conditions (default): Unopened; Opened, not used; Used; Damaged.
• Resolutions (default): Refund, Exchange. "refund" is handled with a credit memo. Other resolutions are recorded with the return and handled by your team, or by an extension listening to the softaware_returns_return_closed event.

Photos

Guest Returns

Processing

Under UK and EU law the original standard delivery cost must be refunded when a whole order is withdrawn; you can always add it on the credit memo.

Automatic Approval

Emails

Nine templates can be replaced with your own (create them from the defaults under Marketing > Email Templates): Return Received (Customer), New Return (Staff), Return Approved, Return Rejected, Parcel Received, Refunded / Closed, Other Status Changes, New Message from Staff (Customer) and New Message from Customer (Staff).

5. The customer's side

Signed-in customers

• My Account > My Returns lists their returns and the orders they can still return, with the last return date.
• The order page shows the return window end date and a Return Items button; My Orders has a Returns column.
• The return form lists the returnable items with the maximum quantity. For each ticked item the customer sets the quantity, reason and condition, then chooses a resolution, adds an optional comment and photos and, if a policy page is set, accepts the returns policy. Configurable products are returned on the parent line, dynamic bundles per component and fixed bundles as a whole.
• The return page shows the status and what happens next, the return instructions and label download once approved, the customer's photos, a field for the tracking number of the return parcel, and a conversation with your team (messages and files). A pending return can be cancelled if you allow it.

Guests

At /returns/guest the guest enters the order number, email address and billing postcode. The order page then shows what can be returned and any earlier returns, and the guest continues with the same form and return page through signed links. If the order belongs to a customer account, the guest is asked to sign in.

On Hyvä the same pages use the module's Hyvä templates, and they work on phones:

6. Handling returns in the admin

The returns grid

Sales > Returns (also Softaware > Returns & RMA > Returns) lists every return with its order, customer, status, items and resolution. Use the filters, the keyword search and the Change Status mass action. "Updated" and "Store View" are available under Columns.

The order page and the customer page also have a Returns tab. Staff can create a return for a customer from the order: Order > Returns > Create Return.

The return page

The page shows the return and order details, the items with requested, approved, received, back-in-stock and refunded quantities, the reasons, conditions and photos, and the Process Return actions:

• Approve Return: set the approved quantity per item, edit the instructions and optionally add a PDF return label. If a carrier integration offers return labels, a "Create: …" button appears for each one.
• Reject Return: give a reason; it is sent to the customer.
• Mark as Received: record the received quantity per item, tick Return to stock where the item can be sold again, and add an optional note (for example the inspection result).
• Refund: Create Credit Memo opens Magento's credit memo with the received items filled in. Check the amounts, then refund online (when the payment method supports it) or offline. When the credit memo is saved, the return is closed automatically and the customer is always sent the Refunded / Closed email (unless customer emails are switched off for the store view).
• Close Without Refund: for exchanges, repairs or store credit handled outside Magento.
• Change Status: any status, including your own ones.

Most actions have an "Email the customer" option. Rejecting and closing without a refund ask for confirmation first.

Conversation and history

Below the actions, Instructions, Label and Tracking shows what was sent to the customer and lets you edit the instructions, labels, tracking number, carrier and resolution. The Conversation holds messages and files in both directions; tick Internal note for notes that the customer never sees and that send no email. Status History records every change with the date, who made it, the comment and whether the customer was emailed.

Statuses

Softaware > Returns & RMA > Statuses lists the built-in statuses (Pending, Approved, Awaiting parcel, Received, Refunded / Closed, Rejected, Cancelled). Rename them, change colour and sort order, or add your own, for example "Inspecting". For your own statuses you decide whether the customer is emailed, whether the status finishes the return and whether the items can be returned again. Built-in statuses cannot be deleted.

Reports

Softaware > Returns & RMA > Reports groups returns by reason, product, month, status, condition or resolution for a period and store view, with the number of returns and items, their value and their share. Rejected and cancelled returns can be included. Export CSV downloads the same table.

Excluding products

• Product edit: Exclude from Returns = Yes.
• Category edit: Exclude Products from Returns = Yes; this also covers products in subcategories.

7. CLI

bin/magento softaware:returns:check-order <order number>
bin/magento softaware:returns:email-preview <return number> <type> [-o file.html]

check-order shows the return window, whether the customer can start a return and the returnable quantity of each line, which answers "why can't my customer return this?". email-preview renders an email without sending it; types are customer_new, staff_new, approved, rejected, received, closed, status, customer_message and staff_message.

8. API and integrations

• REST (admin or integration token, with ACL): GET /V1/softaware-returns/:returnId, GET /V1/softaware-returns (search criteria), POST /V1/softaware-returns, PUT /V1/softaware-returns/:returnId/status.
• GraphQL for signed-in customers: softawareReturns, softawareReturnableItems(order_number), softawareCreateReturn(input).
• Delivery date: observe softaware_returns_delivery_date or implement Softaware\Returns\Api\DeliveryDateProviderInterface, and the window starts on the delivery date.
• Return labels: softaware_returns_label_options and softaware_returns_label_create let a carrier module add "Create: …" buttons and store the PDF and tracking number with the return.
• Other events: softaware_returns_return_created, softaware_returns_status_changed, softaware_returns_return_closed.

9. Permissions (ACL)

Under System > Permissions > User Roles > Role Resources: Softaware > Returns & RMA with View Returns, Manage Returns (approve, receive, refund, reply), Return Statuses and Return Reports, and Stores > Settings > Configuration > Softaware Returns & RMA for the settings. A role with View Returns only sees returns without the action panels.

10. Troubleshooting

• The Return Items button is missing. Run bin/magento softaware:returns:check-order <order number>: it shows whether the window has ended, the order status is not allowed, nothing has shipped yet, everything is already returned or refunded, or the products are excluded.
• A guest cannot find the order. The postcode must be the billing postcode, and too many failed attempts block further lookups for an hour. The counters are stored in the Magento cache.
• The consent checkbox does not appear. Select a page in General > Returns Policy Page.
• Photos are refused. Check the file type (JPEG, PNG, WebP or GIF), the size limit and PHP's upload_max_filesize.
• No emails arrive. Check Send Emails to Customers, the staff addresses and that the store can send mail.
• Hyvä pages look unstyled. Rebuild the Hyvä theme CSS after installing or updating.

11. Uninstall

bin/magento module:disable Softaware_Returns
composer remove softaware/module-returns
bin/magento setup:upgrade
bin/magento cache:flush

The module's tables (softaware_return*) and the files in var/softaware_returns stay in place until you remove them; this keeps the return history if you install the module again.