E-commerce events
add_payment_info
This event signifies a user has submitted their payment information
Parameters (required and recommended)
payment_method
string
Yes
card
The chosen method of payment (see list of possible values below)
user
Yes
consent_categories
is the user's consents list and is mandatory to manage consents. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
revenue
number
No
16.00
Revenue (shipping price and taxes excluded) after discount.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
Example
cact('trigger','add_payment_info', {
payment_method: 'card',
revenue: 16.00,
currency: 'EUR',
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
add_shipping_info
This event signifies a user has submitted their shipping information.
Parameters
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
or value
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
shipping_tier
string
No
Ground
The shipping tier (e.g. Next-day
, Air`) selected for delivery of the purchased item.
Example
cact('trigger','add_shipping_info', {
value: 8.00,
currency: 'EUR',
coupon: 'promo',
shipping_tier: 'ups',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
add_to_cart
This event signifies that an item was added to a cart for purchase.
Parameters (required and recommended)
value
number
Yes*
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','add_to_cart', {
value: 8.00,
currency: 'EUR',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
add_to_wishlist
The event signifies that an item was added to a wishlist. Use this event to identify popular gift items in your app.
Parameters (required and recommended)
value
number
No
8.00
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','add_to_wishlist', {
value: 8.00,
currency: 'EUR',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
begin_checkout
This event signifies that a user has begun a checkout.
Parameters (required and recommended)
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
id
string
No
0_12345
Transaction id. Used as key for updates
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','begin_checkout', {
id: 'O_12345',
coupon: 'CHRISTMAS',
revenue: 16.00,
value: 20.33,
currency: 'EUR',
user: {
id: '12356',
email:'[email protected]'
},
items: [{
id: 'SKU_12345',
quantity: 1,
price: 9.99,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
colors: ['red'],
price: 9.99
}
}, {
id: 'SKU_12346',
quantity: 1,
price: 9.99,
variant: 'green',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12346',
name: 'Heart tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'girl',
brand: 'Jenyfion',
colors: ['blue','white'],
price: 9.99
}
}]
})
generate_lead
Log this event when a lead has been generated to understand the efficacy of your re-engagement campaigns.
Parameters (required and recommended)
value
number
No*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
id
string
No
Lead id
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','generate_lead', {
currency: 'EUR',
value: 9.99,
id: 'L_12345',
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
purchase
Fire this event when one or more items are purchased by a user.
Parameters (required and recommended)
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Tax associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
status
string
Yes
in_progress
Status of the conversion (see list of possible values below). Conversions with status "pending" are not included in default sum and counts aggregated on augmented user attributes feature
last_channel
string
No
display
The last channel just before the purchase.
last_source
string
No
google.com
The last source (referrer) just before the purchase.
Automatically added by cact API
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
Example
cact('trigger','purchase', {
id: 'O_12345',
coupon: 'CHRISTMAS',
revenue: 16.00,
value: 20.33,
shipping_amount: 3.33,
tax_amount: 3.20,
currency: 'EUR',
user: {
id: '12356',
email:'[email protected]'
},
items: [{
id: 'SKU_12345',
quantity: 1,
price: 9.99,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
colors: ['red'],
price: 9.99
}
}, {
id: 'SKU_12346',
quantity: 1,
price: 9.99,
variant: 'green',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12346',
name: 'Heart tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'girl',
brand: 'Jenyfion',
colors: ['blue','white'],
price: 9.99
}
}]
})
refund
Fire this event when a purchase was refund
Parameters (required and recommended)
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Shipping cost associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
items
No*
(*) items
is required for partial refunds but it can be omitted for full refunds.
Automatically added by cact API
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
Example
cact('trigger','refund', {
id: 'O_12345',
coupon: 'CHRISTMAS',
revenue: 16.00,
value: 20.33,
shipping_amount: 3.33,
tax_amount: 3.20,
currency: 'EUR',
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
})
remove_from_cart
This event signifies that an item was removed from a cart.
Parameters (required and recommended)
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','remove_from_cart', {
value: 8.00,
currency: 'EUR',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
select_item
This event signifies an item was selected from a list.
Parameters
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
items
Yes
The items for the event. The items
array is expected to have a single element, representing the selected item.
Example
cact('trigger','select_item', {
item_list_name: 'Related products',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
view_cart
This event signifies that a user viewed their cart.
Parameters (required and recommended)
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','view_cart', {
value: 8.00,
currency: 'EUR',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
view_item
This event signifies that some content was shown to the user. Use this event to manage the most popular items viewed.
Parameters (required and recommended)
revenue
number
Yes*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','view_item', {
value: 8.00,
currency: 'EUR',
items: [{
id: 'SKU_12345',
quantity: 1,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
view_item_list
Log this event when the user has been presented with a list of items of a certain category.
Parameters
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
user
Yes
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
Example
cact('trigger','view_item_list', {
item_list_name: 'Related products',
items: [{
id: 'SKU_12345',
quantity: 1,
price: 9.99,
variant: 'red',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12345',
name: 'Trex tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'boy',
brand: 'Lacoste',
colors: ['red'],
price: 9.99
}
}, {
id: 'SKU_12346',
quantity: 1,
price: 9.99,
variant: 'green',
coupon: 'CHRISTMAS',
discount: 1.99,
product:{
id: '12346',
name: 'Heart tshirt',
category_1: 'clothes',
category_2: 't-shirts',
category_3: 'girl',
brand: 'Jenny',
colors: ['blue','white'],
price: 9.99
}
}],
user: {
id: '12356',
email:'[email protected]',
consent_categories: [1,3]
}
});
- COMMON SCHEMAS -
Items
Parameters (required and recommended)
id
string
Yes
SKU_12345
The ID of an item.
If you don't have an item id, you can use the product id as value. This field is used as key for updates (ex : refund)
variant
string
No
red
The variant of the item.
list_position
number
No
1
The item's position in a list or collection.
discount
number
No
2.00
Monetary value of discount associated with a purchase
quantity
number
Yes
2
The quantity of the item.
affiliation
string
No*
DOWNLOAD
Required for most affiliation's destination.
coupon
string
No
CHRISTMAS
The coupon code associated with an item.
Product
Parameters (required and recommended)
id
string
Yes*
12345
The ID of the product (ex: in your product catalog database)
The item.id
and product.id
do not have to be different. If they are different, typically the product.id
is a database identifier, like 9714107479
and the item.id
is a public-facing identifier like SKU-12345
.
(*) If you have imported your product's catalog in the platform, the product.id
corresponds to the unique product id in the catalog and can be used with id expansion feature.
name
string
Yes
Trex
Product name
price
number
Yes
14.99
The price of the product
currency
string (ISO 4217)
No
EUR
Currency of the price
, in 3-letter ISO 4217 format.
If set, event-level currency
is ignored.
Multiple currencies per event is not supported. Each item should set the same currency.
category_1
string
No
T-Shirts
Product Category (context-specific). item_category2
through item_category5
can also be used if the product has many categories.
brand
string
No
Lacoste
Product brand
colors
Array[string]
No
[blue, white]
The color(s) of the product
size
string
No
128
Size of the article
User
When you send an event, it needs to carry enough information to identify which user made it. We can link events together using cookies. But destination partners require accurate identifiers to take actions.
id
and email
are usually the most useful parameters. Though some destination partners also use firstname
, lastname
, birthdate
, city
, ...
You won't always have all of those parameters. But it is recommended to send them as soon as you can during user's browsing.
Parameters (required and recommended)
id
string
No*
845454
User's main identifier (e.g. CRM id)
(*) required for many destinations and internal processing.
email
string
Yes*
Email (plain value)
(*) required for many destinations and internal processing. Not required if email_sha256
is provided
email_md5
string
No*
8eb1b52... (size 32)
Email, hashed using MD5 algorithm. Not required if email
is provided (see below)
email_sha256
string
No*
836f82d... (size 64)
Email, hashed using SHA-256 algorithm. Not required if email
is provided (see below)
firstname
string
No
John
First name
lastname
string
No
Doe
Last name
gender
string
No
m
Gender
f
for Femalem
for Male
birthdate
string
No
1970-01-01
Birth date, YYYY-MM-DD
format
city
string
No
Boston
City
state
string
No
Massachusetts
State
zipcode
string
No
02108
Zip code
consent_categories
Array
Yes
[1,2,3]
User's consent categories. Necessary to grant data sharing with destination partners. It is automatically filled from web sources if you use Commanders Act CMP.
About Hashing
In some cases, you won't be able to send a parameter plain value. It is either unavailable or restricted.
Thus it might be possible to send the hashed values. We currently accept 2 algorithm : md5
and sha256
.
Every user.<property>
can be sent under hashed format with algorithm suffix: _md5
or _sha256
(underscore followed by lowercase algorithm name)
Example :
{
user: {
email_md5: '8eb1b522f60d11fa897de1dc6351b7e8', // md5('[email protected]')
email_sha256: '836f82db99121b3481011f16b49dfa5fbc714a0d1b1b9f784a1ebbbf5b39577f', // sha256('[email protected]')
phone_md5: '60dd761f55cb17f0532c9fb1679e8ddd', // md5('+33612345678')
phone_sha256: '42d573cfc315801d4cd8eddd5416b416a0bf298b9b9e12d6b07442c91db42bd8', // sha256('+33612345678')
}
}
ℹ️ we only support hex (base16) encoding (i.e.: hashed values are carried by strings with [0-9a-f] characters) Other encodings are not supported yet
No need to send both plain and hashed values :
if you send plain value, the hashed values aren't necessary We can generate hashed values on server side using plain value
if you don't send plain value, then you should fill as much hashed values as possible Partners require different hash algorithms and without plain value, we can't generate any hash. That's why we need the exact hashed value
- ENUMERATED VALUE -
Payment methods
Enumerated Values for payment methods :
payment_method
by_invoice
payment_method
by_bank_transfer_in_advance
payment_method
card
payment_method
check_in_advance
payment_method
cod
payment_method
coupon
payment_method
direct_debit
payment_method
online_payment_system
payment_method
other
Purchase status
Enumerated Values for purchase status:
status
canceled
status
delivered
status
in_progress
status
partially_delivered
status
partially_returned
status
partially_shipped
status
pending_shipment
status
returned
status
shipped
status
pending
Last updated
Was this helpful?