User properties

Here you will find various information about the properties of users.

Do not confuse user properties and event properties. The event properties reflect additional information about the event (for example, the "Made an order" event may have the "Sum", "Products" properties, etc.). User properties reflect user information. For example: name, email, number of orders, the sum of all orders, etc.

Data types

5 types are available:

  • number
  • string
  • date/time
  • boolean
  • list

Numbers can only be integers in range from -2^53 to +2^53, or from -9007199254740992 to +9007199254740992.

Maximal string length is 255 characters.

Strings of up to 255 characters can be items of the list (up to 30 items in one list).

Date/time format: ISO 8601: YYYY-MM-DDTHH:MM:SS. Simplified format is acceptable: YYYY-MM-DD, in which case time is set as: 00:00:00.


    value1: 145,
    value2: "Hello, world!",
    value3: true,
    value4: "2015-09-13T13:25:05",
    value5: ["element1", "element2", "element3"]

Property identification formats

Sometimes a simply creating a property is not enough. For example, if you track the number of times a button is clicked, it would be convenient to increment the property value by one each time (add operation).

Another example - you want to know which section the user visited first. Here, the property should be written only if it is not already created (set_once operation).

A complex format for setting properties is an array of objects. Each object is an atomic operation on a property. There are three fields in the object: op - operation, key - property name, value - value. The following operations are supported:

  • update_or_create - most commonly used operation. Creates property (or updates if it already exists)
  • set_once - create only if property does not exist yet
  • add - add a set amount to the property value (if the property does not exist, it will be created with 0 value, and then increased by a set amount)
  • delete - delete property
  • append - add into a list
  • union - add into a list if such item is not already present in the list
  • exclude - delete from the list


    // Set value (update, if value is already defined)
    {"op": "update_or_create", "key": "my_property", "value": "Hello"},

    // Set if property is undefined
    {"op": "set_once", "key": "my_property", "value": "Hello"},

    // Increment/decrement
    {"op": "add", "key": "my_property", "value": "1"},
    {"op": "add", "key": "my_property", "value": "-1"},
    {"op": "add", "key": "my_property", "value": "15"},
    {"op": "add", "key": "my_property", "value": "-53"},

    // Delete property
    {"op": "delete", "key": "my_property", "value": "0"},

    // Add an item into the list
    {"op": "append", "key": "my_list_property", "value": "super-element"},

    // add into a list if such item is not already present in the list ("add to set")
    {"op": "union", "key": "my_list_property", "value": "super-element"},

    // Delete element from the list
    {"op": "exclude", "key": "my_list_property", "value": "super-element"},

At the moment lists can contain up to 30 items. Only strings can be items of a list.

In case append is used, items are added sequentially. The order will be preserved. When 31st item is added, defining would a new item be added is impossible(and which item would be removed before adding).

In case union is used order is not preserved. New item insertion is not guaranteed if list already contains 30 items. But not having identical items is guaranteed.

System (standard) user properties

All property names beginning with $ are system. Thus custom properties (those you create) should not begin with $.

Only 3 system properties values can be written. These properties are: $name, $phone, $email. All the rest can only be read.

Name Description
$name Name
$email Email
$phone Phone
$last_seen Last activity. Date of last event
$last_contacted Date of last user’s reply or date when a message to user was last sent (including auto-messages)
$last_reply Date of last user’s reply
$conversations_emails Amount of email conversations
$conversations_chats Amount of chat conversations
$conversations_popups Amount of pop-up conversations
$sessions Sessions count
$user_id User ID
$score Score (user rating)
$initial_referrer Initial referrer
$initial_referrer_domain Initial referrer. Only domain
$initial_utm_campaign First UTM Campaign tag
$initial_utm_source First UTM Source tag
$initial_utm_medium First UTM Medium tag
$initial_utm_content First UTM Content tag
$initial_utm_term First UTM Term tag
$last_utm_campaign Last UTM Campaign tag
$last_utm_source Last UTM Source tag
$last_utm_medium Last UTM Medium tag
$last_utm_content Last UTM Content tag
$last_utm_term Last UTM Term tag
$country Country
$region Region
$city City
$latitude Latitude
$longitude Longitude
$email_unsubscribed Unsubscribed from emails
$avatar Name of avatar file. Users avatars are stored here:{{ $avatar }}
$social_vk VK page URL
$social_facebook Facebook page URL
$social_fourqsuare Foursquare page URL
$social_googleplus Google+ page URL
$social_pinterest Pinterest page URL
$social_twitter Twitter page URL
$social_skype Skype

Deprecated properties: $comment, $last_active_user, $online, $idle, $cluster_id, $app_uid, $uid, $identity.

After user performs an event(for example, event with ID=123), he will obtain 3 properties for this event:

Name Description
$event_123_count Number of performances
$event_123_first Date, when event was first performed by the user
$event_123_last Date, when event was last performed by the user

E-commerce properties

E-commerce specific properties. These properties can be identified via API.

Name Description
$cart_amount Cart amount (integer)
$viewed_products Viewed products (list of product names)
$cart_items Cart (list of product names)
$last_order_status Last order status
$last_payment Last payment amount (integer)
$revenue Total revenue from user (integer)
$profit Total profit from user (integer)
$group Group
$discount Discount (integer)
$orders_count Orders count (integer)
$ordered_items Ordered items (list of product names)
$ordered_categories Ordered items’ categories (list of product categories’ names)
$viewed_categories Viewed products’ categories (list of product categories’ names)