Using Superfiliate with a Headless Storefront

Last updated: October 16, 2026

Upon installing our app in your shop, we benefit from many features that the Shopify ecosystem offers to apps. Unfortunately, some of the features that we use to leverage our product are not available out of the box for shops using headless storefronts, and therefore we need some extra work being done by the shop developers in case they wish to use these features.

Choose a landing-page domain for a headless store

Your Superfiliate landing-page hostname, your headless storefront, and your Shopify checkout can use different domains. When enabled for your store, Settings → Custom Domain → A different domain lets you choose a landing-page subdomain on another domain your team owns, even if the storefront address shown in Superfiliate is myshopify.com. If you do not see the option, contact support to check availability.

Using a subdomain of your storefront’s root domain remains recommended for tracking. A different root gives you more branding flexibility but can reduce tracking accuracy: some sales may not be credited to creators. Browsers cannot share a landing-page cookie directly across unrelated roots, and a longer attribution window does not remove that limitation.

A custom landing-page domain does not install tracking on your headless storefront, create vanity redirects on it, or add support for discount links. Follow the implementation sections below for those separate capabilities. Products, discounts and orders still belong to the connected store.

Read Custom Domain Set Up for the domain choices, ownership verification, and tracking considerations.

Feature: Vanity affiliate links

How does it work:

Superfiliate uses the Shopify API to create redirects directly from your shop domain to the affiliate link. This way your affiliate can share their link as yourshop.com/CODE and be attributed a conversion for each purchase made after visiting this page.

The problem:

Superfiliate creates Shopify redirects through the Shopify API. Those redirects apply to Shopify-served routes and do not automatically create matching routes on your headless storefront. For example, your Shopify store may use checkout.yourshop.com while your custom storefront uses yourshop.com. Your developers need to handle the creator paths on the custom storefront if you want those addresses to work there.

The solution:

A similar logic needs to be replicated on your backend. We expect you to have some logic that understands that yourshop.com/CODE should be redirected to the affiliate page, instead of showing a “Not found” page. Since our app is always creating new redirects when new affiliates are joining, ideally your redirect logic would be dynamic by always checking the existing redirects in Shopify API and replicating them, with same path and target attributes.

Do we need to implement this?

Not necessarily. This is only necessary if you want your affiliates to have the vanity URL be the same as your headless domain. If you're ok with affiliates sharing checkout.yourshop.com, this is not necessary.

Feature: Discount code auto application

How does it work:

Shopify provides an easy way to automatically apply a discount code at checkout by giving us the /discount/CODE endpoint. This endpoint simply pushes a cookie containing the affiliate discount code and redirects the user back to a website location. Every redirect built by our team at Superfiliate will attempt to automatically apply discount codes at checkout by using the /discount/ endpoint, followed by a chain of query parameters, including UTM params, but more importantly a redirect query param, that would point to where the user should be redirected after the discount was applied.

The problem:

Headless shops, even the ones built with Hydrogen, does not offer support to the /discount/CODE endpoint, meaning that the redirects coming from our application wouldn't be able to auto-apply the code at checkout, leading the user to a “Not found” page.

The solution:

Your backend should be prepared to handle /discount/CODE endpoint hits, by setting a cookie, or doing whatever logic you judge necessary so that the CODE is auto applied at checkout. Another necessary step would be to read the UTM params present in the URL and preferably keep them, as they're valuable UTM params. The redirect= query param should point to where the user is supposed to be redirect to (usually it's just the home page, but could be a PDP, a collection page, etc).

Do we need to implement this?

If you implemented the "Vanity affiliate links” feature above, then at least the “Not found” error handling would be necessary, otherwise every affiliate link would break. This means your backend needs to be prepared to receive /discount/ endpoint hits, even if your logic is just ignore the code and redirect back to home. The code auto-application and redirect logic are up to you. We offer this as a facilitator for user experience, but can be ignored if you judge as non-necessary.
If your program or a creator uses the External URL redirect destination, Superfiliate skips the /discount/ step and sends shoppers straight to that address, so the discount code is not applied automatically. See Choose where your creator links send shoppers.

Feature: Tracking outside of Superfiliate's Landing Pages

How does it work:

When creating your programs in Superfiliate, you have the option to choose whether to use our own Cobranded Landing Pages for your affiliates, or skip them completely and use your own website as your affiliates landing pages. If you choose to skip our landers, we are still able to track purchases made after visiting links and attributing those conversions to your affiliates, even if a discount code is not used at checkout. We can do that because Shopify allows us to add our own script tag into your store theme, so we're able to track visits.

The problem:

Since your shop is hosted outside of Shopify, we're not allowed to install our tracking script ourselves in your shop page. This means that any visit to an affiliate link that redirects back to your shop's website won't be tracked by our app as a possible conversion.

The solution:

This is a 2-step solution, that requires the script being installed, and then a function call being made inside affiliates pages.

Install this script to the header of your shop website. Remember to replace <MY_SHOPIFY_DOMAIN> with your domain that ends with .myshopify.com

<!-- Start of Superfiliate -->
<script type="text/javascript" async src="https://superfiliate-cdn.com/storefront.js?shop=<MY_SHOPIFY_DOMAIN>"></script>
<!-- End of Superfiliate -->

Call our method to register a page view.
```
$superfiliateStorefront.sdk.handlePageView();
```
We have our own internal logic to discard page views that don't seem to be referred by any Superfiliate. But feel free to also only trigger this when you believe to be best appropriate for your scenario. For example, we always send a utm_content= query param in our redirects, so you could also check for that attribute presence before triggering the function call, if you want.
If you see any errors saying that $superfiliateStorefront is not defined, it probably means the script wasn't installed correctly, or has not loaded yet.
The way you will call it depends a lot on your own specific implementation and framework, use the best-practices from there. But here are some other generic examples for inspiration:
```
<script>
  window.$superfiliateIntervalId = setInterval(() => {
    if (typeof $superfiliateStorefront !== "undefined") {
      clearInterval(window.$superfiliateIntervalId);
      $superfiliateStorefront.sdk.handlePageView();
    }
  }, 1000);
</script>
```
```

<script
  async
  src="..."
  onload="window.$superfiliateStorefront.sdk.handlePageView()" 
></script>

```

Do we need to implement this?

Superfiliate can record visits on its own Cobranded Landing Pages, but that does not confirm tracking is installed on your headless storefront. Install the storefront script and call handlePageView() to record supported visits there, including visits after leaving a landing page. Preserve Superfiliate’s tracking parameters through redirects and checkout, and follow your consent configuration. If the landing page and storefront use different root domains, do not rely on a shared cookie or assume a returning shopper retains the same tracking context. See domain and tracking guidance.
If your program or a creator's redirect destination uses the External URL option to send shoppers to your headless storefront, visits there are only tracked once this is in place.