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 the Web tracking article.

purchase

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

Attribute
Description
Example

purchase_id

Automatically-generated ID of the purchase.

123456a

purchase_status

Status of the purchase.

success / refund

purchase_source_type

Type of the source from which the purchase was done.

online / store

purchase_source_name

Name of the source from which the purchase was done.

domain.com / Corner Store 1st Street, ...

product_list

List of all purchased products, their quantities and other required properties.

[ {"product_id": "abc123", "quantity":1} ]

product_ids

List of IDs of all purchased products.

[ "abc123", "abc456", "abc789" ]

total_price

Total price paid by the customer in the reference currency including tax and shipping.

24

total_price_without_tax

Total price paid by customer in reference currency including shipping but not the tax.

20

total_price_local_currency

Total price paid by the customer in the currency they used for the payment.

2

local_currency

Currency the customer used for the payment.

USD, GBP, EUR

total_quantity

Total quantity of the products purchased.

2

payment_type

Payment method.

bank transfer / online payment / cash / cod

shipping_type

Type of delivery.

courier / personally

shipping_company

Delivery company.

ups

shipping_cost

Price of the delivery.

69

shipping_country

Name of the country to which the products are delivered.

USA

shipping_city

Name of the city to which the products are delivered.

New York

tax_percentage

Sales tax expressed as a percentage.

20

tax_value

Sales tax expressed as money.

4

voucher_code

Code of the voucher used in this purchase.

KA54-548C

voucher_percentage

The discount rate conferred on the customer by the voucher expressed as a percentage.

10

voucher_value

The amount that the voucher subtracted from the prize of the purchase.

2

variant_list

List of all purchased variants, their quantities and other required properties.

[ {"variant_id": "abc123", "quantity":1} ]

variant_ids

List of IDs of all purchased variants.

[ "abc123", "abc456", "abc789" ]

language

Language of website from which the purchase was made.

en

location

URL of the page where the purchase event occurred.

domain

Default 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 will be rendered. There will be as many purchase_item events along with a single purchase event as there were items bought.

Attribute
Description
Example

purchase_id

Automatically-generated ID of the purchase.

123456a

purchase_status

Status of the purchase.

success / refund

purchase_source_type

Type of the source from which the purchase was done.

online / store

purchase_source_name

Name of the source from which the purchase was done.

domain.com / Corner Store 1st Street, ...

product_id

Automatically-generated ID of the product.

abc123

variant_id

Automatically-generated ID of the variant of the product that includes information about colour, size or materials.

abc123small

title

Item name that includes colour, size or materials if available.

Tassel Loafers in Navy Faux Sued

brand

Brand of the purchased item.

END.

category_id

Automatically-generated ID of the final category where the purchased product belongs.

abc123

price

Price of one unit of the item paid by the customer in the reference currency.

18

price_local_currency

Price of one unit of the item paid by the customer in the currency they used for the payment.

90

discount_percentage

In case of a discount, the discount rate used on the item expressed as a percentage.

10

discount_value

In case of a discount, the amount subtracted from the price of the product as a result of the discount.

2

original_price

Price of the item without a discount in a reference currency.

20

original_price_local_currency

Price of the item without a discount in a currency the customer used for the payment.

100

quantity

Quantity of the purchased products.

2

total_price

Total price paid by the customer in the reference currency including tax and shipping.

24

total_price_without_tax

Total price paid by the customer in reference currency including shipping but not the tax.

20

total_price_local_currency

Total price paid by the customer in the currency they used for the payment.

43

local_currency

Currency the customer used for the payment.

USD, GBP, EUR

tags

Custom tags for describing the item.

["new", "sales", "teen", "man"]

category_1

Top level category of products on the website where the item can be found.

Shoes

category_2

Second level category of products on the website where the item can be found.

Trekking

category_3

Third level category of products on the website where the item can be found. (number of categories is not limited to 3)

Ankle boots

categories_path

Path through the categories leading to the product.

Shoes > Trekking > Ankle boots

category_id

Automatically-generated ID of the final category where the purchased product belongs.

abc123

categories_ids

List of IDs of all categories from root until the final one where the purchased product belongs.

["abc123","abc456","abc789"]

language

Language of website from which the purchase was made.

en

location

URL of the page where the purchase event occurred.

domain

Default domain of your website.

webshop.com

cart_update

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

Attribute
Description
Example

action

Customer's action on the basket.

add / remove / empty

button_copy

Text of the button used for adding item to the cart.

Add / Purchase / Add to cart

page_type

Type of a page where cart contents changed.

product / homepage / category / page / checkout

product_id

Automatically-generated ID of the product added/removed.

abc123

variant_id

