> ## 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.

# Event Properties Reference

> Complete reference for all Upstack Data event properties — items array, customer data, checkout fields, and auto-captured context like click IDs and UTMs.

Properties are the data you send with each tracking event. This page documents all available properties and shows how to use them in JavaScript.

<Note>
  Use **camelCase** when sending properties — the platform automatically converts to the format each destination requires.
</Note>

## Full Event Structure

A complete tracking event contains the event name, timestamp, user data, custom data, and automatically captured context.

```javascript theme={null}
window._upstack('track', 'purchase', {
  // Core identifiers
  transactionId: 'ORD-2026-001',
  orderName: '#1042',
  
  // Monetary values
  value: 134.99,
  currency: 'USD',
  subtotalPrice: 149.99,
  tax: 12.00,
  shipping: 8.00,
  discount: 35.00,
  
  // Customer data (improves match quality)
  email: 'customer@example.com',
  phone: '+15551234567',
  firstName: 'Jane',
  lastName: 'Smith',
  
  // Product items
  items: [
    {
      id: 'SKU-001',
      name: 'Running Shoes',
      price: 89.99,
      quantity: 1,
      brand: 'Nike',
      category: 'Footwear'
    }
  ],
  
  // Optional checkout details
  coupon: 'SAVE25',
  paymentType: 'credit_card',
  shippingTier: 'express'
});

// The platform automatically captures additional context:
// - Click IDs (fbclid, gclid, ttclid, etc.)
// - UTM parameters (utm_source, utm_medium, etc.)
// - Device and browser information
// - Geographic data
// - Session and identity information
```

## Core Properties

These properties work with most events.

<CardGroup cols={2}>
  <Card title="value" icon="coins" href="/pixel/events/properties/value">
    Monetary value of the event. Required for purchase, lead, subscribe.
  </Card>

  <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency">
    ISO 4217 currency code. Required with value.
  </Card>

  <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id">
    Unique order identifier. Required for purchase/refund.
  </Card>

  <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name">
    Human-readable order number shown to customers.
  </Card>
</CardGroup>

### Quick Reference

| Property                                                   | Type   | Required                          | Events                                                                                      |
| ---------------------------------------------------------- | ------ | --------------------------------- | ------------------------------------------------------------------------------------------- |
| [`value`](/pixel/events/properties/value)                  | number | Yes for purchase, lead, subscribe | purchase, add\_to\_cart, view\_content, initiate\_checkout, lead, subscribe, trial\_started |
| [`currency`](/pixel/events/properties/currency)            | string | Yes (when value is set)           | Any event with `value`                                                                      |
| [`transactionId`](/pixel/events/properties/transaction-id) | string | Yes for purchase/refund           | purchase, refund                                                                            |
| `orderId`                                                  | string | No                                | purchase, refund                                                                            |
| [`orderName`](/pixel/events/properties/order-name)         | string | No                                | purchase                                                                                    |

<Info>
  `orderId` and `transactionId` are interchangeable — use whichever fits your system. If both are provided, `transactionId` takes precedence.
</Info>

```javascript theme={null}
window._upstack('track', 'purchase', {
  value: 99.99,
  currency: 'USD',
  transactionId: 'ORD-2026-001',
  orderName: '#1042'
});
```

***

## Customer Properties

Properties for identifying customers. Used for identity resolution and destination matching.

<CardGroup cols={2}>
  <Card title="email" icon="envelope" href="/pixel/events/properties/email">
    Primary identifier for cross-device tracking.
  </Card>

  <Card title="phone" icon="phone" href="/pixel/events/properties/phone">
    E.164 format for improved matching.
  </Card>

  <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name">
    Customer name for identity resolution.
  </Card>

  <Card title="Address Fields" icon="location-dot" href="/pixel/events/properties/address">
    Shipping and billing address properties.
  </Card>
</CardGroup>

### Quick Reference

| Property                                     | Type   | Required    | Events                              |
| -------------------------------------------- | ------ | ----------- | ----------------------------------- |
| [`email`](/pixel/events/properties/email)    | string | Recommended | All events (improves match quality) |
| [`phone`](/pixel/events/properties/phone)    | string | No          | All events (improves match quality) |
| [`firstName`](/pixel/events/properties/name) | string | No          | All events                          |
| [`lastName`](/pixel/events/properties/name)  | string | No          | All events                          |

