=== ShareCrew — Creator Profit-Share for WooCommerce ===
Contributors: wpshelf
Tags: woocommerce, affiliate, creators, influencer, commission
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.1.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Share a percentage of each order's profit with the creators who send you orders — computed from your own cost data, not revenue.

== Description ==

ShareCrew gives your WooCommerce creators a link and, if you want, a
discount code, credits the orders they send, and shares a percentage of each
order's **profit** — not its revenue — with them. Maturation, refunds,
statements and payout files are handled for you.

**Requires WooCommerce 8.5 or newer, active** (order attribution). WooCommerce
10.3 or newer is recommended so the Costs card can read WooCommerce's own
Cost of Goods Sold field directly; on an older WooCommerce, ShareCrew still
works from a product cost meta key, a category margin, or a global margin
you set.

= How a creator gets credited =

ShareCrew reads several signals and picks the strongest one, in this order:

1. **A typed code** — a real WooCommerce coupon the creator owns. Most
   short-form video traffic never clicks anything; a viewer types the code
   they saw, so the code is the primary signal, not a fallback.
2. **The referral link** (`/go/{handle}`), which sets a first-party cookie
   on a dedicated, never-cached redirect, or a `?cr=` URL parameter picked
   up by a small client-side script when the landing page itself was served
   from cache.
3. WooCommerce's own order-attribution data, when neither of the above is
   present.
4. A **repeat-customer lock**: for a number of days you choose, a customer's
   later orders are credited to the creator who first brought them, even
   with no code or cookie on the later order.
5. A manual assignment you make yourself on the order.

Exactly one creator is credited per order, and every commission row records
which of these signals won.

Codes are optional. With **links only** switched on, ShareCrew creates no
coupons, no audience discount exists, and every screen, email and the public
program summary speak only of the link; orders are credited by the link,
WooCommerce's attribution data and the repeat-customer lock. Switching codes
off expires the creators' coupons without deleting them, and switching back
restores them.

= Who pays for a code's discount =

A setting decides who carries the discount a creator's code gives:

* **The store** (the default): the code gives the program's discount, and the
  share is worked out on the profit after it, so the store and the creator
  each carry part of it.
* **The creator**: each creator picks their own code's discount, a whole
  percent inside a range you set, and pays for it out of their share. The
  share is worked out as if the code had not been used, then the discount
  comes off it — never below zero, and never carried to another order. Your
  margin on the order is the same with or without the code. Orders credited
  by link carry no code and keep the full share.

Changing who pays, or the range, re-applies the rules to every live creator
coupon at once.

= What "profit" means, and what your store must provide =

A commission can be based on **profit**, on plain **revenue**, or on a
**fixed amount per order**. The basis applies to the whole program; the rate
comes from the creator's tier and can be overridden per creator, product or
category.

In profit mode, ShareCrew builds a breakdown for the order: the price paid,
minus your product cost, an estimated share of shipping and packaging, an
estimated payment-gateway fee, and the cost of any gift item — and shares
your chosen percentage of what is left. It reads your product cost from
WooCommerce's own Cost of Goods Sold field where that WooCommerce feature is
active, or from a cost custom field, a per-category margin, or a global
margin you set — in that order, and it always shows which one supplied a
given line.

**An unknown cost is never treated as zero.** A line whose cost ShareCrew
cannot find puts that commission **on hold**, naming the product, unless you
have explicitly opted to assume a stated default margin instead. A
commission is also held (and capped) if the computed amount would exceed a
safety ceiling you set as a percentage of the order's revenue — this is a
guard against a data error, not a normal outcome. The Settings screen states
plainly how many of your products have a cost ShareCrew can read, because a
profit-share program computed on missing cost data quietly overpays on
exactly the orders that lost you money.

= Payouts: files and store credit — it does not move money =

ShareCrew does not connect to PayPal, Stripe, your bank, or any payment
processor, and it never will move money on your behalf in this version.
What it does:

