=== Profit Warden — WooCommerce Profit Calculator & Real ROAS Tracker ===
Contributors: beralabs, kingbera
Tags: woocommerce profit, profit calculator, order analytics, ROAS, profit margin
Requires at least: 5.3
Tested up to: 7.1
Stable tag: 3.1.15
Requires PHP: 7.2
WC requires at least: 5.0
WC Tested up to: 7.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The #1 WooCommerce profit calculator. See real net profit, true ROAS, and order profitability — directly in your dashboard.

== Description ==

**Stop running your WooCommerce store blind.** Profit Warden is the ultimate **WooCommerce profit calculator** that reveals the true financial health of your store — order by order, campaign by campaign.

Most store owners look at revenue and think they're doing great. But revenue is vanity. **Net profit is sanity.** Profit Warden calculates the exact net profit and profit margin for every single WooCommerce order, accounting for *all* your real costs — not just the product price.

> *"I thought I was making money. Profit Warden showed me I was losing €3 on every order from Meta Ads. Fixed it in a week."*

---

=== 🎯 Why Profit Warden? ===

Standard WooCommerce analytics tools give you **gross revenue**. That number ignores:

* Product purchase cost (COGS)
* Real carrier shipping cost vs. what the customer paid
* Packaging and handling costs
* Payment gateway fees (PayPal, Stripe, cash on delivery)
* Monthly fixed costs: hosting, SaaS, salaries, rent, accounting

Profit Warden deducts **all of these** to show you the only number that matters: **your real net profit**.

---

=== 📊 Features ===

**WooCommerce Profit Calculator — Order Level**
* Calculates net profit and profit margin percentage for every WooCommerce order automatically
* Displays profit analysis box directly on the WooCommerce order detail page
* Supports simple and variable products, each with its own Purchase Cost (COGS) field
* Detects and handles partial and full refunds in real time

**Comprehensive Cost Tracking**
* **COGS (Cost of Goods Sold):** Add a "Purchase Cost (€)" field to each product
* **Real Shipping Cost:** Add an "Actual Cost (€)" field to each shipping method/zone
* **Packaging Cost:** Configure a flat packaging cost per order
* **Gateway Fees:** Automatic estimation for PayPal (3.4% + fixed), Stripe (1.4% + fixed), and COD
* **Fixed Monthly Costs:** Track hosting, SaaS platforms, ad agency retainers, employee salaries, rent, insurance, accounting, and more

**Interactive Financial Dashboard**
* Real-time overview of Total Revenue, Net Profit, Average Margin %, Ad Spend, Real Net Profit, ROAS, Total Orders, Daily Burn Rate, and Break-Even Point
* Beautiful, interactive Chart.js charts for performance trends
* Configurable date ranges: Today, Last 7 Days, Last 30 Days, Last Year
* Top Selling Products and Top Customers ranking tables
* Order Intelligence Feed with live profit status for recent orders

**True ROAS & Ads Integration**
* Connect your **Meta Ads account** via secure OAuth to automatically import daily campaign ad spend
* UTM parameter tracking via cookies: every WooCommerce order is attributed to the campaign that generated it (utm_source, utm_medium, utm_campaign, fbclid, gclid)
* Calculate **True ROAS** — not revenue ÷ ad spend, but **real net profit ÷ ad spend**
* Ads Performance Dashboard with Total Spend, Attributed Orders, Attributed Revenue, and ROAS per campaign

**Automated WooCommerce Profit Reports**
* Email reports sent automatically via WP-Cron: daily, weekly, or monthly
* Loss Alerts: instant email notification when an order is sold at a loss
* Break-Even Point alerts: know exactly when you cross profitability each month

**Setup & Usability**
* Guided Setup Wizard on first activation — no configuration headaches
* Configuration Health Check panel to verify all parameters are properly set
* HPOS (High Performance Order Storage) compatible — ready for modern WooCommerce
* Clean, minimal WordPress admin UI