<Tip>
  Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3.
</Tip>

```javascript theme={null}
window._upstack('track', 'lead', {
  email: 'customer@example.com',
  phone: '+15551234567',
  firstName: 'Jane',
  lastName: 'Smith'
});
```

***

## Checkout & Pricing Properties

Additional properties for checkout and purchase events.

<CardGroup cols={3}>
  <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price">
    Subtotal before tax/shipping.
  </Card>

  <Card title="tax" icon="percent" href="/pixel/events/properties/tax">
    Tax amount applied.
  </Card>

  <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping">
    Shipping cost.
  </Card>

  <Card title="discount" icon="tag" href="/pixel/events/properties/discount">
    Total discount amount.
  </Card>

  <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon">
    Promo code used.
  </Card>

  <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type">
    Payment method used.
  </Card>

  <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier">
    Shipping speed selected.
  </Card>
</CardGroup>

### Quick Reference

| Property                                                   | Type      | Description                                                |
| ---------------------------------------------------------- | --------- | ---------------------------------------------------------- |
| [`subtotalPrice`](/pixel/events/properties/subtotal-price) | number    | Subtotal before tax and shipping                           |
| `price`                                                    | number    | Base price (distinct from `value` which is the total)      |
| [`tax`](/pixel/events/properties/tax)                      | number    | Tax amount                                                 |
| [`shipping`](/pixel/events/properties/shipping)            | number    | Shipping cost                                              |
| [`discount`](/pixel/events/properties/discount)            | number    | Total discount amount applied                              |
| [`coupon`](/pixel/events/properties/coupon)                | string    | Coupon or promo code used                                  |
| [`paymentType`](/pixel/events/properties/payment-type)     | string    | Payment method (`"credit_card"`, `"paypal"`, `"shop_pay"`) |
| [`shippingTier`](/pixel/events/properties/shipping-tier)   | string    | Shipping tier (`"standard"`, `"express"`, `"overnight"`)   |
| `cartId`                                                   | string    | Shopping cart identifier                                   |
| `affiliation`                                              | string    | Store or affiliate name                                    |
| `orderSourceName`                                          | string    | Order source channel                                       |
| `tags`                                                     | string\[] | Array of order or event tags                               |
| `totalUnitCost`                                            | number    | Total cost of goods sold (COGS) for profitability tracking |
| `totalUnitMargin`                                          | number    | Total margin (value - totalUnitCost)                       |

```javascript theme={null}
window._upstack('track', 'purchase', {
  transactionId: 'ORD-12345',
  value: 134.99,
  currency: 'USD',
  subtotalPrice: 149.99,
  tax: 12.00,
  shipping: 8.00,
  discount: 35.00,
  coupon: 'SAVE25',
  paymentType: 'credit_card',
  shippingTier: 'express',
  items: [/* ... */]
});
```

***

## Content Properties

Properties for content-related events like search and page views.

<CardGroup cols={2}>
  <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term">
    Search query entered by the user.
  </Card>

  <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids">
    Array of product IDs from search results.
  </Card>
</CardGroup>

### Quick Reference

| Property                                              | Type      | Description                       | Events                                      |
| ----------------------------------------------------- | --------- | --------------------------------- | ------------------------------------------- |
| [`searchTerm`](/pixel/events/properties/search-term)  | string    | Search query entered              | search                                      |
| [`content_ids`](/pixel/events/properties/content-ids) | string\[] | Array of product IDs              | view\_content, search, add\_to\_cart        |
| `content_type`                                        | string    | `"product"` or `"product_group"`  | view\_content, add\_to\_cart, purchase      |
| `content_name`                                        | string    | Name of content, product, or form | view\_content, lead, complete\_registration |
| `num_items`                                           | number    | Total item count                  | add\_to\_cart, initiate\_checkout, purchase |
| `page_title`                                          | string    | Page title                        | page\_view                                  |
| `referrer`                                            | string    | Referring URL                     | page\_view                                  |

