Merge pull request #49 from klaviyo/202507_ECOS-10765

Configurable Variation Group Sync + API revision bump

Author: cykolln

CHANGELOG.md

@@ -10,6 +10,12 @@ bumped for multiple releases during one month.
 <!-- BEGIN RELEASE NOTES -->
 ### [Unreleased]
 
+### [25.7.0] - 25-07-29
+
+#### Added
+- Site preference to optionally sync variation group identifiers instead of variation base product ids on events. This feature requires collaboration with the Klaviyo support team, as there are Klaviyo integration configurations that also must be set internally.
+- Updates to Klaviyo API revision 2025-07-15. See https://developers.klaviyo.com/en/docs/changelog_
+
 ### [25.4.0] - 25-04-17
 
 #### Added
@@ -101,7 +107,8 @@ bumped for multiple releases during one month.
 <!-- END RELEASE NOTES -->
 
 <!-- BEGIN LINKS -->
-[Unreleased]: https://github.com/klaviyo/SFCC_Klaviyo/compare/25.4.0...HEAD
+[Unreleased]: https://github.com/klaviyo/SFCC_Klaviyo/compare/25.7.0...HEAD
+[25.7.0]: https://github.com/klaviyo/SFCC_Klaviyo/compare/25.4.0...25.7.0
 [25.4.0]: https://github.com/klaviyo/SFCC_Klaviyo/compare/24.9.0...25.4.0
 [24.9.0]: https://github.com/klaviyo/SFCC_Klaviyo/compare/24.1.0...24.9.0
 [24.1.0]: https://github.com/klaviyo/SFCC_Klaviyo/compare/23.7.0...24.1.0

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/eventData/addedToCart.js

