Blog

Shopify Referral Integration Guide

A practical setup guide for stable storefront attribution and campaign launch readiness.

Shopify Referral Integration Guide

Referral programs on Shopify fail or succeed based on setup quality, not campaign strategy. A well-configured integration runs attribution silently across thousands of orders. A misconfigured one generates support tickets, manual attribution corrections, and reward disputes from the first week.

This guide covers the setup steps that determine whether your Shopify referral program works reliably, from first click to reward issuance.

Understanding Shopify's Attribution Constraints

Before configuring anything, it helps to understand why Shopify referral attribution is harder than it looks.

Checkout is a separate domain. Shopify's checkout process (checkout.shopify.com) operates on a different domain from your storefront. Context stored in your storefront's localStorage or session cookies doesn't survive the transition. Any attribution method that relies on client-side storage across domains will drop the referral credit for a significant percentage of orders.

Guest checkout creates identity gaps. A referred friend who checks out as a guest has no Shopify customer record until after the order is placed. Attribution logic that depends on customer ID matching at checkout will miss guest orders entirely.

Theme app extensions have placement constraints. Sorae widgets are deployed via Shopify's theme app extension system, which is the right approach for Online Store 2.0 compatibility, but placement matters. The wrong widget placement on the wrong page produces no attribution data regardless of how well the widget itself is configured.

Understanding these constraints informs every setup decision below.

Step 1: Install and Authorize the App

Install Sorae from the Shopify App Store. The OAuth installation process creates your merchant account, configures webhook subscriptions, and sets up the embedded admin within your Shopify admin navigation.

After installation, verify:

• The Sorae app appears in your Shopify admin left navigation
• Your campaign settings page is accessible
• The webhook subscription list shows order and customer webhooks registered

If the app doesn't appear in navigation after installation, check that the app embed is enabled in your Theme Editor under App Embeds. The tracking embed is deployed through this mechanism.

Step 2: Publish Campaign Pages

Sorae creates campaign pages for your storefront, an advocate start page and a friend landing page, as Shopify pages with the correct templates. These pages are the entry points for your referral program and must be published before attribution testing can begin.

From the Sorae admin setup checklist:

1. Navigate to the Pages setup step
2. Follow the prompts to publish the advocate page and friend landing page to your Shopify storefront
3. Verify both pages appear in your Shopify admin under Pages with the correct templates assigned

Common issues at this step:

• Pages publish but templates aren't assigned; widget won't render
• Pages are published in draft state; attribution links will return 404s
• A prior app left conflicting page templates; Sorae templates need to be the active assignment

Step 3: Place Widgets in the Theme Editor

With pages published, widgets need to be placed in the Theme Editor. Sorae provides theme app extensions for the advocate start view and the friend claim view. These are placed via drag-and-drop in the Theme Editor, no liquid editing required.

Advocate start widget placement:

• Best placed on your post-purchase confirmation page (Order Status page) and on a dedicated "Refer a friend" page
• The post-purchase page catches customers at peak satisfaction, which is the highest-converting moment for advocate entry
• A dedicated referral page gives you a destination for header links and email CTAs

Friend claim widget placement:

• Place on the friend landing page template you published in Step 2
• This is where referred friends land when they click an advocate's share link
• The widget should be above the fold, don't bury it below product grids

After placing widgets, verify they render correctly with a preview in the Theme Editor. An empty widget surface usually means the app embed isn't enabled or the page template assignment is incorrect.

Step 4: Enable the Tracking Embed

The tracking embed is the bridge between your storefront and Shopify checkout. It captures referral context from the friend's landing session and makes it available for order attribute writes during checkout processing.

Enable the tracking embed from Theme Editor → App Embeds. Look for the Sorae tracking embed and toggle it on. This should be on for all pages, not just your referral landing page, context can be captured from any page the friend visits before checkout.

Verify the embed is active by checking the Sorae setup checklist. If the embed status shows inactive after you've enabled it, clear your theme editor cache and check again.

Step 5: Validate Attribution Events

Before launching the campaign to real customers, validate that the integration actually works end-to-end. This means generating a test referral link and completing a test purchase.

What to validate:

1. Click event fires. Use the referral link from a test advocate account. The Sorae analytics dashboard should show a click event within a few seconds of landing on the friend page.

2. Session context persists. Navigate from the friend landing page to a product page, add to cart, and proceed to checkout. The referral context should persist through all of these steps.

3. Order attribute is written. Complete a test checkout. Look at the order in Shopify admin under the order's Additional Details section. The referral attribution attribute should be present.

4. Conversion is recorded. After placing the test order, the Sorae analytics dashboard should show a conversion event. If you see the click but no conversion, the order attribute write step is missing, check that your order paid webhook is registered and active.

5. Reward logic runs correctly. Verify that the test conversion triggers the reward policy checks correctly. Depending on your reward configuration, a test reward may or may not issue, the important thing is that the logic runs without errors.

Step 6: Configure and Launch the Campaign

With attribution validated, configure your campaign policy before going live:

• Reward structure. Set your referrer reward and buyer incentive. Enable new-customer enforcement. Set a minimum subtotal if relevant.
• Delay window. Set a delay period before rewards issue. 14 days is a common starting point for programs with standard return policies.
• Share copy. Generate copy variants for advocates. Test at least two variants so advocates have options.
• Klaviyo connection. If you use Klaviyo, connect the integration before launch so advocate start and conversion events flow into your lifecycle flows from day one.

Maintaining a Reliable Integration

After launch, the two most common integration issues are theme updates that disable the tracking embed and page template changes that break widget rendering.

Set a reminder to check the Sorae setup checklist after any major theme update. Theme updates can reset app embed states, reassign page templates, or change section structures that affect widget placement.

If you see a sudden drop in referral click events without a corresponding drop in share link traffic, the tracking embed is the first place to check. If click events are healthy but conversions drop, check that the order webhook is still active in your Shopify admin under App and Sales Channel → Sorae → Webhooks.

A well-maintained Shopify referral integration is largely self-sustaining once the setup path is complete. The operational leverage comes from spending setup time getting attribution right, so the campaign runs without manual intervention.