Skip to main content

Sales Insights (ECommerce)

Sales Insight has multiple premade analysis that are based on native events but also on the properties that are currently tracked. It allows you to send events at different steps of the purchase funnel to give you a detailed view from start to finish.

You'll first have the products impressions, the creation and evolution of the cart and its content to finally have a transaction.

note

These are examples, the property list can be changed to fit your needs. You can very well remove properties and add custom properties on top. Please note that the implementation in those examples represent best practices whenever you want to fill the premade analyses available in the Piano Analytics interfaces.

Product events

product.display

Mandatory property: product_id

Impression of a product on a given page. Aside from the product_id that is mandatory, this implementation is recommended at least to allow you to fill all of the premade analysis in the interface.

pa.sendEvent('product.display', {
'product_id' : 'LPTAX174', // mandatory
'product' : 'Laptop AX174',
'product_variant' : '8Go RAM',
'product_brand' : 'Laptop',
'product_discount' : false,
'product_placement' : 'banner',
'product_pricetaxincluded' : 1399.9,
'product_pricetaxfree' : 1120.9,
'product_stock' : true,
'product_category1' : 'Hardware',
'product_category2' : 'Computer',
'product_category3' : 'Gaming',
'product_category4' : 'Laptop',
});

product.page_display

Mandatory property: product_id

Impression of a product page. Aside from the product_id that is mandatory, this implementation is recommended at least to allow you to fill all of the premade analysis in the interface.

pa.sendEvent('product.page_display', {
'product_id' : 'LPTAX174', // mandatory
'product' : 'Laptop AX174',
'product_variant' : '8Go RAM',
'product_brand' : 'Laptop',
'product_discount' : false,
'product_placement' : 'banner',
'product_pricetaxincluded' : 1399.9,
'product_pricetaxfree' : 1120.9,
'product_stock' : true,
'product_category1' : 'Hardware',
'product_category2' : 'Computer',
'product_category3' : 'Gaming',
'product_category4' : 'Laptop',
});

product.add_to_cart

Mandatory properties: product_id

Add a product to a cart. Aside from the product_id that is mandatory, this implementation is recommended at least to allow you to fill all of the premade analysis in the interface.

Adding the cart.creation event is only needed whenever the 'product.add_to_cart' creates a new cart.

pa.sendEvents([
{
name: "product.add_to_cart",
data: {
cart_id: "LAPW221C",
product_id: "LPTAX174", // mandatory property
product: "Laptop AX174",
product_variant: "8Go RAM",
product_brand: "Laptop",
product_discount: false,
product_placement: "banner",
product_pricetaxincluded: 1399.9,
product_pricetaxfree: 1120.9,
product_stock: true,
product_category1: "Hardware",
product_category2: "Computer",
product_category3: "Gaming",
product_category4: "Laptop",
product_quantity: 1,
product_cartcreation: true,
},
},
{
name: "cart.creation", // Only if product_cartcreation: true
data: {
cart_id: "LAPW221C", // mandatory property
cart_currency: "EUR",
cart_turnovertaxincluded: 1399.9,
cart_turnovertaxfree: 1120.9,
cart_quantity: 1,
cart_nbdistinctproduct: 1,
},
},
]);

product.remove_from_cart

Mandatory properties: product_id

Remove a product from a cart. Aside from the product_id that is mandatory, this implementation is recommended at least to allow you to fill all of the premade analysis in the interface.

pa.sendEvent('product.remove_from_cart', {
'cart_id' : 'LAPW221C',
'product_id' : 'LPTAX174', // mandatory
'product' : 'Laptop AX174',
'product_variant' : '8Go RAM',
'product_brand' : 'Laptop',
'product_discount' : false,
'product_placement' : 'banner',
'product_pricetaxincluded' : 1399.9,
'product_pricetaxfree' : 1120.9,
'product_stock' : true,
'product_category1' : 'Hardware',
'product_category2' : 'Computer',
'product_category3' : 'Gaming',
'product_category4' : 'Laptop',
'product_quantity' : 1,
});

Cart events

cart.creation

Mandatory property: cart_id

This event can be used alongside others or as a standalone event whenever a new cart is created.

pa.sendEvent('cart.creation', {
'cart_id' : 'LAPW221C', // mandatory
'cart_currency' : 'EUR',
'cart_turnovertaxincluded' : 1399.9,
'cart_turnovertaxfree' : 1120.9,
'cart_quantity' : 1,
'cart_nbdistinctproduct' : 1,
});

cart.display

Mandatory property: cart_id

This event can be sent everytime the cart page is loaded.

