Custom Events

Custom events are a group of events that are manually-tailored for each customer. As opposed to system events, custom events that are included in different projects greatly vary as it is your choice which of them you decide to incorporate. In this article, we will list and explain the most commonly used custom events and attributes. If you want to learn how to set up their tracking go to our Web tracking article.

📘

Location, os, device & browser are already tracked by default in every event using exponea.track() function of the SDK. If you want to add some more default properties TO EVERY EVENT then you can use the track.default_properties. If you need it only for some events, you can also update the events individually. Find out more.

purchase

purchase happens when the customer purchases a product/products on your website.

AttributeDescriptionExample
purchase_idAutomatically-generated ID of the purchase.123456a
purchase_statusStatus of the purchase.success / refund
purchase_source_typeType of the source from which the purchase was done.online / store
purchase_source_nameName of the source from which the purchase was done.domain.com / Corner Store 1st Street, ...
product_listList of all purchased products, their quantities and other required properties.[ {"product_id": "abc123", "quantity":1} ]
product_idsList of IDs of all purchased products.[ "abc123", "abc456", "abc789" ]
total_priceTotal price paid by the customer in the reference currency including tax and shipping.24
total_price_without_taxTotal price paid by customer in reference currency including shipping but not the tax.20
total_price_local_currencyTotal price paid by the customer in the currency they used for the payment.2
local_currencyCurrency the customer used for the payment.USD, GBP, EUR
total_quantityTotal quantity of the products purchased.2
payment_typePayment method.bank transfer / online payment / cash / cod
shipping_typeType of delivery.courier / personally
shipping_companyDelivery company.ups
shipping_costPrice of the delivery.69
shipping_countryName of the country to which the products are delivered.USA
shipping_cityName of the city to which the products are delivered.New York
tax_percentageSales tax expressed as a percentage.20
tax_valueSales tax expressed as money.4
voucher_codeCode of the voucher used in this purchase.KA54-548C
voucher_percentageThe discount rate conferred on the customer by the voucher expressed as a percentage.10
voucher_valueThe amount that the voucher subtracted from the prize of the purchase.2
variant_listList of all purchased variants, their quantities and other required properties.[ {"variant_id": "abc123", "quantity":1} ]
variant_idsList of IDs of all purchased variants.[ "abc123", "abc456", "abc789" ]
languageLanguage of website from which the purchase was made.en
locationURL of the page where the purchase event occurred.https://webshop.com/purchase
domainDefault domain of your website.webshop.com

purchase_item

purchase_item happens when the customer purchases a product on your website. For each item within a purchase, a separate purchase_item should also be rendered. There should be as many purchase_item events along with a single purchase event as there were items bought.

AttributeDescriptionExample
purchase_idAutomatically-generated ID of the purchase.123456a
purchase_statusStatus of the purchase.success / refund
purchase_source_typeType of the source from which the purchase was done.online / store
purchase_source_nameName of the source from which the purchase was done.domain.com / Corner Store 1st Street, ...
product_idAutomatically-generated ID of the product.abc123
variant_idAutomatically-generated ID of the variant of the product that includes information about colour, size or materials.abc123small
titleItem name that includes colour, size or materials if available.Tassel Loafers in Navy Faux Sued
brandBrand of the purchased item.END.
pricePrice of one unit of the item paid by the customer in the reference currency.18
price_local_currencyPrice of one unit of the item paid by the customer in the currency they used for the payment.90
discount_percentageIn case of a discount, the discount rate used on the item expressed as a percentage.10
discount_valueIn case of a discount, the amount subtracted from the price of the product as a result of the discount.2
original_pricePrice of the item without a discount in a reference currency.20
original_price_local_currencyPrice of the item without a discount in a currency the customer used for the payment.100
quantityQuantity of the purchased products.2
total_priceTotal price paid by the customer in the reference currency including tax and shipping.24
total_price_without_taxTotal price paid by the customer in reference currency including shipping but not the tax.20
total_price_local_currencyTotal price paid by the customer in the currency they used for the payment.43
local_currencyCurrency the customer used for the payment.USD, GBP, EUR
tagsCustom tags for describing the item.["new", "sales", "teen", "man"]
category_1Top level category of products on the website where the item can be found.Shoes
category_2Second level category of products on the website where the item can be found.Trekking
category_3Third level category of products on the website where the item can be found. (number of categories is not limited to 3)Ankle boots
categories_pathPath through the categories leading to the product.Shoes > Trekking > Ankle boots
category_idAutomatically-generated ID of the final category where the purchased product belongs.abc123
categories_idsList of IDs of all categories from root until the final one where the purchased product belongs.["abc123","abc456","abc789"]
languageLanguage of website from which the purchase was made.en
locationURL of the page where the purchase event occurred.https://webshop.com/purchase
domainDefault domain of your website.webshop.com

