> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Events (Configure)

> Configure GermainUX to collect Shopify commerce events and correlate them with customer sessions, Session Replay, funnels, products, errors, and outcomes.

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)
[`Mobile App`](https://docs.germainux.com/main/germain-ux-mobile-app)
[`RPA Bot Recorder`](https://docs.germainux.com/main/germain-ux-rpa-bot-recorder)
[`RUM JS`](https://docs.germainux.com/main/germain-ux-rum-js)

Availability
2023.3 or later

> [card] [Configure Shopify Events](#configure-shopify-events)
>
> Event setup for Shopify

> [card] [Configure event collection](#configure-event-collection)
>
> Settings for each event

> [card] [Configure custom insights for Session Replay](#configure-custom-insights-for-session-replay)
>
> Key actions on replay timeline

> [card] [Troubleshooting](#troubleshooting)
>
> Fix event collection issues

## Configure Shopify Events

Configure GermainUX to collect Shopify commerce events and correlate them with customer sessions, Session Replay, conversion funnels, products, errors, and business outcomes.

Examples include product views, cart additions, cart removals, sold-out encounters, checkout activity, purchases, and store-specific customer actions.

### How Shopify events are used

Collected events can be used to:

* Measure product and collection engagement
* Analyze product discovery and search behavior
* Understand cart additions and removals
* Build conversion funnels
* Detect abandonment and friction
* Measure checkout completion

> [accordion] Show all 9
>
> * Correlate commerce activity with errors and performance
> * Display meaningful milestones in Session Replay
> * Trigger alerts, reports, and automation

When displayed on the Session Replay timeline, these events are called **Custom Insights**. The underlying data remains a Shopify or custom event.

Session Replay reconstructs the customer experience from captured browser events; it is not a video recording.

### Prerequisites

Before configuring Shopify events:

* [Deploy GermainUX monitoring for Shopify](https://docs.germainux.com/main/deploy-monitoring-for-shopify.md).
* Confirm that customer sessions appear in GermainUX.
* Install and configure the GermainUX Shopify App when Shopify Web Pixel and checkout events are required.
* Configure the Shopify UX monitoring profile.
* Define privacy and consent requirements.
* Identify the customer journeys and business outcomes to measure.

## Shopify standard events

The GermainUX Shopify integration can collect supported Shopify standard events. Availability depends on the Shopify page, integration method, consent status, and Shopify configuration.

| Shopify source event | GermainUX label | Description |
| - | - | - |
| `page_viewed` | Page Viewed | Customer visited a supported page |

Shopify’s standard event names and availability are defined by the [Shopify Web Pixels API](https://shopify.dev/docs/api/web-pixels-api/standard-events).

### Important checkout-completion behavior

Shopify’s `checkout_completed` event normally fires once per checkout. For post-purchase offers, it may fire on the first upsell page instead of the Thank You page. If the page responsible for generating the event never loads, the event might not be emitted.

Therefore:

* Do not rely only on the Thank You page URL to identify purchases.
* Deduplicate purchase events using an approved non-sensitive checkout or order identifier.
* Do not assume that a missing `checkout_completed` event always means customer abandonment.
* Reconcile conversion reporting with Shopify order data when exact financial reporting is required.

## GermainUX Shopify KPIs

Preconfigured Shopify event KPIs include:

* Shopify Product Cart Addition
* Shopify Product Cart Removal
* Shopify Collection View
* Shopify Product Viewing
* Shopify Cart View

Additional KPIs may be available depending on the GermainUX version and the events configured for the store.

Custom KPIs can be created for:

* Search Submitted
* Search with No Results
* Sold Out
* Checkout Started
* Checkout Step Completed
* Checkout Alert

> [accordion] Show all 14
>
> * Purchase Completed
> * Discount Applied
> * Discount Rejected
> * Subscription Started
> * Wishlist Addition
> * Chat Started
> * Customer Feedback Submitted
> * Return Requested

## Configure event collection

Go to:

**Germain Workspace > Analytics > UX Monitoring Profiles**

Select the profile used by the Shopify store and review the Shopify event or custom event settings.

For each event, configure:

* Source event name
* GermainUX display name
* Storefront URL or domain
* Application
* Environment
* Event attributes

> [accordion] Show all 10
>
> * Success state
> * Business-process mapping
> * Privacy exclusions
> * Session Replay timeline visibility

### Basic examples

#### Add to cart

| Setting | Value |
| - | - |
| Source event | `product_added_to_cart` |

#### Remove from cart

| Setting | Value |
| - | - |
| Source event | `product_removed_from_cart` |

#### Sold out

`SoldOut` is normally a custom event or derived insight rather than a Shopify standard Web Pixel event.

| Setting | Value |
| - | - |
| GermainUX event name | `SoldOut` |

Define precisely what `SoldOut` means. For example:

* Product has no available variants
* Selected variant is unavailable
* Inventory becomes unavailable during cart update
* Checkout rejects the item because inventory changed

These conditions should not necessarily share one event if different teams own or resolve them.

## Event naming conventions

Use stable and consistent event names.

Recommended format:

```text theme={null}
Object + Action
```

Examples:

```text theme={null}
ProductViewed
AddToCart
RemoveFromCart
CartViewed
CheckoutStarted
CheckoutCompleted
DiscountApplied
SearchSubmitted
SearchNoResults
ProductSoldOut
```

Avoid:

* Trailing spaces
* Dynamic identifiers in event names
* Page-specific variations for the same action
* Customer names or email addresses
* Long descriptive sentences
* Multiple spellings of the same event

Store product, cart, or page details as attributes rather than embedding them in the event name.

## Recommended event attributes

Capture only the attributes required for analysis.

| Attribute | Purpose |
| - | - |
| `application` | Shopify store or application |

Use consistent monetary definitions. Document whether `price` represents:

* List price
* Discounted price
* Unit price
* Line price
* Pre-tax value
* Post-tax value

Inconsistent price definitions produce inaccurate revenue and conversion analysis.

## Create custom Shopify events

Use custom events when Shopify does not provide a standard event for the action or business outcome.

Example:

```text theme={null}
germainApm.api.createEvent("ProductSoldOut", {
    success: false,
    productId: productId,
    variantId: variantId,
    productName: productName,
    pageName: "Product Detail"
});
```

Example for a successful discount application:

```text theme={null}
germainApm.api.createEvent("DiscountApplied", {
    success: true,
    discountCode: sanitizedDiscountCode,
    cartValue: cartValue,
    currency: currency
});
```

Only reference variables that exist in the store’s implementation. These examples must be adapted to the theme, application, or integration that emits the event.

### Do not duplicate standard events

Before adding custom code, determine whether the GermainUX Shopify App already collects the corresponding Shopify standard event.

For example, do not create a second `AddToCart` event if `product_added_to_cart` is already collected and mapped to the Shopify Product Cart Addition KPI.

Duplicate events can inflate:

* Conversion volume
* Product engagement
* Cart additions
* Funnel entry
* Purchase totals
* Alert counts

## Configure custom insights for Session Replay

Custom Insights display important Shopify events on the Session Replay timeline, allowing an analyst to move directly to the relevant customer action.

Examples include:

| Insight | Insight |
| - | - |
| Product Viewed | Product Added to Cart |

### Add a timeline event

Where available, use the supported Workspace dashboard or Session Replay configuration editor.

For environments that require the Configuration Console:

**1. Open the GermainUX Configuration Console**

**2. Navigate to: `germain.apm \> workspace \> rcaDashboards`**

**3. Select the User Session Replay dashboard**

**4. Open the target replay portlet**

**5. Open `timelineEvents`**

**6. Click Add**

**7. Enter the event-matching and display settings**

**8. Save the configuration**

**9. Generate the event in a test session**

**10. Confirm that the insight appears at the correct time in Session Replay**

The exact path can differ by GermainUX version. Prefer the Workspace configuration editor whenever the setting is exposed there.

### Timeline-event settings

Configure:

* KPI or event type
* Event name
* Attribute filters
* Display label
* Icon or color
* Success or failure state

> [accordion] Show all 9
>
> * Priority
> * Tooltip content
> * Click or drill-through behavior

Use short, customer-journey-oriented labels such as:

* Added to Cart
* Removed from Cart
* Search Returned No Results
* Checkout Started
* Checkout Alert Displayed
* Purchase Completed

## Configure conversion funnels

Map Shopify events to the appropriate business-process steps.

Example purchase funnel:

**1. `collection_viewed`**

**2. `product_viewed`**

**3. `product_added_to_cart`**

**4. `cart_viewed`**

**5. `checkout_started`**

**6. `checkout_contact_info_submitted`**

**7. `checkout_address_info_submitted`**

**8. `checkout_shipping_info_submitted`**

**9. `payment_info_submitted`**

**10. `checkout_completed`**

Not every customer must perform every optional step. Define:

* Required steps
* Optional steps
* Repeated steps
* Valid alternative paths
* Completion condition
* Abandonment timeout
* Failure conditions

For example, a returning customer might skip address entry, and a direct product-page visitor might never generate a collection-view event.

## Classify alerts and checkout messages

Shopify’s `alert_displayed` event can represent different types of feedback. Do not classify every alert as an application error.

| Classification | Example |
| - | - |
| User validation | Required address field is empty |

Use the message, checkout stage, and related network activity to derive the appropriate classification.

## Privacy and consent

Shopify events can contain customer, cart, order, and checkout information.

Do not collect:

* Payment-card numbers
* Security codes
* Passwords
* Authentication tokens
* Full billing or shipping addresses
* Customer names or email addresses unless explicitly approved
* Unfiltered request or response bodies
* Sensitive free-text values

Configure:

* Consent enforcement
* Attribute allowlists
* URL sanitization
* Input and text masking
* Data retention
* Role-based access
* Store- and region-specific privacy rules

Prefer an allowlist of approved event attributes instead of collecting the complete Shopify event payload.

## Validate Shopify events

Use a test store or Shopify test mode whenever possible.

Complete these scenarios:

* View a collection
* Search for a product
* Add a product to the cart
* Attempt to select a sold-out variant
* Start checkout
* Trigger safe checkout validation

For every event, verify:

* The event occurs once at the expected time.
* Its GermainUX name is correct.
* It belongs to the correct application and environment.
* Product and variant attributes are accurate.
* Quantity, price, and currency are accurate.
* The event correlates with the correct session.

> [accordion] Show all 10
>
> * It appears at the correct point in Session Replay.
> * It maps to the correct business-process step.
> * Sensitive values are absent.
> * Consent choices are respected.

## Troubleshooting

### An event is missing

Confirm that:

* The GermainUX Shopify App or RUM JS is loaded.
* The event is available on the current Shopify page.
* The event subscription is enabled.
* The customer performed the exact action that triggers the event.
* Consent permits the event.
* The store URL matches the monitoring profile.
* The event is not filtered by sampling or privacy rules.
* The event is mapped to the expected GermainUX KPI.

### Events are duplicated

Check for multiple collection paths:

* GermainUX Shopify App
* Shopify Web Pixel
* Custom Pixel
* Theme JavaScript
* Tag manager
* Third-party checkout script
* Custom GermainUX event

Retain one authoritative source for each business event or configure explicit deduplication.

### Checkout events are missing

Confirm that:

* The GermainUX Shopify App and supported pixel integration are installed.
* Checkout collection is enabled.
* The event is available on that checkout surface.
* Checkout consent permits collection.
* The checkout is hosted by Shopify rather than an unmonitored third party.
* The page responsible for emitting the event loaded successfully.

### Events appear but not in Session Replay

Verify that:

* Session Replay is enabled for the session.
* The event uses the correct application and session identifiers.
* A corresponding `timelineEvents` rule exists.
* The rule’s event name and filters match the collected event.
* Replay sampling and consent allowed the session to be captured.

### Purchase totals do not match Shopify

Review:

* Duplicate `checkout_completed` events
* Missing completion pages
* Post-purchase upsell behavior
* Cancelled or refunded orders
* Test orders
* Currency conversion
* Gross versus net revenue definitions
* Differences between browser events and authoritative Shopify order data

Use Shopify order data as the authoritative source for financial reconciliation. Browser events describe the customer journey and may be incomplete when pages fail to load or tracking is restricted.

## Related documentation

* [Deploy](https://docs.germainux.com/main/deploy-monitoring-for-shopify.md) Monitoring for Shopify
* [Configure](https://docs.germainux.com/main/configure-monitoring-for-shopify.md) Monitoring for Shopify
* Configure [Third-Party Checkout](https://docs.germainux.com/main/3rd-party-checkouts-monitoring-for-shopify-configu.md) Monitoring
* Configure [Error](https://docs.germainux.com/main/error-monitoring-for-shopify-configure.md) Monitoring
* Configure User [Feedback](https://docs.germainux.com/main/user-feedback-for-shopify-configure.md)
* [KPIs](https://docs.germainux.com/main/kpis-for-shopify-monitoring.md) for Shopify Monitoring

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.