WP Referral Clarity user guide

WP Referral Clarity sits on top of AffiliateWP and explains your referrals in plain language, to you and to your affiliates. It only reads AffiliateWP’s data. It never changes a referral’s status, so everything here is safe to explore.

Requirements

WordPress 6.5 or newer and PHP 8.0 or newer.
AffiliateWP installed and active. Without it, Referral Clarity shows a notice and stays dormant.

Once it’s active, a Referral Clarity menu appears in wp-admin and the first dashboard snapshot starts building in the background.

The dashboard

Referral Clarity → Dashboard shows today’s revenue, referral count, conversion rate, pending count, this month against last month, and anything waiting on the Anomalies screen.

Referral Clarity dashboard, top row — The top row of the dashboard

Further down is a 30-day revenue chart and your top affiliates by revenue.

Referral Clarity 30-day revenue chart and top affiliates — The 30 day chart and top affiliates

These numbers come from a snapshot, not a live query, so the dashboard stays quick on large programmes. The snapshot refreshes every 60 minutes by default. Click Refresh now in the top right to update it straight away.

Reports

Referral Clarity → Reports always runs live. Combine any of these filters: status, date range, affiliate, campaign, tier, product and referral source.

Referral Clarity report filters — The report filters

Every row in the results carries the same plain-language explanation your affiliates see.

Referral Clarity filtered report results with explanations — Filtered results with an explanation for each referral

Save, share and schedule a report

Apply the filters you want to keep.
Scroll to Save as report and give it a label.
Optionally pick a digest frequency (daily, weekly or monthly) and add recipient emails. The report is rebuilt from live data each time it’s sent.
Optionally tick Share with other admins.
Click Save report.

Saved reports sit in a table at the bottom of the screen. Open one with a click; the person who created it can delete it.

Export

With a filter applied, two buttons appear above the results:

Export CSV downloads the filtered rows.
Export PDF opens a print-ready page in a new tab and your browser’s print dialog. Choose Save as PDF to get the file. The logo, colour and footer come from Settings.

Anomalies

Referral Clarity → Anomalies lists patterns worth a second look. It never blocks, rejects or changes a referral, and AffiliateWP’s own fraud settings keep running separately.

Three patterns are checked on the same schedule as the dashboard:

Rapid repeat conversions: an unusually high number of referrals from one affiliate in a short window.
Referrer and referee match: the customer’s name or email domain matches the affiliate’s own, a common self-referral pattern.
Volume spike: an affiliate’s referrals for the day are a large multiple of their usual daily average.

Click View referral to open it in AffiliateWP, or Mark reviewed when no action is needed.

Status explanations

This is the wording shown wherever a referral status appears. Open Referral Clarity → Status Explanations.

Editing a status explanation in Referral Clarity — Editing the wording for one status and context

Each status (Pending, Unpaid, Paid, Rejected and Forced Pending) has a card. Some have context variants, for example a pending referral held for a return window versus one held for a manual check.

Edit the admin wording and the affiliate wording separately. Name your real return window, payout day or review process.
Add an estimated resolution rule, such as order_date + return_window_days, so affiliates see an expected date instead of just “pending”.
Untick Active to switch a row off; the next best match is used instead.
Use Add a new context for a hold reason specific to your store.

Changes show up everywhere as soon as you save.

Settings

Referral Clarity → Settings has three groups.

Setting	What it does
Snapshot refresh interval (minutes)	How often the dashboard snapshot rebuilds. Default 60.
Forecast horizon (days)	How far ahead the payout forecast looks. Default 30.
Default digest recipients	The addresses filled in when you schedule a report.
Allow affiliates to opt into their own performance digest	Shows the opt-in on each affiliate’s Settings tab. Off means they never see it.
Logo URL, Primary color, Export footer text	Branding for PDF and CSV exports.
License tier	Leftover option; it doesn’t change anything. Every feature is included in every licence.

What your affiliates see

In AffiliateWP, pending referrals don’t normally appear in an affiliate’s area at all. With Referral Clarity, a panel at the top of their Referrals tab shows their approved-but-unpaid total and each pending referral with its reason and, where you’ve set a rule, an expected date.

Affiliate-facing Referral Clarity panel with a pending referral — The affiliate panel showing a pending referral

Their referral history gets a Why column with the same explanations.

Affiliate referrals table with the Why column — The Why column in the affiliates referrals table

If you’ve allowed it, affiliates can opt into their own digest email from their Settings tab.

For developers

The plugin exposes read-only REST endpoints for the dashboard, referrals, status explanations, anomalies, a payout forecast and cohort data. The forecast and cohort data are only available this way, not on an admin screen. Most endpoints are admin-only; logged-in affiliates can read their own referral data.

Questions

Who can see the admin screens?

Anyone with AffiliateWP’s manage_referrals capability.

Why is the dashboard behind?

It reads a snapshot. Click Refresh now, or lower the refresh interval in Settings.

What happens if I deactivate it?

AffiliateWP carries on exactly as before. Deleting the plugin removes its own tables and settings, never AffiliateWP’s data.