cart_update

cart_update happens when an item/items are added or removed from the cart.

AttributeDescriptionExample
actionCustomer's action on the basket.add / remove / empty
button_copyText of the button used for adding item to the cart.Add / Purchase / Add to cart
page_typeType of a page where cart contents changed.product / homepage / category / page / checkout
product_idAutomatically-generated ID of the product added/removed.abc123
variant_idAutomatically-generated ID of the variant of the product added/removed that includes information about colour, size or materials.abc123small
titleName of the item added/removed that includes colour, size or materials if available.Tassel Loafers in Navy Faux Sued
brandBrand of an item added/removed.END.
pricePrice of one unit of the item added/removed to be paid by the customer in the reference currency.18
price_local_currencyPrice of one unit of the item added/removed to be paid by the customer in the currency they are going to use for the payment.90
discount_percentageIn case of a discount, the discount rate used on the item added/removed expressed as a percentage.10
discount_valueIn case of a discount, the amount subtracted from the price of the item added/removed as a result of the discount.2
original_pricePrice of the item added/removed without a discount in a reference currency.20
original_price_local_currencyPrice of the item added/removed without a discount in a currency the customer used for the payment.100
product_listList of all products in the cart after cart update.[ {"product_id": "abc123", "quantity":1} ]
product_idsList of IDs of all products in the cart after cart update.[ "abc123", "abc456", "abc789" ]
total_quantityTotal quantity of the products in the cart.2
total_priceTotal price of the products in the cart in the reference currency.24
total_price_without_taxTotal price of items in the cart in the reference currency including the shipping but not the tax.20
total_price_local_currencyTotal price of items in the cart in the currency the customer will use for the payment.43
local_currencyCurrency the customer will use for the payment.USD, GBP, EUR
tagsCustom tags for describing the item.["new", "sales", "teen", "man"]
category_1Top level category of products on the website where the item can be found.Shoes
category_2Second level category of products on the website where the item can be found.Trekking
category_3Third level category of products on the website where the item can be found.Ankle boots
categories_pathPath through the categories leading to the product.Shoes > Trekking > Ankle boots
category_idAutomatically-generated ID of the final category from which the cart was updated.abc123
categories_idsList of IDs of all categories from root until the final one from which the cart was updated.["abc123","abc456","abc789"]
variant_listList of all variants of the items in the cart, their quantities and other required properties.[ {"variant_id": "abc123", "quantity":1} ]
variant_idsList of IDs of all variants of the items in the cart.[ "abc123", "abc456", "abc789" ]
languageLanguage of website where the cart was updated.en
locationURL of the page where the cart_update event occurred.https://webshop.com/cart-update
domainDefault domain of your website.webshop.com

checkout

checkout happens on with every step (page) of the checkout process.

