Analytics

Commerce Engine analytics has two independent layers:

@commercengine/analytics — a vendor-neutral, zero-runtime-dependency mapping package that turns canonical Commerce Engine entities into Segment/RudderStack-compatible ecommerce envelopes.
Hosted Checkout analytics forwarding — Hosted Checkout uses that package internally and sends the resulting envelopes to the parent application through onAnalyticsEvent.

The mapper package is not tied to Hosted Checkout, the Storefront SDK, Segment, or RudderStack. It can be used with:

Hosted Checkout
a custom checkout built with @commercengine/storefront
a custom checkout calling the REST API directly
browser analytics SDKs
server-side CDP SDKs
raw HTTP ingestion
a fully custom analytics implementation

Mental model

Commerce Engine entity or customer action
  → @commercengine/analytics mapper/builder
  → canonical track or identify envelope
  → your delivery adapter
  → Segment, RudderStack, another CDP, or your own pipeline

@commercengine/analytics performs only the mapping step. It does not:

load a vendor SDK
send network requests
manage consent
store identity
persist an event queue
prescribe where events must be delivered

That separation keeps event schemas consistent while leaving transport, consent, batching, retries, and destination ownership to the application.

Install the mapper package

npm install @commercengine/analytics

It consumes canonical Commerce Engine types through a type-only peer dependency:

Applications using @commercengine/storefront already satisfy that dependency.
REST-only TypeScript applications should also install the generated SDK type package:

npm install @commercengine/storefront-sdk

The analytics bundle itself has no runtime dependency on either SDK package; the peer exists so mapper inputs remain type-safe.

Three supported integration modes

Hosted Checkout

Hosted Checkout maps cart, coupon, checkout-step, payment, identity, and order interactions internally. The parent receives completed envelopes and only needs to forward them.

import type { AnalyticsEvent } from "@commercengine/checkout";
import { initCheckout } from "@commercengine/checkout";

function forwardCheckoutAnalytics(event: AnalyticsEvent) {
  if (event.type !== "track") return;
  analytics.track(event.event, event.properties);
}

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  onAnalyticsEvent: forwardCheckoutAnalytics,
});

Use @commercengine/checkout version 0.5.0 or later for onAnalyticsEvent. This minimal adapter forwards track events only; identity handling depends on which layer owns the Commerce Engine session and is covered below.

Do not rebuild the same checkout events in the parent application. Hosted Checkout already maps them from the canonical cart and order entities. Re-emitting them from both layers creates duplicate conversions and schema drift.

Custom checkout with the Storefront SDK

A custom checkout owns the customer interaction, so it decides when an event has occurred. Map the canonical entity returned by the SDK at that point.

import {
  orderProperties,
  toCartViewed,
  toCheckoutStarted,
  toOrderCompleted,
  trackArgs,
  trackEvent,
} from "@commercengine/analytics";

const { data: cartData, error: cartError } = await sdk.cart.getUserCart();
if (cartError || !cartData?.cart) {
  throw new Error(cartError?.message ?? "Cart not found");
}

analytics.track(...trackArgs(toCartViewed(cartData.cart)));
analytics.track(...trackArgs(toCheckoutStarted(cartData.cart)));

const { data: orderData, error: orderError } =
  await sdk.order.createOrder(orderInput);

if (orderError || !orderData?.order) {
  throw new Error(orderError?.message ?? "Order creation failed");
}

const order = orderData.order;
analytics.track(
  ...trackArgs(trackEvent("Order Created", orderProperties(order))),
);

if (!orderData.payment_required) {
  analytics.track(...trackArgs(toOrderCompleted(order)));
}

For a payment-required order, do not emit Order Completed after createOrder() or after one immediate status check. Provider callbacks are asynchronous, so the first response will commonly remain pending. Run conversion tracking from the same payment-return flow that drives the customer-facing result, or from a server-side payment-success webhook. A browser return flow should wait through pending states with a bounded verifier:

const MAX_POLLS = 40;
const POLL_INTERVAL_MS = 3_000;

