Capture a purchase event

This is for:

Developer

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 user to checkout (or purchase) the items in their cart from the online sporting goods store Barca Sports, which contains product specific information.

Barca purchase event

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', { 1
   'id': 'SP01014_00003',
   'name': 'Seakayak Blue',
   'category': 'Canoes & Kayaks/Kayaks/Sea Kayaks',
   'price': 1400,
   'quantity': 1 2
});

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

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

coveoua('send', 'event'); 5
1 Add product data payload
2 The number of product units purchased
3 Set the action type
4 The currencyCode can either be set in the product data payload or as a global field when initializing the analytics library
5 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 leverage them. 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

id

Required

check

check

check

check

category

Required

check

check

check

check

quantity

Required

check

check

check

check

price

Required

check

check

check

check

name

Required

check

brand

Recommended

check

check

check

check

group1

Recommended

check

check

check

check

variant1

Recommended

check

check

check

check

  1. 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 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 "productid": "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 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.

The following table lists the fields sent along with the event and the solutions that leverage them. 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

id

Required

check

check

check

check

revenue

Required

check

check

check

check

currencyCode

Required

check

check

check

check

tax

Optional

check

affiliation

Optional

check

shipping

Optional

check

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:

Barca purchase event network browser

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

Note
  • If there are different checkout paths, the user should verify the purchase event is sent on all of them.

  • If multiple products are purchased, ensure the’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. 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.

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

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 exact SKU 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

For a complete list of parameters that can be sent in the event, see ​​Log Collect events.

Note

Parameters such as pr1ca can be more generally referred to as prNca, where N represents an interaction involving more than one product.