AttributeDescriptionExample
step_numberNumber of the step of the checkout process.1
step_titleTitle of the step of the checkout process.Shipping / Personal information / Completed
product_listList of all products in the cart.[ {"product_id": "abc123", "quantity":1} ]
product_idsList of IDs of all products in the cart.[ "abc123", "abc456", "abc789" ]
payment_typePayment method.bank transfer / online payment / cash / cod
total_priceTotal price of the products to be purchased.24
total_price_without_taxTotal price of items in the cart in the reference currency including the shipping but not the tax.20
total_price_local_currencyTotal price of items in the cart in the currency the customer will use for the payment.43
local_currencyCurrency the customer will use for the payment.USD, GBP, EUR
total_quantityTotal quantity of the products to be purchased.2
tax_valueSales tax expressed as money.24
tax_percentageSales tax expressed as a percentage.20
shipping_typeType of delivery.courier / personally
shipping_companyDelivery company.ups
shipping_costPrice of shipping.69
shipping_countryName of the country to which the products will be delivered.USA
shipping_cityName of the city to which the products will be delivered.New York
voucher_codeCode of the voucher to be used in this purchase.KA54-548C-TEST
voucher_percentageThe discount rate conferred on the customer by the voucher expressed as a percentage.10
voucher_valueThe amount that the voucher will subtract from the prize of the purchase.2
variant_listList of all variants of the items in the cart, their quantities and other required properties.[ {"variant_id": "abc123", "quantity":1} ]
variant_idsList of IDs of all variants of the items in the cart.[ "abc123", "abc456", "abc789" ]
languageLanguage of website.en
locationURL of the page where the checkout event occurred.https://webshop.com/checkout
domainDefault domain of your website.webshop.com

view_item

view_item happens every time the customer opens the page of a particular product.

AttributeDescriptionExample
product_idAutomatically-generated ID of the product.abc123
variant_idAutomatically-generated ID of the variant of the viewed product that includes information about colour, size or materials.abc123small
titleName of the item viewed that includes colour, size or materials if available.Tassel Loafers in Navy Faux Sued
brandBrand of an item viewed.END.
pricePrice of one unit of the item viewed to be paid by the customer in the reference currency.18
price_local_currencyPrice of one unit of the item viewed by the customer in the currency listed on the website.90
discount_percentageIn case of a discount, the discount rate used on the viewed item expressed as a percentage.10
discount_valueIn case of a discount, the amount subtracted from the price of the viewed item as a result of the discount.2
original_pricePrice of the viewed item without a discount in a reference currency.20
original_price_local_currencyPrice of the viewed item without a discount in the currency listed on the website.100
local_currencyCurrency the customer will use for the payment.USD, GBP, EUR
stock_levelNumber of the particular item in stock.46
tagsCustom tags for describing the item.["new", "sales", "teen", "man"]
category_1Top level category of products on the website where the item can be found.Shoes
category_2Second level category of products on the website where the item can be found.Trekking
category_3Third level category of products on the website where the item can be found. (number of categories is not limited to 3)Ankle boots
categories_pathPath through the categories leading to the product.Shoes > Trekking > Ankle boots
category_idAutomatically-generated ID of the final category where the viewed product belongs.abc123
categories_idsList of IDs of all categories from root until the final where the viewed item belongs.["abc123","abc456","abc789"]
languageLanguage of website.en
locationURL of the page where the view_item event occurred.https://webshop.com/shoes/end.-red-39
domainDefault domain of your website.webshop.com

view_category

view_category happens every time the customer opens the page of a particular category of products.

AttributeDescriptionExample
category_idAutomatically-generated ID of the viewed category.abc123
category_nameName of the category.Shoes
category_listed_productsList of all product IDs in the category.["A1", "C3", "G5", "A2"]
category_1Either the top level category of products preceding the currently viewed category or the currently viewed category.Shoes
category_2Either the second level category of products preceding the currently viewed category or the currently viewed category.Trekking
category_3Either the third level category of products preceding the currently viewed category or the currently viewed category. (number of categories is not limited to 3)Ankle boots
categories_pathPath through the categories leading to the category page currently seen.Shoes > Trekking > Ankle boots
categories_idsList of IDs of all categories from the root until the selected category.["abc123","abc456","abc789"]
local_currencyCurrency the customer will use for the payment.USD, GBP, EUR
languageLanguage of website.en
locationURL of the page where the view_category event occurred.https://webshop.com/shoes/shoes
domainDefault domain of your website.webshop.com

consent

Attributes of the consent can be found in our Tracking consent events article.

banner

