007AJ Referral Affiliate 1.0.0 Documentation

Run your own affiliate program inside WordPress: affiliates apply, share referral links or coupons, earn commission on sales, and you pay them with a PayPal Mass Pay file.

1. Quick start

1. Activate the plugin and open Referral Affiliate > Setup Wizard.
2. Pick your commission (for example 20%), cookie lifetime, approval mode and emails. Leave Create pages ticked to create the Become an Affiliate and Affiliate Area pages.
3. Click Finish setup. Share the Become an Affiliate page with partners.

2. Affiliates

• Registration: shortcode [ajra_registration] or the Affiliate Registration block. Visitors create an account; logged-in users just apply. A hidden honeypot field stops simple bots.
• Approval: manual by default (status Pending). Turn on Auto-approve under Settings to activate new affiliates immediately.
• Statuses: Pending, Active, Inactive, Rejected. Only Active affiliates are tracked and earn.
• Admin: Referral Affiliate > Affiliates lets you add an existing user, edit status, custom rate, payment email and notes, approve/reject, and delete. Deleting is refused while the affiliate has unpaid or paid referrals; set them Inactive instead to keep payment history.

3. Tracking

• Links: https://yoursite.com/?ref=12, ?ref=username, or the pretty form https://yoursite.com/ref/12/ (also works after any page path, e.g. /shop/ref/12/). Change the variable and the format (ID or username) in Settings.
• A first-party cookie (default 30 days) remembers the affiliate. Credit setting: last referrer (default) or first referrer.
• Each tracked click is a visit. The IP address is never stored; only a 16-character salted hash that rotates monthly.
• Self-referrals are blocked: an affiliate's own clicks are not tracked, and orders whose customer account or billing email matches the affiliate are not credited (an order note explains why). You can allow them in Settings.
• Coupons (WooCommerce): edit a coupon and choose an Affiliate. Orders using it credit that affiliate even without a cookie; a linked coupon beats the cookie.

4. Commissions

Priority: product rate > affiliate rate > site default.

• Percentage applies to each product line's total after discounts.
• Flat site/affiliate rate pays once per order. A flat product rate pays rate × quantity.
• Exclude tax and Exclude shipping are on by default. When shipping is included, it earns the percentage rate (flat rates never pay on shipping).
• Per product (WooCommerce > Product data > General): rate type, rate, or No affiliate commission.
• Amounts are rounded to 2 decimals. Developers can adjust with the ajra_calculated_commission filter.

5. Referral statuses

Bulk actions report exactly how many rows changed and list any that could not change and why.

6. Integrations

• WooCommerce (classic and block checkout, HPOS compatible): referral created as Pending at checkout; Processing/Completed → Unpaid; Refunded/Cancelled/Failed → Rejected. A referral that is already Paid is never silently reversed: the order gets a note so you can review it. Partial refunds do not change the referral.
• Easy Digital Downloads 3.x: completed purchases create Unpaid referrals; refunded or revoked orders reject them.
• Paid Memberships Pro: the first checkout payment creates a referral; refunded/cancelled orders reject it. Renewal payments are not credited.
• Anything else: call ajra_add_referral( array( 'base' => 49.00, 'context' => 'myshop', 'reference' => 'ORDER-123', 'customer_email' => $email ) ). It uses the tracked affiliate and their rate, returns the referral ID (the same ID if that reference was already recorded) or a WP_Error. Change status with ajra_set_referral_status_by_reference( 'myshop', 'ORDER-123', 'unpaid' ). Hooks: ajra_referral_added, ajra_referral_status, ajra_affiliate_added, ajra_affiliate_status, ajra_payout_created, filter ajra_referral_args.

7. Payouts

1. Open Referral Affiliate > Payouts. Unpaid earnings are listed per affiliate (those below the minimum payout cannot be selected).
2. Click Download PayPal CSV. The file has no header and 5 columns: recipient email, amount, currency, unique ID, note, which is the format PayPal Payouts / Mass Pay accepts. The payment email falls back to the account email; the file is refused (and the affiliates named) if any address is invalid. Downloading never marks anything paid.
3. Upload the file in PayPal and send the payment.
4. Back in WordPress click Mark selected as paid. Each affiliate gets one payout record. This is idempotent: submitting the same form twice, or marking already-paid referrals, never pays twice and the message says how many were already paid.
5. Made a mistake? Undo on a payout returns its referrals to Unpaid.

8. Affiliate area

Shortcode [ajra_affiliate_area] or the Affiliate Area block. Tabs: Dashboard (unpaid and paid earnings, pending referrals, visits, conversion rate, rate), Referral URLs (with a generator for any page), Referrals, Visits, Payouts, Creatives (copy-ready HTML) and Settings (payment email). Every tab shows only the logged-in affiliate's own data.

9. Creatives

Referral Affiliate > Creatives: add text links or banners (image URL from your Media Library) with a destination page. Affiliates get the code with their own link inserted.

10. Emails

New application (to admin), approved and rejected (to the affiliate), and new referral (to the affiliate). Each can be switched off and edited under Settings. Placeholders: {name} {email} {site_name} {referral_url} {area_url} {admin_url} {amount}. Emails use wp_mail(), so any SMTP plugin (for example MailBolt SMTP) delivers them.

11. Reports and export

The Overview shows totals and a day-by-day table (earnings, referrals, visits) with bars for any date range. Earnings count Unpaid + Paid referrals. Referral Affiliate > Export downloads affiliates, referrals and unpaid-earnings CSV files. Cells that start with = + - @ are prefixed so spreadsheets do not run them as formulas.

12. Privacy

• Stored: affiliate profile (user, payment email, website, notes), referrals, visits (landing URL, referrer, hashed IP), payouts.
• Cookies: ajra_ref (affiliate ID) and ajra_visit (visit ID), HttpOnly, SameSite=Lax, for the configured number of days. Mention them in your privacy and cookie policy.
• No data is sent to any outside service. The plugin makes no remote requests.

13. Uninstall

Data is kept when the plugin is deleted, unless you turn on Settings > Uninstall > Remove data. Then all tables, settings and product/coupon meta are removed. Pages created by the wizard are left in place.

14. Requirements

WordPress 6.2+, PHP 7.4 to 8.5, MySQL/MariaDB with InnoDB. WooCommerce, EDD and PMPro are optional.

Changelog

1.0.0 Initial release.