Create Custom Events

Last update: Mon Sep 15 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

Admin
Developer

You can extend the eventing platform by creating your own storefront events to collect data unique to your industry. When you create and configure a custom event, it is sent to the Adobe Commerce Events Collector.

Handle custom events

Custom events are supported for the Adobe Experience Platform only. Custom data is not forwarded to Adobe Commerce dashboards and metrics trackers.

For any custom event, the collector:

Adds identityMap with ECID as a primary identity
Includes email in identityMap as a secondary identity if personalEmail.address is set in the event
Wraps the full event inside an xdm object before forwarding to the Edge

Example:

Custom event published through Adobe Commerce Events SDK:

mse.publish.custom({
    commerce: {
        saveForLaters: {
            value: 1,
        },
    },
});

In Experience Platform Edge:

{
  xdm: {
    identityMap: {
      ECID: [
        {
          id: 'ecid1234',
          primary: true
        }
      ],
      email: [
        {
          id: "runs@safari.ke",
          primary: false
        }
      ]
    },
    commerce: {
        saveForLaters: {
            value: 1
        }
    }
  }
}

NOTE

Using custom events may affect default Adobe Analytics reports.

Handle event overrides (custom attributes)

For any event set with a customContext, the collector overrides or extends fields in the event payload from the fields in the custom context. The use case for overrides is when a developer wants to reuse and extend contexts set by other parts of the page in already supported events.

Event overrides are only applicable when forwarding to Experience Platform. They are not applied to Adobe Commerce and Sensei analytics events. The Adobe Commerce Events Collector README provides additional info.

NOTE

When augmenting productListItems with custom attributes in Experience Platform event payloads, match products using SKU. This requirement does not apply to product-page-view events.

Usage

const mse = window.magentoStorefrontEvents;

mse.publish.productPageView(customCtx);

Example 1

This example adds custom context when publishing the event.

magentoStorefrontEvents.publish.productPageView({
    productListItems: [
        {
            productCategories: [
                {
                    categoryID: "cat_15",
                    categoryName: "summer pants",
                    categoryPath: "pants/mens/summer",
                },
            ],
        },
    ],
});

Example 2

This example adds custom context before publishing the event.

const mse = window.magentoStorefrontEvents;

mse.context.setCustom({
  productListItems: [
    {
      productCategories: [
        {
          categoryID: "cat_15",
          categoryName: "summer pants",
          categoryPath: "pants/mens/summer",
        },
      ],
    },
  ],
});

mse.publish.productPageView();

Example 3

This example sets the custom context in the publisher and overwrites the custom context previously set in the Adobe Client Data Layer.

In this example, the pageView event will have Custom Page Name 2 in the web.webPageDetails.name field.

const mse = window.magentoStorefrontEvents;

mse.context.setCustom({
  web: {
    webPageDetails: {
      name: 'Custom Page Name 1'
    },
  },
});

mse.publish.pageView({
  web: {
    webPageDetails: {
      name: 'Custom Page Name 2'
    },
  },
});

Example 4

This example adds custom context to productListItems events with multiple products.

const mse = window.magentoStorefrontEvents;

mse.context.setCustom({
  productListItems: [
    {
      SKU: "24-WB01", //Match SKU to override correct product in event payload
      productCategory: "Hand Bag", //Custom attribute added to event payload
      name: "Strive Handbag (CustomName)" //Override existing attribute with custom value in event payload
    },
    {
      SKU: "24-MB04",
      productCategory: "Backpack Bag",
      name: "Strive Backpack (CustomName)"
    },
  ],
});

mse.publish.shoppingCartView();

Luma-based stores:

Luma-based stores natively implement publishing events, so you can set custom data by extending customContext.

For example:

mse.context.setCustom({
  web: {
    webPageDetails: {
      name: 'Custom Page Name'
    },
  },
});

NOTE

Overriding events with custom attributes may affect default Adobe Analytics reports.

recommendation-more-help

1dd1eb92-da61-46c0-8ff9-3831f21eb23e