=== ProfitEngine — Purchasing & Inventory ===
Contributors: shiponkarmakar
Tags: inventory, purchasing, suppliers, purchase orders, profit
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.1
WC requires at least: 8.0
WC tested up to: 11.2
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

WooCommerce purchasing, inventory planning, supplier management and real-profit analytics: know what to buy, from whom, when, and your true margin.

== Description ==

ProfitEngine is a purchasing, inventory-planning and profit system built directly on WooCommerce. It answers the questions a store owner asks every week:

* **What should I buy, and how much?**
* **From which supplier, and when?**
* **What will it cost to get it into my warehouse?**
* **What is my real profit after costs, discounts, fees and shipping?**

Most stores only see a simple "price minus cost" figure. ProfitEngine records the true cost of every sale at the moment it happens, forecasts demand from your own sales history, and turns that into a clear reorder list and purchase orders you can send to suppliers.

= Video walkthrough =

See ProfitEngine in action: reorder suggestions, purchase orders and real profit.

https://www.youtube.com/watch?v=dfzAm9jW9Pg

= Dashboard =

* **Sales overview chart:** orders, revenue and profit over time, with Today (hour by hour), Last 30 Days, Last 90 Days and Last 1 Year views. Hover any period to see its exact figures; click the legend to show or hide a series.
* **Key numbers at a glance:** revenue, profit and margin, product & order cost, purchase spending, inventory value and products to reorder.
* **Recommendations:** what to act on next, such as products to reorder now, products sold at a loss, stock running low, thin margins and any setup steps still to finish.
* **Top products by profit** and **margin distribution** across your catalogue.
* **Suppliers to order from** with the recommended spend for each, **supplier spending**, and **recent purchase orders**.

= Smart reorder =

* Every product with demand is ranked by urgency: **Critical** (will run out before a new order could arrive), **Warning** (at or below its reorder point) and **Recommended** (should be topped up soon).
* A suggested order quantity for each product, rounded up to the supplier's minimum order quantity (MOQ).
* Stock already on the way in open purchase orders is taken into account, so you never order twice.
* Tick the products you want, adjust quantities, and create purchase orders in one click. They are split automatically into one order per supplier.
* Forecasts recompute automatically every night, or on demand with one click.

= Transparent forecasting =

Every suggestion is built from simple formulas you can check:

* Average daily sales = units sold ÷ sales window (days)
* Days of stock remaining = current stock ÷ average daily sales
* Safety stock = your manual value, or average daily sales × safety days
* Reorder point = your manual value, or (average daily sales × lead time) + safety stock
* Suggested quantity = average daily sales × (lead time + coverage days) + safety stock − current stock − stock already on order

= Purchase orders =

* Create, edit, send and receive purchase orders with sequential PO numbers.
* Status lifecycle: Draft → Sent → Partially received → Received (or Cancelled). Received orders are locked to protect your history.
* **Partial and full receiving:** received quantities are added to WooCommerce stock automatically. If stock tracking is off for a product, it is switched on and the received quantity becomes its starting stock.
* **Landed cost:** shipping and other costs (customs, handling, fees) are shared across the order's lines by value, so each product's cost reflects what it really cost to bring in.
* **Tax handling:** mark tax as recoverable (VAT/GST you claim back, kept out of product cost) or non-refundable (import duty, added into product cost).
* Discounts and tax as a fixed amount or a percentage.
* **Multi-currency:** buy in your supplier's currency with an exchange rate to your store currency.
* The expected delivery date defaults to today; the product's supplier is linked automatically when you add it to an order.
* **Printable purchase order** with your own logo, ready to print or save as PDF and send to the supplier.
* Submitting the same receipt twice can never add stock twice.

= Suppliers =

* Supplier records with contact person, email, phone, address, currency, payment terms, lead time, minimum order value and notes.
* Per-product supplier details: supplier SKU, purchase cost, MOQ and lead time, with a primary supplier per product.
* Archive suppliers you no longer use without losing their history.

= Products =

* A fast stock grid with product thumbnails, supplier, selling price, cost, margin, stock, inventory value and reorder point.
* Filter by **In stock**, **Low**, **Out** or **Not tracked**, search, and sort any column.
* Set purchasing data for simple products and for each variation of a variable product.
* Bulk-assign a supplier (and cost) to many products at once.
* Turn on stock tracking for a product straight from the grid.

= Real profit =

