Referrals

Referrals

OLoyalty ships a dual-sided refer-a-friend engine: the referrer and the referred friend both receive a reward when the friend places their first qualifying order.

Lifecycle

Referrals progress through these states (wp_oloyalty_referrals.status):

1. invited - referrer shared a code
2. signed_up - friend created an account
3. purchased - friend placed their first qualifying order
4. rewarded - both rewards issued
5. flagged - blocked pending manual review by fraud signals
6. rejected - admin denied the referral
7. reversed - reward clawed back after refund

Cookie capture

When any URL is visited with ?ref=<code>, OLoyalty_Referrals::capture_cookie() looks up the referrer by their member referral code and writes the oloyalty_ref cookie (30 days, HttpOnly, SameSite=Lax). On user_register, the new user is linked to that referrer via members.referred_by.

First qualifying order

On woocommerce_checkout_order_processed (and the completed/processing transitions), OLoyalty_Referrals::on_first_order() looks up the referral, runs fraud checks, and issues the configured rewards. The referrer reward and the friend reward are independent reward IDs - they can be different.

Fraud signals

OLoyalty_Fraud computes a numeric fraud_score (0.00 to 1.00) from a set of signals stored in the fraud_signals JSON:

• IP overlap between referrer and friend
• Shipping or billing address overlap
• Email domain overlap
• Sub-threshold order value
• Account age of the friend

Referrals above the score threshold land in the manual review queue (status='flagged') and are listed in OLoyalty, Referrals.

Refund claw-back

On woocommerce_order_status_refunded or woocommerce_order_status_cancelled, OLoyalty_Referrals::on_refund() reverses the issued rewards and transitions the referral to reversed.

REST surface

• GET /wp-json/oloyalty/v1/members/me - current user's balance, tier, referral code
• POST /wp-json/oloyalty/v1/members/<id>/adjust - manual point adjustment (requires oloyalty_adjust capability)
• GET /wp-json/oloyalty/v1/members/<id>/ledger - paginated ledger