@@ -33,6 +33,7 @@ function getData(basket) {
             var lineItem = basketItems[itemIndex];
             var currentProductID = lineItem.productID;
             var basketProduct = ProductMgr.getProduct(currentProductID);
+
             if (!basketProduct) {
                 throw new Error('Product with ID [' + currentProductID + '] not found');
             }
@@ -67,10 +68,11 @@ function getData(basket) {
                     primaryCategory           : primaryCategory
                 };
 
-                if (!basketProduct.master && 'masterProduct' in basketProduct) {
-                    currentLineItem.masterProductID = basketProduct.masterProduct.ID;
+                if (basketProduct.variant) {
+                    currentLineItem.masterProductID = klaviyoUtils.getParentProductId(basketProduct);
                 }
 
+
                 var priceData = klaviyoUtils.priceCheck(lineItem, basketProduct);
                 currentLineItem.price = priceData.purchasePrice;
                 currentLineItem.priceValue = priceData.purchasePriceValue;

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/eventData/orderConfirmation.js

@@ -131,8 +131,8 @@ function getData(order) {
                     'Product Image URL'      : KLImageSize ? productDetail.getImage(KLImageSize).getAbsURL().toString() : null
                 };
 
-                if (!productDetail.master && 'masterProduct' in productDetail) {
-                    currentLineItem['Master Product ID'] = productDetail.masterProduct.ID;
+                if (productDetail.variant) {
+                    currentLineItem['Master Product ID'] = klaviyoUtils.getParentProductId(productDetail);
                 }
 
                 var priceData = klaviyoUtils.priceCheck(productLineItem, productDetail);

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/eventData/startedCheckout.js

@@ -45,8 +45,8 @@ function getData(currentBasket) {
             if (currentProductID != null && !empty(basketProduct) && basketProduct.getPriceModel().getPrice().value > 0) {
                 var productObj = prepareProductObj(lineItem, basketProduct, currentProductID);
 
-                if (!basketProduct.master && 'masterProduct' in basketProduct) {
-                    productObj['Master Product ID'] = basketProduct.masterProduct.ID;
+                if (basketProduct.variant) {
+                    productObj['Master Product ID'] = klaviyoUtils.getParentProductId(basketProduct);
                 }
 
                 if (options && options.length) {

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/eventData/viewedProduct.js

@@ -22,10 +22,16 @@ function getData(productID) {
             throw new Error('Product with ID [' + productID + '] not found');
         }
 
+        data['Product ID'] = klaviyoUtils.getParentProductId(product);
+
+        if (!product.master && 'masterProduct' in product) {
+            // this is very unlikely to happen because PDPs are not typically used for variants
+            data['Master Product ID'] = product.masterProduct.ID;
+        }
+
         var prices = require('*/cartridge/scripts/klaviyo/viewedProductHelpers.js').getProductPrices(product);
 
         klaviyoUtils.setSiteIdAndIntegrationInfo(data, siteId);
-        data['Product ID'] = product.ID;
         data['Product Name'] = product.name;
         data['Product Page URL'] = URLUtils.https('Product-Show', 'pid', product.ID).toString();
         data['Product Image URL'] = product.getImage(KLImageSize).getAbsURL().toString();
@@ -37,10 +43,6 @@ function getData(productID) {
         data['value'] = prices.price;
         data['value_currency'] = session.getCurrency().getCurrencyCode();
 
-        if (!product.master && 'masterProduct' in product) {
-            data['Master Product ID'] = product.masterProduct.ID;
-        }
-
         var categories = [];
         var catProduct = (product.variant) ? product.masterProduct : product;
         for (var i = 0, len = catProduct.categoryAssignments.length; i < len; i++) {

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/services.js

@@ -10,15 +10,15 @@ var Site = require('dw/system/Site');
  * @returns {string} API version in YYYY-MM-DD format
  */
 function getApiVersion() {
-    return '2025-04-15';
+    return '2025-07-15';
 }
 
 /**
  * Returns the User-Agent string used in the X-Klaviyo-User-Agent header
  * @returns {string} User-Agent string
  */
 function getUserAgent() {
-    return 'sfcc-klaviyo/25.4.0';
+    return 'sfcc-klaviyo/25.7.0';
 }
 
 // HTTP Services

cartridges/int_klaviyo_core/cartridge/scripts/klaviyo/utils.js

@@ -82,6 +82,38 @@ function dedupeArray(items) {
 }
 
 
+// this uses the use_variation_group_id site preference to determine if the base product ID should be the variation group ID or the master product ID.
+// this site preference is ONLY to be used in collaboration with Klaviyo support, because there is additional configuration required during integration setup in Klaviyo.
+// this is so that Klaviyo can correctly attribute events to the correct catalog item in Klaviyo, for use in reporting, product feeds, flows, etc.
+function getParentProductId(product) {
+    if (!product) {
+        return null;
+    }
+
+    var useVariationGroup = Site.getCurrent().getCustomPreferenceValue('use_variation_group_id') || false;
+
+    if (useVariationGroup) {
+        // Return variation group ID when preference is enabled
+        if (product.variant) {
+            var productVariationModel = product.getVariationModel();
+            var groups = productVariationModel.getVariationGroups();
+            return groups.length > 0 ? groups[0].ID : null;
+        } else if (product.variationGroups.length > 0) {
+            return product.variationGroups[0].ID;
+        }
+        // Fallback for other product types (bundle, set, etc.) or items w/o variations
+        return product.ID;
+    }
+
+    // Return master product ID for variants when preference is disabled (the default)
+    if (!product.master && 'masterProduct' in product) {
+        return product.masterProduct.ID;
+    }
+
+    // Return product ID for master products or standalone items
+    return product.ID;
+}
+
 // helper function to extract product options and return each selected option into an object with five keys: 'Line Item Text', 'Option ID' and 'Option Value ID', 'Option Price' and 'Option Price Value.
 // This helper accomodates products that may have been configured with or feature multiple options by returning an array of each selected product option as its own optionObj.
 function captureProductOptions(prodOptions) {
@@ -405,6 +437,7 @@ module.exports = {
     getProfileInfo        : getProfileInfo,
     prepareDebugData      : prepareDebugData,
     dedupeArray           : dedupeArray,
+    getParentProductId    : getParentProductId,
     captureProductOptions : captureProductOptions,
     captureProductBundles : captureProductBundles,
     captureBonusProduct   : captureBonusProduct,

metadata.zip

@@ -63,7 +63,7 @@ test.describe('Test Klaviyo started checkout event', () => {
         expect(eventData.external_catalog_id).toBe(KLAVIYO_E2E_TEST_SITE_ID);
         expect(eventData.integration_key).toBe(KLAVIYO_DEMANDWARE_INTEGRATION_KEY);
         expect(eventData['Item Count']).toBe(1);
-        expect(eventData.line_items[0]['Product Name']).toBe('Incase');
+        expect(eventData.line_items[0]['Product Name']).toBe('Bootleg Trouser');
         expect(eventData['$email']).toBe(email);
     });
 });
@@ -97,8 +97,8 @@ test.describe('Test Klaviyo add to cart event', () => {
         expect(eventData.integration_key).toBe(KLAVIYO_DEMANDWARE_INTEGRATION_KEY);
 
         expect(eventData.itemCount).toBe(1);
-        expect(eventData.lineItems[0].productName).toBe('Incase');
-        expect(eventData.productAddedToCart.productName).toBe('Incase');
+        expect(eventData.lineItems[0].productName).toBe('Bootleg Trouser');
+        expect(eventData.productAddedToCart.productName).toBe('Bootleg Trouser');
     });
 });
 
@@ -115,7 +115,7 @@ test.describe('Test Klaviyo order confirmation event', () => {
         await checkoutPage.fillShippingForm(testData);
         await checkoutPage.submitShippingForm();
         await checkoutPage.fillPaymentForm(paymentData);
-        await page.waitForTimeout(3000);
+        await page.waitForTimeout(10000);
         expect(await page.innerText('h1.page-title')).toBe('Thank You');
 
         const events = await checkEventWithRetry(email, KLAVIYO_METRIC_ID_ORDER_CONFIRMATION);
@@ -135,7 +135,7 @@ test.describe('Test Klaviyo order confirmation event', () => {
 
         expect(eventData['Item Count']).toBe(1);
         expect(eventData.product_line_items.length).toBe(1);
-        expect(eventData.product_line_items[0]['Product Name']).toBe('Incase');
+        expect(eventData.product_line_items[0]['Product Name']).toBe('Bootleg Trouser');
     });
 });
 

test/src/tests/e2e/sfra/checkout/checkout-tests.spec.js

@@ -52,7 +52,7 @@ test.describe('Test Klaviyo viewed product event', () => {
         expect(metricData.attributes.integration.key).toBe('api');
 
         // Validate event data
-        expect(eventData['Product Name']).toBe('Incase');
+        expect(eventData['Product Name']).toBe('Bootleg Trouser');
         expect(eventData.external_catalog_id).toBe(KLAVIYO_E2E_TEST_SITE_ID);
         expect(eventData.integration_key).toBe(KLAVIYO_DEMANDWARE_INTEGRATION_KEY);
     });