Product Return Manager — Complete guide

DataFirefly Product Return Manager turns PrestaShop 8 return management into an end-to-end automated flow: customer self-service request (account or guest), PDF label with QR code, scan validation on receipt, 13-axis analytics, voucher or refund, admin manual returns, automatic reason translation via ChatGPT and ERP integration via hook. This documentation covers installation, full configuration and daily usage.

Installation

Standard PrestaShop installation: go to Modules → Module Manager → Upload a module, select the dfproductreturn.zip file, and confirm. The module automatically creates 9 tables prefixed df_return_* and df_product_return*, installs default return reasons, registers its hooks (displayCustomerAccount, displayMyAccountBlock, displayHeader, etc.) and adds two back-office menu entries: Product Returns (management) and Return Analytics (statistics).

Configuration

Go to Modules → Module Manager → DataFirefly Product Return Manager → Configure. The main settings:

• Return window (days) — window during which the customer can request a return after their order. 30 days by default. Applies only to customer-initiated returns; the admin manual return ignores it.
• Eligible order statuses — only orders in these statuses display the “Request a return” button (typically “Delivered”).
• Enable voucher — offers the voucher option as compensation mode.
• Enable refund — offers the refund option on the original payment method.
• Admin email — address notified on each new return request.
• Partial / full refund state — the two order states applied depending on the refund type performed.
• OpenAI API key — required only for automatic translation of return reasons via ChatGPT (see dedicated section).

Return reasons and categories

The module organizes reasons on two levels: categories (“Product issue”, “Logistics issue”, “Change of mind”…) and reasons attached to each category (“Wrong size”, “Defective item”, “Delivery too long”…). This hierarchy feeds the analytics: you see the macro distribution by category, then the detail by reason.

Manage them from the Reasons tab of the configuration: creation, editing, deactivation, display order. Default reasons are installed with the module — adapt them to your catalog.

Automatic translation via ChatGPT

Once your OpenAI API key is entered in the configuration, a Translate button appears on each reason and category. One click translates the label into all activated languages of the store, with contextualized e-commerce vocabulary. Translations remain manually editable after generation. Get your key at platform.openai.com — the cost per translation is negligible (fractions of a cent).

Customer journey (logged-in)

The logged-in customer sees a “My returns” link in their customer area. To initiate a return:

1. They open the eligible order and click “Request a return”.
2. They check the products to return and adjust quantities.
3. They choose a reason category, then a precise reason, and add an optional comment.
4. They validate — the return goes to “Pending” status and two emails are sent: confirmation to the customer with the PDF label attached, notification to the admin.

The customer then tracks their return status (pending, accepted, refused, refunded) from “My returns”, with the ability to re-download their PDF label at any time.

Guest returns (v1.7+)

Customers who checked out without creating an account access returns at the same URL as logged-in customers. An unauthenticated visitor sees an “Order reference + email” form instead of the “My orders” list. How it works:

• Validation is server-side: the order reference + email pair must exactly match an existing order (case-insensitive email comparison).
• On mismatch, the error message is intentionally generic — anti-enumeration protection, no information about existing references is revealed.
• Once validated, the visitor accesses the standard return flow for that order only (scoped PrestaShop session).
• The label PDF remains accessible from the email link without login, protected by a 64-character random token unique to the return.
• A “Use a different order” banner lets the visitor reset the guest session and switch to a different order.

The PDF label and QR code

Each return generates a PDF containing: the return address, the return number, the list of products and quantities, the instructions, and a unique QR code including a cryptographic verification token. The customer prints it and sticks it on their package.

Multiple return addresses

Configure multiple addresses in the Addresses tab (main warehouse, high-volume processing site, EU vs non-EU address…). Each return is associated with an address that appears on its label.

QR scan validation on receipt

When the package arrives, your operator scans the QR with a phone or a USB scanner. The scan opens the secure validation page — an active PrestaShop admin session is required; without a session, the page redirects to the back-office login. The operator then sees the complete return details, checks the physical condition of the products, and clicks Validate or Refuse.

Validation triggers a cascade: order transition to the configured state (partial or full refund), voucher or refund generation, status update email to the customer, and dispatch of the actionOrderSlipAdd hook for third-party integrations.

