> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use Direct-to-Checkout UTM links

> Learn how to trigger post-purchase funnels using UTM parameters, including setup for direct-to-checkout links

Aftersell supports triggering funnels based on UTM parameters, which is an optional feature specifically intended for advanced use cases. You can configure your funnel to activate when a customer visits your site with a specific UTM query string.

This setup is optional and typically required only for advanced tracking needs, such as direct-to-checkout links or campaign-specific offers.

## How UTM triggers work

UTM triggers allow you to show specific post-purchase funnels based on UTM parameters in the URL. This is useful for:

* **Campaign-specific offers** - Show different upsells based on the marketing campaign
* **Direct-to-checkout links** - Trigger funnels when customers skip the storefront
* **Channel attribution** - Personalize offers based on traffic source (email, social media, ads)
* **A/B testing** - Test different offers for different campaign variations

## Quick start: Basic UTM trigger setup

For standard storefront visits (not direct-to-checkout), you can set up UTM triggers using the Aftersell app embed. To see how to quickly get started with UTM triggers, check out this video:

<iframe src="https://go.screenpal.com/player/cOfD38nOD9i" title="How to set up UTM Triggers" allowFullScreen style={{ width: '100%', aspectRatio: '16/9', borderRadius: '12px' }} />

### Enable the UTM app embed

To track UTM parameters on storefront pages:

1. In your Shopify admin, go to **Online Store > Themes**
2. Click **Customize** on your active theme
3. In the theme editor, click the **App embeds** icon (puzzle piece) in the left sidebar
4. Find **Aftersell UTM Tracker** and toggle it **on**
5. Click **Save**

Once enabled, Aftersell will automatically capture UTM parameters when customers visit your storefront with UTM links.

### Configure UTM triggers in your funnel

After enabling the app embed:

1. Go to **Post-purchase Funnels** in the Aftersell admin
2. Create or edit a funnel
3. In the **Triggers** section, add a **UTM Parameter** trigger
4. Configure the UTM parameter and value you want to match
5. Save your funnel

## Supported UTM parameters

Aftersell supports the following standard UTM parameters:

* `utm_source` - Identifies the traffic source (e.g., google, newsletter, facebook)
* `utm_medium` - Identifies the marketing medium (e.g., email, cpc, social)
* `utm_campaign` - Identifies the specific campaign (e.g., spring\_sale, product\_launch)
* `utm_term` - Identifies paid search keywords (e.g., running+shoes)
* `utm_content` - Differentiates similar content or links (e.g., banner\_ad, text\_link)
* `utm_id` - Identifies the campaign ID (e.g., campaign\_123)

All six parameters are tracked and can be used to trigger funnels.

## Partial field matching

When configuring UTM triggers, Aftersell supports **partial matching** for UTM parameter values. This means:

* ✅ **Trigger value:** `spring` → **Matches:** `spring_sale`, `spring_2026`, `early_spring`
* ✅ **Trigger value:** `email` → **Matches:** `email_newsletter`, `promotional_email`
* ✅ **Trigger value:** `sale` → **Matches:** `spring_sale`, `flash_sale`, `sale_2026`

This flexibility allows you to create broader triggers that match multiple campaign variations without creating separate triggers for each one.

**Example:** If you set a trigger for `utm_campaign` contains `sale`, it will match any campaign with "sale" in the name, such as `spring_sale`, `summer_sale`, or `flash_sale_2026`.

## Direct-to-checkout UTM links

The basic setup shown in the video above does **not** support links that send customers **directly to checkout**. By default, Aftersell can only detect UTM parameters on storefront pages. This is because it relies on a theme app embed, which works only on storefront pages and not on the checkout or thank-you page.

### Enable UTM tracking on checkout pages

To track UTM parameters on the checkout page (for direct-to-checkout links), you need to **add a Shopify Pixel** to your store.

⚠️ **Important limitations:**

* This setup requires the visitor to have a **cart token** when they arrive at checkout through a UTM link. Without a cart token, the UTM data will not be captured.
* **Express checkout methods (Shop Pay, Apple Pay, Google Pay) are not supported** because they bypass the cart and do not generate a cart token. Customers using express checkout will not trigger UTM-based funnels.

### Setting up the Shopify pixel

Follow these step-by-step instructions to set up direct-to-checkout UTM tracking:

