=== OrderWorth ===
Tags: woocommerce, profit, cost of goods, margin, reporting
Requires at least: 6.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.9.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Explainable order-profit estimates, missing-cost checks and an attention list.

== Description ==

Start on staging, reconcile known orders and keep backups. See the documentation and release notes for supported scope and compatibility limits.

OrderWorth combines native order-item COGS with explicit payment, shipping and
packaging expense assumptions. It flags missing data, estimated losses and low
margins. Orders with incomplete data are excluded from aggregate profit.

Free includes:
* Optional five-lesson quickstart: Start, Not now, Resume and Replay.
* Per-user reading progress, separate from observed store/report checks.
* Choose recent or older dates; the default is the last 30 calendar days.
* Manual report continuation beyond 5,000 orders, including a single busy day.
* Progress and complete-only totals; up to 3,660 inclusive calendar days per period.
* Data coverage, clickable exclusion reasons, order reviews and fresh per-order totals.
* Translation-ready interface and quickstart; language availability depends on installed translations.
* Recorded native order-item costs; no substitution of current product costs.
* New-order expense snapshots and labeled current assumptions for older orders.
* Explicit manual order costs, including confirmed zero.
* Refund review and manual recoverable-stock costs.
* Estimate columns for legacy and HPOS WooCommerce order lists.
* Payment and shipping method rules, with existing Pro settings preserved.
* Setup health checks and reviewed manual CSV imports without a 100-row cut-off.
* Up to 8 MiB CSVs, bounded previews, 50-row review pages and guarded 20-row writes.
* Guarded 24-hour import undo; old order costs are never backfilled.
* Capability/nonce checks and no external telemetry.

Requires WooCommerce 9.9+; declared minima do not imply every version combination
has been tested. Initial scope: simple products/variations in one store currency.
Subscriptions, bundles, marketplaces and currency conversion are outside scope.
Ads, overhead, income tax and unsupplied expenses are excluded.
These are order-contribution estimates, not accounting statements.

The separate Pro add-on adds period comparisons, profit-change drivers, personal report
presets, scheduled summaries, product/category allocations, weekly/monthly trends,
resumable background reports, bulk product-cost and verified-fee CSV imports,
recorded-fee review, complete report packs and optional scheduled packs with alerts.
Free runs locally with no license checks or custom updater. Install Free updates manually from the official download page. Pro is a separate add-on; purchases, updates and written support are managed on the OrderWorth website.

== Installation ==

1. Back up a staging site with WooCommerce.
2. Enable WooCommerce native COGS and record product costs for new orders.
3. Upload and activate this ZIP.
4. Open WooCommerce > OrderWorth > Cost assumptions; confirm your expenses.
5. Optionally use Quickstart, then run a report and review missing data.
6. For a fresh pair, install Free 1.9.7 first, then Pro 1.9.4 or newer; keep both active.
7. For an existing pair, back up, replace Pro first, then Free, without uninstalling.
   Pro 1.9.4 waits for Free 1.9.7 before loading its new workflows.

== Calculation ==

Order total - sales tax - refunds net of refunded tax
- original product costs + confirmed recovered product costs
- payment expense - shipping expense - packaging expense.

Discounts are already reflected in order revenue, never subtracted again.
Native order-item COGS already includes quantity.
Payment assumptions apply to original gross including tax/shipping, and are
retained after refunds unless overridden with the final actual expense.
Default expenses are assumptions, not automatically retrieved actual fees.
A later refund changes the original order's creation-date reporting period.

Saved add-on shipping, fulfilment and returns records remain intact when Pro is
inactive or incompatible. Affected orders are excluded from profit totals until
the compatible processing is active again; run a fresh report after reactivation.
Orders without those records retain all Free calculations.

== Privacy and removal ==

No external API calls or tracking. Reports go to authorized admin browsers.
No customer names, addresses or email fields are requested for reports.
Stores owwc_settings, owwc_pro_rules and order meta _owwc_assumptions / _owwc_overrides.
Import previews/undo expire after 24 hours (cache eviction can shorten this).
Product import stamps use _owwc_cost_import; the last import reference is user meta
owwc_last_import. CSV imports change current product costs, not existing order costs.
Review metadata includes WordPress user ID and time.
Guide progress uses owwc_guide_v1 user meta. owwc_guide_report stores the latest
completed report date/ranges/counts/currency; owwc_guide_review stores the latest
review ID and change signature. All are local to each user and preserved on uninstall.
Owner-bound scan-ID transients and private owwc_manual_ financial/selection chunks
expire after one hour. Large CSV sources, duplicate checks and child preview batches
use private owwc_import_ transients with the original 24-hour preview/undo expiry.
Cache eviction can shorten availability. Uploaded CSVs use private PHP temporary
storage and are never placed in public uploads. Optional local interface activity
and dismissal preferences are stored per WordPress account; no telemetry is sent.
Contextual suggestions appear at most once per browser-tab session, shared across
reports and imports. A site/account-scoped flag in sessionStorage survives reloads
and navigation in that tab. If sessionStorage is unavailable, suggestions stay
hidden. Continuing a Free workflow hides the card for that session; "Hide this
suggestion" saves a persistent preference for that suggestion type.
Deactivation and uninstall preserve settings and order reviews.
Never delete native WooCommerce orders or costs to remove this plugin.

