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 referral code from the dashboard
  • An incognito or private browsing window
  • 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 → Rewards → Activity
  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 belongs to 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) — 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 → Rewards → Activity
  3. A new claim should appear linked to your test referral code, with the order details

If the claim doesn’t show up: confirm the order actually went through in WooCommerce (Orders → All Orders) rather than stalling before the order was placed.

Check 4: Conversion recorded

  1. Confirm the order is marked Completed or Processing in WooCommerce
  2. Open the dashboard → Rewards → Activity
  3. A conversion should appear linked to the claim from check 3, with the order total

If the conversion doesn’t show up: conversions count completed, paid orders. If the order isn’t marked Completed or Processing yet, the conversion will appear once it is. 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 methods 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 a pending status until you mark it paid
  • Buy-now-pay-later (Klarna, Afterpay, Affirm) — payment may confirm later

For each method, run a real test purchase (use small amounts and refund afterward). If a conversion doesn’t appear after a successful, paid order, 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. Debug mode adds verbose entries to your WordPress debug log and browser console — helpful for troubleshooting, unnecessary noise during normal operation.

Common issues

Discount not applying

Work through these in order:

CheckHow to verify
Cart is below the minimum purchase amountCompare the cart subtotal against the minimum in Configure → Rewards
First-purchase-only is enabled and this customer has ordered beforeCheck the customer’s email for prior orders in WooCommerce — if found, the discount is correctly withheld
The referral code is inactiveLook the code up in your dashboard and confirm it’s active
The discount type/value isn’t setConfirm a reward is configured in Configure → Rewards

The most reliable way to test: use a fresh incognito window, arrive through the full ?ref=YOUR_TEST_CODE link, and complete checkout in that same window without switching browsers or devices mid-way. If a test isn’t behaving, start over in a new incognito window.

Conversion not recording

CheckHow to verify
The order isn’t paid yetCheck the order status — On Hold or Pending Payment orders haven’t been paid. Marking the order paid records the conversion.
The order’s payment failedCheck WooCommerce → Orders. Only completed, paid orders count as conversions.
An asynchronous payment methodBank transfer and some BNPL methods confirm later; the conversion appears once the order is marked paid.

For most card checkouts that show Completed or Processing, the conversion appears 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

CauseFix
Your domain isn’t verifiedIn the dashboard → Admin → Domains, add and verify your site’s domain. The widget won’t 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 fails 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 scripts. Test in a clean browser profile.

Testing tips

If you’re running several test purchases, use a fresh incognito/private window for each one so a previous test doesn’t interfere with the next. This is the simplest way to keep tests clean.

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. Most caching plugins already exclude /checkout/ and /cart/ by default, but it’s worth verifying — caching these session-specific pages causes inconsistent checkout behavior.

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.

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):

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

Logs are written to /wp-content/debug.log. During a test order you’ll see entries prefixed with [AdvocateLoop] confirming each step — for example a click being recorded, the coupon being applied, the claim, and the conversion. If one of those entries is missing, that tells you which step to investigate.

Browser console

The browser-side widget and checkout JavaScript log to the 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

Errors or warnings appear with a red icon. A 401, 403, or 404 usually means a permission or connection issue. A JavaScript syntax error is likely from a different plugin or theme.

What to send to support

If you contact support about a tracking issue, this 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 when 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 and a debug.log snippet usually pins down the issue in one round-trip.