Measure a Purchase

Ecommerce Developer Product Documentation

The following image is taken from a checkout confirmation page view of the fictitious online store, TheGym.

The user is about to complete a purchase and you want to measure this type of interaction. The data has only been set by the previous commands. It must be sent with either a pageview or with a generic event.

TheGym Checkout Confirmation Page View

Tracking Commerce Events Prerequisites

Before each event, ensure that you’ve:

How to Measure a Purchase

In the previous add to cart example, the user completes their purchase of a pair of ski boots.

First use the ec:addProduct command to include the relevant product data in the event you’re about to send:

coveoua('ec:addProduct', {
   'id': '037212201_DKBL',
   'name': 'backland 120',
   'brand': 'Atomic',
   'category': 'sport/ski_mountaineering/boots',
   'price': 447.20,
   'variant': '037212201_DKBL_22',
   'quantity': 1
});

To include multiple products one must add ec:addProduct for each item:

coveoua('ec:addProduct', {
   'id': '037212201_DKBL',
   'name': 'backland 120',
   'brand': 'Atomic',
   'category': 'sport/ski_mountaineering/boots',
   'price': 447.20,
   'variant': '037212201_DKBL_22',
   'quantity': 1
});
coveoua('ec:addProduct', {
   'id': '034177201_YB',
   'name': 'Specter 2.0',
   'brand': 'la_sportiva',
   'category': 'sport/ski_mountaineering/boots',
   'price': 423.15,
   'variant': '034177201_YB_22',
   'quantity': 2
});
Note

When you structure your items with product grouping, ensure you add the group field to the product dataset. This will send all related items in the analytics payload.

You then use the ec:setAction command to specify that the action done on this data is a product purchase:

coveoua('ec:setAction', 'purchase', {
    'id': 'transaction-1234',
    'affiliation': 'TheGym',
    'revenue': '467.20',
    'tax': '42.47',
    'shipping': '20.00'
});

Finally, you use the send command to send the event to Coveo UA:

If Then

The purchase action and product information is added before the pageview event is sent

There’s no need to send the pageview event. The pageview event you previously configured on the page will contain the action and product information.

The user interaction didn’t open a new page

Manually send the purchase action with a generic event.

Transaction Fields Reference

Global Fields Reference

User Fields Reference

Users fields are related to the current user.

userId (String)

Example: myuser@mycompany.com

Important

Before using the userId field, see User Authentication.

currencyCode (String)

The currency code is a three-letter code that identifies the user’s currency.

The code follows the ISO 4217 standard.

Example: CAD

anonymizeIp (Boolean)

Use this field to anonymize the IP address by removing the last subnet of the current user’s IP address. Coveo will never store unencrypted IPs, even when this setting is set to false.

loyaltyCardId (String)

A unique identifier provided to a returning user.

loyaltyTier (String)

A level of membership where users receive perks and benefits depending on their rank.

Example: Platinum

thirdPartyPersona (String)

This represents additional market segmentation based on user characteristics (demographics, interests, needs, or location) which aren’t created by Coveo Machine Learning. When you already have a set of segments for your users, enter the information in this field.

companyName (String)

The name of a specific company for business-to-business sales.

favoriteStore (String)

The primary store selected by a returning user.

storeName (String)

The name of the current store selected by the user.

userIndustry (String, Optional)

For business-to-business (B2B) environments that need to indicate which industry’s vertical structure the user belongs to (e.g., healthcare,technology, insurance).

userRole (String, Optional)

For business-to-business (B2B) environments that need to indicate the role or title of the current user (e.g., director, manager, specialist).

userDepartment (String, Optional)

For business-to-business (B2B) environments that need to indicate the department of the current user (e.g., IT, Design, Procurement, Sales).

businessUnit (String, Optional)

This field defines the current catalog in use. For a solution with multiple catalogs, we use the catalog passed in this field to separate reporting and machine learning between catalogs.

Page Fields Reference

Page fields are sent using the set command, or alongside a pageview event as shown in the following command:

coveoua('send', 'pageview', {
    page: '/mypage'
})

page (String)

The path portion of the page URL.

Example: /mycurrentpage

title (String)

The title of the page. The default value is retrieved from document.title.

Example: My Super Site

location (String)

The full URL of the page. The default value is retrieved from document.location.

Example: https://www.mysupersite.com/home === Global Custom Fields Reference

The custom field allows users to add additional custom values as an object. Everything in this field will be unfolded to the parent object and then sent to coveoua.

To set custom fields for the whole page, use the set command, passing the custom string as a second argument, and an object containing the desired key-value pairs as a third argument.

Example

On custom user data

  coveoua('set', 'custom',  {
    visitorAge: 18,
    rewardsMember: true
});
// sets the `custom` field for each top-level object

When you use the send command

coveoua('send', 'pageview');

The following data is sent to coveoua

visitorAge: 18,
rewardsMember: true

Product Data Fields Reference

Product Fields Reference

