=== Refused Parcel Detector ===
Contributors: toply
Tags: woocommerce, returns, cash on delivery, refused parcel, cod
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.6.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Detect customers who refuse COD parcels. Score return risk, flag risky orders, and stop losses from refused cash-on-delivery deliveries.

== Description ==

Refused Parcel Detector is an essential tool for any WooCommerce store that offers cash-on-delivery (COD) payment. The plugin automatically analyzes your order history and identifies customers who have a pattern of refusing or returning parcels.

Statistics show that a single refused parcel can wipe out the profit from 3-4 successfully completed orders due to round-trip shipping costs. Refused Parcel Detector gives you full visibility into these losses directly in your admin panel.

= Key Benefits =

* **Financial Dashboard:** A modern control panel shows your total monetary losses from returns and failed deliveries, your store-wide return rate percentage, and the total number of risky customers — all calculated automatically from your existing WooCommerce orders.

* **Risky Customers Table:** A paginated table lists every customer who has had at least one failure, sorted by number of incidents. Each row shows email, total orders, returns/failures, risk score (%), and a recommendation — so you always know who to watch before you ship.

* **COD Risk Alerts:** Customers with a risk score above 35% are automatically flagged with a **"Card Required"** warning directly in your dashboard — a clear signal to manually require card payment, call the customer to confirm, or hold the order before shipping. Stop losing money on refused parcels before they ever leave your warehouse. *(Full automatic COD blocking at checkout available in Pro.)*

* **Risk Badge on Orders List:** A color-coded "Return Risk" column is added to the WooCommerce orders list (green / orange / red). Spot high-risk orders instantly before processing or dispatching.

* **Order Detail Risk Profile:** Open any individual order and see the customer's full risk profile directly in the billing section — score percentage, risk level, number of past failures, and total orders placed.

* **Risky Customers Filter:** A dropdown on the orders list lets you instantly display only orders from customers with a history of failures. Select "Risky customers only" and click Filter — works with both standard WooCommerce and HPOS.

* **Admin Dashboard Widget:** A summary widget on the WordPress home screen shows your three key stats at a glance every time you log in. Move or hide it via Screen Options.

* **Automatic Order Note:** When a customer with a return history places an order, a private note is automatically added to that order — visible in the order timeline to admins only. Shows the risk score, level, and number of past failures. Works immediately, no configuration required.

* **Phone Detection:** The plugin cross-references both billing email and billing phone when calculating a customer's score. If a customer places a new order with a different email but the same phone number, their risk history is still detected correctly.

* **Zero Configuration:** Install, activate, and the data is immediately available. The plugin reads directly from your existing WooCommerce orders — no import, no cron job, no setup required.

* **HPOS Compatible:** Fully compatible with WooCommerce High-Performance Order Storage (WooCommerce 7.1+) and standard post-based storage. Detection is automatic.

== Installation ==

1. Download the archive and extract the `toply-return-risk-predictor` folder into `/wp-content/plugins/`.
2. Activate the plugin from the 'Plugins' menu in WordPress.
3. Go to WooCommerce → Refused Parcel Detector to view your dashboard and statistics.

== Frequently Asked Questions ==

= How is the score calculated? =
Score = (losses ÷ total orders) × 100. The statuses that count as losses are configurable in Settings — by default: Failed, Refunded, and Cancelled. You can enable or disable each status to match your store's workflow.

= Is it safe for the database? =
Yes, queries are optimized and run only when an admin visits the plugin page or the orders list. The checkout process and front-end performance are not affected.

= Does it work with WooCommerce HPOS? =
Yes. The plugin automatically detects whether HPOS (High-Performance Order Storage) is enabled and uses the correct query path in both cases.

= What happens if a customer uses different emails? =
The plugin cross-references the billing phone number as well. If the same phone appears on a new order with a different email, the customer's full risk history is still applied correctly.

== Screenshots ==

1. The Refused Parcel Detector control panel with capital statistics.
2. The color-coded risk indicator in the orders list.

== Changelog ==

= 1.6.0 =
* Added: Automatic private order note for risky customers — when a customer with a return history places an order, a note is added to the order timeline automatically (e.g. "⚠ Return Risk: 67% (High Risk) — 4 failed/refunded out of 6 total orders"). No configuration required.
* Fixed: Comparison table now correctly shows phone detection and email alerts as available in the free version.

= 1.5.0 =
* Added: Email notification system — activation report, weekly digest (every Monday), and real-time alerts for risky customer orders.
* Added: Notification email field in Settings section.
* Added: One-click unsubscribe link in all notification emails.

= 1.4.0 =
* Added: Settings section to configure which order statuses count as financial losses (Failed, Refunded, Cancelled).
* Fixed: Per-customer risk scores now respect the configured statuses instead of using a hardcoded list.
* Fixed: HPOS orders filter now uses parameterized queries for security.
* Improved: Empty dashboard now shows three distinct states — new store (monitoring active), healthy store (no risky customers), and normal results view.
* Updated: Help text no longer states "Cancelled is excluded" — status counting is now fully configurable.

= 1.3.8 =
* Fix: all interface strings replaced with English equivalents.

= 1.3.7 =
* Added permanent Free vs Pro comparison table at the bottom of the dashboard page.
* Added two header action buttons (Free Trial / Buy Pro) for quick access after dismissing the promo banner.
* Added Pro upgrade link below "Card Required" recommendations in the risky customers table.
* Upgrade banner now dismissible permanently per user (stored in user_meta) — Guideline 11 compliant.

= 1.3.6 =
* Upgrade banner: redesigned copy to highlight COD blocking as main Pro benefit; sub-headline now bold white for maximum visibility.

= 1.3.5 =
* Upgrade banner: all text now white and clearly visible; buttons and notes aligned on one row with center alignment.

= 1.3.4 =
* Redesigned upgrade banner: all content right-aligned, reordered buttons (Try Pro Free → trial note → Buy Pro → billing options).

= 1.3.3 =
* Improved upgrade banner: trial note now clearly visible in green to highlight no credit card required.

= 1.3.2 =
* Redesigned Pro upgrade banner: more compact, mentions Pro explicitly, cleaner CTA buttons.

= 1.3.1 =
* Fixed: losses amount now displays the store's WooCommerce currency code (RON, EUR, USD, etc.).

= 1.3.0 =
* Added upgrade section in dashboard showing Pro features and personalized loss amount.
* Added "Start 7-Day Free Trial" button (no credit card required) and "See paid plans" button.

= 1.2.0 =
* Added "How to use" collapsible section in dashboard explaining all features, score colors, and where to find each function.
* Added WordPress admin dashboard widget showing total losses, return rate, and risky customer count (hideable via Screen Options).
* Added risk profile card in the billing section of individual order pages.
* Added "Risky customers only" filter dropdown on the orders list (works with both HPOS and legacy storage).
* Improved: badge-yellow color level for medium-risk customers in dashboard table.

= 1.1.0 =
* Full HPOS compatibility (WooCommerce 7.1+ custom order tables).
* Added dual hooks for orders list column — works on both legacy and HPOS screens.
* Dashboard queries now detect storage mode automatically.
* Fixed double-counting bug when filtering by both email and phone.
* Added Requires Plugins: woocommerce header.
* Plugin now initializes after WooCommerce is confirmed loaded.

= 1.0.2 =
* Added full internationalization (i18n) support with WordPress translation system.
* All interface strings are now translatable via translate.wordpress.org.
* Added Domain Path header and languages/ folder.

= 1.0.1 =
* Minor improvements.

= 1.0.0 =
* Initial community release. Historical analysis and risk scoring.