pa.sendEvent('cart.display', {
'cart_id' : 'LAPW221C', // mandatory
'cart_currency' : 'EUR',
'cart_turnovertaxincluded' : 1399.9,
'cart_turnovertaxfree' : 1120.9,
'cart_quantity' : 1,
'cart_nbdistinctproduct' : 1,
});

cart.update

Mandatory property: cart_id

This event can be sent everytime the cart gets updated. It is meant to send the latest known state of the cart's value.

pa.sendEvent('cart.update', {
'cart_id' : 'LAPW221C', // mandatory
'cart_currency' : 'EUR',
'cart_turnovertaxincluded' : 1399.9,
'cart_turnovertaxfree' : 1120.9,
'cart_quantity' : 1,
'cart_nbdistinctproduct' : 1,
});

cart.delivery

Mandatory property: cart_id

This event can be used to measure the delivery method selection step. The shipping properties in the example are not mandatory but can be sent on this step if known at this moment. Otherwise it can be done in the cart.payment step

pa.sendEvent('cart.delivery', {
'cart_id' : 'LAPW221C', // mandatory
'cart_currency' : 'EUR',
'cart_turnovertaxincluded' : 1399.9,
'cart_turnovertaxfree' : 1120.9,
'cart_quantity' : 1,
'cart_nbdistinctproduct' : 1,
'shipping_delivery' : '1Express',
'shipping_costtaxincluded' : 11.99,
'shipping_costtaxfree' : 10.99,
});

cart.payment

Mandatory property: cart_id

This event can be used to measure the payment step. The payment method can be sent at this moment if known.

pa.sendEvent('cart.payment', {
'cart_id' : 'LAPW221C', // mandatory
'cart_currency' : 'EUR',
'cart_turnovertaxincluded' : 1399.9,
'cart_turnovertaxfree' : 1120.9,
'cart_quantity' : 1,
'cart_nbdistinctproduct' : 1,
'shipping_delivery' : 'Express',
'shipping_costtaxincluded' : 11.99,
'shipping_costtaxfree' : 10.99,
'payment_mode' : 'Credit card',
});

cart.awaiting_payment and product.awaiting_payment

Mandatory property: cart_id and product_id and cart_version

These events can be used whenever the transaction needs to be validated by a third party (3D Secure for example). The products are not mandatory but will allow you to see the different articles in the cart.

You will then be able to validate the cart, once you get the response, through a transaction event (can also be done server-side).

pa.sendEvents([
{
name: "cart.awaiting_payment",
data: {
cart_id: "LAPW221C", // mandatory property
cart_version: "VER211SQ", // mandatory property
cart_currency: "EUR",
cart_creation_utc: 1666196008,
cart_turnovertaxincluded: 1399.9,
cart_turnovertaxfree: 1120.9,
cart_quantity: 1,
cart_nbdistinctproduct: 1,
shipping_delivery: "Express",
shipping_costtaxincluded: 11.99,
shipping_costtaxfree: 10.99,
},
},
{
name: "product.awaiting_payment",
data: {
cart_id: "LAPW221C", // mandatory property
cart_version: "VER211SQ", // mandatory property
product_id: "LPTAX174", // mandatory property
product: "Laptop AX174",
product_variant: "8Go RAM",
product_brand: "Laptop",
product_discount: false,
product_placement: "banner",
product_pricetaxincluded: 1399.9,
product_pricetaxfree: 1120.9,
product_stock: true,
product_category1: "Hardware",
product_category2: "Computer",
product_category3: "Gaming",
product_category4: "Laptop",
product_quantity: 1,
},
},
]);
note

Using this method, please note that the server-side confirmation needs to happen under 24h. The confirmation event will be excluded after this time limit. If needed, the confirmation_delay property can be added to your awaiting_payment events. Should this property be tagged with a relevant value, the limit can be extended from 24h to up to 72h.

Server-side events

Server-side transaction confirmation

Mandatory property: cart_id and transaction_id and offsite_confirmation:true

This server-side request allows you to validate a cart that was previously awaiting payment.

https://<xxxxxxx>.pa-cd.com/hit.xiti?s=123456789&events=[{"name":"transaction.confirmation","data":{"cart_id":"XXXXX",
"transaction_id":"XXXXX", "offsite_confirmation":true}}]&rdt=off

Transaction events

transaction.confirmation and product.purchased

Mandatory property: product_id and transaction_id

These events are sent whenever a transaction is made. On this example, the cart and the products are validated. The cart_id is not mandatory for these events.

