Using Superfiliate with a Headless Storefront

Last updated: April 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.

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:

Via Shopify API, Superfiliate only has access to create redirects from your “Online Store” configured domain. By going headless, Shopify demands you to have 2 different domains: one for the online store theme, and other for your hydrogen/in-house headless setup. For instance, usually the online store domain is something like checkout.yourshop.com and there's some logic implemented in your backend to redirect from checkout.yourshop.com back to yourshop.com . This unfortunately does not work out of the box for the affiliate redirects.

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.

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?

If you're using our own Cobranded Landing Pages, this would be not critical, as we'd still be able to track link visits. But we would not be tracking any visit to your own website as an affiliate page view. If you're NOT using our Cobranded Landing Pages, we highly recommend this is implemented, to avoid any tracking issues and make sure your affiliates are being rewarded for their conversions if their discount code is not used.