Skip to main content

Checkout Tracking Implementation

Updated

📌 Overview

 

Checkout Tracking allows Hue to measure how much Hue content contributes to your store's conversions. To do this, we track which product variants were purchased as a result of a shopper interacting with a Hue module.

A purchase is attributed to Hue when either of the following is true:

  • The product variant was added to cart directly from the Hue module.
  • The product variant was added to cart using the PDP's Add to Cart button, after the shopper interacted with a Hue module.

A shopper is considered to have "interacted" with a Hue module if they:

  • Clicked on any element within a Hue module, or
  • Watched a video review.

 

💡 Why Do We Use This?

  • You want visibility into how Hue content is influencing purchases on your store.
  • You want accurate conversion reporting that reflects Hue's actual impact.

 

🪜 How It Works

Shopify allows merchants to collect and pass behavioral customer data for marketing and reporting purposes through Pixels — JavaScript snippets with access to customer events like page_viewed and checkout_completed.

Hue uses this functionality to listen for the checkout_completed event. When it fires, Hue logs the relevant checkout data.

 

Integration Options


Option 1: Hue Assisted

Hue can complete the integration on your behalf, allowing us to verify the accuracy of your metrics.

To enable this, grant Hue's Collaborator Account the following permissions under Store Settings:

  • View customer events
  • Manage and add custom pixels

 

Option 2: Self-Serve Integration (Shopify)

If you'd rather set this up yourself:

  1. Log in to your Shopify admin panel.
  2. Open the Settings menu in the bottom-left corner.
  3. Select the Customer events tab.
  4. Click Add custom pixel.
  5. Give the pixel any name you'd like.
  6. Paste in the following code:
 
javascript
analytics.subscribe("checkout_completed", async (event) => {
  const { lineItems, totalPrice, order } = event.data.checkout
  const hueCustomerId = window.localStorage.getItem('hue_customer_id') || ''

  // filter out only hue related attributes
  const hueAttrs = event.data.checkout.attributes.filter((obj) => {
    return obj.key.startsWith('hue_event_')
  })

  const eventsToLog = []

  for (const item of lineItems) {
    const hueMetadata = hueAttrs.find(({ key }) => {
      const splitted = key.split('hue_event_')
      return splitted[splitted.length - 1] === item.variant.id
    })

    let eventToTrack = {
      cartTotalPrice: totalPrice,
      variantId: item.variant.id,
      productId: item.variant.product.id,
      cartId: order.id,
      isFirstOrder: order?.customer?.isFirstOrder,
      quantity: item.quantity,
      variantPrice: item.variant.price,
      storefront: window.location.hostname,
      customerId: hueCustomerId
    }

    if (hueMetadata?.value) {
      eventToTrack = {
        ...eventToTrack,
        ...JSON.parse(hueMetadata.value),
      }
    }

    eventsToLog.push(eventToTrack)
  }

  try {
    fetch('https://api.poweredbyhue.app/shoppers-api/v1/analytics/checkout', {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        data: eventsToLog
      }),
      keepalive: true
    })
  } catch(err) {
    console.log(err)
  }
});
  1. Click Save in the top-left corner.
  2. Once saved, click Connect.

You're all set! Please notify the Hue team once this step is complete.

Note: See the recommended privacy settings for this pixel in the screenshot below. (Insert privacy settings screenshot here.)

 

 


Option 3: Non-Shopify Integration

If your store isn't built on Shopify, your own system can call Hue's API directly to log checkout events once a purchase is completed. The implementation is very similar to the Shopify pixel above.

Your system will need to build an eventToTrack object for each line item in the purchase, using values from your own system:

 
javascript
const log_checkout = () => {
   // This line looks up the hue_customer_id, so that this checkout event
   // can be matched up with other events like viewing a review video.
   // This is used for metrics reporting like conversion rates.
   const hueCustomerId = window.localStorage.getItem('hue_customer_id') || ''

  // Add your code here to provide the lineItems

  const eventsToLog = []
  for (const item of lineItems) {
    let eventToTrack = {
      cartTotalPrice: totalPrice,
      variantId: item.variantId,
      productId: item.productId,
      cartId: orderId,
      isFirstOrder: isFirstOrder,
      quantity: item.quantity,
      variantPrice: item.price,
      storefront: window.location.hostname,
      customerId: hueCustomerId
    }
    eventsToLog.push(eventToTrack)
  }

  try {
    fetch('https://api.poweredbyhue.app/shoppers-api/v1/analytics/checkout', {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        data: eventsToLog
      }),
      keepalive: true
    })
  } catch(err) {
    console.log(err)
  }
}


Here's an example of the events generated for a checkout with two line items. The variantId values are your own system's IDs, and customerId is provided by Hue and looked up in the first line of the function above. (isFirstOrder is optional.)

 
javascript
eventsToLog = [{
  cartTotalPrice: { amount: 80.0, currencyCode: "USD" },
  variantId: "VARIANT_123",
  productId: "PRODUCT_ID_FROM_YOUR_SYSTEM_1",
  cartId: "ORDER_ID_FROM_YOUR_SYSTEM",
  isFirstOrder: true,
  quantity: 1,
  variantPrice: { amount: 32.0, currencyCode: "USD" },
  storefront: "https://www.yourwebsite.com/",
  customerId: "$device:194d4494f80125-04edf4b1e24a47-1d525636-384000-194d4494f81125"
},
{
  cartTotalPrice: { amount: 80.0, currencyCode: "USD" },
  variantId: "VARIANT_456",
  productId: "PRODUCT_ID_FROM_YOUR_SYSTEM_2",
  cartId: "ORDER_ID_FROM_YOUR_SYSTEM",
  isFirstOrder: true,
  quantity: 3,
  variantPrice: { amount: 16.0, currencyCode: "USD" },
  storefront: "https://www.yourwebsite.com/",
  customerId: "$device:194d4494f80125-04edf4b1e24a47-1d525636-384000-194d4494f81125"
}]


📍 What Gets Logged

Once a shopper completes an order, Hue logs a Checkout event with the following properties. This only happens if the cart contains at least one product that Hue is integrated on, since we're only interested in purchases that may have been influenced by a Hue interaction.

PropertyDescription
cartIdUnique identifier for the entire cart. If you want to know the number of items in a cart, group records by cartId.
cartTotalPriceTotal value of the cart — post-tax, post-discount, post-shipping. (Can also be calculated by summing the prices of all items under the same cartId.)
productIdExternal ID of the product.
isFirstOrderIndicates whether this was the shopper's first purchase.
quantityQuantity of a single item in the cart. For example, if a shopper buys 3 of the same variant, this generates one event with quantity: 3.
storefrontThe URL the checkout event originated from.
variantIdExternal ID of the product variant.
variantPricePrice of a single unit of the variant. To calculate total spend on a variant, multiply variantPrice by quantity.


🛠️ Troubleshooting

I don't see the Customer Events tab in Shopify Settings

  • Confirm you have admin-level access to your Shopify store. This setting is typically restricted to store owners and staff with full permissions.

I'm not sure the pixel is working correctly

  • Consider using Option 1: Hue Assisted so our team can verify the setup and confirm events are being logged accurately.

I have a custom storefront and I'm not sure how to integrate

  • Use Option 3: Non-Shopify Integration and call Hue's API directly from your checkout completion logic.

Related articles