> ## Documentation Index
> Fetch the complete documentation index at: https://docs.referbro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & Event Tracking

> Verify your setup is working and fix common issues

## Verifying Event Tracking

After setting up your campaign and widgets, use the Analytics dashboard to confirm events are flowing correctly.

<Steps>
  <Step title="Open Analytics">
    Go to **Apps → Referbro → Analytics** in your Shopify Admin.
  </Step>

  <Step title="Check the Event Analysis Table">
    Scroll to the **Event Analysis** section. You should see these event types after testing:

    | Event            | When It Fires                          | What It Confirms                              |
    | :--------------- | :------------------------------------- | :-------------------------------------------- |
    | `LINK_GENERATED` | Customer gets a referral code          | Campaign is active and generating codes       |
    | `LINK_CLICKED`   | Someone clicks a referral link         | Referral links are working                    |
    | `ORDER_PLACED`   | A referred friend completes a purchase | Discount code applied and order tracked       |
    | `WHATSAPP_SENT`  | A WhatsApp message is sent             | Provider connection and templates are working |

    <Note>
      If you just set up for the first time, place a test order to generate initial events. Events may take a few seconds to appear.
    </Note>
  </Step>

  <Step title="Verify the Conversion Funnel">
    Check the **Conversion Funnel** section. A healthy setup shows:

    1. **WhatsApp Message Sent** — top of funnel (messages going out)
    2. **People Visited** — middle (link clicks happening)
    3. **People Bought** — bottom (conversions occurring)

    If a level shows zero while the one above it has activity, there's a drop-off at that stage — see the troubleshooting sections below.
  </Step>

  <Step title="Check Referral Details">
    The **Referral Details** table shows individual referral records with statuses:

    * **Pending** — Referral tracked, waiting for reward return period
    * **Paid** — Reward issued to referrer
    * **Cancelled** — Order was returned/cancelled
    * **Self-Referral** — Same person detected (no reward issued)
  </Step>
</Steps>

***

## Common Issues

