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

# Enriching Events with GTM

> Access checkout session context to enrich analytics events using Google Tag Manager Custom HTML tags

Sometimes the standard event data isn't enough. You may want to enrich your analytics events with additional context from the checkout session—such as whether the user is a VIP member, their loyalty tier, or platform-specific data. Ollie Shop exposes session context through global objects that you can access directly from GTM.

## Real-World Example: Enriching VIP Enrollment

In the [Custom Events](/ollie-shop/analytics/custom-events) guide, we created a `vip_enrollment` event that fires when a customer joins your VIP program. Now let's enrich that event with additional context from the checkout session.

Using a GTM Custom HTML tag, you can add the customer's VIP status from your platform's session data:

<Tabs>
  <Tab title="Using Ollie Session">
    ```html theme={"system"}
    <script>
      var session = window.__CHECKOUT_SESSION__ || {};

      dataLayer.push({
        event: 'vip_enrollment_enriched',
        enrollment_source: 'checkout',
        is_guest: session.user?.isGuest || false,
        cart_value: session.totals?.total || 0
      });
    </script>
    ```
  </Tab>

  <Tab title="Using Platform Session (VTEX)">
    ```html theme={"system"}
    <script>
      var rawSession = window.__RAW_CHECKOUT_SESSION__ || {};

      dataLayer.push({
        event: 'vip_enrollment_enriched',
        enrollment_source: 'checkout',
        vip_enrollment: rawSession.vipEnrollment || false,
        is_logged_in: rawSession.loggedIn || false
      });
    </script>
    ```

    <Info>
      The `vipEnrollment` field is available in the VTEX session when the customer has opted into your VIP program during checkout.
    </Info>
  </Tab>
</Tabs>

## Available Session Objects

Ollie Shop exposes two global objects with checkout session data. For a complete reference with full examples, see the [Session](/ollie-shop/concepts/session) documentation.

| Object                            | Description                                |
| --------------------------------- | ------------------------------------------ |
| `window.__CHECKOUT_SESSION__`     | Ollie Shop's normalized session data       |
| `window.__RAW_CHECKOUT_SESSION__` | Raw platform session (VTEX, Shopify, etc.) |

## Common Use Cases

### User Segmentation

Enrich events with user attributes for better segmentation in analytics:

```html theme={"system"}
<script>
  var session = window.__CHECKOUT_SESSION__ || {};

  dataLayer.push({
    event: 'checkout_step_completed',
    user_type: session.user?.isGuest ? 'guest' : 'registered',
    cart_value: session.totals?.total || 0,
    item_count: session.cartItems?.length || 0
  });
</script>
```

### Platform-Specific Data

Access raw platform data when you need fields not available in the normalized session:

```html theme={"system"}
<script>
  var rawSession = window.__RAW_CHECKOUT_SESSION__ || {};

  dataLayer.push({
    event: 'vtex_checkout_data',
    sales_channel: rawSession.salesChannel,
    trade_policy: rawSession.tradePolicy,
    seller_id: rawSession.sellers?.[0]?.id
  });
</script>
```

## Setting Up in GTM

<Steps>
  <Step title="Create a Custom HTML Tag">
    In GTM, go to **Tags > New > Tag Configuration > Custom HTML**. Paste your enrichment script.
  </Step>

  <Step title="Set the Trigger">
    Configure the tag to fire on the appropriate trigger—for the VIP enrollment example, use a Custom Event trigger matching `vip_enrollment`.
  </Step>

  <Step title="Test in Preview Mode">
    Use [GTM Preview mode](https://support.google.com/tagmanager/answer/6107056) to verify your enriched events are pushing correctly to the `dataLayer`.
  </Step>

  <Step title="Publish">
    Once verified, publish your GTM container to apply changes to your live checkout.
  </Step>
</Steps>

## Best Practices

* **Always use fallbacks** — Use `|| {}` and `|| false` to prevent errors if session objects aren't loaded yet
* **Keep scripts lightweight** — GTM Custom HTML runs synchronously; complex logic can impact checkout performance
* **Use descriptive event names** — Suffix enriched events (e.g., `*_enriched`) to distinguish them from the original events
* **Test thoroughly** — Session data availability may vary depending on checkout stage

## Further Reading

* [Session Objects Reference](/ollie-shop/concepts/session) — Full session structure and examples
* [useCheckoutSession Hook](/ollie-shop/api/useCheckoutSession) — Access session data in components
* [GTM Custom HTML Tags](https://support.google.com/tagmanager/answer/6107167)
* [GTM Preview Mode](https://support.google.com/tagmanager/answer/6107056)