---

=== 🔒 Data Privacy & External Service ===

When **Data Sync** is enabled (explicit opt-in required), Profit Warden sends WooCommerce order data to the Templatebera API (`api.beralabs.it`) for profit calculation and campaign attribution. **No personally identifiable customer data is transmitted.** The Ads Integration feature uses OAuth via the same service to connect your Meta Ads account. You can disable data sync at any time from the Settings page.

---

=== 👤 Who Is Profit Warden For? ===

* **WooCommerce store owners** who want to know if they're actually making money — not just revenue
* **eCommerce managers** tracking multiple cost centers (warehouse, staff, SaaS, logistics)
* **Digital marketing agencies** managing WooCommerce clients who need real ROAS data, not inflated revenue-based ROAS
* **Dropshippers** who need to factor in real COGS and shipping margins at the order level
* **Accountants and CFOs** who need automated profit reports instead of manual spreadsheets

---

=== ⚡ Get Started in 3 Steps ===

1. Install and activate Profit Warden — a setup wizard will launch automatically
2. Enter your variable costs (packaging, shipping, gateway fees) and fixed monthly costs (hosting, SaaS, etc.)
3. Set the "Purchase Cost" on each product — Profit Warden does the rest automatically

---

== Installation ==

1. Upload the `profit-warden` folder to the `/wp-content/plugins/` directory, or install directly from the WordPress Plugin Directory.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. A **Setup Wizard** will guide you through the initial configuration: enter your report email, variable costs (packaging, default shipping, gateway fees), and fixed monthly costs.
4. Go to **Profit Warden → Costs** to review or update your cost structure at any time.
5. Edit your WooCommerce products and fill in the **"Purchase Cost (€)"** field in the General tab.
6. Edit each WooCommerce shipping method and fill in the **"Actual Cost (€)"** field added by Profit Warden.
7. *(Optional)* Go to **Profit Warden → Ads Integration** to connect your Meta Ads account and enable True ROAS tracking.

== Frequently Asked Questions ==

= How does Profit Warden calculate profit for each WooCommerce order? =

For every order, Profit Warden subtracts from the gross order revenue: the sum of purchase costs (COGS) of all items multiplied by their quantity, the real carrier shipping cost (from the "Actual Cost" field on the shipping method), a flat packaging cost, and the estimated payment gateway fee (PayPal, Stripe, or COD). The result is the **net profit** for that order. Fixed monthly costs are used separately for Break-Even Point and Daily Burn Rate calculations.

= What is True ROAS and why is it better than standard ROAS? =

Standard ROAS = Revenue ÷ Ad Spend. This is misleading because it ignores your actual costs. A campaign with ROAS 4x might still be losing you money if your margins are thin. Profit Warden's **True ROAS** = Net Profit ÷ Ad Spend. This is also known as **POAS (Profit On Ad Spend)**. It tells you exactly how much real profit each euro spent on advertising is generating — empowering you to cut losing campaigns and scale profitable ones.

= Can I use Profit Warden without the Meta Ads integration? =

Absolutely. The core WooCommerce profit calculator — order-level profitability, cost tracking, dashboard, and email reports — works completely independently of the Ads Integration. The Meta Ads connection is an optional feature that enhances the dashboard with ad spend data and True ROAS metrics.

= Does Profit Warden send my customer data to any external server? =

Only if you explicitly enable the Data Sync feature (opt-in). When enabled, order data (costs, margins, UTM parameters) is sent to `api.beralabs.it`. **No personally identifiable customer data** (such as full names, addresses, or payment information) is ever transmitted. You can disable this feature at any time from the Settings page.

= How do I track which Meta Ads campaign generated a profitable WooCommerce order? =

