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

# Standard Events Reference

> Reference every Upstack standard event with required properties, optional fields, and example JSON payloads — for instrumenting custom integrations and validating event taxonomy compliance.

Standard events are predefined event types that Upstack recognizes across all destinations. Each event has a fixed name, a set of required properties, and optional properties that improve match quality and reporting granularity.

<Tip>
  You don't need to manually instrument these events. The Upstack Pixel fires standard events automatically based on Shopify storefront interactions. This reference describes the payload structure so you can verify data in the dashboard or build custom integrations.
</Tip>

All events share a common envelope:

```json theme={null}
{
  "event_name": "EventName",
  "event_time": "2026-02-18T14:30:00.000Z",
  "event_source_url": "https://example-store.com/products/classic-tee",
  "user_data": { ... },
  "custom_data": { ... }
}
```

See [Properties & Context](/data-dictionary/properties-and-context) for the full field reference.

***

<AccordionGroup>
  <Accordion title="PageView" icon="eye">
    Fires on every page load across the storefront.

    **When it fires:** Each time a visitor loads or navigates to a page.

    **Required properties:**

    | Property           | Type     | Description            |
    | ------------------ | -------- | ---------------------- |
    | `event_name`       | string   | `"PageView"`           |
    | `event_time`       | ISO 8601 | Timestamp of the event |
    | `event_source_url` | string   | Full URL of the page   |

    **Optional properties:**

    | Property     | Type   | Description            |
    | ------------ | ------ | ---------------------- |
    | `page_title` | string | HTML title of the page |
    | `referrer`   | string | Referring URL          |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "PageView",
      "event_time": "2026-02-18T14:30:00.000Z",
      "event_source_url": "https://example-store.com/collections/summer",
      "user_data": {
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbc": "fb.1.1708271400.AbC123",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "page_title": "Summer Collection | Example Store",
        "referrer": "https://www.google.com/"
      }
    }
    ```
  </Accordion>

  <Accordion title="ViewContent" icon="shirt">
    Fires when a visitor views a product page or collection page.

    **When it fires:** Product detail page load, collection page load.

    **Required properties:**

    | Property       | Type      | Description                      |
    | -------------- | --------- | -------------------------------- |
    | `event_name`   | string    | `"ViewContent"`                  |
    | `event_time`   | ISO 8601  | Timestamp of the event           |
    | `content_ids`  | string\[] | Product or variant IDs viewed    |
    | `content_type` | string    | `"product"` or `"product_group"` |

    **Optional properties:**

    | Property       | Type   | Description                            |
    | -------------- | ------ | -------------------------------------- |
    | `content_name` | string | Product or collection title            |
    | `value`        | number | Product price                          |
    | `currency`     | string | ISO 4217 currency code (e.g., `"USD"`) |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "ViewContent",
      "event_time": "2026-02-18T14:31:12.000Z",
      "event_source_url": "https://example-store.com/products/classic-tee",
      "user_data": {
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "content_ids": ["8012345678"],
        "content_type": "product",
        "content_name": "Classic Cotton Tee",
        "value": 34.99,
        "currency": "USD"
      }
    }
    ```
  </Accordion>

  <Accordion title="AddToCart" icon="cart-plus">
    Fires when a visitor adds an item to their cart.

    **When it fires:** Add-to-cart button click, quantity increase in cart.

    **Required properties:**

    | Property       | Type      | Description                  |
    | -------------- | --------- | ---------------------------- |
    | `event_name`   | string    | `"AddToCart"`                |
    | `event_time`   | ISO 8601  | Timestamp of the event       |
    | `content_ids`  | string\[] | Product or variant IDs added |
    | `content_type` | string    | `"product"`                  |
    | `value`        | number    | Total value of items added   |
    | `currency`     | string    | ISO 4217 currency code       |

    **Optional properties:**

    | Property       | Type   | Description    |
    | -------------- | ------ | -------------- |
    | `content_name` | string | Product title  |
    | `num_items`    | number | Quantity added |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "AddToCart",
      "event_time": "2026-02-18T14:32:05.000Z",
      "event_source_url": "https://example-store.com/products/classic-tee",
      "user_data": {
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "content_ids": ["8012345678"],
        "content_type": "product",
        "content_name": "Classic Cotton Tee",
        "value": 34.99,
        "currency": "USD",
        "num_items": 1
      }
    }
    ```
  </Accordion>

  <Accordion title="InitiateCheckout" icon="credit-card">
    Fires when a visitor starts the checkout flow.

    **When it fires:** Checkout page load, "Begin Checkout" button click.

    **Required properties:**

    | Property      | Type      | Description                    |
    | ------------- | --------- | ------------------------------ |
    | `event_name`  | string    | `"InitiateCheckout"`           |
    | `event_time`  | ISO 8601  | Timestamp of the event         |
    | `content_ids` | string\[] | Product or variant IDs in cart |
    | `value`       | number    | Cart subtotal                  |
    | `currency`    | string    | ISO 4217 currency code         |

    **Optional properties:**

    | Property       | Type   | Description         |
    | -------------- | ------ | ------------------- |
    | `content_type` | string | `"product"`         |
    | `num_items`    | number | Total items in cart |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "InitiateCheckout",
      "event_time": "2026-02-18T14:33:45.000Z",
      "event_source_url": "https://example-store.com/checkout",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "ph": "f6e5d4c3b2a1...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbc": "fb.1.1708271400.AbC123",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "content_ids": ["8012345678", "8012345679"],
        "content_type": "product",
        "value": 89.98,
        "currency": "USD",
        "num_items": 2
      }
    }
    ```
  </Accordion>

  <Accordion title="Purchase" icon="bag-shopping">
    Fires when an order is completed.

    **When it fires:** Order confirmation / thank-you page load, Shopify order webhook.

    **Required properties:**

    | Property      | Type      | Description                                            |
    | ------------- | --------- | ------------------------------------------------------ |
    | `event_name`  | string    | `"Purchase"`                                           |
    | `event_time`  | ISO 8601  | Timestamp of the event                                 |
    | `content_ids` | string\[] | Product or variant IDs purchased                       |
    | `value`       | number    | Order total (excluding tax/shipping unless configured) |
    | `currency`    | string    | ISO 4217 currency code                                 |
    | `order_id`    | string    | Shopify order ID or name                               |

    **Optional properties:**

    | Property       | Type   | Description                   |
    | -------------- | ------ | ----------------------------- |
    | `content_type` | string | `"product"`                   |
    | `content_name` | string | Comma-separated product names |
    | `num_items`    | number | Total items purchased         |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "Purchase",
      "event_time": "2026-02-18T14:35:20.000Z",
      "event_source_url": "https://example-store.com/thank-you",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "ph": "f6e5d4c3b2a1...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbc": "fb.1.1708271400.AbC123",
        "fbp": "fb.1.1708271400.XyZ789",
        "external_id": "cust_12345"
      },
      "custom_data": {
        "content_ids": ["8012345678", "8012345679"],
        "content_type": "product",
        "value": 89.98,
        "currency": "USD",
        "order_id": "#1042",
        "num_items": 2
      }
    }
    ```

    <Warning>
      Ensure `value` reflects the actual order amount sent to ad platforms. Discrepancies between Shopify order totals and reported CAPI revenue are the most common attribution debugging issue.
    </Warning>
  </Accordion>

  <Accordion title="Search" icon="magnifying-glass">
    Fires when a visitor uses site search.

    **When it fires:** Search results page load, predictive search interaction.

    **Required properties:**

    | Property        | Type     | Description              |
    | --------------- | -------- | ------------------------ |
    | `event_name`    | string   | `"Search"`               |
    | `event_time`    | ISO 8601 | Timestamp of the event   |
    | `search_string` | string   | The search query entered |

    **Optional properties:**

    | Property       | Type      | Description                     |
    | -------------- | --------- | ------------------------------- |
    | `content_ids`  | string\[] | Product IDs returned in results |
    | `content_type` | string    | `"product"`                     |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "Search",
      "event_time": "2026-02-18T14:36:00.000Z",
      "event_source_url": "https://example-store.com/search?q=cotton+tee",
      "user_data": {
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "search_string": "cotton tee",
        "content_ids": ["8012345678", "8012345680"],
        "content_type": "product"
      }
    }
    ```
  </Accordion>

  <Accordion title="Lead" icon="user-plus">
    Fires when a visitor submits a lead form.

    **When it fires:** Contact form submission, quote request, product inquiry.

    **Required properties:**

    | Property     | Type     | Description            |
    | ------------ | -------- | ---------------------- |
    | `event_name` | string   | `"Lead"`               |
    | `event_time` | ISO 8601 | Timestamp of the event |

    **Optional properties:**

    | Property       | Type   | Description            |
    | -------------- | ------ | ---------------------- |
    | `content_name` | string | Form or campaign name  |
    | `value`        | number | Estimated lead value   |
    | `currency`     | string | ISO 4217 currency code |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "Lead",
      "event_time": "2026-02-18T14:37:00.000Z",
      "event_source_url": "https://example-store.com/contact",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0..."
      },
      "custom_data": {
        "content_name": "Product Inquiry",
        "value": 150.00,
        "currency": "USD"
      }
    }
    ```
  </Accordion>

  <Accordion title="CompleteRegistration" icon="user-check">
    Fires when a customer creates an account.

    **When it fires:** Account registration form submission.

    **Required properties:**

    | Property     | Type     | Description              |
    | ------------ | -------- | ------------------------ |
    | `event_name` | string   | `"CompleteRegistration"` |
    | `event_time` | ISO 8601 | Timestamp of the event   |

    **Optional properties:**

    | Property       | Type   | Description                    |
    | -------------- | ------ | ------------------------------ |
    | `content_name` | string | Registration type or source    |
    | `value`        | number | Assigned value of registration |
    | `currency`     | string | ISO 4217 currency code         |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "CompleteRegistration",
      "event_time": "2026-02-18T14:38:15.000Z",
      "event_source_url": "https://example-store.com/account/register",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0..."
      },
      "custom_data": {
        "content_name": "Storefront Registration"
      }
    }
    ```
  </Accordion>

  <Accordion title="AddPaymentInfo" icon="credit-card">
    Fires when a customer enters payment details during checkout.

    **When it fires:** Payment step completion in the checkout flow.

    **Required properties:**

    | Property     | Type     | Description            |
    | ------------ | -------- | ---------------------- |
    | `event_name` | string   | `"AddPaymentInfo"`     |
    | `event_time` | ISO 8601 | Timestamp of the event |

    **Optional properties:**

    | Property      | Type      | Description                    |
    | ------------- | --------- | ------------------------------ |
    | `content_ids` | string\[] | Product or variant IDs in cart |
    | `value`       | number    | Cart value at payment step     |
    | `currency`    | string    | ISO 4217 currency code         |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "AddPaymentInfo",
      "event_time": "2026-02-18T14:34:30.000Z",
      "event_source_url": "https://example-store.com/checkout/payment",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "content_ids": ["8012345678"],
        "value": 34.99,
        "currency": "USD"
      }
    }
    ```
  </Accordion>

  <Accordion title="AddShippingInfo" icon="truck">
    Fires when a customer enters shipping details during checkout.

    **When it fires:** Shipping step completion in the checkout flow.

    **Required properties:**

    | Property     | Type     | Description            |
    | ------------ | -------- | ---------------------- |
    | `event_name` | string   | `"AddShippingInfo"`    |
    | `event_time` | ISO 8601 | Timestamp of the event |

    **Optional properties:**

    | Property      | Type      | Description                    |
    | ------------- | --------- | ------------------------------ |
    | `content_ids` | string\[] | Product or variant IDs in cart |
    | `value`       | number    | Cart value at shipping step    |
    | `currency`    | string    | ISO 4217 currency code         |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "AddShippingInfo",
      "event_time": "2026-02-18T14:34:00.000Z",
      "event_source_url": "https://example-store.com/checkout/shipping",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0...",
        "fbp": "fb.1.1708271400.XyZ789"
      },
      "custom_data": {
        "content_ids": ["8012345678", "8012345679"],
        "value": 89.98,
        "currency": "USD"
      }
    }
    ```
  </Accordion>

  <Accordion title="Subscribe" icon="envelope">
    Fires when a visitor subscribes to email or SMS marketing.

    **When it fires:** Newsletter signup, SMS opt-in, popup subscription form.

    **Required properties:**

    | Property     | Type     | Description            |
    | ------------ | -------- | ---------------------- |
    | `event_name` | string   | `"Subscribe"`          |
    | `event_time` | ISO 8601 | Timestamp of the event |

    **Optional properties:**

    | Property   | Type   | Description                |
    | ---------- | ------ | -------------------------- |
    | `value`    | number | Estimated subscriber value |
    | `currency` | string | ISO 4217 currency code     |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "Subscribe",
      "event_time": "2026-02-18T14:39:00.000Z",
      "event_source_url": "https://example-store.com/",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0..."
      },
      "custom_data": {
        "value": 5.00,
        "currency": "USD"
      }
    }
    ```
  </Accordion>

  <Accordion title="StartTrial" icon="play">
    Fires when a visitor begins a free trial.

    **When it fires:** Trial signup confirmation, trial activation.

    **Required properties:**

    | Property     | Type     | Description            |
    | ------------ | -------- | ---------------------- |
    | `event_name` | string   | `"StartTrial"`         |
    | `event_time` | ISO 8601 | Timestamp of the event |

    **Optional properties:**

    | Property       | Type   | Description                |
    | -------------- | ------ | -------------------------- |
    | `content_name` | string | Trial plan or product name |
    | `value`        | number | Trial plan value           |
    | `currency`     | string | ISO 4217 currency code     |

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "StartTrial",
      "event_time": "2026-02-18T14:40:00.000Z",
      "event_source_url": "https://example-store.com/trial-signup",
      "user_data": {
        "em": "a1b2c3d4e5f6...hashed",
        "client_ip_address": "203.0.113.42",
        "client_user_agent": "Mozilla/5.0..."
      },
      "custom_data": {
        "content_name": "Premium Plan Trial",
        "value": 49.99,
        "currency": "USD"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Custom Events" icon="code" href="/data-dictionary/custom-events">
    Define events beyond the standard taxonomy for your unique business needs.
  </Card>

  <Card title="Properties & Context" icon="table" href="/data-dictionary/properties-and-context">
    Full reference for all user\_data, custom\_data, and context fields.
  </Card>
</CardGroup>