Skip to main content

Social Snowball for Headless Shopify Stores

Written by Ani Gupta

If you're using a custom Shopify storefront with Shopify checkout, integrating Social Snowball requires a bit of code implementation. Here's a step-by-step guide to help you set up Social Snowball on your headless Shopify shop:

Important prerequisite:
When a shopper clicks an affiliate link, they’ll first land on a URL like:

https://www.website.com/CODE

This should redirect to the final landing page:

https://www.website.com/?snowball=CODE

Make sure the ?snowball=CODE query parameter persists after the redirect. If it’s dropped, Social Snowball will not be able to capture and attribute referrals.

STEP 1: Add the Social Snowball Script

Within the <head> section of your storefront theme code, add the following script:

<script> window.SocialSnowball = { shop: "your-shop-name.myshopify.com" } </script> <script src="https://api.socialsnowball.io/js/referral.js?shop=your-shop-name.myshopify.com"></script>

Note: Replace your-shop-name.myshopify.com with the actual myshopify.com URL of your Shopify store. After adding the code, save your theme file.

Testing:

Once you've added the code, we recommend testing the attributions on your headless Shopify store:

  1. Create a test affiliate account on Social Snowball and go through the referral process.

  2. Make a test purchase using the affiliate’s link and confirm that the sale is tracked in your Social Snowball dashboard.

  3. Verify that click events are being tracked - for example, after clicking the affiliate link, the UTM Link Clicks (Unique) count in the affiliate’s profile should increase by 1.

STEP 2 (Optional but Recommended): Add the __snowball Attribute

If you’re running a headless storefront, you can manually pass the affiliate code into checkout. Adding the __snowball attribute ensures that affiliate attribution is tied directly to the order in Shopify. Even if other tracking methods (like clicks or pixels) are interrupted, this attribute acts as a fallback to keep commissions accurate.

1. Capture the affiliate code from the landing page URL

  • When a shopper clicks an affiliate link, they’ll be redirected to a final landing page in the format:

    https://www.website.com/?snowball=CODE

  • Capture the CODE value from the snowball query parameter.

  • Store this value in a cookie or local/session storage so it persists while the customer continues browsing.

2. Pass the code into checkout as an attribute

  • When creating a checkout session via Shopify’s Storefront API or Checkout API, include a custom attribute with the key __snowball.

  • Set its value to the affiliate’s code captured in the above step.

Best Practice:

  • Only set the __snowball attribute if the snowball query parameter is present.

  • If no affiliate code is found, leave the attribute unset to avoid cluttering orders with empty values.

3. Confirm it appears in the order

  • Make a test purchase using an affiliate link.

  • Once the checkout is completed, go to Shopify Admin → Orders.

  • Under Additional details, you should see:

    __snowball: CODE

Since headless setups can vary, please contact our chat support for help if you encounter any problems even after implementing the above steps.

Did this answer your question?