pa.sendEvents([
{
name: "transaction.confirmation",
data: {
cart_id: "LAPW221C",
cart_currency: "EUR",
cart_turnovertaxincluded: 1399.9,
cart_creation_utc: 1666196008,
cart_turnovertaxfree: 1120.9,
cart_quantity: 1,
cart_nbdistinctproduct: 1,
shipping_delivery: "Express",
shipping_costtaxincluded: 11.99,
shipping_costtaxfree: 10.99,
transaction_id: "TR221SI", // mandatory property
transaction_promocode: ["REDUC10"],
transaction_status: "charged",
transaction_firstpurchase: true,
payment_mode: "Credit card",
},
},
{
name: "product.purchased",
data: {
cart_id: "LAPW221C",
product_id: "LPTAX174", // mandatory property
product: "Laptop AX174",
product_variant: "8Go RAM",
product_brand: "Laptop",
product_discount: false,
product_placement: "banner",
product_pricetaxincluded: 1399.9,
product_pricetaxfree: 1120.9,
product_stock: true,
product_category1: "Hardware",
product_category2: "Computer",
product_category3: "Gaming",
product_category4: "Laptop",
product_quantity: 1,
payment_mode: "Credit card",
transaction_id: "TR221SI", // mandatory property
transaction_promocode: ["REDUC10"],
},
},
{
name: "product.purchased",
data: {
cart_id: "LAPW221C",
product_id: "LPTAX176", // mandatory property
product: "Laptop AX176",
product_variant: "16Go RAM",
product_brand: "Laptop",
product_discount: false,
product_placement: "banner",
product_pricetaxincluded: 1599.9,
product_pricetaxfree: 1220.9,
product_stock: true,
product_category1: "Hardware",
product_category2: "Computer",
product_category3: "Gaming",
product_category4: "Laptop",
product_quantity: 1,
payment_mode: "Credit card",
transaction_id: "TR221SI", // mandatory property
transaction_promocode: ["REDUC10"],
},
},
]);

Annexes

Product properties

PropertyDescriptionTypeMandatoryExample
product_idIDstringYes'LPTAX174'
productLabelstring'Laptop AX174'
product_variantVariantstring'8Go RAM'
product_brandBrandstring'Loptap'
product_discountDiscounted product?booleanfalse
product_placementWhere is the product visible from?string'banner'
product_pricetaxincludedPrice tax includedfloat1399.90
product_pricetaxfreePrice tax freefloat1120.90
product_stockProduct in stock?booleantrue
product_quantityQuantityint1
product_category1Level 1 categorystring'Hardware'
product_category2Level 2 categorystring'Computer'
product_category3Level 3 categorystring'Gaming'
product_category4Level 4 categorystring'Laptop'
product_cartcreationCart created by this product addition?booleanfalse

Cart properties

PropertyDescriptionTypeMandatoryExample
cart_idIDstringYes'HW-8892'
cart_currencyCurrency (ISO 4217)string'EUR'
cart_turnovertaxincludedTurnover tax includedfloat2900.00
cart_turnovertaxfreeTurnover tax freefloat2340.50
cart_creation_utcCart creation date (timestamp UTC in seconds)int1501065673
cart_quantityNumber of productsint3
cart_nbdistinctproductNumber of distinct productsint2
cart_versionWhen updating the cart awaiting payment (adding/removing a product), it will be necessary to generate a new unique version identifier (cart_version) associated with the cart (cart_id). This is necessary when using pending carts/products (cart.awaiting_payment / product.awaiting_payment)string'v1'
confirmation_delayThis property should be used if the default confirmation window needs to be extended, up to 72h. This is necessary when using pending carts/products (cart.awaiting_payment / product.awaiting_payment)int72

Transaction properties

PropertyDescriptionTypeMandatoryExample
transaction_idIDstringYes'29984'
transaction_promocodePromo code listarray of string['BLACKFRIDAY', 'VIP']
transaction_firstpurchaseFirst purchase of the customer?booleantrue
transaction_statusTransaction statusstring'charged'

Shipping properties

PropertyDescriptionTypeMandatoryExample
shipping_deliveryShipping typestring'Express'
shipping_costtaxincludedShipping cost tax includedfloat10.50
shipping_costtaxfreeShipping cost tax freefloat8.00

Payment properties

PropertyDescriptionTypeMandatoryExample
payment_modePayment modestring'Credit card'

Available currencies

