=== 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.10.18
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 ==

OrderWorth helps WooCommerce merchants review order-profit estimates, find missing costs and understand which orders need attention. Free includes manual reports, expense assumptions, order reviews and reviewed product-cost imports. It has no trial expiry, licence requirement or paid order-count limit. Advanced automation and comparisons are provided by the separate Pro add-on.

Keep a current backup and reconcile a few known orders against your records. 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.
* Simple global payment/shipping defaults and manual order expenses; conditional method rules belong to Pro.
* 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; optional sharing starts only after explicit consent.

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, reusable supplier mappings and explicitly confirmed
background product-cost imports, verified-fee CSV imports, recorded-fee review,
complete report packs and optional scheduled packs with alerts. Free keeps its
continued manual CSV imports and guarded undo without a paid row boundary.
Free runs locally with no license checks or custom updater. Free repository updates
are delivered through WordPress.org when available. Pro is a separately distributed
add-on; purchases, updates and written support are managed on the OrderWorth website.

== Installation ==

1. Back up your WordPress site with WooCommerce.
2. Enable WooCommerce native COGS and record product costs for new orders.
3. Upload and activate this ZIP.
4. The first individual activation opens OrderWorth > Cost assumptions. Confirm your expenses.
5. Optionally use Quickstart, then run a report and review missing data.
6. For a fresh pair, install the current Free release first, then matching Pro; keep both active.
7. For an existing pair, back up, replace Free first, then Pro, without uninstalling.
   Use the current matched pair for the complete workspace.
8. Pro needs initial licence activation for this site. Free does not need a licence.

= Can I keep the WordPress sidebar visible? =
Yes. OrderWorth opens in focus mode on its own screens. Use Exit focus mode in
the workspace header to restore the WordPress navigation. Enter focus mode turns
it back on. This choice is saved for your WordPress user on this site. Back to
WordPress always takes you to the dashboard. Other admin pages are unchanged.

== 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 ==

Reports run locally and go to authorized admin browsers. No optional sharing starts until a site administrator explicitly selects and saves a choice.
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.
On a single-site installation, 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. Optional local
workflow counts, recording consent and suggestion preferences use _owwc_experience_v1.
On multisite, these four records use separate keys for each site and WordPress account.
Previously shared network-wide records remain stored but are not read or copied
into the site-specific state. Count recording starts off on each site until you
opt in there; previous network-wide consent is not transferred. Single-site keys
and existing single-site choices remain unchanged. These records are 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 site and WordPress account; no telemetry is sent.
Only one contextual suggestion card is shown at a time. Dynamic suggestions after
reports, imports and fee reviews appear at most once per workflow type in a
browser-tab session. Separate site/account/workflow flags in sessionStorage survive
reloads and navigation in that tab; if sessionStorage is unavailable these dynamic
suggestions stay hidden. Completed-report and import counts used to recognise the
current task exist only in the current page's memory and are not transmitted.
The expense-settings preview remains available until it is dismissed or Pro previews
are hidden. Continue with Free removes that card for the current page; Hide this
suggestion saves a persistent preference for that workflow type. Optional local
workflow counting remains a separate opt-in and sends no telemetry.

Pro preview visibility and an explicitly remembered workflow use the site/account-scoped
_owwc_pro_journey_v1 user-meta record. The choice stores the workflow name, creation
and expiry times, a site-binding hash and a revision used to reject stale forms.
Opening a preview stores no task. A chosen task is no longer usable after seven
days; scheduled cleanup removes it when WordPress cron runs, which can be later.
Forget this task removes the choice early. WordPress privacy export includes this
state; privacy erasure clears the choice and visibility preference while retaining
a minimal revision tombstone to reject stale forms. Uninstall removes this journey
record and its expiry hook on each site (including all sites on multisite), while the financial, guide and optional
workflow-count records described above retain their existing preservation rules.
The external pricing link contains no chosen workflow or store identifiers and
uses a no-referrer policy. The website processes ordinary request data as described
at https://orderworth.com/privacy.html .

Deactivation and uninstall preserve settings and order reviews.
Never delete native WooCommerce orders or costs to remove this plugin.

