Capture a purchase event

This is for:

Developer

In this article

When to send a purchase event
Capture a purchase event using Coveo UA library commands
Purchase event validation

This article explains how to capture when a user completes a purchase as part of the user journey, and how to send the information to Coveo Usage Analytics (Coveo UA) along with the product information using the Coveo UA library.

When to send a purchase event

This event comes after the capture cart event and is sent when the user completes a purchase. The event can contain multiple products. For example, if two products were purchased at once, both would be grouped in the same purchase event.

The following image shows the action taken by a visitor to checkout (or purchase) the items in their cart from the online sporting goods store Barca Sports, which contains product specific information.

Capture a purchase event using Coveo UA library commands

When the user completes a purchase, you must run the following JavaScript code which contains Coveo UA library commands.

coveoua('ec:addProduct', { 
   'id': 'SP01014_00003',
   'name': 'Seakayak Blue',
   'category': 'Canoes & Kayaks/Kayaks/Sea Kayaks',
   'price': 1400, 
   'quantity': 1 
});

coveoua('ec:addProduct', { ... }); // add for additional products

coveoua('ec:setAction', 'purchase', { 
    'id': 'a5054ff6-cc90-48e5-a489-5df65522f79f-1692294769825',
    'revenue': '1470.00',
});

coveoua('send', 'event');

	Add product data payload
	The number of product units purchased
	Set the action type
	The `currencyCode` for the item’s price is set as a global field when initializing the Coveo UA library
	Send the event

Add product data payload

The ec:addProduct command includes the relevant product data in the event you’re about to send. In this case the product dataset contains the product id, name, category, price and quantity product data fields.

For more information, refer to the Coveo UA command list.

Product dataset requirements

The following table lists the fields sent along with the event and the solutions that use these fields. Search, Listings, and Recs columns refer to whether the ML that powers those solutions needs those data points. The Reporting column is for general reporting purposes that encompasses all solutions.

Field Priority Search Listings Recs Reporting

Required

Required

Required

Required

Required

Recommended

group¹

Recommended

variant¹

Recommended

Only needed when you need to setup ML to either recommend at the group or variant level.

Note

When you structure your items with product grouping, ensure that you add the group field to the product dataset in all sent events.

Using the recommended approach for product data, you would find, for example, "ec_item_group_id": "001" and "ec_product_id": "001-red" in the product dataset payload. The group can be represented by any string as long as it’s consistent. In other words, the same value (in this case, 001) is used on the different products in the group.

Set the action type

The ec:setAction command is used to specify which action type is to be performed on this data. In the case above, we want to indicate that it relates to a purchase. For all transaction fields, see Transaction fields reference.

Field Priority Search Listings Recs Reporting

Required

Required

Optional

Optional

Optional

Send the event

Finally, the send command sends an event with a given payload to the Coveo analytics endpoint.

Purchase event validation

When the purchase event is logged, use the developer tools for client-side request verification to inspect your visit to ensure everything done using the UI is captured as a set of consistent and coherent events. This must occur after the implementation is applied.

Inspect the purchase event through the network browser and ensure it satisfies the following:

1 The client ID (cid) is consistent with other events sent on the page.

2 The currency matches what’s being displayed to the visitor.

3 Confirm the event is a purchase (pa).

Notes

If there are different checkout paths, the user should verify the purchase event is sent on all of them.
If multiple products are bought, ensure they’re all logged in the purchase event.

4 Category values should use / to represent hierarchies and use | to represent multiple values.

5 The product ID (pr1id) matches what’s set in the catalog entity. Similarly, if group and variant are being sent, they must also match.

6 Contains transaction specific details, such as the unique transaction id and total revenue.

After a successful transaction, if a visitor revisits the transaction confirmation page after 30 days, a second purchase event with the same transaction id will be sent.

However, if the visitor revisits the transaction confirmation page within 30 days, the purchase event is deduplicated, meaning that the transaction won’t be counted twice.

Event field data mapping

The following table shows how the client-side fields are mapped to parameters in the analytics request sent to Coveo UA. You need to ensure this information is properly passed in the payload.

Field name Description Parameter

Field name	Description	Parameter
`id` (product)	Identifier for the base product	`pr1id`
`category`	The product category	`pr1ca`
`price`	The price shown to the user (including discounts)	`pr1pr`
`brand`	The product brand	`pr1br`
`name`	The product name	`pr1nm`
`group`	The product group ID	`pr1group`
`variant`	The unique identifier of the variant selected	`pr1va`
`quantity`	Quantity added or removed	`pr1qt`
`id` (transaction)	An identifier used to track a specific transaction	`ti`
`currencyCode`	The currency of the product being purchased	`cu`
`revenue`	The total value of the transaction, including taxes and shipping	`tr`
`tax`	The total transaction tax	`tt`
`affiliation`	The store where a transaction took place	`ta`
`shipping`	The transaction shipping cost	`ts`

id (product)

Identifier for the base product

The product category

The price shown to the user (including discounts)

pr1pr

brand

The product brand

pr1br