async function waitForPayment(orderNumber: string) {
  for (let attempt = 0; attempt < MAX_POLLS; attempt += 1) {
    const { data, error, response } =
      await sdk.order.getPaymentStatus(orderNumber);

    if (error) {
      const status = response?.status;
      const transient =
        status === undefined ||
        status === 429 ||
        status >= 500;

      if (!transient) throw new Error(error.message);
    } else if (
      data?.status === "success" ||
      data?.status === "failed" ||
      (data?.status !== "pending" && data?.status !== "partially_paid")
    ) {
      return data;
    }

    await new Promise((resolve) =>
      setTimeout(resolve, POLL_INTERVAL_MS),
    );
  }

  return null;
}

const payment = await waitForPayment(order.order_number);

if (payment?.status === "success") {
  const { data: completed, error: orderDetailError } =
    await sdk.order.getOrderDetails({
      order_number: order.order_number,
    });

  if (orderDetailError || !completed?.order) {
    throw new Error(
      orderDetailError?.message ?? "Completed order could not be retrieved",
    );
  }

  analytics.track(...trackArgs(toOrderCompleted(completed.order)));
}

Do not start a second polling loop solely for analytics. Reuse the authoritative payment-status flow that already drives the checkout return page. If the bounded check ends in pending or times out, do not emit the conversion; let a later payment-return visit, account refresh, or idempotent server webhook record completion once success is authoritative. The package maps the entity; your application still owns the semantic trigger. For example, emit Checkout Started when the customer actually begins checkout, not merely because a cart happened to load.

Custom checkout with direct REST calls

The package works the same way when the Commerce Engine entity came from REST rather than the TypeScript SDK.

import {
  orderProperties,
  toCheckoutStarted,
  toOrderCompleted,
  trackArgs,
  trackEvent,
} from "@commercengine/analytics";
import type { Cart, Order } from "@commercengine/storefront-sdk";