Available currencies
CodeName
AFNAfghan Afghani
ALLAlbanian Lek
DZDAlgerian Dinar
AOAAngolan Kwanza
ARSArgentine Peso
AMDArmenian Dram
AWGAruban Florin
AUDAustralian Dollar
AZNAzerbaijani Manat
BSDBahamian Dollar
BHDBahraini Dinar
BDTBangladeshi Taka
BBDBarbadian Dollar
BYNBelarusian Ruble
BYRBelarusian Ruble
BZDBelize Dollar
BMDBermudian Dollar
BTNBhutanese Ngultrum
BOBBolivian Boliviano
BAMBosnia and Herzegovina Convertible Mark
BWPBotswana Pula
BRLBrazilian Real
GBPBritish Pound
BNDBrunei Dollar
BGNBulgarian Lev
BIFBurundian Franc
KHRCambodian Riel
CADCanadian Dollar
CVECape Verdean Escudo
KYDCayman Islands Dollar
XAFCentral African Cfa Franc
XPFCfp Franc
CLPChilean Peso
CNYChinese Renminbi Yuan
CNHChinese Renminbi Yuan Offshore
COPColombian Peso
KMFComorian Franc
CDFCongolese Franc
CRCCosta Rican Colón
HRKCroatian Kuna
CUCCuban Convertible Peso
CZKCzech Koruna
DKKDanish Krone
DJFDjiboutian Franc
DOPDominican Peso
XCDEast Caribbean Dollar
EGPEgyptian Pound
EEKEstonian Kroon
ETBEthiopian Birr
EUREuro
FKPFalkland Pound
FJDFijian Dollar
GMDGambian Dalasi
GELGeorgian Lari
GHSGhanaian Cedi
GIPGibraltar Pound
XAUGold (Troy Ounce)
GTQGuatemalan Quetzal
GGPGuernsey Pound
GNFGuinean Franc
GYDGuyanese Dollar
HTGHaitian Gourde
HNLHonduran Lempira
HKDHong Kong Dollar
HUFHungarian Forint
ISKIcelandic Króna
INRIndian Rupee
IDRIndonesian Rupiah
IQDIraqi Dinar
IMPIsle of Man Pound
ILSIsraeli New Sheqel
JMDJamaican Dollar
JPYJapanese Yen
JEPJersey Pound
JODJordanian Dinar
KZTKazakhstani Tenge
KESKenyan Shilling
KWDKuwaiti Dinar
KGSKyrgyzstani Som
LAKLao Kip
LVLLatvian Lats
LBPLebanese Pound
LSLLesotho Loti
LRDLiberian Dollar
LYDLibyan Dinar
LTLLithuanian Litas
MOPMacanese Pataca
MKDMacedonian Denar
MGAMalagasy Ariary
MWKMalawian Kwacha
MYRMalaysian Ringgit
MVRMaldivian Rufiyaa
MROMauritanian Ouguiya
MURMauritian Rupee
MXNMexican Peso
MDLMoldovan Leu
MNTMongolian Tögrög
MADMoroccan Dirham
MZNMozambican Metical
MMKMyanmar Kyat
NADNamibian Dollar
NPRNepalese Rupee
ANGNetherlands Antillean Gulden
TWDNew Taiwan Dollar
NZDNew Zealand Dollar
NIONicaraguan Córdoba
NGNNigerian Naira
NOKNorwegian Krone
OMROmani Rial
PKRPakistani Rupee
XPDPalladium
PABPanamanian Balboa
PGKPapua New Guinean Kina
PYGParaguayan Guaraní
PENPeruvian Sol
PHPPhilippine Peso
XPTPlatinum
PLNPolish Złoty
QARQatari Riyal
RONRomanian Leu
RUBRussian Ruble
RWFRwandan Franc
SHPSaint Helenian Pound
SVCSalvadoran Colón
WSTSamoan Tala
STDSão Tomé and Príncipe Dobra
SARSaudi Riyal
RSDSerbian Dinar
SCRSeychellois Rupee
SLLSierra Leonean Leone
XAGSilver (Troy Ounce)
SGDSingapore Dollar
SKKSlovak Koruna
SBDSolomon Islands Dollar
SOSSomali Shilling
ZARSouth African Rand
KRWSouth Korean Won
LKRSri Lankan Rupee
SDGSudanese Pound
SRDSurinamese Dollar
SZLSwazi Lilangeni
SEKSwedish Krona
CHFSwiss Franc
TJSTajikistani Somoni
TZSTanzanian Shilling
THBThai Baht
TOPTongan Paʻanga
TTDTrinidad and Tobago Dollar
TNDTunisian Dinar
TRYTurkish Lira
TMTTurkmenistani Manat
TMMTurkmenistani Manat
UGXUgandan Shilling
UAHUkrainian Hryvnia
CLFUnidad de Fomento
AEDUnited Arab Emirates Dirham
UYUUruguayan Peso
USDUS Dollar
UZSUzbekistan Som
VUVVanuatu Vatu
VEFVenezuelan Bolívar
VESVenezuelan Bolívar Soberano
VNDVietnamese Đồng
XOFWest African Cfa Franc
YERYemeni Rial
ZMKZambian Kwacha
ZMWZambian Kwacha
ZWDZimbabwean Dollar