banner happens when the customer is shown a banner you had created. banner is considered to be a semi-custom event because you have to manually set up the tracking of a new custom-made banner while the banner templates provided are tracked automatically. Learn more about weblayers in our guide.

🚧

Javascript editing

Web layer conditions rely on the event banner and attributes action = show and interaction = true / false. If you change this structure in the JS editor, the web layer won't work properly.

AttributeDescriptionExample
actionUser's action towards the banner. If there was none the value is just "show".click / subscribe / show / close
banner_nameCustom-given name of the banner.Subscription banner
banner_idAutomatically-generated ID of the banner.4sa5729971a4f992sj9
banner_typeTemplate or custom-given name of the type of a banner with certain properties.medium_rectangle
interactionInformation on whether the user interacted with the banner.true
category_listed_productsList of all product IDs in the category.["A1", "C3", "G5", "A2"]
category_1Top level category of products on the website where the banner can be found.Shoes
category_2Second level category of products on the website where the banner can be found.Trekking
category_3Third level category of products on the website where the banner can be found. (number of categories is not limited to 3)Ankle boots
categories_pathPath through the categories leading to the category page currently seen.Shoes > Trekking > Ankle boots
categories_idsList of IDs of all categories from the root until the selected category.["abc123","abc456","abc789"]
local_currencyCurrency the customer will use for the payment.USD, GBP, EUR
languageLanguage of website.en
domainDefault domain of your website.webshop.com
locationURL of the page with the banner.http://eshop.exponea.com/chaz-kangeroo-hoodie-banner.html
pathLast part of the URL of the page with the banner.chaz-kangeroo-hoodie-banner.html
deviceMobile device from which the user sees the page with the banner. If the visit was not through a mobile device then it is marked as "other".Iphone
osOperating system of the device through which the user sees the page with the banner.Windows
browserBrowser through which the the user sees the page with the banner.Chrome

values of the action attribute for a banner

ValueDescription
clickThe customer clicked on the promotional banner to see more about the offer.
subscribeThe customer filled the subscribe banner with their contact information and sent it.
showThe banner was shown to the customer.
closeThe customer closed the banner.

recommendation

recommendation happens when the customer is shown a recommendation box you had created. recommendation is considered to be a semi-custom event because you have to manually set up the tracking of a new custom-made recommendation while the recommendation templates provided are tracked automatically. Learn more about recommendations in our guide.

AttributeDescriptionExample
actionUser's action towards the banner. If there was none the value is just "show".serve / get / show / timeout / click
recommendation_idAutomatically-generated ID of the recommendation engine variant (model) used.4sa5729971a4f992sj9
recommendation_variant_idAutomatically-generated ID of the recommendation engine variant (model) used.cf_5729971a4f992sj9
product_idAutomatically-generated ID of a product from the recommendation box that was clicked on by the customer.abc123
product_idsList of automatically-generated IDs of the products shown in the recommendation.a262740, b256429, c270262, d248197
pricePrice of a product from the recommendation box that was clicked on by the customer.15
placementPlacement of the recommendation box rendering.homepage / product_detail / ...
ab_variantName of the particular recommendation variant.Variant A / Variant B / Control Group
variant_idAutomatically-generated ID of a particular variant of a product from the recommendation box that was clicked on by the customer.abc123small

values of the action attribute for a recommendation

ValueDescription
serveThe webpage requested information on the recommendation from the server.
getThe webpage received the information on the recommendation from the server and rendered the recommendation on the page. (The customer might still not have seen it, for example, if the box was located at the bottom and they did not scroll down the page enough)
show (often named wrapper_reach)The webpage received the information on the recommendation from the server and rendered the recommendation on the page AND the customer actually saw it.
timeoutThe requested recommendation was not returned by the servers to the webpage within the specified time period.
clickThe customer clicked on the recommendation box to see the recommended product.
closeThe customer closed the recommendation box.

📘

Efficient Engagement usage

When generated, custom events get procesed and stored, thus counting toward your Monthly Processed Events (MPE) and Maximum Events Storage (MES) covered by your contract. Learn how to optimize your MPE and MES in this best practices article to get the most out of your Engagement experience!