Admin manual returns (v1.6+)

Customer service can create a return for any order, regardless of the configured return window and the order status — designed for goodwill gestures, phone-negotiated returns and retroactive regularizations.

1. Click “Create manual return” in the returns list header in the back-office.
2. Step 1 — enter the order reference or ID (an order from 2022, cancelled or in draft is accepted).
3. Step 2 — tick the products to return, their quantities, their reason, the compensation type (voucher or credit slip), and adjust the per-line refund amount if needed.
4. Validate: the return is processed immediately — voucher or credit slip generated on the spot, stock restored, order state updated, Fastmag hook dispatched.

A “Notify customer” checkbox (unchecked by default) sends the standard confirmation email if you wish. A free-form admin note can be attached to the return.

Per-line refund amount override (v1.7+)

Each manual return line has an editable “Refund amount” field. The default value (unit price × quantity) is automatically recalculated when the quantity changes, until an amount is entered manually — the entered value is then preserved as is. The proportional discount ratio of the order, applied to regular customer returns, is disabled for manual returns: the entered amount is exactly the refunded amount. Useful for partial refunds (damaged product refunded at 50%), goodwill gestures or regularizations. The generated credit slip preserves the excl/incl tax breakdown proportional to the original line’s tax rate.

Voucher or refund

Depending on your configuration, validating a return produces either a voucher (native PrestaShop cart rule, usable on a future order), or a refund to process on the original payment method. The two dedicated order states (partial / full) distinguish the cases in your exports and accounting reports.

Analytics dashboard

The Return Analytics menu exposes 13 axes of analysis, all filterable by period and by store:

• Global KPIs — return volume, return rate, returned value, voucher / refund distribution.
• By reason category and by reason — identify dominant causes.
• By country — spot geographic anomalies (failing carrier in an area).
• Top returned products — the references to examine (sizing guide, supplier quality).
• Reason × country and reason × product crossings — the level of detail to act on.
• Monthly (12 months) and daily trends — seasonality and peaks.
• Average processing time — your customer service performance.
• Day-of-week distribution and top returner customers — abuse detection.

The CSV Export button downloads all returns of the filtered period (return number, order, customer, products, reason, status, dates, amount) for external analysis or BI import.

Fastmag and ERP integration

On each validated return, the module dispatches the PrestaShop actionOrderSlipAdd hook with the order, the product list and the quantities. Any module listening to this hook (DataFirefly Fastmag module, ERP connectors, Systempay…) receives the notification in real time. Admin manual returns dispatch the same hook.

The “Re-sync past returns to Fastmag” button (returns list toolbar) re-triggers the hook on all past returns — essential after installing an ERP connector after this module, or after a synchronization incident.

Transactional emails

Three automatic emails, provided in 6 languages (FR, EN, ES, IT, PT, DE): request confirmation to the customer (with PDF attached), notification to the admin, status update to the customer (validation / refusal / refund). On admin manual returns, the customer email is optional (checkbox unchecked by default). Customize the templates in modules/dfproductreturn/mails/<language>/ or via PrestaShop’s native email translation system.

Multi-store

All tables carry an id_shop: each store has its own reasons, return addresses and analytics. The back-office multi-store selector naturally filters the returns list and the dashboard.

Troubleshooting

The “Request a return” button doesn’t appear

Check three points: the order is in an eligible status (configuration), the return window hasn’t expired, and the module is active on the relevant store (multi-store context). Reminder: for an out-of-window return, use the admin manual return.

The guest form rejects a valid order

The entered email must be exactly the one on the order (case is ignored, typos are not). Check the order reference — it’s the alphanumeric reference (e.g. XKBKNABJK), not the numeric ID.

The QR scan displays “Access denied”

This is the expected behavior without an admin session: the operator must be logged into the PrestaShop back office in the same browser. Log in then re-scan.

ChatGPT translation fails

Check the API key in the configuration, the available credit on your OpenAI account, and that your server allows outgoing connections to api.openai.com (port 443).

Fastmag doesn’t receive returns

Check that the Fastmag module is installed and hooked to actionOrderSlipAdd, then use “Re-sync past returns to Fastmag” to catch up on history.