* Profit is recorded for every order line at the moment of sale: revenue (after discounts and refunds) minus product cost, shipping, payment fees and other costs. Tax is excluded by default.
* **Cost history is preserved:** changing a product's cost later never rewrites the profit of past sales.
* Refunds and cancellations are reflected automatically.
* **Cost basis** of your choice: weighted average or last purchase cost, updated each time stock is received.
* **Configurable revenue recognition:** choose which order statuses count as revenue. Cash-on-Delivery stores can count only Completed orders so unpaid orders don't inflate profit.
* Profit by product with a full cost breakdown (product, shipping, payment fees, other).
* **Historical backfill:** calculate profit for orders placed before you installed the plugin.

= Reports =

* Profit by product, profit by category, sales vs cost, supplier spending, purchase history and inventory value.
* Date filtering, sortable columns and totals.
* **Export to CSV** (safe to open in Excel or Google Sheets) or **PDF**.

= Stock notifications =

Get told the moment something needs attention, wherever your team already works:

* **Email**, sent by your own site.
* **Slack**, **Discord** and **Microsoft Teams** through a channel webhook.
* **Telegram** through your own bot.
* **Custom webhook**: the alert as JSON for Zapier, Make, n8n or your own code, with an optional HMAC signature.

Choose which alerts you want: reorder now (critical), running low, out of stock, low stock, purchase order overdue and stock received. Alerts raised together are grouped into one message, and a quiet period stops the same product alerting again and again. An optional **daily digest** lists everything to reorder with suggested quantities and estimated spend, at the hour you choose.

Messages are sent in the background with automatic retries, so a slow service never slows down your store. Each channel has a **Send test** button and shows its last delivery, and a delivery log lists recent sends. Every channel is off until you turn it on.

= Built for WooCommerce =

* Compatible with WooCommerce High-Performance Order Storage (HPOS).
* Works with simple and variable products.
* Uses your store's currency, symbol position and number format everywhere.
* Modern, fast admin interface built with the WordPress REST API and React.
* Only administrators and shop managers can access it.
* Translation-ready.
* Your data stays on your own site. It only connects to an outside service if you turn on a notification channel (see External services).

== External services ==

ProfitEngine works entirely inside your WordPress site. It only contacts an outside service when **you** turn on a notification channel on the ProfitEngine > Notifications screen. Every channel is off by default, and nothing is sent until you enable one and save.

When a channel is on, a message is sent to it when an alert you selected happens (a product needs reordering, runs low or out of stock, a purchase order is overdue or received), when the daily digest is due, and when you press **Send test**. A message contains your store name, the alert headline, the product names and SKUs involved, their stock level, sales rate, days of stock left and suggested order quantity, purchase order numbers and supplier names, and a link back to your admin. No customer or order details are sent.