1. In your Shopify admin, go to **Settings > Customer Events**.
2. Click **Add Custom Pixel** and give it any name you like.
3. Under the **Permission** dropdown, select **Analytics**. This is the only permission required.
4. For the **Data Sale** dropdown, you can choose **Data collected does not qualify as data sale**. Aftersell keeps all collected data private and never shares it with anyone other than you.
5. In the code editor that appears, paste in the code provided below.
6. Click **Save**, then **Connect**.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
/**  
 * IMPORTANT: This pixel can only fire on sessions where the  
 * customer has a cart object, otherwise it will be skipped.  
 * For example, clicking "Buy Now" on a product page skips the cart,  
 * going directly to checkout.  
**/  
function processData({event, cartToken}) {  
  // TODO: Edit MYSHOPIFY_DOMAIN to your domain. E.g.  
  // const MYSHOPIFY_DOMAIN = 'example-store.myshopify.com';  
  const MYSHOPIFY_DOMAIN = '';  
  
  const enableDebug = false;  
  
  // DO NOT EDIT PAST HERE  
  const SESSION_STORAGE_KEY = 'as-customer-trigger-data';  
  const HOST = 'https://start.aftersell.app';  
  
  if (!MYSHOPIFY_DOMAIN) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing Shopify domain");  
    }  
    return;  
  }  
  if (!cartToken) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing cart token");  
    }  
  }  
    
  let existingCustomerData = null;  
  try {  
      existingCustomerData = JSON.parse(  
          sessionStorage.getItem(SESSION_STORAGE_KEY) || 'null'  
      );  
  } catch (ignore) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because malformed user data json");  
    }  
  }  
    
  const allowedUrlParams = [  
        'utm_source',  
        'utm_medium',  
        'utm_campaign',  
        'utm_term',  
        'utm_id',  
        'utm_content',  
    ];  
    
  const searchParams = new URLSearchParams(event.context.window.location.search);  
  let hasCustomerData = false;  
  const customerData = {};  
  for (const param of allowedUrlParams) {  
    const paramValue = searchParams.get(param) || existingCustomerData?.[param];  
    if (paramValue) {  
        hasCustomerData = true;  
        customerData[param] = paramValue;  
    }  
  }  
  
  if (hasCustomerData) {  
    sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(customerData));  
  
    const postBody = {  
      shop: MYSHOPIFY_DOMAIN,  
      cartToken,  
      checkoutToken: event.data.checkout.token ?? undefined,  
      customerTriggerData: customerData,  
    };  
  
    if (enableDebug) {  
      console.log("UTM pixel fired with the following data:", postBody);  
    }  
      
    fetch(`\${HOST}/api/v1/storefrontSessions`, {  
        method: 'POST',  
        headers: {  
            'Content-Type': 'application/json',  
        },  
        body: JSON.stringify(postBody),  
    });  
  } else {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because there was no data to send");  
    }  
  }  
}  
  
analytics.subscribe('checkout_started', (event) => {  
   // minimum realistic time between adding item to cart and clicking checkout  
    const COOKIE_POLLING_INTERVAL_MS = 500;  
  
    let currentCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
    processData({event, cartToken: currentCookieValue});  
  
    setInterval(() => {  
        const newCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
        if (newCookieValue !== currentCookieValue) {  
            currentCookieValue = newCookieValue;  
            processData({event, cartToken: newCookieValue});  
        }  
    }, COOKIE_POLLING_INTERVAL_MS);  
});  
  
function getCookieValue({ cookie, cookieName }) {  
    const cartCookieRegex = new RegExp(`^\${cookieName}=`);  
    const cartCookie = cookie  
        .split(';')  
        .map((val) => val.trim())  
        .find((val) => cartCookieRegex.test(val));  
    if (!cartCookie) return null;  
    const cartCookieValue = cartCookie.replace(`\${cookieName}=`, '');  
    return cartCookieValue;  
}
```

**Important configuration notes:**

* **Edit `MYSHOPIFY_DOMAIN`:** You must replace the empty string with your store's myshopify.com domain (e.g., `'example-store.myshopify.com'`)
* **Enable debug mode (optional):** Set `enableDebug = true` to see console logs for troubleshooting
* **Supported parameters:** The pixel tracks all six standard UTM parameters listed in the `allowedUrlParams` array

## Testing your UTM trigger setup

After setting up UTM triggers, use this checklist to verify everything is working correctly:

### For storefront UTM tracking (app embed)

* ✅ **App embed enabled:** Verify the Aftersell UTM Tracker app embed is toggled on in your theme settings
* ✅ **Test URL:** Visit your store with a UTM parameter (e.g., `yourstore.com?utm_campaign=test`)
* ✅ **Complete purchase:** Add a product to cart and complete checkout
* ✅ **Check funnel:** Verify the correct funnel appears on the thank-you page
* ✅ **Order browser:** Check the Aftersell Order Browser to confirm the UTM trigger was detected

### For direct-to-checkout UTM tracking (Shopify pixel)

* ✅ **Pixel installed:** Verify the custom pixel is saved and connected in Settings > Customer Events
* ✅ **Domain configured:** Confirm `MYSHOPIFY_DOMAIN` is set correctly in the pixel code
* ✅ **Cart token present:** Ensure the customer has items in cart before going to checkout (required for tracking)
* ✅ **Test URL:** Use a direct-to-checkout link with UTM parameters (e.g., `yourstore.com/checkout?utm_campaign=test`)
* ✅ **Complete purchase:** Complete the checkout process
* ✅ **Check funnel:** Verify the correct funnel appears on the thank-you page
* ✅ **Order browser:** Check the Aftersell Order Browser to confirm the UTM trigger was detected
* ⚠️ **Express checkout:** Remember that Shop Pay, Apple Pay, and Google Pay will NOT work with UTM triggers

### Troubleshooting tips

If UTM triggers are not working:

1. **Enable debug mode:** Set `enableDebug = true` in the pixel code and check browser console for error messages
2. **Verify cart token:** Ensure customers have items in cart before reaching checkout (pixel requires cart token)
3. **Check trigger configuration:** Verify the UTM parameter and value in your funnel trigger match the URL parameters
4. **Test partial matching:** Remember that triggers use partial matching - `sale` will match `spring_sale`, `flash_sale`, etc.
5. **Check funnel priority:** If multiple funnels match, only the highest priority funnel will show
6. **Review Order Browser:** Use the Aftersell Order Browser to see which triggers fired for each order

## Best practices for UTM triggers

* **Use consistent naming:** Establish a naming convention for your UTM parameters (e.g., `utm_campaign=email_spring_2026`)
* **Leverage partial matching:** Use broader trigger values to match multiple campaign variations
* **Test before launching:** Always test your UTM links and triggers before sending to customers
* **Document your campaigns:** Keep a record of which UTM parameters you're using for each campaign
* **Combine with other triggers:** Use UTM triggers alongside product or order value triggers for more precise targeting
* **Monitor performance:** Regularly check the Order Browser to see which UTM campaigns are driving the most upsells