* Builds a payout run from every creator's approved, matured commissions.
* Exports a **PayPal CSV** file (ready to upload to PayPal's own mass-payout
  tool) and a **bank-transfer CSV** file (holder, IBAN, BIC, amount), each
  with a numbered statement per creator.
* Issues **WooCommerce store credit** directly, as a coupon restricted to
  the creator's own account, with an optional bonus percentage for choosing
  credit over cash.
* Records what was paid on a numbered, sequential statement per creator,
  carrying your self-billing text for your bookkeeper.

You upload the CSV file to PayPal or your bank yourself, and mark the run
paid once you have; a payout run and marking it paid are always two separate
actions, both recorded with who did it.

= The cache requirement, stated plainly =

The referral cookie is set only on the `/go/` redirect, and that response
must never be served from cache. A full-page cache or CDN that caches
`/go/` — or strips its `Set-Cookie` header — will serve the first visitor's
cookie to everyone after them, silently. ShareCrew's Settings screen names
the exact path to exclude for Cloudflare, LiteSpeed and nginx, and a daily
health check fetches your own `/go/_probe` URL to confirm the exclusion is
still in place, naming the caching layer and the fix when it is not. Codes
are unaffected by this: a typed code is credited whether or not the cookie
ever gets set.

= Privacy and consent =

* The click log stores a salted, one-way hash of the visitor's IP and
  browser string, the referring host, the landing path, a coarse country
  and device class — never the IP or user-agent string itself — and it is
  pruned after the retention period you set.
* **Tracking mode is a setting you choose during setup**, honestly:
  "Always" sets the referral cookie unconditionally; "Only with consent"
  waits for a marketing-category consent signal before setting it; "Code
  only" never sets a cookie at all and relies on typed codes and manual
  attribution. ShareCrew does not decide your legal posture for you.
* **"Only with consent" is the default.** It reads the WP Consent API
  (`wp_has_consent( 'marketing' )`), which consent plugins such as Complianz
  or CookieYes provide. Without such a plugin, a link click never sets the
  cookie: codes and the repeat-customer lock credit orders as usual, and a
  link is credited only when WooCommerce's own order attribution recorded
  the visit.
* A creator's own data can be exported and erased through WordPress's
  built-in Tools → Export/Erase Personal Data screens. Erasure replaces the
  creator's name, handle, platforms, application text, tax profile and
  payout details with a placeholder; commission and payout amounts are kept
  as your accounting record, the same way WooCommerce keeps order records
  after a customer erasure.
* ShareCrew's own database holds no customer name, email or address — a
  creator's own account pages never show a customer's identity, only an
  order number and date.
* ShareCrew has no backend of its own: it calls no ShareCrew-hosted or
  third-party service, and it makes **no requests to any outside service**.
  Everything it computes runs on your site, against your own WooCommerce
  data. The one HTTP request it makes at all is a daily fetch of your own
  site's own `/go/_probe` URL — a same-origin check of your own cache
  layer, described above, never a call to WP Shelf or anyone else. Creator
  avatars in the portal and on the opt-in leaderboard come from WordPress's
  own avatar setting, which by default the visitor's browser loads from
  Gravatar.

= What it does not do =

ShareCrew is not an affiliate network, an influencer CRM, a content-approval
tool, a customer refer-a-friend scheme, or a payment processor. It does not
move money to a creator directly; it prepares the files and the store-credit
coupon, and a person carries out the transfer. It does not decide your
tracking-consent posture, generate a legal terms page for you (it offers a
starting-point terms skeleton, clearly labelled as not legal advice), or
handle any tax filing or withholding. It flags a code whose recent use looks
unusual — an unexplained spike in uses, or referrals from a known coupon-site
domain — for you to review; a flag is information for a human, never an
automatic block or void.

= When a creator leaves =