Review reminders use local, site/account-scoped _owwc_review_request_v1 user meta: the first completed nonempty report time, up to three report dates, and your reminder choice. A prompt may appear only in OrderWorth after 30 days and reports on three different days, once WordPress confirms the public listing through its regular update metadata. There is no extra network request or positive-rating filter. Choose Leave an honest review, Remind me in 30 days, or Don’t ask again; preferences remain under Help & preferences. Choosing review stops prompts without checking whether a review was posted. Choosing review or never stops further reminder-date collection. WordPress privacy export and erasure cover this record; uninstall removes it from each site, including all sites on multisite. Optional workflow-count consent remains separate.

== FAQ ==

= Is the Free plugin a trial? =
No. Its included features do not expire or require a purchase. Large manual
reports and product-cost imports continue in batches; the batch sizes are not
paid usage quotas. Upload, storage, date-range and temporary-data safeguards
still apply to protect the site and keep incomplete results from being shown
as complete. The separate Pro add-on provides additional tools.

= 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. Local
focus-mode and upgrade-preview preferences are removed; financial data stays.

== Updating a direct installation ==

Back up first. Replace Free with the current release first, then replace Pro with its matching release if you use it.
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.

== Optional external service ==

OrderWorth Free works without an account, domain sharing or a newsletter signup.
After all Quickstart lessons are marked read, a final optional step offers separate
domain sharing and email signup. Both choices start unchecked and the email field
starts empty. Skip and finish sends nothing; Save choices and finish sends only
the choices you select. Both actions open Profit overview. Optional service errors
leave your lesson progress complete and show a status with a link to Privacy choices.
Reading the lessons does not confirm that costs are saved or reports are accurate.

You can change these choices later in Help & preferences > Privacy choices.
There, Continue without sharing sends nothing. Replaying Quickstart preserves
saved choices and does not repeat an already handled invitation.

Only selecting and saving a choice sends an HTTPS request to
https://orderworth.com/newsletter-api/v1/plugin-welcome/:
* Domain sharing: only the installed site's public domain (no URL path/query), to know
  which sites have chosen to report using OrderWorth.
* Email signup: the address you enter and this installation's Free/Pro edition,
  for OrderWorth tips, release news and offers. Email-only signup does
  not send the site domain. Confirm your email to join; existing subscriptions
  and preferences are unchanged. Any newsletter includes unsubscribe/preferences.
* Connection controls: a random ID and protected credential, consent version,
  request time, consent and latest-report timestamps. The server also receives
  normal network metadata such as the requesting IP address. No orders,
  customers, financial figures, WP/PHP versions or plugin lists are sent.

Selected details refresh at most weekly; email edition changes may refresh after
an hour. A changed site address pauses sharing. An unconfirmed request expires
locally after 24 hours and needs cancellation and fresh choices before retrying.
Stop controls remove the selected details locally before requesting remote removal.
Failures expose a Retry control. A pending enrollment is cancelled in full.
Stopping email sharing cancels this connection's pending signup/edition link;
a confirmed newsletter subscription is separate: use Unsubscribe in an email.

Deactivation clears scheduled refreshes and retains choices for reactivation.
Uninstall sends no request and clears local email/domain/credentials under the
connection lock, retaining a nonpersonal revision to reject old consent forms.
If another request holds the lock, local choices may remain; stop sharing and retry
before deleting. Remote inactive records expire under the service retention policy.
Stop sharing before uninstalling to request remote deletion. Confirmed newsletters
are not cancelled by deactivation, deletion, or cancelling a Pro licence.

Email-matched local choices participate in WordPress personal data export/erasure.
Credentials and connection IDs are never included in the export. Local workflow
counts, financial reports and the Pro licence remain independent of these choices.

Service privacy and retention: https://orderworth.com/privacy.html#plugin-choices
Service terms: https://orderworth.com/terms.html

== Changelog ==

= 1.10.18 =
* Keep focused workspace buttons readable in dark mode with a visible keyboard outline.
* Keep report batches on one consistent set of expense assumptions, thresholds and timezone; require a fresh scan after settings change.
* Share the same configuration checks across small and large reports.

= 1.10.17 =
* Match the Pro maintenance release for overlapping background work; Free features and saved data are unchanged.

= 1.10.16 =
* Use the bundled OrderWorth website icon in the workspace and WordPress menu.
* Matched Free and Pro release; reporting, licence and update behavior is unchanged.

