Skip to content
AdvocateLoop Docs

WooCommerce Referral Troubleshooting

This page has three parts: a pre-launch checklist for validating everything works before you go live, a list of common issues with diagnostic steps, and a guide to using debug mode to investigate problems.

Validate before going live

Before you direct real customers to your referral program, run through this checklist. If all four checks pass, your integration is working end-to-end and you’re ready to launch.

Test environment setup

You’ll need:

  • Your live (or staging) WordPress site with the plugin installed and connected
  • The AdvocateLoop dashboard open
  • A test referrer code from the dashboard (Referrers → New Referrer)
  • An incognito or private browsing window (so cookies don’t interfere with the test)
  • Each payment method you intend to support enabled in WooCommerce

Turn on debug mode in the plugin settings (WooCommerce → AdvocateLoop → Debug mode = On) before starting. This logs detailed information about what the plugin is doing.

Check 1: Click tracking

  1. In your incognito window, visit your store with the referral code in the URL: 
    https://yourstore.com/?ref=YOUR_TEST_CODE
  2. Open your dashboard → Insights → Clicks
  3. Within a few seconds, a new click should appear with your test code

If the click doesn’t show up: confirm the plugin shows a green connection status in WordPress settings, and that your test code is associated with your brand in the dashboard.

Check 2: Discount applies

  1. From the same incognito window, add a product to your cart that meets any minimum purchase amount you’ve configured
  2. Go to checkout
  3. The referral discount should appear as a coupon line in the cart totals
  4. The referral code section in the checkout form should show your applied message

If the discount doesn’t appear: check your dashboard’s reward configuration (Configure → Rewards) for active rules — minimum purchase amount, first-purchase-only, and so on. See Discount not applying below.

Check 3: Claim recorded

  1. Complete the checkout — fill in your test details, choose a payment method, and place the order
  2. Open the dashboard → Insights → Claims
  3. A new claim should appear linked to your test referral code, with the order details

If the claim doesn’t show up: the order may have failed at the payment step. Check the order status in WooCommerce (Orders → All Orders). Failed payment attempts don’t generate claims.

Check 4: Conversion recorded

  1. Confirm the order is marked Completed or Processing in WooCommerce (i.e., payment succeeded)
  2. Open the dashboard → Insights → Conversions
  3. A conversion should appear linked to the claim from check 3, with the order total

If the conversion doesn’t show up: the most common cause is that the payment hasn’t been confirmed yet. For most credit-card checkouts, this is near-instant; for asynchronous payment methods (bank transfer, buy-now-pay-later), conversion recording waits for payment confirmation. See Conversion not recording below.

Test each payment method

The four checks above cover one payment path. Before launch, repeat at least checks 2-4 using every payment method you intend to offer. Different payment methods can complete the order flow differently:

  • Standard credit card — page submission, then return to confirmation
  • PayPal Standard / Express — redirects to PayPal, then returns
  • Apple Pay / Google Pay / Shop Pay — native payment sheet, no page redirect
  • Stripe Checkout / Stripe Elements — varies by configuration
  • Bank transfer / Cheque — order placed in pending status, conversion fires when you manually mark it paid
  • Buy-now-pay-later (Klarna, Afterpay, Affirm) — may have asynchronous payment confirmation

For each payment method, run a real test purchase (use small amounts and refund afterward). If a conversion doesn’t appear after a successful purchase, that’s the signal to investigate that specific payment method.

Turn off debug mode before launch

Once validation is complete, turn debug mode back off in the plugin settings. Debug mode adds verbose entries to your WordPress debug log and your browser console, which is helpful for troubleshooting but unnecessary noise during normal operation.

Common issues

Discount not applying

Most common causes, in rough order of likelihood:

CauseHow to verify
Cart below the minimum purchase amountCompare cart subtotal against the minimum in your dashboard’s Configure → Rewards
Referral cookie not setConfirm the customer arrived via ?ref=CODE URL — visit history may not preserve query parameters
Cookie expiredDefault attribution window is 30 days; if the customer’s last click was longer ago, the discount won’t apply
Different browser or deviceCookies don’t cross devices; a customer who clicked on phone but checked out on laptop won’t have the cookie
First-purchase-only restriction failingCheck if the customer’s email has prior orders in WooCommerce — if so, the discount is correctly blocked
Code is invalid or expired in your dashboardLook up the code in Referrers and confirm it’s active

Quick check: confirm the customer reached checkout in the same browser they used to click the referral link, and that they arrived via a ?ref=CODE URL. If the referral state isn’t present, the discount won’t apply.

Conversion not recording

Most common causes:

CauseHow to verify
Payment hasn’t been confirmed yetCheck order status — if it’s On Hold or Pending Payment, the conversion is waiting. Manually marking the order paid will fire the conversion.
Order was placed but payment failedCheck WooCommerce → Orders for failed transactions. Failed payments don’t generate conversions (this is intentional).
Asynchronous payment methodBank transfer, some BNPL services, and manual payment methods can take hours or days to confirm. The conversion will fire when the order moves to a paid status.
Customer email doesn’t match the claimIf the customer used a different email at checkout than was associated with the claim, attribution may not connect. The claim shows on the dashboard but conversion attribution may be partial.

For most stripe/credit-card checkouts that show Completed or Processing in WooCommerce, the conversion should appear in the dashboard within seconds. If it doesn’t, enable debug mode and check the WordPress debug.log for entries related to the order.

Widget not showing

Most common causes:

CauseFix
Your domain isn’t verifiedIn dashboard → Admin → Domains, add your site’s domain. The widget refuses to load on unverified domains.
Shortcode placement issueConfirm the shortcode is on the page — [advocate_loop_widget] — and not inside a code block or escaped
JavaScript errors on the pageOpen browser devtools → Console. If another script is failing before the widget loads, the widget may not render. Look for errors before any AdvocateLoop messages.
Plugin not activeConfirm the plugin is activated in Plugins → Installed Plugins
Browser blocking the widget scriptAd blockers and privacy extensions occasionally block referral/affiliate scripts. Test in a clean browser profile.

Stale cookies from testing

If you’ve been testing multiple referral codes in the same browser, a previous code may still be stored. To clear:

  • Clear cookies for your site in your browser settings, OR
  • Use a new incognito/private window for each test

For a clean test, always use a fresh incognito window.

Page cache serving stale checkout

If you use a page-caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache, etc.), make sure the WooCommerce checkout and cart pages are excluded from cache. WooCommerce’s documentation covers this for each major caching plugin — the exclusion list usually already includes /checkout/ and /cart/ by default, but it’s worth verifying.

A cached checkout page can serve stale referral state to subsequent visitors, which is both bad for tracking accuracy and a privacy concern (one customer’s cart-state being shown to another).

The widget shortcode on regular content pages is cache-safe — see Shortcodes: Caching notes.

Plugin shows “Connection failed” after working previously

Usually means the API key was regenerated in the dashboard. The old key is invalidated immediately when a new one is generated.

Fix: copy the current API key from Settings → API Keys in the dashboard and paste it into the plugin’s settings, then save.

Three duplicate “applied” notices on checkout

Resolved in plugin version 4.3.1. If you’re seeing duplicated coupon-applied notices, upgrade the plugin to the latest version. The fix consolidates all “applied” confirmation into a single in-field message in the referral code area, removing the duplicate top-of-page notices.

Using debug mode

Debug mode adds detailed logging that helps diagnose tracking issues. Enable it in WooCommerce → AdvocateLoop → Debug mode.

When debug mode is on, the plugin logs to two places:

WordPress debug log

For debug log entries to be written, your WordPress install must have debug logging enabled. Add these lines to wp-config.php (above the /* That's all, stop editing! */ comment):

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Logs are written to /wp-content/debug.log. With debug mode enabled and a customer flowing through the referral lifecycle, you’ll see entries like:

[AdvocateLoop] [INFO] Click recorded for V2AVMRDJ
[AdvocateLoop] [INFO] Coupon auto-applied after cart update
[AdvocateLoop] [INFO] Claim tracked successfully
[AdvocateLoop] [INFO] Conversion recorded for order 12345

If any of those entries are missing from a test order, that tells you which step in the lifecycle isn’t completing.

Browser console

The browser-side widget and checkout JavaScript log to the browser console with the prefix [AdvocateLoop]. To check:

  1. Open browser devtools (F12 or right-click → Inspect)
  2. Switch to the Console tab
  3. Walk through the customer flow

Typical messages during a successful checkout:

[AdvocateLoop WooCommerce] Checkout script loaded
[AdvocateLoop WooCommerce] Referral code: "V2AVMRDJ"
[AdvocateLoop] Claim recorded

Errors or warnings appear with a red icon. If you see a 401, 403, or 404 error, that usually means a permission or connection issue. If you see a JavaScript syntax error, it’s likely from a different plugin or theme — AdvocateLoop’s scripts are tested across versions.

What to send to support

If you contact support about a tracking issue, the following information makes diagnosis much faster:

  • Plugin version (in Plugins → Installed Plugins)
  • WooCommerce version
  • WordPress version
  • The order ID of a test that failed (or the time window during which it happened)
  • Your brand ID
  • The referral code you tested with
  • A snippet of debug.log from around the time of the test (with debug mode on)
  • Browser console output from the test

The combination of a specific order ID + a debug.log snippet usually pins down the issue in one round-trip.