const cartResponse = await fetch(`${baseUrl}/carts/${cartId}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

if (!cartResponse.ok) throw new Error("Unable to load cart");

const cartPayload = await cartResponse.json();
const cart = cartPayload.content.cart as Cart;
analytics.track(...trackArgs(toCheckoutStarted(cart)));

const orderResponse = await fetch(`${baseUrl}/orders`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "content-type": "application/json",
  },
  body: JSON.stringify(orderInput),
});

if (!orderResponse.ok) throw new Error("Unable to create order");

const orderPayload = await orderResponse.json();
const order = orderPayload.content.order as Order;
analytics.track(
  ...trackArgs(trackEvent("Order Created", orderProperties(order))),
);

if (!orderPayload.content.payment_required) {
  analytics.track(...trackArgs(toOrderCompleted(order)));
}

For payment-required REST orders, use the same bounded pending-state loop in the payment-return flow—or an idempotent server webhook—until GET /orders/{order_number}/payment-status reports success. Then retrieve GET /orders/{order_number} and map that current Order with toOrderCompleted(). One immediate status check and a redirect back from the payment provider are not proof of payment success. Prefer generated Commerce Engine types even in REST integrations. Do not create parallel hand-written cart, product, and order interfaces that can drift from the API.

Entity mappers

The package includes pure mappers for events that can be derived from canonical Commerce Engine entities.

Mapper	Event	Canonical input
`toProductsSearched`	`Products Searched`	Search string
`toProductViewed`	`Product Viewed`	`Product`, `ProductDetail`, or `Item`
`toProductClicked`	`Product Clicked`	`Product`, `ProductDetail`, or `Item`
`toProductListViewed`	`Product List Viewed`	Product entities
`toProductListFiltered`	`Product List Filtered`	Product entities
`toProductAdded`	`Product Added`	`CartItem`
`toProductRemoved`	`Product Removed`	`CartItem`
`toCartViewed`	`Cart Viewed`	`Cart`
`toCheckoutStarted`	`Checkout Started`	`Cart`
`toCheckoutStepViewed`	`Checkout Step Viewed`	`Cart`
`toCheckoutStepCompleted`	`Checkout Step Completed`	`Cart`
`toPaymentInfoEntered`	`Payment Info Entered`	`Cart`
`toOrderCompleted`	`Order Completed`	`Order`
`toOrderUpdated`	`Order Updated`	`Order`
`toOrderCancelled`	`Order Cancelled`	`Order`
`toOrderRefunded`	`Order Refunded`	`Order`

The mappers derive currency and standard monetary fields from the entity. Product mappers also normalize differences between Product, ProductDetail, and flattened Item shapes.

Selected variants

A parent product can represent several variants. Pass the selected variant when mapping a product interaction:

const event = toProductViewed(product, {}, {
  variant: selectedVariant,
});

analytics.track(...trackArgs(event));

The selected variant overrides the emitted SKU, price, image, variant name, variant ID, and variant slug. Without an explicit selection, the mapper uses the default variant when one exists.

Product list events

import {
  toProductListViewed,
  trackArgs,
} from "@commercengine/analytics";

analytics.track(
  ...trackArgs(
    toProductListViewed(items, {}, {
      listId: category.id,
      category: category.name,
    }),
  ),
);

Avoid rebuilding product arrays manually or hardcoding currency. Let the mapper normalize the Commerce Engine entities.

Events without a single source entity

Use trackEvent for actions such as coupons, promotions, wishlist interactions, reviews, and custom business events.

import { trackArgs, trackEvent } from "@commercengine/analytics";

analytics.track(
  ...trackArgs(
    trackEvent("Coupon Applied", {
      cart_id: cart.id,
      coupon_id: couponCode,
      discount: cart.coupon_discount_amount,
    }),
  ),
);

For custom events, reuse the package’s property builders instead of reconstructing canonical cart or order fields.

import {
  cartProperties,
  orderProperties,
  trackArgs,
  trackEvent,
} from "@commercengine/analytics";

analytics.track(
  ...trackArgs(trackEvent("Cart Created", cartProperties(cart))),
);

analytics.track(
  ...trackArgs(trackEvent("Order Created", orderProperties(order))),
);

Browser, server, and HTTP delivery

The mapper returns a complete Segment/RudderStack HTTP-style envelope. Adapt it to the delivery API you use.

Browser SDK

Browser SDKs typically keep identity in ambient state and expect (event, properties):

analytics.track(...trackArgs(toProductViewed(product)));

Do not pass the whole envelope to a Segment-style browser track() method. analytics.track(eventEnvelope) is interpreted as an event-name argument. Use trackArgs or pass event.event and event.properties separately.

Server SDK

A server process has no ambient browser identity. Add identity to the mapper context and pass the resulting envelope fields to the server SDK.

const event = toOrderCompleted(order, {
  userId,
  anonymousId,
});

serverAnalytics.track({
  userId: event.userId,
  anonymousId: event.anonymousId,
  event: event.event,
  properties: event.properties,
});

Raw HTTP

A compatible ingestion endpoint can accept the complete envelope unchanged:

const event = toOrderCompleted(order, {
  userId,
  anonymousId,
});

await fetch(analyticsIngestionUrl, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify(event),
});

Identity ownership

Identity is separate from event mapping. Choose one owner for each application architecture.

Storefront SDK + Hosted Checkout

When using authMode: "provided", the parent Storefront SDK owns tokens and identity. A sound pattern is:

Hosted Checkout forwards track envelopes
Storefront SDK token updates drive identify
Hosted Checkout identify envelopes are ignored to avoid a second identity path

function forwardCheckoutAnalytics(event: AnalyticsEvent) {
  if (event.type !== "track") return;
  analytics.track(event.event, event.properties);
}

Checkout-only integration

When Hosted Checkout uses authMode: "managed", it owns the session. The parent adapter can consume both track and identify envelopes. Handle anonymous identity using the destination’s supported anonymous-ID API. Do not call identify(undefined, traits).

Custom checkout

A custom checkout can use toIdentify, identifyArgs, or userTraits with either a full Commerce Engine User or the JWT-derived UserInfo.

import {
  identifyArgs,
  toIdentify,
} from "@commercengine/analytics";

const user = await sdk.getUserInfo();
if (user) {
  analytics.identify(...identifyArgs(toIdentify(user)));
}

The mapper distinguishes a true anonymous user from a known user. It does not equate “logged out” with “anonymous”; a logged-out user can still be a known Commerce Engine identity.

Hosted Checkout events

Hosted Checkout currently uses the mapper package internally for customer actions including:

Area	Events
Cart	`Cart Created`, `Cart Viewed`, `Product Added`, `Product Removed`
Recommendations	`Recommended Products Viewed`
Checkout	`Checkout Started`, `Checkout Step Viewed`, `Checkout Step Completed`
Payment	`Payment Info Entered`
Coupons	`Coupon Entered`, `Coupon Applied`, `Coupon Removed`, `Coupon Denied`
Orders	`Order Created`, `Order Completed`
Identity	Canonical `identify` envelope

Checkout-step events can include a numeric step, a more specific step_name, the selected shipping method, and the selected payment method. Hosted Checkout suppresses duplicate emission for key session-level signals such as checkout start, recommendation views, and order completion. Downstream destinations should still apply their normal idempotency and deduplication policies.

Data minimization

The standard property builders intentionally avoid copying large operational objects into analytics payloads. Raw addresses, shipments, inventory lots, seller details, payment authentication data, tokens, and OTP values are not included by default. Add custom properties only when they serve a defined analytics purpose and comply with the application’s consent and privacy policy.

Common mistakes

Mistake	Consequence	Correct approach
Treating the package as a RudderStack client	No events are delivered	Add your own destination adapter
Assuming it only works with Hosted Checkout	Unnecessary hand-built schemas in custom checkout	Map REST or SDK entities directly
Recreating Hosted Checkout events in the parent	Duplicate conversions	Forward `onAnalyticsEvent`
Forwarding identify from both checkout and Storefront SDK	Competing identity transitions	Choose one identity owner
Passing a full envelope to browser `track()`	Invalid invocation	Use `trackArgs`
Hardcoding currency	Incorrect multi-currency data	Let mappers derive it
Emitting events because data loaded, rather than because the user acted	Misleading funnels	Let the application own semantic trigger timing
Throwing from instrumentation	Analytics can disrupt commerce UX	Keep analytics non-blocking

Verification checklist

[ ] every customer action has one event owner
[ ] Hosted Checkout events are forwarded, not rebuilt
[ ] custom checkout events use canonical REST/SDK entities
[ ] browser destinations receive event + properties, not the whole envelope
[ ] server/HTTP destinations receive explicit identity context
[ ] currency and totals come from Commerce Engine entities
[ ] anonymous activity joins the known identity after login
[ ] no tokens, OTPs, raw card data, or complete addresses are emitted
[ ] analytics failures cannot interrupt checkout
[ ] consent and destination loading are controlled by the application

@commercengine/analytics

Browse the current package documentation, exported mappers, types, and source.

Getting Started

Framework Guides

Reference

Mental model

Install the mapper package

Three supported integration modes

Hosted Checkout

Custom checkout with the Storefront SDK

Custom checkout with direct REST calls

Entity mappers

Selected variants

Product list events

Events without a single source entity

Browser, server, and HTTP delivery

Browser SDK

Server SDK

Raw HTTP

Identity ownership

Storefront SDK + Hosted Checkout

Checkout-only integration

Custom checkout

Hosted Checkout events

Data minimization

Common mistakes

Verification checklist

@commercengine/analytics

​Mental model

​Install the mapper package

​Three supported integration modes

​Hosted Checkout

​Custom checkout with the Storefront SDK

​Custom checkout with direct REST calls

​Entity mappers

​Selected variants

​Product list events

​Events without a single source entity

​Browser, server, and HTTP delivery

​Browser SDK

​Server SDK

​Raw HTTP

​Identity ownership

​Storefront SDK + Hosted Checkout

​Checkout-only integration

​Custom checkout

​Hosted Checkout events

​Data minimization

​Common mistakes

​Verification checklist

@commercengine/analytics

Mental model

Install the mapper package

Three supported integration modes

Hosted Checkout

Custom checkout with the Storefront SDK

Custom checkout with direct REST calls

Entity mappers

Selected variants

Product list events

Events without a single source entity

Browser, server, and HTTP delivery

Browser SDK

Server SDK

Raw HTTP

Identity ownership

Storefront SDK + Hosted Checkout

Checkout-only integration

Custom checkout

Hosted Checkout events

Data minimization

Common mistakes

Verification checklist