= 1.10.15 =
* Match the Pro background-report progress update; existing Free features and saved data are preserved.

= 1.10.14 =
* Clearly identify activated Pro and separate its working shortcuts from Free upgrade previews.
* Improve current-page navigation and keyboard feedback across the workspace.
* Keep anchored section headings visible below the focus-mode toolbar.

= 1.10.13 =
* Match the Pro update-controls maintenance release while retaining existing Free functionality.

= 1.10.12 =
* Match the Pro updater maintenance release while retaining accessible navigation, network preference cleanup and localized import counts.

= 1.10.11 =
* Remove the legacy underline from workspace navigation while keeping active-state styling and keyboard focus.
* Remove local focus/upgrade preferences and their expiry events from every site on multisite uninstall, preserving financial data.
* Translate product and conflict counts correctly for singular and plural import/undo results.

= 1.10.10 =
* Clarify grouped navigation with consistently indented child links and active states.
* Keep locked Pro tools out of navigation, show useful previews for saved Pro URLs, and group Shared reports with Reporting.
= 1.10.9 =
* Add a local, dismissible review reminder after a month of meaningful report use.
* Keep review choices inside OrderWorth; no ratings, report contents or reminder data are transmitted.
* Clarify backup and known-order checks; update WooCommerce tested metadata.

= 1.10.8 =
* Offer separate optional domain sharing and email signup after all Quickstart lessons are read, with Skip and finish and Save choices and finish actions.
* Keep completed lessons and existing privacy choices intact; optional service errors do not prevent opening reports.
* Retain Privacy choices for later changes and keep first activation focused on cost assumptions.

= 1.10.7 =
* Separate optional domain sharing and email signup in Free, with local-first withdrawal, explicit consent and privacy controls. No signup is required for reports.
* Matched release retains focused activation, existing licence activation and financial calculations.

= 1.10.6 =
* Open OrderWorth from its own WordPress menu.
* Use focus mode with a visible exit control and a preference saved for each user on this site.
* Redirect the first successful single-plugin activation to cost assumptions; preserve bulk activation, existing-user preferences and ordinary WordPress navigation.

= 1.10.5 =
* Fix manual report continuation above 5,000 orders when Pro is not installed, while preserving checks for changed settings and saved rules.
* Distinguish an empty report filter from a period with no eligible orders.
* Clarify that Free is not a trial and its batch sizes are processing safeguards, not paid usage limits.

= 1.10.4 =
* Added Expense rules, Profit insights and Scheduled reports Pro previews with genuine, labelled example screenshots and setup steps.
* Relevant suggestions stay inside OrderWorth and can be dismissed; each account can hide or restore the Pro preview navigation.
* An explicit continuation remembers the selected task locally for seven days. Activation can return to that Pro setup screen without saving settings or enabling scheduled work.
* Get Pro, Activate Pro and Open actions reflect the installed add-on and local activation state. Free workflows and the existing licence contract remain unchanged.


= 1.10.3 =
* Require a successful site licence activation before using Pro tools; keep Free reports and saved financial data available.

= 1.10.2 =
* Report controls become available only after their submit handler is ready; keyboard/native fallback preserves the workspace route.
* Move reusable conditional payment/shipping expense rules to the separate Pro add-on. Keep manual expenses, global defaults and recorded snapshots in Free. Preserve stored configuration; unavailable rules require explicit manual review.

= 1.10.1 =
* Keep current installation and Quickstart instructions version-neutral.
* Clarify Free manual CSV imports and Pro supplier mappings/background imports.
* Scope Quickstart records and optional workflow preferences to each multisite site and account.
* Preserve single-site choices and unused legacy multisite records without transferring recording consent.

= 1.10.0 =
* New navy and teal workspace with grouped navigation and a responsive mobile menu.
* Profit estimates show included order coverage and expense assumptions beside the result.
* Review actions precede expandable cost details; explanatory text is easier to read.
* Scheduled-report preview now shows a clearly labelled fictional finished report.
* Existing calculations, review protections, settings, licensing and scheduled-work consent remain unchanged.


= 1.9.9 =
* Added local Pro workflow examples and clearer comparison and schedule navigation.
* Clarified automatic annual renewal and cancellation for new subscriptions.

= 1.9.8 =
* 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.