<AccordionGroup>
  <Accordion title="Widget not showing on the storefront">
    **Symptoms:** The Refer & Earn floating button doesn't appear on your store.

    **Possible causes & fixes:**

    1. **App Embed not enabled** — Go to **Shopify Admin → Online Store → Themes → Customize → App embeds** (🧩 icon) and toggle on **Refer & Earn**.
    2. **No active campaign** — The widget only appears when there's an active campaign. Check **Apps → Referbro → Campaigns** and ensure one campaign is active.
    3. **UTM restriction enabled** — If **Show on UTM** is enabled in Campaign Configuration, the widget only appears for visitors with matching UTM parameters. Disable it for testing.
    4. **Theme caching** — Some themes aggressively cache. Try visiting your store in an incognito window or clearing your browser cache.
  </Accordion>

  <Accordion title="Referral Received popup not showing for referred friends">
    **Symptoms:** A friend clicks the referral link but doesn't see the discount popup.

    **Possible causes & fixes:**

    1. **App Embed not enabled** — Ensure **Referral Received** is toggled on in **Theme Customizer → App embeds**.
    2. **Referral link format incorrect** — The link must include `?ref=CODE` as a query parameter. Check that the referral code is in the URL.
    3. **Browser blocking popups** — The popup may be blocked. Try disabling popup blockers for testing.
  </Accordion>

  <Accordion title="WhatsApp messages not being sent">
    **Symptoms:** No WhatsApp messages are received after placing an order or sharing.

    **Possible causes & fixes:**

    1. **Provider not connected** — Go to **Apps → Referbro → WhatsApp Settings** and verify your API URL and API Token are entered.
    2. **Templates not approved** — Check your provider's platform (e.g., Pragma dashboard, Meta Business Suite) to confirm your templates are in **Approved** status.
    3. **Template ID mismatch** — The Template ID in Referbro must **exactly match** the template name on your provider's platform. Check for typos, extra spaces, or case differences.
    4. **Template not enabled** — Ensure the template toggle is set to **Enabled** in Referbro WhatsApp Settings.
    5. **Phone number format** — WhatsApp requires the full international format (e.g., `+91XXXXXXXXXX`). Ensure customer phone numbers include the country code.

    <Tip>
      Use the **Send Test Message** button in WhatsApp Settings to isolate whether the issue is with the provider connection or with trigger timing.
    </Tip>
  </Accordion>

  <Accordion title="Rewards not being issued to referrers">
    **Symptoms:** A friend purchased using the referral code, but the referrer hasn't received their reward.

    **Possible causes & fixes:**

    1. **Reward return period hasn't elapsed** — Check the **Reward Return Period** in Campaign Configuration. The reward is only issued after this many days. If set to `7`, wait 7 days after the friend's order.
    2. **Order was cancelled** — Cancelled or refunded orders void the reward automatically.
    3. **Self-referral detected** — If the referrer and friend share the same email or IP, Referbro flags it as a self-referral and blocks the reward. Check the **Referral Details** table for a `Self-Referral` status.
    4. **Friend didn't use the code** — If **Allow Without Code** is disabled, the friend must apply the discount code at checkout. Enable this option if you want to rely on link-click tracking instead.
    5. **Delivery status not updating** — Referbro schedules the reward based on Shopify's delivery status. If your shipping provider doesn't update fulfillment status, configure a **Delivered tag** in **Campaign Configuration → Advanced settings** as a fallback. See [Advanced Settings](/docs/features/campaigns#advanced-settings).
  </Accordion>

  <Accordion title="RTO orders not cancelling referral rewards">
    **Symptoms:** An order was returned to origin (RTO), but the referral reward was not cancelled.

    **Possible causes & fixes:**

    1. **RTO tag not configured** — Go to **Campaign Configuration → Advanced settings** and set the **RTO tag** field to the exact Shopify order tag your system applies for RTO orders.
    2. **Tag not applied to order** — Verify the RTO tag has actually been added to the order in Shopify Admin → Orders. The tag must match exactly (case-sensitive).
    3. **Reward already issued** — RTO cancellation only applies to rewards in `PENDING` or `FAILED` status. If the reward has already been issued (`SUCCESS`), the cancellation is a no-op. Manual clawback is required in this case.
    4. **No referral record** — If the order was not a referral order (no `DiscountInfo` record), the RTO tag is silently ignored. Check **Referral Details** for the order.
  </Accordion>

  <Accordion title="Discount code not applying at checkout">
    **Symptoms:** The referee says the discount code doesn't work at checkout.

    **Possible causes & fixes:**

    1. **Code expired or already used** — Each referral code is single-use per friend. If the friend already used it, a new code won't be issued.
    2. **Minimum subtotal not met** — Check the **Minimum Subtotal** in Campaign Configuration. The friend's cart must meet this threshold.
    3. **Segment restriction** — Referral discounts are automatically restricted to new customers (those with no prior purchases). Existing customers will not be able to apply the referral discount code.
    4. **Discount stacking conflict** — If Shopify doesn't allow multiple discounts, check the **Combines With** options in Campaign Configuration.
  </Accordion>

  <Accordion title="Checkout extension widget not appearing">
    **Symptoms:** No referral widget on the Thank You or Order Status page.

    **Possible causes & fixes:**

    1. **Widget not added** — Go to **Shopify Admin → Settings → Checkout → Customize** and verify the **Referbro Widget** block is added to the Thank You and/or Order Status pages.
    2. **Using legacy checkout** — Checkout extensions require Shopify's **Checkout Extensibility**. If you're on a plan or theme that uses the legacy checkout, the extension won't appear.
    3. **No active campaign** — The widget only renders when there's an active campaign configured.
  </Accordion>
</AccordionGroup>

***

## Still Stuck?

If you've tried the steps above and the issue persists:

📧 Contact **[arjun@referbro.com](mailto:arjun@referbro.com)** with:

* Your store URL
* The specific issue you're experiencing
* A screenshot of your Referbro Analytics page (Event Analysis section)