AI Returns Predictor — Complete guide
Install, configure and operate return-risk scoring before shipping for PrestaShop 8 and 9.
AI Returns Predictor analyses every order the moment it is validated and assigns a return-risk score from 0 to 100, classified into three levels (Low, Medium, High). The score appears right on the order page, with a factor breakdown, and your logistics team is alerted by email before shipping whenever an order crosses the high-risk threshold. This guide covers installation, configuration, how the scoring engine works and the optional AI layer.
Installation
- Download the
dfreturnspredictor.ziparchive from your DataFirefly account. - PrestaShop back office → Modules → Upload a module → send the ZIP.
- On install, the module creates its
df_return_risktable, registers its hooks and adds the Shipping → Returns Predictor tab.
Compatible with PrestaShop 8.0 to 9.x, on PHP 7.4 to 8.3. No theme override, no Composer dependency. Multistore and multilingual compatible.
General configuration
Go to Modules → AI Returns Predictor → Configure.
Risk thresholds
Two thresholds determine the level assigned to each order based on its score:
- Medium threshold (default 40): score at/above which an order becomes Medium risk.
- High threshold (default 70): score at/above which an order becomes High risk and triggers the logistics alert.
Below the Medium threshold, the order is rated Low. Thresholds must satisfy 1 ≤ Medium < High ≤ 100.
High-return categories
Enter the comma-separated IDs of categories known for frequent returns (fashion, apparel, footwear…). Products belonging to these categories raise the order’s score.
Logistics alert
- Logistics alert email: address notified when an order crosses the high-risk threshold. Leave the field empty to disable email alerts.
The alert is sent only once per order, on the first detection of high risk. Later recomputes do not send a new email.
AI layer (optional)
The module works without AI thanks to its heuristic engine. You can enable an optional AI layer to refine the score and generate a short explanation.
- Enable AI refinement: if disabled, no external call is made.
- Mistral API key: stored server-side, never exposed to the front office.
- Mistral model: for example
mistral-small-latest.
On any network error, API outage or timeout (8 s), the module automatically falls back to the heuristic score. Scoring never blocks order preparation.
How the score is computed
The heuristic engine combines six explainable factors, each contributing a capped number of points. The total is bounded between 0 and 100.
- Customer return history (0–30): ratio of past returns to the customer’s valid orders.
- Size / variant bracketing (0–25): same product ordered in several variations (sizes, colours), a sign of try-on intent.
- Basket value (0–15): order amount relative to the shop’s average basket.
- High-return categories (0–20): presence of products in the categories you declared.
- New customer (0–8): no usable purchase history.
- Basket size (0–10): number of distinct items in the order.
Each factor shows its point contribution on the order page, making the score fully transparent — no black box.
The risk panel on the order
On every order page (hook displayAdminOrderSide), a “Return risk” panel shows:
- the score out of 100 and the colour-coded level (Low / Medium / High);
- the breakdown of contributing factors with their points;
- the AI explanation, where applicable;
- a Recompute button that re-runs the scoring via AJAX without reloading the page.
The score is computed automatically when the order is validated (hook actionValidateOrder) and refreshed on status changes (hook actionOrderStatusPostUpdate).
The logistics dashboard
The Shipping → Returns Predictor tab lists all scored orders, sorted by descending score. You will find the reference, customer, status, score, level and alert indicator. Filter by level to isolate high-risk orders before parcels are prepared. The “View” action opens the relevant order page directly.
The email alert
When an order crosses the high-risk threshold at creation, a summary email is sent to the configured logistics address: order reference, score, level, customer, contributing factors and any AI note. Email templates are provided in French and English, and sending accounts for the customer’s language and the order’s originating shop.
The module informs and alerts, but never changes the order status and does not prevent shipping. The final decision stays human.
Compatibility and technical notes
- PrestaShop 8.0 to 9.x, multistore and multilingual.
- Legacy admin controller (no Symfony controller) for PS8/PS9 compatibility.
- Back-office AJAX endpoint via the 4th argument of
getAdminLink(); JSON rendered by a dedicated method. df_return_risktable: one record per order, with score, level, factors (JSON) and alert flag.- Optional AI layer: only the data needed for the calculation is sent to Mistral; automatic fallback to the heuristic.
FAQ and troubleshooting
The risk panel does not appear on the order page. Check that the module is hooked on displayAdminOrderSide and that the order was created after installation. Use the “Recompute” button to force scoring.
No email alert is received. Check that the alert address is set and valid, and that the order actually exceeds the High threshold. The alert is sent only once per order.
The AI returns no explanation. Check the Mistral API key and model name. The module falls back to the heuristic score anyway; no score is lost.
Are all new customers considered risky? No. The lack of history only adds a small uplift; the score depends mostly on the other factors (bracketing, categories, basket value).