Setting Up SATHI on a Headless Shopify Storefront

SATHI tracks clicks on Shopify stores using script tags that load through your Shopify theme. Headless storefronts (for example, a Next.js site hosted on Vercel) don't use a Shopify theme, so these scripts never load and clicks are not recorded. SATHI fully supports headless stores, but your development team needs to add a few pieces to your storefront code. Once these steps are complete, click tracking, order attribution, and discount codes will all work as expected.

Keep the Ref Parameter on Redirects

When a shopper clicks an ambassador's link, they land on a URL that includes a ref parameter, like this:

https://www.your-site.com/?ref=jane

If your site redirects shoppers for any reason (locale, trailing slash, a marketing landing page, and so on), the final URL must still include ?ref=jane.

If the ref parameter is dropped during a redirect, SATHI cannot record the click or attribute the order to the ambassador.

Track Clicks

Add the following script to the <head> of every page on your storefront. Replace STORE.myshopify.com with your Shopify store domain.

<script src="https://api.mysathi.io/headless/shopify/pixel" data-shopify-domain="STORE.myshopify.com"></script>

The script reads the ref parameter from the URL and records the click against that ambassador.

Attribute Sales to Ambassadors

To link an order to an ambassador, your storefront needs to add a _sathi_ref attribute to the cart. This attribute carries through to the paid order.

1. Read the ref value from the landing URL (for example, ?ref=jane).

2. Store that value while the shopper browses your site. A cookie or local storage works.

3. When you create or update the cart, set the following attribute:

{
  "attributes": {
    "_sathi_ref": "jane"
  }
}

Only set _sathi_ref when a ref value is present in the URL.

To confirm this is working, place a test purchase through an ambassador link. Open the order in Shopify and you should see _sathi_ref: jane under Additional details.

Automatically Apply Discount Codes

To apply the ambassador's discount code at checkout, call the SATHI API with the ref value from the landing URL. Replace STORE.myshopify.com with your Shopify store domain.

Example request:

GET https://api.mysathi.io/headless/affiliates/discount?ref=jane&shopifyDomain=STORE.myshopify.com

Example response:

{
  "data": {
    "code": "JANE10"
  }
}

Apply the returned code to the shopper's cart so it shows up at checkout.

Still need help?
Reach out anytime to our Support team using the button at the bottom-right corner of your dashboard, or email us at [email protected].