Skip to content
AdvocateLoop Docs

How WooCommerce Referral Tracking Works

This page walks through what actually happens — step by step — when a referred customer visits your WooCommerce store and completes a purchase. Understanding the full lifecycle makes it easier to debug issues, explain the integration to teammates, and decide what (if anything) to customize.

The high-level flow

Customer clicks referral link
        ↓
Page loads — referral code captured and stored
        ↓
Customer browses, adds product to cart
        ↓
Coupon auto-applies when cart meets the conditions
        ↓
Customer fills out checkout, places order
        ↓
Claim recorded against the advocate
        ↓
Payment completes
        ↓
Conversion recorded — advocate is credited

Each step is automatic. The customer never sees a coupon code or has to manually claim anything — they just shop normally and the discount appears.

A referred customer arrives at your store through a referral link. Referral links look like:

https://yourstore.com/?ref=V2AVMRDJ
https://yourstore.com/some-product/?ref=V2AVMRDJ

The referral code can be in any URL parameter your brand has configured (default: ref, referral, adv, advocate). You can add custom parameter names in your AdvocateLoop dashboard under Configure → Tracking.

When the page loads:

  • The plugin reads the referral code from the URL
  • A click is recorded against the advocate’s code (visible in your dashboard under Insights → Clicks)
  • The code is stored in a cookie that persists for the attribution window you’ve configured (default: 30 days)

From this point forward, even if the customer leaves your site and comes back through a regular link, the referral is remembered until the attribution window expires or until they convert.

Step 2: Browsing and cart-building

The customer browses your store normally. Nothing visible happens at this stage — no banners, no popups, no interruption. The plugin is just watching for the customer to add something to their cart.

When the customer adds an item:

  • The plugin checks whether the customer has an active referral code in their cookie
  • If they do, it checks whether the cart meets the conditions for the discount (e.g., minimum purchase amount)
  • If both checks pass, the discount is auto-applied to the cart as a coupon

The customer sees the discount applied in their cart subtotal, just as if they’d manually entered a coupon code.

Step 3: Discount auto-applies in cart

The discount appears as a line in the cart and checkout totals. The exact label is configured in your dashboard under Configure → Widget → Checkout applied message.

The customer also sees an in-field message inside the referral code area at checkout — something like:

Referral code V2AVMRDJ applied! You’re getting 15% off.

This message comes from your dashboard’s reward configuration, so the wording reflects whatever discount you’ve set up (percentage, fixed amount, free shipping, etc.).

For more on how the discount itself behaves — minimums, maximum caps, stacking with other coupons — see Discounts & Coupons.

Step 4: Customer fills out checkout

The customer fills out the WooCommerce checkout form normally — billing details, shipping address, payment method. No additional fields are added by the plugin; the standard WooCommerce checkout is exactly what the customer sees.

Step 5: Order created, claim recorded

When the customer places the order, WooCommerce creates the order record. At that moment, the plugin records a claim to AdvocateLoop, linking:

  • The advocate (via the referral code)
  • The customer (via the customer’s checkout details)
  • The order (via order total and line items)

A claim represents the start of a successful referral — the system now knows this customer is referred and which advocate gets credit.

The claim is visible in your dashboard under Insights → Claims with a status of “pending.”

Step 6: Payment processed

Most checkouts have a short delay between the order being placed and payment being confirmed:

  • Credit-card checkouts: usually seconds (3-D Secure may add a step)
  • Express checkouts (Apple Pay, Google Pay): nearly instant
  • Asynchronous payments (bank transfer, BNPL services, some wallets): can take minutes to days

The plugin waits for payment confirmation rather than recording the conversion immediately on order placement. This ensures conversions only count when the customer actually pays — failed or abandoned payments don’t generate phantom conversions.

Step 7: Conversion recorded

Once WooCommerce confirms payment, the plugin records a conversion linked to the claim from step 5. The conversion captures:

  • Order total (what the customer actually paid)
  • Tax, shipping, and discount amounts
  • Order line items
  • The advocate to credit

The claim’s status updates from “pending” to “confirmed,” and the advocate becomes eligible for their reward.

The conversion is visible in your dashboard under Insights → Conversions. Your advocate’s reward processing (issuing store credit, sending a payout, etc.) follows your configured reward settings.

Step 8: Post-purchase share opportunity

After a successful purchase that wasn’t itself a referral (i.e., the customer wasn’t referred but just bought normally), the order-received page can show a share widget inviting the customer to become an advocate themselves. This is controlled by the Show share widget on thank-you page setting in the WordPress plugin admin.

For customers who were referred, the share widget is suppressed by default — they just used someone’s code, so showing them a “refer friends” widget immediately would feel pushy. You can override this in plugin settings if you prefer to show it to everyone.

What happens with refunds

If you refund an order in WooCommerce (whether fully or partially), the plugin notifies AdvocateLoop. The original conversion is adjusted:

  • Full refund — the conversion is reversed, and the advocate’s reward eligibility for that referral is removed
  • Partial refund — the conversion total is reduced proportionally, and the advocate’s reward (if percentage-based) is reduced accordingly

This keeps your referral numbers accurate to actual paid revenue.

What happens across multiple sessions

Customers often don’t buy on their first visit. The plugin handles this:

  • Same device, multiple sessions — the referral cookie persists for the attribution window. If the customer comes back within 30 days (or whatever you’ve configured), the referral is still active and the discount still applies.

  • Different device — if the customer clicks the link on their phone but completes the purchase on their laptop, AdvocateLoop can still attribute the conversion in many cases using details the customer provides at checkout. This works best when you’ve placed the widget somewhere customers naturally interact with it.

  • Cookie cleared — if the customer clears cookies, the local referral attribution is lost, but the conversion can often still be attributed from the details the customer provides at checkout.