Product fields are set with the ec:addProduct command.

id (String, Required)

The SKU used to uniquely identify your product.

Example: 001-red

name (String, Optional)

Example: Very nice shoe

brand (String, Optional)

Example: Coveo

category (String, Optional)

Represents a grouping of products having particular shared characteristics.

Field format Examples

Single

"sport"

Hierarchical

"sport/hiking/apparel"

Multi-value

"sport/hiking/apparel|sport/climbing/apparel"

Ensure that you aren’t sending events that include breadcrumbs with temporary categories or events, such as sales or clearance items.

group (String, Optional)

Represents an ID that’s specific to an item that has multiple SKUs attached to it. This is useful if you only want one item per group to be recommended by the machine learning algorithms.

variant (String, Optional)

A string that defines the variant of the product.

Example: 001-red-8_wide

list (String, Optional)

The list containing the associated products. For an example of this parameter, see Measure Events on a Listing or Search Page.

price (Currency, Optional)

Example: 12.34

quantity (Numeric, Optional)

Example: 12

coupon (String, Optional)

The name of the coupon used on this specific product.

Example: PROMO-1234

position (Numeric, Optional)

The item’s position. For example, the first item displayed in a list should have position: 1.

Example: 2

Note

For products and impressions, only a position greater than or equal to 1 is valid. If position: 0 is passed, it’ll be removed and not sent through the API with the item.

Transaction Fields Reference

Transaction fields are set with coveoua('ec:setAction', <ACTION>)

id (String, Required)

An identifier used to track a specific transaction.

Example: transaction-1234

affiliation (String, Optional)

The store where a transaction took place. Sent when you want to link a purchase or refund to a specific store.

Example: Shoe Store

revenue (Currency, Optional)

The total value of the transaction, including taxes and shipping.

Example: 123.21

tax (Currency, Optional)

The total transaction tax.

Example: 8.23

shipping (Currency, Optional)

The transaction shipping cost.

Example: 5.00

coupon (String, Optional)

The name of the coupon used on the whole transaction.

Example: PROMO-FREE-SHIPPING-2020

Quote Fields Reference

Field references related to providing a quote to the user.

id (Numeric, Optional or required?)

An identifier used to track a specific transaction.

affiliation (String, Optional)

The store where a quote took place. Sent when you want to link a quote to a specific store.

Example: Shoe Store

Review Fields Reference

Review fields provide customers the opportunity to rate and comment on products they have purchased.

id (Numeric, Required)

An identifier used to track a specific transaction.

rating (Numeric, Optional)

A rating described on a numeric scale from 0 to 10.

Note

When using a different rating method, for example a review of 0 to 5 stars, ensure you convert the score to a 0 to 10 scale.

comment (String, Optional)

A written summary of a user’s experience with a product or service.

Product Data Custom Fields Reference

The custom field allows users to add additional custom values as an object. Everything in this field will be unfolded to the parent object and then sent to coveoua.

To set custom fields in a product impression, use the ec:addProduct command, and add a custom object containing the desired key-value pairs in your main product impression object.

Example

On custom product data, when you use the ec:addProduct command

  coveoua('ec:addProduct', {
    'id': '001-red',
    'name': 'A very nice pair of shoes',
    'brand': 'Coveo',
    'category': 'Running shoes',
    'price': 90.22,
    'variant': '001-red-8_wide',
    'custom' : {
      'onSale' : false
    }
});

When you use the send command

coveoua('send', 'event');

It will send the following data

id: '001-red',
name: 'A very nice pair of shoes',
brand: 'Coveo',
category: 'Running shoes',
price: 90.22,
variant: '001-red-8_wide',
onSale : false

Impression Data Field Reference

Product fields are set with the ec:addImpression command.

id (String, Required)

The SKU used to uniquely identify your product.

Example: 001-red

position (Numeric, Required)

The item’s position. For example, the first displayed in a list should have position: 1.

Example: 2

Note

For products and impressions, only a position greater than or equal to 1 is valid. If position: 0 is passed, it’ll be removed from the payload.

name (String, Optional)

Example: Very nice shoe

brand (String, Optional)

Example: Coveo

category (String, Optional)

Example: Shoe

variant (String, Optional)

A string that defines the variant of the product.

Example: 001-red-8_wide

list (String, Optional)

The list that the associated products belong to. For an example of this parameter, see Measure Events on a Listing or Search Page.

price (Currency, Optional)

Example: 12.34

Currency

Currency is a system of money in common use that’s utilized as a medium of exchange for the products or services that one wants to purchase. We currently accept a currency data type when it’s entered as an integer, a decimal value, or as a string.

Example: 1337.123456

The decimal point is a delimiter between the whole and fractional part of the currency amount. The number of decimal places allowed after the period is 6.

Any text surrounding the value, such as a currency symbol, will be removed before it’s sent to Coveo UA. For example, when €-20.00 is entered, only -20.00 is sent.

What's next for me?