== FAQ ==

= Why is zero cost flagged? =
Native zero can mean unset. Confirm a genuine zero with an order-level cost of 0.

= Why did changing settings not alter old orders? =
Existing expense snapshots stay unchanged. Use a deliberate per-order override.

= Does Free stop at 5,000 orders or 100 product-cost rows? =
No. Larger manual reports select and verify IDs in batches, calculate 50 orders
per request and retain frozen results on the server. Completed results show 25
orders per page, grouped by review priority and order ID. Stop pauses the browser;
Resume manual scan continues within the original one-hour window. Keep the page
open while working. Incomplete, expired or failed scans do not show complete totals.
After editing an order from a large report, run a fresh scan for updated totals.

Manual CSV imports have no paid row boundary. Review every preview page and confirm
before applying; larger files continue in bounded preview and write requests. CSVs
can be up to 8 MiB, or the lower server upload limit. Large-file records also have a
16 KiB safety budget. Nothing applies until the complete preview validates. Ordinary
settings, costs changed by another editor, and historical order costs stay protected.

Server limits remain: one-hour report expiry, 128 MiB of large-report row storage,
8 MiB of report metadata/aggregates and 1 MiB per retained report batch. Complex
orders or limited hosting can reach these budgets sooner. Use a smaller date range
or CSV when necessary; these are resource guards, not a paid upgrade requirement
or a promise of unlimited throughput.

= Does deleting the plugin remove order data? =
No. It deliberately preserves settings and reviews for a safe reinstall.

== Updating a direct installation ==

Back up first. Replace Pro with 1.9.4 if you use it, then replace Free with 1.9.7.
Use Plugins > Add New > Upload Plugin and choose Replace current with uploaded.
Do not uninstall the plugins first. The existing plugin folders, settings, order
reviews and product costs are preserved. Run fresh reports after updating.
On a new site, install Free first, then Pro. Keep only one Free edition active.

== Changelog ==

= 1.9.7 =
* Use OrderWorth consistently in plugin folders, entry files, translations, updater identity, hooks and internal identifiers.
* Retain the input-sanitization fixes and Free continuation improvements from 1.9.6.


= 1.9.6 =
* Validate and sanitize every CSV field before retaining deferred rows or source chunks.
* Reject malformed SKUs, overflowing product IDs and invalid costs without changing product identity or values.
* Preserve preview, confirmation, guarded import and undo workflows.

= 1.9.5 =
* Hide contextual suggestions after continuing a Free workflow, while retaining persistent dismissal.
* Show at most one contextual suggestion per browser-tab session across workflows and page loads.
* Add a Free/Pro comparison table and concise workflow cards with expandable details.

= 1.9.4 =
* Reject malformed refund-review and CSV option values before actions; use orderworth.com in Free.

= 1.9.3 =
* Reject malformed confirmation and preference flags before changing stored data.

= 1.9.2 =
* Align the matching security-maintenance pair; all Free functionality is retained.

= 1.9.1 =
* Preserve saved add-on financial adjustments and exclude affected estimates when their processing is unavailable.
* Reject malformed report identifiers and dates, and safely encode navigation parameters.
* Correct direct-to-directory migration instructions.

= 1.9.0 =
* Continue larger manual reports in bounded requests with private frozen rows and complete totals.
* Import beyond 100 product-cost rows with staged previews, guarded apply and the original undo window.
* Make missing-data reason counts filterable without changing order eligibility.
* Add dismissible local workflow guidance while preserving Free manual actions.
* Keep older Pro companions usable for existing small reports; matched Pro 1.9.0 adds advanced large-report views.

= 1.8.0 =
* Keep the shared header within narrow screens when text is enlarged.
* Include stable order-line identities for the separately installed Pro returns workflow.
* Explain stale returns reviews and mismatched actual-expense currencies when Pro supplies them.
* Preserve existing Free features, saved settings, manual reviews and historical order costs.

= 1.7.1 =
* Reject malformed or unfinished quoted CSV fields before product-cost import previews.
* Preserve valid CSV imports, confirmation, guarded undo and existing settings.

= 1.7.0 =
* Guard native product-cost changes against concurrent cost imports while preserving unrelated product edits.
* Keep all Free reporting, method rules, small imports and reviewed order costs available.
* Support the matched Pro 1.7.0 workflows; update Free first.

= 1.6.0 =
* Add report lifecycle extension points for matched Pro report packs.
* Preserve Free features, calculation rules, settings and reviewed order costs.

Earlier release history is included in changelog.txt.
