Skip to main content

Referral Analytics Explained

Referral dashboard data and endpoints explained

Written by James Dohm

Introduction

Referral analytics help you understand how your referral campaigns are performing and where to optimize. This article explains the core metrics and how to interpret them.
​

Availability

  • Referral Analytics is available on plans that include Analytics.

  • Referral campaign management is available on plans that include Referral Campaigns.


​

In-app Metrics for Referrals

Revenue Metrics

  • Total Referral Revenue Generated is calculated by summing friend revenue and advocate revenue

  • Friend Revenue Generated is calculated from orders associated with referred referrals (orders where the customer was referred by someone else)

  • Advocate Revenue Generated is calculated from orders associated with referrer referrals (orders from customers who have referred others)


​

Traffic and Status Metrics

  • Referral Traffic counts referrals created in your selected date range

  • Blocked counts referrals with blocked status

  • Claimed refers to referrals with status pending or completed (friends who claimed the offer and were issued a friend discount code)

  • Completed refers to referrals with status completed (referrals that resulted in an order)

  • Other statuses you may see include unclaimed and ineligible


​

Performance Metrics

  • Top Advocates are customers ranked by their completed referrals count

  • Claim Rate is calculated as the percentage of claimed referrals versus claimable referrals (non-blocked referrals)

  • Conversion Rate is calculated as the percentage of completed referrals versus claimed referrals

  • New Customers Acquired counts completed referrals. In most setups this reflects first purchases, but campaigns configured to allow all orders can include repeat purchasers.


​

Discount Metrics

  • Total in Friend Discounts sums the discount amounts used by referred friends

  • Total in Advocate Discounts sums the discount amounts used by advocates (referrers)


​

Source and Share Metrics

  • Top Advocate Signup Sources tracks where advocates are coming from based on UTM parameters in widget events

  • Top Advocate Share Clicks tracks which sharing methods (social media, email, etc.) advocates use most, based on share_type in widget events

Top Advocate Signup Sources started tracking on August 3, 2023. Top Advocate Share Clicks started tracking on October 18, 2024.
​

All metrics are calculated within specific date ranges and support comparison with previous timeframes for trend analysis.
​

How to interpret your referral performance

There is no universal benchmark that applies to every store. Referral results vary based on traffic quality, incentive structure, fraud settings, product type, and customer mix.
​

Reading block rate in context

Use block rate as a quality signal, not just a number to minimize.
​

For reporting, many merchants calculate block rate as:
​

Blocked referrals / Referral traffic

  • If block rate is high while conversion and new-customer quality are strong, your fraud settings may be filtering risky traffic as intended

  • If block rate jumps after a campaign or offer change, review traffic sources and campaign setup

  • If block rate is very low while abuse increases, your protection settings may be too loose


​

If blocked referrals seem high, check these first

  1. Traffic source quality (affiliate traffic, paid social, and incentive aggregators can increase low-intent or duplicate referrals)

  2. Offer structure (very high incentives can attract abuse)

  3. IP and household behavior (shared networks or repeated attempts)

  4. Existing-customer attempts (referrals are intended for net-new customers)

  5. Campaign and fraud settings (eligibility and protection thresholds)

For a full breakdown of block causes and settings, see Referrals fraud prevention tools.
​

Dashboard counts vs API counts

You may see differences between dashboard numbers and exported/reporting totals. Common reasons include:

  • Different date ranges or time zones

  • Different status filters (for example, pending + completed for claimed referrals)

  • Campaign-level vs account-level views

  • Attribution differences between referral-attributed revenue and total Shopify sales

  • Referral order eligibility settings, such as first-order-only versus all-orders-eligible campaigns


​

Technical Endpoints for Widget Events and Referrals

Widget Events API

Returns logs of widget interactions such as clicks, shares, and loads on referral widgets.
​

Key Query Parameters :

  • filters[app_widget_type]: e.g. referral_social_share

  • filters[action_type]: e.g. click

  • filters[customer_id]: filter by specific customer

  • filters[time_at][gte] and filters[time_at][lt]: filter by event timestamp range

  • pagination[page], pagination[per_page], pagination[since_id], pagination[limit]

  • sort[order_type] and sort[order_direction]

Response Fields :

  • type: always widget_event

  • action_type: user interaction type (e.g. click)

  • app_widget_type: the widget type (e.g. referral)

  • properties.share_type: channel used to share (e.g. sms, email, etc.)

Example widget event:

{ "type": "widget_event", "id": "5861bb7-7ec8-467e-a630-cee3c2289e59", "attributes": { "app_widget_type": "referral_social_share", "action_type": "click", "properties": { "share_type": "sms" }, "time_at": "2025-05-04T19:22:11.000Z", "url_path": "/pages/refer-a-friend", "visitor_token": "9646dbf9a7ed4873585cdb9dbf9f", "customer_id": null, "shop_id": null }}

Referrals API

Returns referral entries including status, discount details, and conversion data.
​

Useful Filters :

  • filters[referral_campaign_id]: filter by campaign

  • filters[updated_at][gte] and filters[updated_at][lt]: filter by update timestamp range

  • pagination[page], pagination[per_page], pagination[since_id], pagination[limit]

  • sort[order_type] and sort[order_direction]

Use this endpoint when you need filtered referral-level records outside the in-app dashboard.
​

Referral Campaigns analytics

Visit the campaigns dashboard to see a high-level overview of the following metrics:
​

Metrics term
​

Description
​

Status
​

Current state of a referral campaign (inactive, active, or expired).
​

Clicks
​

The number of referral records associated with the campaign.
​

Claims
​

The number of referrals in claimed statuses (pending + completed).
​

Completed
​

The number of referral claims that are fully completed, usually resulting in advocate reward eligibility.
​

Some completed referrals can still appear in advocate reward workflow states like Pending Fulfillment or Pending Verification while reward handling finishes.
​

Revenue Generated
​

The total revenue generated from referred customer orders in that campaign.
​

Common Questions

What’s the difference between Claimed and Completed?
Claimed means the friend claimed the offer and was issued a friend discount code (pending status). Completed means the friend then placed an eligible purchase and the referral moved to completed.
​

Why are my Top Advocates not showing recent activity?
Top Advocates only reflect completed referrals. If their referrals are still in pending or blocked status, they won’t be counted.
​

Can I track where advocates are sharing links?
Yes. Use widget events with share_type to see channels such as email, SMS, and social shares.
​

What causes a referral to be blocked?
Fraud prevention logic. Common causes include duplicate or suspicious IP activity, self-referrals, existing-customer checks, phone/address similarity, and other abuse patterns.
​

What is a “good” referral block rate benchmark?
There is no fixed benchmark that applies to every brand. Block rate depends on your traffic quality, incentive level, fraud settings, and customer behavior. Compare trends over time and evaluate them alongside claim rate, conversion rate, and customer quality.
​

What should I do if my block rate increases?
Review traffic sources, reward structure, and fraud settings first, then audit recent campaign or policy changes. If needed, use the Referrals fraud prevention tools checklist and contact support with examples of blocked referrals.
​

Why isn’t the referral revenue matching Shopify sales?
Rivo attributes referral revenue to orders with verified referral attribution, so total referral revenue can differ from overall Shopify sales.

Related Articles
Referral campaign builder
Customer referrals explained
Referral Smart Links explained
Managing the status of your referrals
Adding a referral campaign pop-up
Did this answer your question?