Profit Warden installs a lightweight JavaScript tracking script that captures UTM parameters and ad click IDs (fbclid, gclid) in browser cookies at the moment a visitor lands on your store. When the visitor places an order, these parameters are saved to the order metadata. With the Meta Ads integration enabled, Profit Warden then matches the order's net profit against the campaign-level ad spend to compute True ROAS.

= Is Profit Warden compatible with WooCommerce HPOS (High Performance Order Storage)? =

Yes. Profit Warden version 3.1.9 and above fully declares HPOS compatibility. It is tested and ready for modern WooCommerce with custom order tables enabled.

= Can Profit Warden send automatic profit reports via email? =

Yes. You can configure automated profit/loss reports to be sent via email on a **daily, weekly, or monthly** schedule using WP-Cron. You will also receive instant alert emails when an order is sold at a loss or when you reach the monthly break-even point.

== Screenshots ==

1. Profit Warden - Main Dashboard and Financial Charts.
2. Profit Warden - Variable and Fixed Costs Configuration.
3. WooCommerce Order Details - Profit Analysis Box.
4. Ads Integration Dashboard.

== Videos ==

1. [youtube https://youtu.be/-LeIQ67hU98?is=YnewN-HrlfIKuOix]
2. [youtube https://youtu.be/yx2B6A0ekr8?is=FT_0Xgpp85SgFwbu]

== Changelog ==

= 3.1.13 =
* FIX: aggiornato endpoint API su beralabs.it

= 3.1.12 =
* FIX: Aggiornato URL API principale in api.beralabs.it per maggiore stabiltà e performance.

= 3.1.11 =
* SECURITY: Resolved a vulnerability where the SQLite database could be publicly accessible on Nginx setups. Added robust protection mechanisms including an empty index.php, enforced .htaccess rules, and a randomized fallback hash for the SQLite file name.



= 3.1.10 =
* SECURITY: Fixed vulnerability regarding SQLite database direct access. Ensure .htaccess and index.php are always present in the uploads directory to protect against unauthorized downloads.


= 3.1.9 =
* FEATURE: Added WooCommerce version compatibility headers.
* FEATURE: Declared HPOS compatibility for custom order tables.

= 3.1.8 =
* FEATURE: Restored data transmission consent in setup wizard.

= 3.1.7.2 =
* FEATURE: Complete standalone mode update for local processing.

= 3.1.7 =
* FEATURE: Added SVN AutoGen tools for release management.
* FIX: General code updates and readiness for publishing.

= 3.1.5 =
* FEATURE: Enhanced local calculation engine for faster profit analysis.
* COMPLIANCE: Ensured text domain is set to profit-warden for full I18N compatibility.

= 3.1.4 =
* FEATURE: Added Ads Integration Dashboard for Meta and Google Ads.
* FIX: Verified UTM tracking logic across checkouts.

= 3.1.2 =
* FIX: Resolved cookies mismatch in UTM tracking.
* FIX: Backward compatibility for legacy tracking cookies.

= 3.1.1 =
* FEATURE: Added Onboarding Setup Wizard for easy configuration.
* SECURITY: Added nonces and permission checks to all admin actions.
* FIX: Renamed assets for better unique prefixing.

= 2.2-beta =
* FIX: Corrected plugin version format in the header.
* FIX: Aligned text domain for internationalization.
* FEATURE: Added periodic reporting via WP-Cron.

== Upgrade Notice ==

= 3.1.9 =
WooCommerce version compatibility headers updated and HPOS fully declared. Recommended update for all users on WooCommerce 7+.

= 3.1.5 =
Performance improvements for the local calculation engine and compatibility updates.

= 3.1.4 =
Introduces the new Ads Integration Dashboard to monitor marketing performance directly from WordPress.

= 3.1.2 =
Fixes critical tracking issues with UTM parameters. Update recommended for accurate ad attribution.

= 3.1.1 =
New onboarding flow and security enhancements.

= 2.2-beta =
This version introduces cron-based reporting and fixes minor compliance issues. Please review your settings under Profit Warden after updating.