* **Slack** (hooks.slack.com): the message is posted to the incoming webhook URL you enter. [Terms of service](https://slack.com/terms-of-service), [Privacy policy](https://slack.com/trust/privacy/privacy-policy).
* **Discord** (discord.com): the message is posted to the channel webhook URL you enter. [Terms of service](https://discord.com/terms), [Privacy policy](https://discord.com/privacy).
* **Telegram** (api.telegram.org): the message is sent through the Telegram Bot API with the bot token and chat ID you enter. [Terms of service](https://telegram.org/tos), [Privacy policy](https://telegram.org/privacy).
* **Microsoft Teams** (Power Automate Workflows): the message is posted to the workflow webhook URL you enter. [Microsoft Services Agreement](https://www.microsoft.com/servicesagreement), [Privacy statement](https://privacy.microsoft.com/privacystatement).
* **Custom webhook**: the message is posted as JSON to the URL you enter, which you control. That service's own terms and privacy policy apply.

Email alerts are sent by your own site through WordPress mail and do not use an outside service unless your site is already set up to send mail through one.

== Installation ==

1. In your WordPress admin, go to **Plugins → Add New**, search for **ProfitEngine** and click **Install Now**. (Or upload the plugin zip under **Plugins → Add New → Upload Plugin**.)
2. Click **Activate**. WooCommerce must be installed and active.
3. Open **ProfitEngine** in the admin menu.
4. Follow the setup steps on the Dashboard:
   * Add your suppliers.
   * Set purchase costs and suppliers for the products you buy (on the **Products** screen).
   * Open **Reorder** and click **Recompute forecasts**.
   * Create your first purchase order.
5. Optional: under **Settings**, choose your cost basis, payment fees, revenue statuses and forecasting defaults, then run **Historical profit** to include past orders.

== Frequently Asked Questions ==

= Does ProfitEngine require WooCommerce? =

Yes. ProfitEngine works on top of WooCommerce and needs WooCommerce 8.0 or newer to be installed and active.

= Does it work with variable products? =

Yes. Each variation has its own cost, supplier and stock, and is forecast and ordered separately.

= How is "real profit" calculated? =

For each order line: revenue (after discounts and refunds, excluding tax) minus the product cost, its share of shipping, payment fees and any other costs you configure. Tax is excluded by default because it is passed on to the tax authority; you can include it under Settings.

= Will changing a product's cost change my past profit figures? =

No. The cost of each sale is recorded when the sale happens, so your history stays accurate even when your purchase costs change later.

= Does it count unpaid Cash-on-Delivery orders as revenue? =

Only if you want it to. Under **Settings → Revenue recognition** you choose which order statuses count. By default Processing and Completed orders count; Cash-on-Delivery stores usually untick Processing so revenue is only recognised once an order is Completed (delivered and paid).

= Can I see profit for orders placed before I installed the plugin? =

Yes. Go to **Settings → Historical profit** and run the backfill. It processes your past orders in the background in small batches.

= Does ProfitEngine change my WooCommerce stock? =

Only when you receive a purchase order: the received quantity is added to the product's stock. If stock tracking was off for that product, it is turned on and the received quantity becomes its starting stock. It never changes your prices or other product data.

= How do I order a product from its Stock & costs window? =

The Stock & costs window only holds settings; nothing there places an order. Click **Create purchase order** at the bottom of the window to open a new purchase order with the product already added (every variation for a variable product), its supplier selected and the supplier unit cost filled in. Adjust the quantities, then create the draft or send it. You can also start from Purchase Orders > New purchase order, or from the Reorder screen.

= What is the difference between "Supplier unit cost" and "Unit cost for profit"? =

**Supplier unit cost** is what a supplier charges you per unit, in that supplier's currency. It pre-fills purchase orders and the estimated spend on the Reorder screen. **Unit cost for profit** is your actual cost per unit in your store currency, and it is what ProfitEngine uses to calculate profit on each sale. It starts from the supplier unit cost and then updates automatically every time you receive stock (weighted average or last purchase cost, as set in Settings), so it can include shipping and other landed costs. Changing it affects new sales only; past sales keep the cost they were recorded with.

= What is landed cost? =

The full cost of getting stock into your store: the supplier's price plus a share of shipping, customs, handling and other order costs. ProfitEngine spreads those extra costs across the products in a purchase order by value, so each product's cost (and therefore your profit) is accurate.

= How should I enter VAT or GST on a purchase order? =

If you can claim the tax back, leave it as recoverable, and it stays out of product cost. If it is a non-refundable tax or import duty, tick **Non-refundable** and it is added into the landed cost of the products.

= Can I buy from suppliers in another currency? =

Yes. Set the purchase order currency and an exchange rate to your store currency. Costs are converted to your store currency when stock is received.

= What is the difference between weighted average and last purchase cost? =

Weighted average blends the cost of the stock you already have with each new delivery, which smooths out price changes. Last purchase cost always uses the most recent delivery's cost. Choose under **Settings → Cost basis**.

= How does the reorder list decide what is urgent? =

**Critical** means the stock will run out before a new order could arrive (days of stock left is less than the supplier's lead time). **Warning** means stock is at or below its reorder point. **Recommended** means it will run low within your coverage period. Products with no recent sales are not listed.

= How often are forecasts updated? =

Automatically every night, and whenever you click **Recompute forecasts** on the Reorder screen. Forecasts are calculated in small background batches so large catalogues don't slow your site.

= How do I correct stock after a count, damage or a return? =

Open the product's Stock & costs window. The Stock section lists each variation with its current stock: type the quantity you counted, choose a reason and save. ProfitEngine updates WooCommerce stock and logs each change (who, when, why and by how much) in the product's recent stock history. Variations that WooCommerce isn't tracking show an Enable tracking button with a starting quantity.

= Can variations share one stock quantity? =

Yes. When you enable stock tracking on a variable product, choose **One shared stock** (the same as WooCommerce's "Track stock quantity" on the product) or **Separate per variation**. You can switch later from the Stock section in the product's Stock & costs window, and the quantity is carried across. With shared stock, every variation shows the same days of stock left, and each one's suggested order is based on its share of recent sales, so the suggestions add up to what the whole product needs.

= Can I set my own reorder point or safety stock? =

Yes. Set them per product (or per variation). Leave them empty and ProfitEngine calculates them for you from sales velocity, lead time and your safety-days setting.

= Can I print or email a purchase order to my supplier? =

Each purchase order has a printable version with your logo, which you can print or save as a PDF and send to your supplier. Add your logo under **Settings → Purchase order branding**.

= Can I export reports? =

Yes. Every report can be exported to CSV or PDF.

= Will it slow down my store? =

No. ProfitEngine only loads its scripts on its own admin screens, records profit with a lightweight step when an order's status changes, and runs heavy work (forecasts, backfill) in the background using WooCommerce's Action Scheduler.

= Is it compatible with High-Performance Order Storage (HPOS)? =

Yes. ProfitEngine declares full compatibility with WooCommerce HPOS.

= Who can access ProfitEngine? =

Administrators and shop managers (any role that can manage WooCommerce). Other users cannot see its screens or data.

= Does it send my data anywhere? =

Not unless you ask it to. All data is stored in your own WordPress database. The only time ProfitEngine contacts an outside service is when you turn on a notification channel such as Slack or Telegram, and then it only sends the stock alert itself. See the External services section for exactly what is sent.

= Can ProfitEngine alert me on Slack, Discord, Telegram or Teams? =

Yes. Open ProfitEngine > Notifications, turn on a channel, paste its webhook URL (or, for Telegram, your bot token and chat ID), save, and press **Send test**. Email is also available and needs no setup. Each channel has a link to its official setup guide.

= Will I get flooded with alerts? =

No. Only real changes alert: a product becoming critical, or dropping to its reorder point. Alerts raised at the same time are grouped into one message, and the quiet period (24 hours by default) stops the same product or purchase order alerting again. If you prefer one message a day, turn off the instant alerts and use the daily digest.

= Can I send alerts to WhatsApp, Zapier, Make or n8n? =

Yes, with the Custom webhook channel. It posts each alert as JSON to any https URL, so you can forward it anywhere those tools reach, including WhatsApp. Add a signing secret to verify the X-ProfitEngine-Signature header (HMAC-SHA256 of the request body).

= What if a notification fails? =

It is retried automatically up to 3 times over about half an hour. The channel shows its last delivery result, and the delivery log on the Notifications screen lists recent sends with any error from the service.

= What personal data does it store? =

It does not store customer personal data. Profit records contain only order IDs and product figures. It stores the supplier contact details you enter (contact name, email, phone and address).

= What happens to my data if I deactivate or delete the plugin? =

Deactivating never removes data. Deleting the plugin also keeps your suppliers, purchase orders and cost history, so you can reinstall without losing anything. The only exception is if you turn on **Settings → Delete all plugin data when uninstalled**, which removes everything.

= Is ProfitEngine translation-ready? =

Yes. All text is translatable, and a translation template is included.

== Screenshots ==

1. Dashboard: sales overview chart with orders, revenue and profit, plus key numbers.
2. Dashboard: recommendations, top products by profit, margin distribution and suppliers to order from.
3. Reorder: what to buy, grouped by urgency, with editable quantities and one-click purchase orders.
4. Forecast breakdown: every input and formula behind a reorder suggestion.
5. Purchase orders: every PO with its status, expected date and total.
6. Purchase order editor: supplier, currency, exchange rate, line items and landed cost per unit.
7. Purchase order totals: discount, tax, shipping and other costs shared into landed cost.
8. Receiving: receive all or part of a purchase order straight into WooCommerce stock.
9. Printable purchase order with your logo, supplier details and totals.
10. Suppliers: contacts, currency, lead time and linked products.
11. Supplier editor: contact details, payment terms, lead time and minimum order value.
12. Products: stock grid with price, cost, margin, stock and inventory value.
13. Stock & costs window: supplier, supplier unit cost, MOQ, lead time, safety stock and reorder point.
14. Bulk actions: assign a supplier to many products at once.
15. Enable stock tracking for a product straight from the Products screen.
16. Profit: real profit by product with a full cost breakdown.
17. Reports: profit by product with CSV and PDF export.
18. Reports: sales vs cost over time.
19. Notifications: email, Slack, Discord, Telegram, Microsoft Teams and custom webhook channels, each with a test button.
20. Notifications: alert types, quiet period, daily digest and the delivery log.
21. Settings: profit model, payment fees and shipping cost allocation.
22. Settings: forecasting defaults, revenue recognition and purchase order branding.
23. Settings: data on uninstall and historical profit backfill.

== Changelog ==

= 1.1.0 =
* New: stock notifications by email, Slack, Discord, Telegram, Microsoft Teams or a custom webhook.
* New: alerts for reorder now, running low, out of stock, low stock, overdue purchase orders and received stock, grouped into one message with a quiet period.
* New: optional daily reorder digest at the hour you choose.
* New: send-test button, last-delivery status per channel and a delivery log. Failed sends are retried automatically.
* New: Stock section in the product Stock & costs window. Enter counted quantities per variation, pick a reason (stock count, damaged, returned, other) and add a note. Every change is logged with who made it, and the recent history is shown.
* New: product-level (shared) stock for variable products. Choose one shared quantity for all variations or separate stock per variation, and switch between them at any time with the stock carried across. Reorder suggestions for shared stock split the quantity by each variation's share of sales.
* Readme: added a video walkthrough.
* The product row button is now "Stock & costs" (it was "Purchasing", which suggested it bought something). The window has a new Create purchase order button that opens a new PO with the product, its supplier and supplier unit cost already filled in.
* Clearer cost labels in the product Stock & costs window: "Purchase cost" is now "Supplier unit cost" and "Current cost" is now "Unit cost for profit", each with an explanation.
* Purchase orders show product images: a thumbnail beside each product in the Add product list and on each line item. Variations without their own image use the product's image; products with no image show none.
* New: Collapse menu button in the ProfitEngine sidebar to fold the WordPress admin menu and give tables more room.
* Fixed menu items briefly turning blue while clicking or loading the next page.
* New: turn stock tracking on for a single variation from the Stock & costs window, without leaving ProfitEngine.
* Enabling stock tracking on a variable product now takes a separate starting quantity for each variation, with a live total. Previously one number was copied to every variation.
* New: Stop tracking stock in the product Stock & costs window, with a confirmation that explains what changes.
* Delete and Stop tracking buttons are red again (they were showing in the brand green).
* Supplier payment terms are now a dropdown of standard terms (50% Advance, Net 30, Net 60, COD, CIA, Deferred Payment, L/C). Terms entered before are kept.
* Smaller success and error messages with a status icon.
* Fixed square corners showing behind rounded text fields and the search box.
* Developers: new profit_engine_forecast_severity_changed and profit_engine_po_received actions, and a profit_engine_notification_message filter.

= 1.0.5 =
* Fixed the Critical badge on the Reorder screen showing without its red style.
* Opening a product's forecast breakdown no longer resets its forecast to zero sales.
* Products with stock tracking off are no longer flagged for reorder.
* Updating a supplier through the REST API with only some fields no longer clears the others.
* Fixed field alignment and the stock line in the product purchasing popup.
* Sales vs cost chart: readable axis text and rounded axis values.
* Added screenshots for every screen.

= 1.0.4 =
* New dashboard: sales overview chart (orders, revenue and profit) with Today, 30-day, 90-day and 1-year views.
* New sidebar navigation and page layout.
* Amounts now follow the store's WooCommerce currency format (symbol position, separators).
* Fixed weekly charts and the "Sales vs cost" report showing no data for 90-day and 1-year ranges.

= 1.0.3 =
* Text domain now matches the plugin slug (profit-engine).
* Receiving a purchase order is now safe against double submission (stock is never added twice).
* Faster Products screen on large stores (purchasing data is loaded in one batch).
* The nightly forecast recompute is now scheduled reliably.
* CSV exports neutralise spreadsheet formulas in text cells.

= 1.0.2 =
* Purchase order print view now enqueues its assets through the standard WordPress functions.
* Styled the date-range pickers and refined the Profit cost breakdown.

= 1.0.1 =
* Revenue recognition is now configurable: choose which WooCommerce order statuses count toward revenue and profit (e.g. Cash-on-Delivery stores can count only Completed/Delivered instead of Processing).
* Purchase orders: added an "Other cost" field (customs, handling, fees) that is allocated across units into landed cost.
* Purchase orders: added a "Non-refundable" tax option: recoverable VAT/GST stays out of landed cost, while non-refundable duty is allocated into unit cost.
* Purchase orders: the product's supplier is now linked automatically when a PO is created, and the Expected date defaults to today.
* Fixed a supplier-cost precision issue when linking products to a supplier.
* Compliance and packaging: WordPress.org guideline fixes (name, tags, tested-up-to), removed inline print styles/scripts, and cleaned Plugin Check warnings.

= 1.0.0 =
* Initial release: suppliers, product purchasing data, purchase orders with receiving, transparent forecasting, smart reorder dashboard, real-profit engine, reports and historical backfill.

== Upgrade Notice ==

= 1.1.0 =
Adds stock notifications by email, Slack, Discord, Telegram, Microsoft Teams or webhook, plus a daily reorder digest. All channels start off.

= 1.0.5 =
Fixes forecasts being reset when viewing a forecast breakdown, plus several layout fixes.
