eCommerce Programs Only

On standard Shopify (Liquid) themes, Kickbooster's app embed handles referral tracking automatically and no code changes are required. Hydrogen storefronts are headless and don't run theme app embeds, so you'll need to capture referral tracking in your Hydrogen app yourself. This guide shows you how.

How Tracking Works

Every Kickbooster referral link includes four tracking parameters in the URL:

kbr_medium
kbr_source
kbr_content
kbr_campaign

To attribute an order to the referring affiliate, these four values need to be saved as cart attributes on the customer's cart. Cart attributes automatically carry through checkout onto the order, where Kickbooster reads them to credit the correct affiliate. The attribute keys must match the parameter names exactly — don't rename or prefix them.

Step 1: Handle Attribute Updates in Your Cart Route

In your cart route (app/routes/cart.tsx in the standard Hydrogen skeleton), make sure the action handles CartForm.ACTIONS.AttributesUpdateInput. If the visitor doesn't have a cart yet — which is usually the case when they first land from a referral link — create one with the attributes instead:

import {CartForm, type CartQueryDataReturn} from '@shopify/hydrogen';
import {data, type ActionFunctionArgs} from 'react-router';

export async function action({request, context}: ActionFunctionArgs) {
  const {cart} = context;
  const formData = await request.formData();
  const {action, inputs} = CartForm.getFormInput(formData);

  let result: CartQueryDataReturn;

  switch (action) {
    // ... your existing cases (LinesAdd, LinesUpdate, etc.)
    case CartForm.ACTIONS.AttributesUpdateInput:
      // Create the cart with the attributes if the visitor doesn't have one yet
      result = cart.getCartId()
        ? await cart.updateAttributes(inputs.attributes)
        : await cart.create({attributes: inputs.attributes});
      break;
    default:
      throw new Error(`${action} cart action is not defined`);
  }

  // The cart ID may change after each mutation, so update the cookie each time
  const headers = cart.setCartId(result.cart.id);
  return data(result, {status: 200, headers});
}

If your cart route already has a switch statement handling other cart actions, you only need to add the AttributesUpdateInput case.

Step 2: Add a Tracking Component

Create a component that reads the kbr parameters from the URL and submits them to your cart route:

// app/components/KickboosterTracking.tsx
import {useEffect, useRef} from 'react';
import {useFetcher, useLocation} from 'react-router';
import {CartForm} from '@shopify/hydrogen';

const TRACKING_KEYS = ['kbr_medium', 'kbr_source', 'kbr_content', 'kbr_campaign'];

export function KickboosterTracking(): null {
  const fetcher = useFetcher();
  const {search} = useLocation();
  const submitted = useRef(false);

  useEffect(() => {
    if (submitted.current) return;

    const params = new URLSearchParams(search);
    const attributes = TRACKING_KEYS.map((key) => ({
      key,
      value: params.get(key) ?? '',
    })).filter((attribute) => attribute.value);

    // Only track when a full Kickbooster referral link is present
    if (attributes.length !== TRACKING_KEYS.length) return;

    submitted.current = true;
    fetcher.submit(
      {
        [CartForm.INPUT_NAME]: JSON.stringify({
          action: CartForm.ACTIONS.AttributesUpdateInput,
          inputs: {attributes},
        }),
      },
      {method: 'POST', action: '/cart'},
    );
  }, [search, fetcher]);

  return null;
}

Then render it once in your root layout (app/root.tsx) so it runs on every page a customer might land on:

import {KickboosterTracking} from '~/components/KickboosterTracking';

// Inside your Layout or App component's returned JSX:
<KickboosterTracking />

The component only submits when all four parameters are present, so regular (non-referral) visits are unaffected.

Step 3: Verify Tracking Is Working

Visit your storefront using an affiliate's referral link (or any URL with test values, e.g. ?kbr_medium=affiliate&kbr_source=test&kbr_content=test&kbr_campaign=test)
Add a product to the cart and confirm the cart's attributes contain the four kbr values (you can check the /cart fetcher response in your browser's network tab, or query the cart with the attributes field included)
Place a test order — the referral should appear on your Kickbooster dashboard once the order is completed

Things to Keep in Mind

Make sure your cart query includes the attributes field in its fragment if you want to inspect attributes on the cart object in your app.
This approach saves tracking on the initial visit. Attribution lasts as long as the customer's cart — if the cart is cleared or a new one is created before purchase, the tracking attributes are lost. You can additionally persist the parameters in a cookie and re-apply them for longer attribution windows.
The attribute keys must be exactly kbr_medium, kbr_source, kbr_content, and kbr_campaign for Kickbooster to attribute the order.

Implementing Kickbooster Tracking on a Shopify Hydrogen Storefront