Automatically-generated ID of the variant of the product added/removed that includes information about colour, size or materials.

abc123small

title

Name of the item added/removed that includes colour, size or materials if available.

Tassel Loafers in Navy Faux Sued

brand

Brand of an item added/removed.

END.

price

Price of one unit of the item added/removed to be paid by the customer in the reference currency.

18

price_local_currency

Price 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_percentage

In case of a discount, the discount rate used on the item added/removed expressed as a percentage.

10

discount_value

In case of a discount, the amount subtracted from the price of the item added/removed as a result of the discount.

2

original_price

Price of the item added/removed without a discount in a reference currency.

20

original_price_local_currency

Price of the item added/removed without a discount in a currency the customer used for the payment.

100

product_list

List of all products in the cart after cart update.

[ {"product_id": "abc123", "quantity":1} ]

product_ids

List of IDs of all products in the cart after cart update.

[ "abc123", "abc456", "abc789" ]

total_quantity

Total quantity of the products in the cart.

2

total_price

Total price of the products in the cart in the reference currency.

24

total_price_without_tax

Total price of items in the cart in the reference currency including the shipping but not the tax.

20

total_price_local_currency

Total price of items in the cart in the currency the customer will use for the payment.

43

local_currency

Currency the customer will use for the payment.

USD, GBP, EUR

tags

Custom tags for describing the item.

["new", "sales", "teen", "man"]

category_1

Top level category of products on the website where the item can be found.

Shoes

category_2

Second level category of products on the website where the item can be found.

Trekking

category_3

Third level category of products on the website where the item can be found.

Ankle boots

categories_path

Path through the categories leading to the product.

Shoes > Trekking > Ankle boots

category_id

Automatically-generated ID of the final category from which the cart was updated.

abc123

categories_ids

List of IDs of all categories from root until the final one from which the cart was updated.

["abc123","abc456","abc789"]

variant_list

List of all variants of the items in the cart, their quantities and other required properties.

[ {"variant_id": "abc123", "quantity":1} ]

variant_ids

List of IDs of all variants of the items in the cart.

[ "abc123", "abc456", "abc789" ]

language

Language of website where the cart was updated.

en

location

URL of the page where the cart_update event occurred.

domain

Default domain of your website.

webshop.com

checkout

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

Attribute
Description
Example

step_number

Number of the step of the checkout process.

1

step_title

Title of the step of the checkout process.

Shipping / Personal information / Completed

product_list

List of all products in the cart.

[ {"product_id": "abc123", "quantity":1} ]

product_ids

List of IDs of all products in the cart.

[ "abc123", "abc456", "abc789" ]

payment_type

Payment method.

bank transfer / online payment / cash / cod

total_price

Total price of the products to be purchased.

24

total_price_without_tax

Total price of items in the cart in the reference currency including the shipping but not the tax.

20

total_price_local_currency

Total price of items in the cart in the currency the customer will use for the payment.

43

local_currency

Currency the customer will use for the payment.

USD, GBP, EUR

total_quantity

Total quantity of the products to be purchased.

2

tax_value

Sales tax expressed as money.

24

tax_percentage

Sales tax expressed as a percentage.

20

shipping_type

Type of delivery.

courier / personally

shipping_company

Delivery company.

ups

shipping_cost

Price of shipping.

69

shipping_country

Name of the country to which the products will be delivered.

USA

shipping_city

Name of the city to which the products will be delivered.

New York

voucher_code

Code of the voucher to be used in this purchase.

KA54-548C-TEST

voucher_percentage

The discount rate conferred on the customer by the voucher expressed as a percentage.

10

voucher_value

The amount that the voucher will subtract from the prize of the purchase.

2

variant_list

List of all variants of the items in the cart, their quantities and other required properties.

[ {"variant_id": "abc123", "quantity":1} ]

variant_ids

List of IDs of all variants of the items in the cart.

[ "abc123", "abc456", "abc789" ]

language

Language of website.

en

location

URL of the page where the checkout event occurred.

domain

Default domain of your website.

webshop.com

view_item

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

Attribute
Description
Example

product_id

Automatically-generated ID of the product.

abc123

variant_id

Automatically-generated ID of the variant of the viewed product that includes information about colour, size or materials.

abc123small

title

Name of the item viewed that includes colour, size or materials if available.

Tassel Loafers in Navy Faux Sued

brand

Brand of an item viewed.

END.

price

Price of one unit of the item viewed to be paid by the customer in the reference currency.

18

price_local_currency

Price of one unit of the item viewed by the customer in the currency listed on the website.

90

discount_percentage

In case of a discount, the discount rate used on the viewed item expressed as a percentage.

10