When a creator leaves the program — archived by you, leaving on their own,
or erased through WordPress's privacy tools — a negative balance (refunds that
arrived after they were paid) is written off with a recorded ledger row, so
nobody is asked to pay money back. The exception is a creator you archive as
**removed for fraud**: their balance is kept as it is, and approving them
again later clears that mark.

= Status =

ShareCrew runs on a live WooCommerce store. Its money rules are covered by
an append-only ledger with checked invariants, twenty-nine profit-share
fixtures verified to the cent, and a property test over randomised order,
refund and payout sequences. Questions and reports are welcome in the
support forum.

== Installation ==

1. Install and activate the plugin. WooCommerce 8.5 or newer must already
   be active.
2. Open **WP Shelf → ShareCrew** in wp-admin and work through the
   getting-started checklist, starting with **Tracking mode** — this is a
   legal-posture choice, not a default to leave alone.
3. On the **Costs** card, check how many of your products have a cost
   ShareCrew can read, and set a category or global margin for the rest, or
   choose revenue-share mode instead.
4. On the **Attribution** card, exclude `/go/` from your cache and CDN
   rules, using the exact pattern the screen prints for your setup.
5. Publish a page with the ShareCrew apply-form block or the
   `[sharecrew_apply]` shortcode, then approve applications under
   **Applications**. Approval issues the creator's coupon code (unless you
   run links only) and referral link.
6. On the **Payouts** card, choose which payout methods you offer and your
   payout schedule and minimum.

== Frequently Asked Questions ==

= My translation plugin only translates some of ShareCrew's strings =

Some translation plugins capture a string only when it is displayed on a
page view. Many ShareCrew strings appear only in emails sent from scheduled
jobs, so such a plugin never sees them. Hook
`do_action( 'sharecrew_warm_strings' )` on `wp_footer` on one page of your
site: it renders every portal and email string invisibly, so they can be
captured and translated. Third-party strings can be added through the
`sharecrew_warm_strings_extra` filter.

= Link clicks are not being credited =

If Tracking mode is "Only with consent" (the default), the cookie is set
only once a WP Consent API plugin reports marketing consent; with no such
plugin installed, it is never set. If that is not the cause, your page cache
may be caching the `/go/` redirect or stripping its cookie.
Exclude paths starting with `/go/` (or your configured link base) from every
cache layer — Cloudflare cache and Set-Cookie transform rules, LiteSpeed's Do
Not Cache URIs, nginx `proxy_cache` / `fastcgi_cache`. ShareCrew's health
check tests this daily and names the layer and the fix. Creator codes are
credited regardless of your cache configuration.

= Why is a commission on hold? =

Almost always one of two reasons, and both are named on the commission:
ShareCrew could not find a cost for a line on the order (check the Settings
→ Costs card for which products are missing a cost, or opt into an assumed
default margin), or the computed amount exceeded the safety ceiling you set
as a percentage of order revenue, which holds and caps the row so a data
error surfaces instead of paying out silently. A held commission can be
released once the underlying cost or setting is corrected.

= Does ShareCrew pay tax on a creator's behalf? =

No. ShareCrew records what each creator was paid on a numbered statement
per payout, which carries your self-billing text for your bookkeeper. It
does not calculate, withhold, remit or file any tax, and it does not tell
you whether a creator is a business or an employee. Take tax advice for your
own program.

== Screenshots ==

