=== IDSource Referral & Cashback Manager ===
Contributors: idsources
Tags: referrals, cashback, referral manager, csv export
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Manage customer referrals and cashback rewards in WordPress — submissions, approval workflow, tiered payouts, and CSV export.

== Description ==

IDSource Referral & Cashback Manager is a complete referral and cashback system for WordPress. Let your customers refer friends through a simple front-end form, then review, approve, and track every referral from a dedicated manager portal — no coding required.

Configurable cashback tiers automatically calculate rewards based on the final job value, so approving a payout takes seconds. Managers get their own front-end login, and every action is recorded for a clear audit trail.

Add the included shortcodes to any page to display the referral form, manager portal, and login. Everything works with any theme.

**Key features**

* Public referral submission form with consent and terms confirmation.
* Front-end manager portal to review, filter, and update referrals.
* Configurable cashback tiers based on the final job value.
* Referral status workflow (New, Quoted, Booked, Completed, Approved, Paid, Rejected).
* One-click CSV export of referral data.
* Email notifications for submissions, approvals, and payouts.
* Dedicated Referral Manager user role with its own front-end access.
* Built-in anti-spam protection on the public form.
* Audit log of manager actions.
* WordPress personal data exporter integration.
* Conditional uninstall cleanup — your data is only removed if you choose.

== Installation ==

1. Upload the `idsource-referral-cashback-manager` folder to `/wp-content/plugins/`.
2. Activate `IDSource Referral & Cashback Manager` from the WordPress Plugins screen.
3. Create a public referral page and add `[idsource_referral_form]`.
4. Create a manager login page and add `[idsource_referral_login]`.
5. Create a manager portal page and add `[idsource_referral_manager]`.
6. Go to `Referral Manager -> Settings`.
7. Configure cashback tiers, email settings, login URL, terms URL, and manager URL.
8. Assign the `Referral Manager` role to manager users, or grant the custom capabilities manually.

The settings page includes a `Shortcodes & Pages` help section with copyable shortcode fields, a setup checklist, and a `Create Required Pages` button.

The page creation action creates missing pages and updates existing required pages to use the current canonical shortcode:

* Referral Form: `refer-a-friend`, `[idsource_referral_form]`
* Referral Manager: `referral-manager`, `[idsource_referral_manager]`
* Referral Login: `referral-login`, `[idsource_referral_login]`

If a required page already exists and contains the current shortcode, it is reused. If it exists without the current shortcode, the page content is replaced with the canonical shortcode. The action updates `Login URL` and `Manager URL` for created, reused, or updated pages. `Terms URL` remains reserved for referral terms or conditions.

The referral form page does not require a stored URL setting. It only needs a page containing `[idsource_referral_form]`. The Manager and Login URLs are stored because they are used by access and redirect flows.

== Frequently Asked Questions ==

= Do customers need a WordPress account to submit a referral? =

No. The referral form is public. Anyone can submit a referral without logging in.

= Who can access the manager portal? =

Only users with the Administrator role or the dedicated Referral Manager role can view and update referrals through the manager portal.

= Does the plugin collect friend email or phone details? =

No. The public referral form collects the friend's name and area only.

= Does the plugin collect bank details? =

No. Cashback payment is handled manually outside the plugin.

= How is cashback calculated? =

Cashback is calculated from the final job value using the configured cashback tiers.

= Does the plugin send emails automatically? =

The plugin sends an admin notification and a referrer confirmation after a successful referral submission. Cashback approved and paid emails are optional settings.

= Does the plugin include CSV import? =

No. CSV export is included; CSV import is not available in this version.

= Does the plugin support WordPress personal data export? =

Yes. The plugin registers a WordPress personal data exporter for referrals matching the requester's referrer email address.

= Does the plugin support WordPress personal data erasure? =

Not in this version. Referral records are operational business records used for cashback, audit history, and dispute handling, so erasure is intentionally deferred until a clear retention and anonymization policy is in place.

= Does the plugin work with any theme? =

Yes. The form, manager portal, and login are added to standard WordPress pages using shortcodes, so they work with any theme.

== Screenshots ==

1. Referral Manager dashboard — track every referral with live status counts, cashback amounts, search, date filtering, and one-click CSV export.
2. The public referral form your customers use to submit a friend, with consent and terms confirmation.
3. Reviewing and approving a referral — update status, record the final job value, add internal notes, and confirm the cashback payout.
4. Plugin settings — configurable cashback tiers by job value, email notifications, and page links.

== Changelog ==

= 1.0.0 =

* Initial public release.
* Public referral submission form.
* Referral management interface.
* Cashback tracking.
* CSV export.
* Privacy tools.

== Upgrade Notice ==

= 1.0.0 =
Initial public release.
