ReCurr Pro Tutorial Series — Part 4: Affiliate Commissions & Payouts

ReCurr Pro feature — Requires an active ReCurr Pro licence (RECPRO-XXXX-XXXX-XXXX-XXXX) and the ReCurr Pro plugin installed alongside the ReCurr base plugin.

Once your affiliate program is live, referrals will start generating commissions. This tutorial covers the full referral tracking flow — from the moment a customer clicks a referral link to when the affiliate gets paid.

---

Before You Begin

• Your affiliate program is configured (Pro Tutorial 3)
• At least one affiliate is approved and has a referral code
• At least one commission program is active

---

Part A: How Referral Tracking Works

Understanding the tracking flow helps you troubleshoot issues and answer affiliate questions.

---

Step 1: The Referral Link

Every approved affiliate receives a unique referral code. Their referral link takes the format:

https://yourstore.com/?ref=CODE

When a potential customer clicks this link:

1. Cookie is set — A first-party, HTTP-only cookie is stored in the visitor’s browser, lasting for the configured cookie duration (default: 30 days)
2. Visit is logged — The click is recorded in the referral visits table with the URL, referrer, IP address, user agent, and UTM campaign data
3. Deduplication — Repeat visits from the same IP within one hour are not counted as separate clicks

Screenshot 1: Example referral link in a browser address bar, showing the ?ref= parameter.

---

Step 2: Attribution at Checkout

When the visitor completes a purchase:

1. Cookie check — The system reads the referral cookie to identify the affiliate
2. Coupon check — If no cookie, checks if the customer used an affiliate-linked coupon
3. Cookieless fallback — If enabled, matches by IP + user agent against recent visit records
4. Order meta stored — The affiliate code is saved on the WooCommerce order (survives asynchronous PayFast ITN callbacks). This works the same on the classic checkout and the WooCommerce Block Checkout
5. Self-referral blocked — If the buyer is the affiliate themselves (matched by user ID, email, or IP), no referral is created

Screenshot 2: Diagram showing the attribution flow: Click → Cookie → Checkout → Commission.

---

Step 3: Commission Calculation

Once the order is confirmed (status: completed or processing):

1. The system identifies the matching commission program based on the purchased product
2. Commission is calculated per line item:
   • Percentage: commission rate × line item total
   • Flat: fixed amount per qualifying item
3. A referral record is created with status Pending, for the affiliate who referred the sale — and for nobody else
4. The affiliate’s balance is credited

Example: 15% Commission on R159 Monthly Subscription

Event	Commission	Affiliate Balance
Initial sale	R23.85 (pending)	R23.85
Month 2 renewal	R23.85 (pending)	R47.70
Month 3 renewal	R23.85 (pending)	R71.55

Screenshot 3: Referral record showing the order, affiliate, commission amount, and pending status.

---

Step 4: Renewal Commissions

If the commission program has Recurring Commissions enabled:

1. Each successful subscription renewal payment is picked up (a declined renewal earns nothing)
2. The system looks up the original sale referral for this subscription
3. If found, a new renewal referral is created for the same affiliate
4. The recurring limit is checked — if set to 12 and this is renewal #13, no commission is generated

Renewal commissions follow the same holding period as initial commissions.

Affiliates on PayFast Split: renewal commissions go into your normal approve-and-pay-out queue, like any other affiliate’s, until renewal splits are turned on. First payments are still split at checkout. Renewal splits are off by default until a real PayFast renewal has shown an affiliate receiving the split; to turn them on, add this line with a code-snippets plugin or in your theme’s functions.php:

add_filter( 'crb_payfast_split_send_on_renewal', '__return_true' );

If a renewal carrying a split is then refused by PayFast, remove the line again.

Screenshot 4: Referral list showing an initial sale referral followed by several renewal referrals for the same subscription, with type column showing “sale” and “renewal”.

---

Step 5: The Holding Period

Commissions start with Pending status and remain pending for the configured holding period (default: 14 days). This protects against:

• Customers who request refunds shortly after purchase
• Fraudulent transactions
• Chargebacks

After the holding period, a daily cron job automatically transitions pending referrals to Approved status. Approved commissions become eligible for payout.

Status	Meaning
Pending	Within holding period — not yet eligible for payout
Approved	Holding period passed — eligible for payout
Paid	Payout has been processed
Rejected	Commission was clawed back (refund, fraud, or manual rejection)

Screenshot 5: Referral list showing referrals in different statuses: pending, approved, and paid.

---

Step 6: Refund Clawback

When an order is refunded or cancelled:

1. All pending and approved referrals for that order are automatically set to Rejected
2. The affiliate’s balance is reduced by the commission amount
3. The clawback is logged in the affiliate’s activity record

This is fully automatic — no admin action required.

A commission already paid through PayFast Split cannot be clawed back this way — PayFast has settled it into the affiliate’s account. It is flagged instead: noted on the order and listed under Refunded orders with unrecoverable split commissions on the Affiliate Reports screen, so you can recover or offset the amount with the affiliate yourself.

Screenshot 6: A referral record showing “Rejected” status with the reason “Order refunded”.

---

Part B: Managing Referrals

---

Step 7: View All Referrals

Navigate to Subscriptions > Affiliates and click on an affiliate to view their referral history. You can also view all referrals across all affiliates from the referrals tab.

The referrals list shows:

Column	Description
Referral ID	Unique identifier
Affiliate	Who earned the commission
Type	Sale or Renewal
Order	Linked WooCommerce order
Amount	Commission earned
Status	Pending, Approved, Paid, or Rejected
Date	When the referral was created

