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

# Event Tracking

> Reference for the customer behaviour events storekit collects and how they integrate with analytics platforms like Google Analytics, GTM, and Meta Pixel.

storekit collects behavioural events to help you understand customer journeys, optimise conversions, and power marketing integrations. This page explains what we track, how data flows, and how events integrate with third-party platforms.

## Native Event Collection

storekit automatically collects events across web and native apps without requiring additional code.

### Core Commerce Events

<AccordionGroup>
  <Accordion title="active_on_site">
    Fired when a customer lands on the store.

    ```json theme={null}
    {
      "event": "active_on_site",
      "properties": {
        "accountId": "40586258-8a99-4651-b79f-0a1ab602a926",
        "id": 8709,
        "slug": "your-store"
      }
    }
    ```
  </Accordion>

  <Accordion title="menu_loaded">
    Fired when the menu has fully loaded.

    ```json theme={null}
    {
      "event": "menu_loaded",
      "properties": {
        "menuId": 12345
      }
    }
    ```
  </Accordion>

  <Accordion title="viewed_product">
    Fired when a customer opens a product modal.

    ```json theme={null}
    {
      "event": "viewed_product",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "currency": "GBP",
        "price": 350,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "plu": "FW001",
        "sku": "SKU-FW-001"
      }
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    Fired when an item is added to the basket.

    ```json theme={null}
    {
      "event": "add_to_cart",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "price": 400,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "modifiers": [
          {
            "id": 111,
            "name": "Oat Milk",
            "price": 50
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="remove_from_cart">
    Fired when an item is removed from the basket.

    ```json theme={null}
    {
      "event": "remove_from_cart",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "price": 400,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "modifiers": []
      }
    }
    ```
  </Accordion>

  <Accordion title="started_checkout">
    Fired when the customer opens the checkout screen.

    ```json theme={null}
    {
      "event": "started_checkout",
      "properties": {
        "currency": "GBP",
        "items": [
          {
            "id": 98765,
            "name": "Flat White",
            "price": 400,
            "quantity": 2,
            "modifiers": []
          }
        ],
        "venueSlug": "your-store",
        "value": 8.00
      }
    }
    ```
  </Accordion>

  <Accordion title="order_completed">
    Fired when payment is confirmed and the order is placed.

    ```json theme={null}
    {
      "event": "order_completed",
      "properties": {
        "orderId": "ord_789xyz",
        "total": 12.50,
        "currency": "GBP",
        "venueSlug": "your-store",
        "order": {
          "items": [...],
          "fulfillmentMethod": "delivery",
          "customer": {...}
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Search & Discovery Events

<AccordionGroup>
  <Accordion title="products_searched">
    Fired when a customer performs a search (debounced by 1 second).

    ```json theme={null}
    {
      "event": "products_searched",
      "properties": {
        "query": "coffee",
        "resultCount": 12
      }
    }
    ```
  </Accordion>

  <Accordion title="cross_sell_modal_view">
    Fired when the upsell/cross-sell modal is displayed.

    ```json theme={null}
    {
      "event": "cross_sell_modal_view",
      "properties": {
        "productCount": 4,
        "crossSellType": "product"
      }
    }
    ```

    `crossSellType` is either `"product"` or `"category"` depending on configuration.
  </Accordion>
</AccordionGroup>

### Discount Events

<AccordionGroup>
  <Accordion title="discount_entered">
    Fired when a customer submits a discount code.

    ```json theme={null}
    {
      "event": "discount_entered",
      "properties": {
        "code": "SUMMER20"
      }
    }
    ```
  </Accordion>

  <Accordion title="discount_applied">
    Fired when a discount code is successfully applied.

    ```json theme={null}
    {
      "event": "discount_applied",
      "properties": {
        "discount_id": 456,
        "discount_name": "Summer Sale",
        "discount_amount": 500,
        "discount_type": "percentage"
      }
    }
    ```
  </Accordion>

  <Accordion title="discount_denied">
    Fired when a discount code is rejected.

    ```json theme={null}
    {
      "event": "discount_denied",
      "properties": {
        "discount_code": "EXPIRED10",
        "reason": "Code has expired",
        "status_code": 400
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Promotional Offer Events

<AccordionGroup>
  <Accordion title="viewed_offer">
    Fired when a promotional offer becomes visible.

    ```json theme={null}
    {
      "event": "viewed_offer",
      "properties": {
        "offerId": 123,
        "linkId": "link_abc",
        "type": "banner",
        "value": "20% off"
      }
    }
    ```
  </Accordion>

  <Accordion title="click_offer">
    Fired when a customer clicks on a promotional offer.

    ```json theme={null}
    {
      "event": "click_offer",
      "properties": {
        "offerId": 123,
        "linkId": "link_abc",
        "type": "banner",
        "value": "20% off"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Stories Events

<AccordionGroup>
  <Accordion title="story_viewer_opened">
    Fired when a customer opens the story viewer.

    ```json theme={null}
    {
      "event": "story_viewer_opened",
      "properties": {
        "storyId": 789,
        "storyIndex": 0,
        "storyTitle": "New Summer Menu",
        "totalStories": 5,
        "source": "menu_page"
      }
    }
    ```
  </Accordion>

  <Accordion title="story_viewed">
    Fired when a story page is viewed.

    ```json theme={null}
    {
      "event": "story_viewed",
      "properties": {
        "storyId": 789,
        "storyTitle": "New Summer Menu",
        "pageIndex": 2,
        "totalPages": 4,
        "hasVideo": true,
        "hasCta": true
      }
    }
    ```
  </Accordion>

  <Accordion title="story_navigation">
    Fired when a customer navigates between story pages.

    ```json theme={null}
    {
      "event": "story_navigation",
      "properties": {
        "storyId": 789,
        "fromPage": 1,
        "toPage": 2,
        "direction": "forward",
        "method": "tap"
      }
    }
    ```
  </Accordion>

  <Accordion title="story_cta_clicked">
    Fired when a customer clicks a CTA within a story.

    ```json theme={null}
    {
      "event": "story_cta_clicked",
      "properties": {
        "storyId": 789,
        "pageIndex": 2,
        "ctaType": "product",
        "ctaLabel": "Order Now",
        "ctaData": { "productId": 456 },
        "videoProgressPercent": 75
      }
    }
    ```
  </Accordion>

  <Accordion title="story_completed">
    Fired when a customer views all pages of a story.

    ```json theme={null}
    {
      "event": "story_completed",
      "properties": {
        "storyId": 789,
        "storyTitle": "New Summer Menu",
        "totalPages": 4,
        "timeSpentSeconds": 32
      }
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_closed">
    Fired when the story viewer is closed.

    ```json theme={null}
    {
      "event": "story_viewer_closed",
      "properties": {
        "storyId": 789,
        "pageIndex": 2,
        "totalStoriesViewed": 3,
        "totalPagesViewed": 8,
        "timeSpentSeconds": 45,
        "closeMethod": "swipe_down"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Experimentation Events

<AccordionGroup>
  <Accordion title="viewed_experiment">
    Fired when a customer is exposed to an A/B test variant.

    ```json theme={null}
    {
      "event": "viewed_experiment",
      "properties": {
        "experimentId": "checkout-flow-v2",
        "variationId": 1,
        "venueId": 8709,
        "accountId": "40586258-8a99-4651-b79f-0a1ab602a926",
        "venueSlug": "your-store"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Item ID Resolution

When sending events to analytics platforms, storekit resolves the `item_id` using the following priority:

1. **PLU** - Point of sale lookup code (preferred for POS-connected stores)
2. **SKU** - Stock keeping unit
3. **POS ID** - External POS system identifier
4. **ID** - storekit's internal product ID (fallback)

This ensures your analytics data uses the same identifiers as your POS system for accurate reporting and attribution.

```
item_id = product.plu || product.sku || product.posId || product.id
```

<Tip>
  For best results, ensure your products have PLU codes configured if you're using a POS integration. This keeps your analytics data consistent with your POS reports.
</Tip>

## Platform Integrations

storekit forwards events to third-party platforms in their native format. Events are transformed automatically—no mapping required.

### Meta (Facebook) Pixel

Events are sent to Meta's Pixel API. A `PageView` event fires automatically on initialisation.

<AccordionGroup>
  <Accordion title="AddToCart">
    Triggered by `add_to_cart`

    ```json theme={null}
    {
      "content_ids": [98765],
      "content_name": "Flat White",
      "currency": "GBP",
      "value": "4.00",
      "content_type": "product"
    }
    ```
  </Accordion>

  <Accordion title="InitiateCheckout">
    Triggered by `started_checkout`

    ```json theme={null}
    {
      "currency": "GBP",
      "value": 8.00
    }
    ```
  </Accordion>

  <Accordion title="Purchase">
    Triggered by `order_completed`

    ```json theme={null}
    {
      "currency": "GBP",
      "value": "12.50",
      "content_type": "product"
    }
    ```
  </Accordion>
</AccordionGroup>

<Info>
  Meta Pixel provides better attribution than browser-only pixels, especially with iOS privacy changes and ad blockers.
</Info>

### Google Analytics 4 / Google Tag Manager

Events are pushed to the `dataLayer` following GA4's e-commerce schema.

<AccordionGroup>
  <Accordion title="active_on_site">
    ```json theme={null}
    {
      "event": "active_on_site",
      "userId": null,
      "sessionId": null,
      "pagePath": null
    }
    ```
  </Accordion>

  <Accordion title="view_item">
    Triggered by `viewed_product`

    ```json theme={null}
    {
      "event": "view_item",
      "currency": "GBP",
      "value": 3.50,
      "items": [
        {
          "item_id": "FW001",
          "item_name": "Flat White"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    ```json theme={null}
    {
      "event": "add_to_cart",
      "value": 4.00,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 1
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="begin_checkout">
    Triggered by `started_checkout`

    ```json theme={null}
    {
      "event": "begin_checkout",
      "value": 8.00,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "affiliation": "your-store",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 2,
          "category": "Hot Drinks",
          "item_variant": "Oat Milk"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="purchase">
    Triggered by `order_completed`

    ```json theme={null}
    {
      "event": "purchase",
      "transaction_id": "ord_789xyz",
      "value": 12.50,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "affiliation": "your-store",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 2,
          "category": "Hot Drinks",
          "item_variant": "Oat Milk"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### Klaviyo

Events are sent to Klaviyo for email marketing automation. Customer identity is linked via email when available using `klaviyo.identify()`.

<AccordionGroup>
  <Accordion title="Active on Site">
    Triggered by `active_on_site`

    ```json theme={null}
    {
      "AccountId": "40586258-8a99-4651-b79f-0a1ab602a926",
      "VenueId": 8709,
      "VenueSlug": "your-store"
    }
    ```
  </Accordion>

  <Accordion title="Viewed Product">
    Triggered by `viewed_product`

    ```json theme={null}
    {
      "ProductId": 98765,
      "ProductName": "Flat White",
      "ProductPrice": 350,
      "ProductImage": "https://cdn.storekit.com/products/flat-white.jpg"
    }
    ```
  </Accordion>

  <Accordion title="Added to Cart">
    Triggered by `add_to_cart`

    ```json theme={null}
    {
      "ProductId": 98765,
      "ProductName": "Flat White",
      "ProductPrice": 400,
      "ProductImage": "https://cdn.storekit.com/products/flat-white.jpg"
    }
    ```
  </Accordion>

  <Accordion title="Started Checkout">
    Triggered by `started_checkout`

    ```json theme={null}
    {
      "Currency": "GBP",
      "Value": 8.00
    }
    ```
  </Accordion>
</AccordionGroup>

### 1st Party Event Collection

For customers who want full data ownership, storekit can send events directly to your own data warehouse. All events include base context properties automatically.

**Base context (included in all events):**

```json theme={null}
{
  "account_id": "40586258-8a99-4651-b79f-0a1ab602a926",
  "venue_id": 8709,
  "venue_slug": "your-store"
}
```

<AccordionGroup>
  <Accordion title="venue_loaded">
    Triggered by `active_on_site`. Also identifies the user.

    ```json theme={null}
    {
      "event": "venue_loaded"
    }
    ```
  </Accordion>

  <Accordion title="menu_loaded">
    ```json theme={null}
    {
      "event": "menu_loaded",
      "menu_id": 12345
    }
    ```
  </Accordion>

  <Accordion title="product_modal_view">
    Triggered by `viewed_product`

    ```json theme={null}
    {
      "event": "product_modal_view",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 350,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_plu": "FW001"
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    ```json theme={null}
    {
      "event": "add_to_cart",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 400,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_quantity": 1,
      "product_plu": "FW001",
      "add_to_cart_source": null
    }
    ```
  </Accordion>

  <Accordion title="remove_from_cart">
    ```json theme={null}
    {
      "event": "remove_from_cart",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 400,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_quantity": 1,
      "product_plu": "FW001"
    }
    ```
  </Accordion>

  <Accordion title="order_completed">
    ```json theme={null}
    {
      "event": "order_completed",
      "orderId": "ord_789xyz",
      "total": 12.50,
      "currency": "GBP"
    }
    ```
  </Accordion>

  <Accordion title="cross_sell_modal_view">
    ```json theme={null}
    {
      "event": "cross_sell_modal_view",
      "product_count": 4,
      "cross_sell_type": "product"
    }
    ```
  </Accordion>

  <Accordion title="viewed_offer">
    ```json theme={null}
    {
      "event": "viewed_offer",
      "offer_id": 123,
      "link_id": "link_abc",
      "type": "banner",
      "value": "20% off"
    }
    ```
  </Accordion>

  <Accordion title="clicked_offer">
    Triggered by `click_offer`

    ```json theme={null}
    {
      "event": "clicked_offer",
      "offer_id": 123,
      "link_id": "link_abc",
      "type": "banner",
      "value": "20% off"
    }
    ```
  </Accordion>

  <Accordion title="products_searched">
    ```json theme={null}
    {
      "event": "products_searched",
      "query": "coffee",
      "result_count": 12
    }
    ```
  </Accordion>

  <Accordion title="experiment_viewed">
    Triggered by `viewed_experiment`

    ```json theme={null}
    {
      "event": "experiment_viewed",
      "experiment_key": "checkout-flow-v2",
      "variation_id": 1,
      "account_id": "40586258-8a99-4651-b79f-0a1ab602a926",
      "venue_id": 8709,
      "venue_slug": "your-store"
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_opened">
    ```json theme={null}
    {
      "event": "story_viewer_opened",
      "story_id": 789,
      "story_index": 0,
      "story_title": "New Summer Menu",
      "total_stories": 5,
      "source": "menu_page"
    }
    ```
  </Accordion>

  <Accordion title="story_viewed">
    ```json theme={null}
    {
      "event": "story_viewed",
      "story_id": 789,
      "story_title": "New Summer Menu",
      "page_index": 2,
      "total_pages": 4,
      "has_video": true,
      "has_cta": true
    }
    ```
  </Accordion>

  <Accordion title="story_navigation">
    ```json theme={null}
    {
      "event": "story_navigation",
      "story_id": 789,
      "from_page": 1,
      "to_page": 2,
      "direction": "forward",
      "method": "tap"
    }
    ```
  </Accordion>

  <Accordion title="story_cta_clicked">
    ```json theme={null}
    {
      "event": "story_cta_clicked",
      "story_id": 789,
      "page_index": 2,
      "cta_type": "product",
      "cta_label": "Order Now",
      "cta_data": { "productId": 456 },
      "video_progress_percent": 75
    }
    ```
  </Accordion>

  <Accordion title="story_completed">
    ```json theme={null}
    {
      "event": "story_completed",
      "story_id": 789,
      "story_title": "New Summer Menu",
      "total_pages": 4,
      "time_spent_seconds": 32
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_closed">
    ```json theme={null}
    {
      "event": "story_viewer_closed",
      "story_id": 789,
      "page_index": 2,
      "total_stories_viewed": 3,
      "total_pages_viewed": 8,
      "time_spent_seconds": 45,
      "close_method": "swipe_down"
    }
    ```
  </Accordion>
</AccordionGroup>

## Configuration

### Enabling Integrations

1. Go to **Settings > Integrations** in your dashboard
2. Select the analytics platform
3. Enter your pixel/measurement ID or API key:
   * **Google Tag Manager**: Container ID (GTM-XXXXX)
   * **Meta Pixel**: Pixel ID
   * **Klaviyo**: API Key
4. Events begin flowing immediately

### Supported Chat Integrations

The analytics system also initialises chat widgets when configured:

* Front Chat
* Superchat
* Tawk.to
* Intercom

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing in Meta/Google">
    Check that your pixel ID is correct and the integration is enabled. Server-side events may take up to 24 hours to appear in some dashboards due to platform processing delays.
  </Accordion>

  <Accordion title="Revenue values don't match">
    Ensure your analytics platform is configured for the correct currency. storekit sends values in the store's local currency. Note that prices in events are in minor units (pence/cents) unless otherwise specified.
  </Accordion>

  <Accordion title="Missing user identity">
    Anonymous visitors are tracked with a device-based ID. User identity is associated once they provide their email at checkout.
  </Accordion>

  <Accordion title="Store Designer mode">
    Analytics are disabled when viewing the store in Store Designer mode to avoid polluting your data with test traffic.
  </Accordion>
</AccordionGroup>