Troubleshoot storefront events

Most storefront tracking problems come down to one of four things: the embed or pixel isn’t active, a destination isn’t fully configured, two tracking sources are firing the same event, or consent is legitimately blocking it. Work through these in order.

No events at all

Check Settings → Storefront events first:

The Storefront tracking embed card must show Active. If it shows Not detected, the Máximo Pixels app embed isn’t turned on in your theme, see Enable tracking.
The Conversion pixel card must show Registered. If it shows Setting up, use Register pixel to register it manually.
In Shopify admin, check Settings → Customer events for Máximo’s pixel. A Disconnected status means the pixel needs to be re-registered, see the recovery steps in Enable tracking.

Events for some destinations only

Storefront events are captured once, then fanned out per destination. If one destination (say, TikTok) isn’t receiving events while others are, the gap is almost always in that destination’s own configuration rather than in capture:

Confirm the destination has a pixel ID (or catalog connection) saved on its own settings page. The conversion pixel only fires beacons for destinations that are actually configured.
Confirm the relevant event is enabled for that destination on its Events settings, a merchant can turn individual events off per destination, and a disabled event is simply skipped for that one platform.
Check Pixel presence to see whether that destination’s tracking is actually running on the page.

Duplicate events

Máximo sends each storefront conversion to a platform once, and stamps every event with a shared event ID so a platform can recognize duplicate reports of the same action and count it once.

Real duplicates almost always come from a second tracking source outside Máximo (another app, or a gtag, fbq, or ttq snippet added to the theme by hand) firing the same conversion independently. Máximo can deduplicate against its own sends, but not against tags it doesn’t control. If you see doubled conversions, search your theme for a manually installed pixel and check whether another app is also managing the same destination.

Google Analytics 4 has no equivalent deduplication, so Máximo is careful to fire each GA4 event from exactly one place: the theme embed for events it can see directly (page and product views), and the pixel for everything else (search, cart removal, add-to-cart, checkout). A duplicated GA4 event usually means a second, independent GA4 tag is also installed on the theme.

Missing purchase value

If a completed order is reaching your destination but arrives with no value or currency, check that the order itself carries a total, Máximo reads the value directly off the checkout at the time it completes. If the order used a currency your shop doesn’t otherwise process, confirm the destination is configured to accept that currency.

Custom events aren’t showing up

Confirm the toggle on Settings → Storefront events → Custom events is on. Custom events are rolling out gradually: if the card isn’t there at all, it isn’t available for your store yet.
Check the event’s name doesn’t match a standard event name (purchase, add_to_cart, checkout_started, page_viewed, and similar). A matching name is dropped rather than recorded as a custom event. See Naming rules.
Check the event’s data is within the payload limits (16 KB, 5 levels deep, 200 keys, 128-character key names). An event over any of these limits is dropped entirely. See Payload limits.
On a Hydrogen storefront, confirm the Máximo SDK itself is configured with a config URL and config key (Settings → Storefront architecture). Without it, no events reach Máximo, custom or standard.
On a Hydrogen storefront, events published with useAnalytics().publish() are forwarded only if their exact name is listed on <MaximoAnalytics customEvents={[...]} />. maximo.track() needs no list.
Very early events can be missed: on a theme, only if the Máximo app embed hadn’t finished loading yet when the event was published (your data warehouse still gets it); on Hydrogen, if it was published on a visitor’s very first page view before the SDK’s configuration had loaded, it’s dropped entirely. See What’s not covered.
Confirm you have a data warehouse connected. Custom events are delivered there and nowhere else.

Custom traits aren’t showing up

Confirm the toggle on Settings → Storefront events → Custom events is on. Traits roll out separately from custom events: if the card doesn’t show the line “The same toggle turns on custom traits.”, traits aren’t available for your store yet.
An identify call needs analytics consent. Traits on a track call follow their event’s consent. See Consent.
Check the trait names aren’t reserved (email, phone, name, country, anything starting with address or hashed, click and cookie IDs, and so on). An identify with a reserved name is rejected entirely; on a track call, only the traits are dropped. See Rules.
Check two keys don’t convert to the same snake_case name (loyaltyTier and loyalty_tier). Values can be text, numbers, true or false, lists, or objects, but they can’t nest more than 4 levels deep, and reserved names are rejected inside objects too.
Check the limits: 50 traits and 8 KB per call, 200 traits per profile (400 counting cleared ones), and 500 distinct trait names per store. A new trait past a profile or store limit is dropped while existing traits keep updating. See Rules.
If you call identify repeatedly with the same traits, Máximo skips the repeats for 24 hours. A change to any trait is sent right away.
Traits on a track call are stored with that event only. To update the shopper’s profile, send them on an identify call.
Confirm you have a data warehouse connected. Track-call traits go only there.

Custom traits aren’t reaching Klaviyo or Amplitude

Only traits from identify calls are sent. Traits on a track call stay with their event.
Klaviyo: confirm Profile sync is on and the Custom traits row is on under Klaviyo → Profiles → Profile properties. Traits sync nightly, and only for customers who have placed an order and pass Profile sync’s marketing consent rules.
Amplitude: confirm Identify customers is on. Traits are sent with the customer identify after each paid order, so they update with the customer’s next order.
A trait named like one of Máximo’s own properties isn’t sent: in Klaviyo, any name starting with maximo_; in Amplitude, names such as order_count, total_spent and utm_source. See Custom traits.

Custom events aren’t reaching Google Tag Manager

This needs both custom events and your dataLayer push turned on. Either one off means nothing is pushed.
On checkout pages, confirm you’ve re-pasted the current Máximo checkout tracking snippet under Settings → Customer events → Add custom pixel. A snippet pasted before custom events shipped doesn’t pick this up automatically.
Custom events published from a customer account extension still reach your data warehouse, but they’re never forwarded to the dataLayer, because Google Tag Manager has nothing to listen on there.
An event repeated many times in a short window is deliberately throttled. See Sending custom events to Google Tag Manager for the exact limits. This only affects the dataLayer push; your data warehouse still receives every event.

Beacons are gated on the shopper’s consent, read from Shopify’s Customer Privacy API. Máximo’s own event capture requires analytics consent, and every ad platform, Google Ads and GA4 included, requires marketing consent. See Consent for the full mapping.

If a shopper has declined, or Shopify doesn’t yet count them as allowed, Máximo skips the beacon. This is expected behavior, not a bug, check your consent banner configuration if you believe shoppers are being blocked who shouldn’t be.

Still stuck

Check the Delivery monitor for server-side delivery failures grouped by destination and reason, it’s often the fastest way to see exactly what’s failing and why.