Use the filters to narrow by status, date range, or specific affiliate.

Screenshot 7: The referrals list with filters for status, date, and affiliate, showing a mix of sale and renewal referrals.

---

Step 8: Manually Approve or Reject Referrals

While referrals auto-approve after the holding period, you can take manual action:

1. Select one or more referrals using the checkboxes
2. Choose Approve or Reject from the bulk actions dropdown
3. Click Apply

Manually approving a referral before the holding period ends is useful for trusted affiliates. Rejecting is useful if you suspect fraud.

Screenshot 8: Referral list with two referrals selected and the bulk actions dropdown showing “Approve” and “Reject” options.

---

Part C: Processing Payouts

---

Step 9: View Pending Payouts

Navigate to Subscriptions > Payouts. The payout overview shows:

• Total Pending — sum of all approved commissions across all affiliates
• Total Paid — sum of all completed payouts to date

Below, you will see a list of affiliates with approved balances above the minimum payout threshold (default: R100).

Screenshot 9: The Payouts overview showing total pending and total paid amounts, with a list of affiliates eligible for payout.

---

Step 10: Process a Payout

To pay an affiliate:

1. Click Process Payout next to the affiliate’s name
2. Confirm the payout amount and method
3. Click Confirm

Payout Methods

Method	Description
Manual	You pay the affiliate outside the system (e.g., bank transfer) and mark the payout as completed
EFT	Record an EFT bank transfer — you process this through your bank and mark complete
Store Credit	Automatically generates a single-use WooCommerce coupon for the payout amount (fixed_cart type, 90-day expiry, restricted to the affiliate’s email)
PayFast Split	A first-payment commission split at the point of sale is already paid and marked paid automatically (no separate payout needed). Renewal commissions (until renewal splits are turned on) and any commission larger than its payment were not split, and are paid out here like any other affiliate’s

Screenshot 10: The payout confirmation dialog showing the affiliate name, amount, and payment method selection.

---

Step 11: Bulk Pay All Approved

To process payouts for all eligible affiliates at once:

1. On the Payouts page, click Pay All Approved
2. Review the summary — number of affiliates and total amount
3. Click Confirm

Each affiliate’s approved referrals are consolidated into a single payout record.

Screenshot 11: The “Pay All Approved” confirmation showing 5 affiliates and a total payout of R2,450.00.

---

Step 12: Review Payout History

The Payouts page shows the full history of all processed payouts:

Column	Description
Payout ID	Unique identifier
Affiliate	Who was paid
Amount	Payout amount
Method	Manual, EFT, Store Credit, or PayFast Split
Status	Pending, Processing, Completed, or Failed
Processed By	Admin who initiated the payout
Date	When the payout was processed

If a payout fails, the referrals are reverted to Approved status and the affiliate’s balance is restored.

Screenshot 12: Payout history table showing completed payouts with different payment methods.

---

Fraud Detection

ReCurr Pro includes built-in fraud detection that automatically blocks suspicious referrals:

Check	Description
Self-Referral	Blocks affiliates referring themselves (user ID, email, and IP matching)
Cookie Stuffing	Detects and blocks attempts to set referral cookies without genuine clicks
Order Minimum	Referrals on orders below a configurable minimum are blocked

Fraud checks run automatically on both clicks and referral creation. Blocked referrals are logged for admin review.

---

Important Notes

• Commissions are per line item. If a customer buys multiple subscription products in one order, each qualifying product generates its own referral.
• One level only. A commission is earned by the affiliate who referred the sale, and by nobody else.
• Store credit coupons expire after 90 days. Affiliates should be informed to use their store credit before it expires.
• PayFast Split pays first-payment commissions instantly. The split happens at transaction time, so there is no holding period or manual payout step, and the commission is automatically marked as “Paid”. Two exceptions go through the normal holding period and payout instead: renewal commissions, until renewal splits are turned on (Step 4), and a commission larger than the payment it comes from — no split is sent, the order carries a note saying why, and the whole commission is paid out in the normal way.
• Failed payouts are reversible. If you mark a payout as failed, all associated referrals go back to Approved and the balance is restored.

---

What’s Next?

Up next: Pro Tutorial 5: Affiliate Portal & Creatives — Setting up the frontend affiliate dashboard, banners, text links, and QR codes.

---

Quick Checklist

• [ ] Understood the referral tracking flow (click → cookie → checkout → commission)
• [ ] Reviewed how attribution works (cookie, coupon, cookieless fallback)
• [ ] Understood the commission calculation for your active programs
• [ ] Verified renewal commissions are configured correctly
• [ ] Reviewed the holding period and auto-approval process
• [ ] Understood refund clawback behaviour
• [ ] Viewed and filtered the referrals list
• [ ] Processed a test payout (manual or store credit)
• [ ] Reviewed payout history

---

This is Part 4 of the ReCurr Pro Tutorial Series.

Tutorial	Topic
Pro 1. CRM Getting Started	Contacts, lifecycle stages, tags, tasks
Pro 2. CRM Automation & Campaigns	Automated workflows, email campaigns, merge tags
Pro 3. Affiliate Program Setup	Enabling affiliates, registration, commission programs
Pro 4. Affiliate Commissions & Payouts	Referral tracking, commissions, payout processing (you are here)
Pro 5. Affiliate Portal & Creatives	Frontend portal, banners, links, QR codes
Pro 6. Reports & Analytics	CRM dashboard, affiliate reports, revenue insights