discount_value

In case of a discount, the amount subtracted from the price of the viewed item as a result of the discount.

2

original_price

Price of the viewed item without a discount in a reference currency.

20

original_price_local_currency

Price of the viewed item without a discount in the currency listed on the website.

100

local_currency

Currency the customer will use for the payment.

USD, GBP, EUR

stock_level

Number of the particular item in stock.

46

tags

Custom tags for describing the item.

["new", "sales", "teen", "man"]

category_1

Top level category of products on the website where the item can be found.

Shoes

category_2

Second level category of products on the website where the item can be found.

Trekking

category_3

Third level category of products on the website where the item can be found. (number of categories is not limited to 3)

Ankle boots

categories_path

Path through the categories leading to the product.

Shoes > Trekking > Ankle boots

category_id

Automatically-generated ID of the final category where the viewed product belongs.

abc123

categories_ids

List of IDs of all categories from root until the final where the viewed item belongs.

["abc123","abc456","abc789"]

language

Language of website.

en

location

URL of the page where the view_item event occurred.

domain

Default domain of your website.

webshop.com

view_category

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

Attribute
Description
Example

category_id

Automatically-generated ID of the viewed category.

abc123

category_name

Name of the category.

Shoes

category_listed_products

List of all product IDs in the category.

["A1", "C3", "G5", "A2"]

category_1

Either the top level category of products preceding the currently viewed category or the currently viewed category.

Shoes

category_2

Either the second level category of products preceding the currently viewed category or the currently viewed category.

Trekking

category_3

Either 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_path

Path through the categories leading to the category page currently seen.

Shoes > Trekking > Ankle boots

categories_ids

List of IDs of all categories from the root until the selected category.

["abc123","abc456","abc789"]

local_currency

Currency the customer will use for the payment.

USD, GBP, EUR

language

Language of website.

en

location

URL of the page where the view_category event occurred.

domain

Default domain of your website.

webshop.com

consent

Attributes of the consent can be found in the 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. More on web layers

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.

Attribute
Description
Example

action

User's action towards the banner. If there was none the value is just "show".

banner_name

Custom-given name of the banner.

Subscription banner

banner_id

Automatically-generated ID of the banner.

4sa5729971a4f992sj9

banner_type

Template or custom-given name of the type of a banner with certain properties.

medium_rectangle

interaction

Information on whether the user interacted with the banner.

true

category_listed_products

List of all product IDs in the category.

["A1", "C3", "G5", "A2"]

category_1

Top level category of products on the website where the banner can be found.

Shoes

category_2

Second level category of products on the website where the banner can be found.

Trekking

category_3

Third level category of products on the website where the banner can be found. (number of categories is not limited to 3)

Ankle boots

categories_path

Path through the categories leading to the category page currently seen.

Shoes > Trekking > Ankle boots

categories_ids

List of IDs of all categories from the root until the selected category.

["abc123","abc456","abc789"]

local_currency

Currency the customer will use for the payment.

USD, GBP, EUR

language

Language of website.

en

domain

Default domain of your website.

webshop.com

location

URL of the page with the banner.

path

Last part of the URL of the page with the banner.

chaz-kangeroo-hoodie-banner.html

device

Mobile 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

os

Operating system of the device through which the user sees the page with the banner.

Windows

browser

Browser through which the the user sees the page with the banner.

Chrome

values of the action attribute for a banner

Value
Description

click

The customer clicked on the promotional banner to see more about the offer.

subscribe

The customer filled the subscribe banner with their contact information and sent it.

show

The banner was shown to the customer.

close

The 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. More on recommendations

Attribute
Description
Example

action

User's action towards the banner. If there was none the value is just "show".

recommendation_id

Automatically-generated ID of the recommendation engine variant (model) used.

4sa5729971a4f992sj9

recommendation_variant_id

Automatically-generated ID of the recommendation engine variant (model) used.

cf_5729971a4f992sj9

product_id

Automatically-generated ID of a product from the recommendation box that was clicked on by the customer.

abc123

product_ids

List of automatically-generated IDs of the products shown in the recommendation.

a262740, b256429, c270262, d248197

price

Price of a product from the recommendation box that was clicked on by the customer.

15

placement

Placement of the recommendation box rendering.

homepage / product_detail / ...

ab_variant

Name of the particular recommendation variant.

Variant A / Variant B / Control Group

variant_id

Automatically-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

Value
Description

serve

The webpage requested information on the recommendation from the server.

get

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

timeout

The requested recommendation was not returned by the servers to the webpage within the specified time period.

click

The customer clicked on the recommendation box to see the recommended product.

close

The customer closed the recommendation box.

Custom events


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.