```javascript theme={null}
window._upstack('track', 'search', {
  searchTerm: 'blue running shoes',
  content_ids: ['SKU-001', 'SKU-002', 'SKU-003']
});
```

***

## Promotional Properties

Properties for tracking promotions, campaigns, and affiliate activity.

<CardGroup cols={3}>
  <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id">
    Promotion/campaign identifier.
  </Card>

  <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name">
    Promotion display name.
  </Card>

  <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name">
    Creative/ad variant name.
  </Card>

  <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot">
    Placement position on page.
  </Card>

  <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id">
    Store/affiliate/location ID.
  </Card>
</CardGroup>

### Quick Reference

| Property                                                   | Type   | Description                              | Events                                 |
| ---------------------------------------------------------- | ------ | ---------------------------------------- | -------------------------------------- |
| [`promotionId`](/pixel/events/properties/promotion-id)     | string | Promotion or campaign identifier         | view\_content, add\_to\_cart, purchase |
| [`promotionName`](/pixel/events/properties/promotion-name) | string | Promotion display name                   | view\_content, add\_to\_cart, purchase |
| [`creativeName`](/pixel/events/properties/creative-name)   | string | Creative or ad variant name              | view\_content, add\_to\_cart, purchase |
| [`creativeSlot`](/pixel/events/properties/creative-slot)   | string | Creative placement position              | view\_content, add\_to\_cart, purchase |
| [`locationId`](/pixel/events/properties/location-id)       | string | Store, affiliate, or location identifier | All events                             |

```javascript theme={null}
window._upstack('track', 'view_content', {
  items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }],
  value: 89.99,
  currency: 'USD',
  promotionId: 'SUMMER_SALE_2026',
  promotionName: 'Summer Sale 2026',
  creativeName: 'hero_banner_v2',
  creativeSlot: 'homepage_hero',
  locationId: 'store_nyc_001'
});
```

***

## Detailed Property References

<CardGroup cols={2}>
  <Card title="Items Array" icon="list" href="/pixel/events/properties/items">
    Product details for e-commerce events — id, name, price, quantity, brand, category, variant.
  </Card>

  <Card title="Address Properties" icon="location-dot" href="/pixel/events/properties/address">
    Shipping and billing address fields — address1, city, province, country, zip.
  </Card>

  <Card title="SaaS Properties" icon="building" href="/pixel/events/properties/saas">
    B2B/SaaS properties — account, subscription, trial, payment, and churn tracking.
  </Card>

  <Card title="Auto-Captured Fields" icon="wand-magic-sparkles" href="/pixel/events/properties/auto-captured">
    Click IDs, UTMs, and context fields captured automatically by the pixel.
  </Card>
</CardGroup>

***

## Naming Conventions

### Input vs Output Format

Send properties in **camelCase** — the platform converts to each destination's required format automatically.

| Your Input      | Meta CAPI Output | GA4 Output                |
| --------------- | ---------------- | ------------------------- |
| `transactionId` | `transaction_id` | `transaction_id`          |
| `firstName`     | `fn` (hashed)    | `first_name`              |
| `email`         | `em` (hashed)    | `user_id` (if configured) |

### Legacy Snake Case Properties

Some properties use snake\_case for compatibility with Meta and GA4 conventions:

| Property       | Format      | Notes                                              |
| -------------- | ----------- | -------------------------------------------------- |
| `content_ids`  | snake\_case | Array of product IDs (Meta convention)             |
| `content_type` | snake\_case | `"product"` or `"product_group"` (Meta convention) |
| `content_name` | snake\_case | Content or product name                            |
| `num_items`    | snake\_case | Total item count                                   |

<Info>
  The platform accepts both formats and normalizes automatically. You can use either `contentIds` or `content_ids` — both work.
</Info>

### Event Names

Event names use **snake\_case** (e.g., `add_to_cart`, `initiate_checkout`, `view_content`).

```javascript theme={null}
// Correct
window._upstack('track', 'add_to_cart', { ... });
window._upstack('track', 'view_content', { ... });

// Incorrect
window._upstack('track', 'AddToCart', { ... });
window._upstack('track', 'viewContent', { ... });
```