1. Commissions, with one order's breakdown open: each product's cost and where it came from (measured from WooCommerce's cost of goods, or estimated from your settings), shipping, packaging and the payment fee, then the profit, the creator's rate and their share.
2. The creator portal in My Account, on the Storefront theme: the creator's code, their link with its QR code, and their clicks, orders and earnings over the last 30 days. A creator sees order numbers and dates, never a customer's name or address.
3. Payouts → Due: what each creator is owed from matured commissions, grouped by payout method — bank transfer, PayPal or store credit. An amount below your payout minimum rolls into the next run.
4. A numbered statement for a paid payout, with the store as issuer, each commission it covers, the payout reference and your self-billing text.
5. Settings → Costs: how many of your products have a cost ShareCrew can read, which ones do not, and the order in which cost sources are tried. A commission on a product with no known cost is held rather than computed as if the cost were zero.
6. The Overview: attributed revenue, profit shared and profit per €1 of program cost over 30 days, top creators by profit, what needs attention, and the result of the daily check on the referral-link redirect.
7. A creator's Earnings screen on a phone: pending, available and paid totals, and each order with its status and the date it becomes available.

== Changelog ==

= 0.1.2 =
* Changing the link base in Settings now takes effect on the next page load.
  Before, links on the new base answered "not found" until permalinks were
  saved again.
* Links on a previous link base keep working: they redirect to the same
  creator's link on the new base, so links already shared or printed as QR
  codes do not break.
* Changed: saving on a ShareCrew admin screen now shows that it is working, then moves keyboard focus to the result, so you — and a screen reader — know at once whether the save worked. A failed save says so in a message you can dismiss, next to the form, instead of a paragraph above it.

= 0.1.1 =
* A refused request (a user without permission to manage ShareCrew) now
  answers 403 Forbidden instead of a server error.
* The creator detail screen's main link follows your link base setting
  instead of always showing /go/.
* Settings help text now matches what the plugin does: in Codes only mode a
  customer lock still credits an order and WooCommerce's order attribution
  is not read, and a payout run includes every commission payable when the
  run is created.

= 0.1.0 =
* First release. Attribution resolves a code, a
  referral link and cookie, WooCommerce's own order-attribution data, a
  repeat-customer lock, or a manual assignment, in that order, and freezes
  the reason onto each commission row.
* The profit-share engine computes a per-order breakdown from WooCommerce's
  Cost of Goods Sold, a cost custom field, a category margin or a global
  margin, with shipping, packaging and payment-fee estimates, and shares a
  percentage of profit or of revenue, or pays a fixed amount per order: one
  basis for the program, with the rate set by tier and overridable per
  creator, product or category.
* An unknown cost holds the commission rather than assuming zero; a safety
  ceiling on the computed amount holds and caps rather than paying an amount
  a data error produced.
* Commission and payout rows are append-only: a correction is a new row, and
  a paid row is never edited.
* Creator codes are real WooCommerce coupons the plugin owns and can rotate
  in one click.
* Payout runs export a PayPal CSV, a bank-transfer CSV, or issue WooCommerce
  store credit with an optional bonus, and record a numbered statement per
  creator; marking a run paid is always a separate action from creating it.
* Creators progress through tiers based on trailing profit generated, with
  per-creator, per-product and per-category rate overrides.
* Gift orders: an approved gift request creates a real, paid WooCommerce
  order with its own cost counted against the creator's tiers.
* Per-post links let a creator track a specific piece of content, with
  self-reported view and engagement figures, clearly labelled as
  self-reported.
* A daily leak monitor flags a code whose recent use looks unusual — a spike
  in uses with no click behind them, or referrals from a known coupon-site
  domain — for a human to review; nothing is voided automatically.
* Nineteen transactional emails cover the creator's and the merchant's side
  of the program, from application through payout.
* A WordPress privacy exporter and eraser cover a creator's own data;
  commission and payout amounts are kept as accounting records after
  erasure, the way WooCommerce keeps order records.
* The merchant console adds an Overview with program ROI, Creators,
  Applications, a Commissions screen with a per-order breakdown drawer, and
  Settings, under the shared WP Shelf admin menu.
* A public application form and a program-summary block/shortcode let
  visitors apply and read the program's terms without an account.
* Links-only mode: no codes and no audience discount, with every surface
  speaking only of the link; switching back restores the creators' coupons.
* Creator-funded discounts: each creator picks their code's discount inside
  a range you set and pays it from their share, never below zero.
* A negative balance is written off when a creator leaves, except for a
  creator removed for fraud; re-approval clears that mark.
* Compatible with WooCommerce's High-Performance Order Storage and
  block-based checkout.
