---
title: Commerce UA API reference
slug: l29e0540
canonical_url: https://docs.coveo.com/en/l29e0540/
collection: coveo-for-commerce
source_format: adoc
---
# Commerce UA API reference

> **Important**
>
> We strongly recommend that all new Commerce implementations use the [Event Protocol](https://docs.coveo.com/en/o1n91230/) to log events.

## Coveo UA command list

The Coveo UA library provides a set of commands to send commerce events to Coveo and track user interactions.

[%header,cols="3"]
|===
|Commands
|Description
|Associated parameters

|`init`
|Initializes the Coveo UA JavaScript
|[`<COVEO_API_KEY_OR_SEARCH_TOKEN>`](https://docs.coveo.com/en/l2bf0354#user-authentication)
[`<ENDPOINT>`](https://docs.coveo.com/en/l2bf0354#coveo-ua-alternate-endpoints)

|`set`
|Sets the website context or user ID
|`custom`
`userId`
`currencyCode`

|`version`
|Returns the current version of the tracking library
|

|`ec:addProduct`
|Includes the relevant product data in the event you're about to send
|

|`ec:setAction`
|Specifies the action done on this data
|`add`
`remove`
`detail`
`purchase`
`click`

|`send`
|Sends an event with a given name and payload to the analytics endpoint
|`event`
|===

## 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](https://docs.coveo.com/en/l2bf0354#user-authentication).

#### `currencyCode` (string)

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

The code follows the [`ISO 4217`](https://en.wikipedia.org/wiki/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 (Coveo ML)](https://docs.coveo.com/en/188/).
When you already have a set of segments for your users, enter the information in this field.

#### `trackingId` (string)

> **Note**
>
> Available on version 2.28.15 of the [Coveo UA library](https://www.npmjs.com/package/coveo.analytics) and greater.

The value to identify which web property an event is related to.
This is a human-readable name you can use when sending analytics events.

```json
{
  ...
  "trackingId": "online_store",
  ...
}
```

See [Tracking ID](https://docs.coveo.com/en/l2bf0354#tracking-id) for more information.

#### `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)

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

#### `userRole` (string)

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

#### `userDepartment` (string)

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

#### `businessUnit` (string) - deprecated

> **Important**
>
> This field has been deprecated.
> You no longer need to send this data when logging analytics events.

This field defines the current [catalog entity](https://docs.coveo.com/en/3143/) in use.
For a solution with multiple catalog entities, Coveo uses the one passed in this field to separate reporting and machine learning between catalog entities.

### Page fields reference

> **Warning**
>
> The page view event has been deprecated and is no longer necessary to send.
> Unless you're creating custom reports using this event, you should stop sending it, as doing so will simplify your implementation.

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

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

#### `page` (string)

The path portion of the page URL that allows users to track pages for single page apps (SPA) and mobile apps.

To send the `page`, add the following line before sending the `pageview` event, for example:

```js
coveoua('set', 'page', window.location.pathname)
```

#### `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

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

When you use the `send` command

```js
coveoua('send', 'custom');
```

The following data is sent to `coveoua`:

```text
visitorAge: 18,
rewardsMember: true
```

## Product data fields reference

### Product fields reference

Product fields are set with the `ec:addProduct` command.

#### `id` (string)

The unique identifier of the product.
The value must match exactly, including case, the value of the [product identifier field](https://docs.coveo.com/en/n73f0502#define-a-unique-product-identifier) configured in the catalog entity.

> **Note**
>
> The product identifier field must be [mapped to the `permanentid` field](https://docs.coveo.com/en/n8of7021#map-to-permanentid), so the `pr1id` value must also match the `permanentid` field value.

Example: `001-red`

#### `name` (string)

Example: `Very nice shoe`

#### `brand` (string)

Example: `Coveo`

#### `category` (string)

Represents a grouping of products having particular shared characteristics.

[%header,cols="2"]
|===
|Field format
|Examples

|Single
|`"sport"`

|Hierarchical
|`"sport/hiking/apparel"`

|Multi-value
|`"sport/hiking/apparel\|sport/climbing/apparel"`
|===

When logging events, the Coveo Platform expects the `category` values to be sent in a different format than when [configuring `category` values for your products](https://docs.coveo.com/en/m53g7119/).

The format expected when uploading `category` values to your index is `|` for delimiting hierarchies and `;` for delimiting multiple values.
Whereas the format expected when logging events is `/` for delimiting hierarchies and `|` for delimiting multiple values.

When logging events, the Coveo Platform only requires the last level of the hierarchy to be sent.

For example, if you have a category defined in the index as `Canoes & Kayaks ; Canoes & Kayaks|Kayaks ; Canoes & Kayaks|Kayaks|Tandem Kayaks`, you only need to send `Canoes & Kayaks/Kayaks/Tandem Kayaks` in the event.

> **Important**
>
> Ensure that you aren't sending events that include breadcrumbs with temporary categories or events, such as `sales` or `clearance` items.

#### `group` (string)

In the context of [product grouping](https://docs.coveo.com/en/l78i2152/), this is a unique identifier which is specific to an item that has multiple siblings attached to it.
This is useful if you only want one item per group to be recommended by the machine learning algorithms.

> **Note**
>
> When you structure your items with [product grouping](https://docs.coveo.com/en/l78i2152/), ensure that you add the [`group`](https://docs.coveo.com/en/l29e0540#group-string) field to the product dataset in all sent events.
> 
> Using the recommended approach for [product data](https://docs.coveo.com/en/m53g7119/), 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.

#### `variant` (string)

A string that defines the unique non-displayable version of the product. Often called a [stock keeping unit (SKU)](https://docs.coveo.com/en/mc7e0592/).

Example: `001-red-8_wide`

> **Note**
>
> If the `variant` field is sent on an initial event, you must ensure it's sent on all future events, where applicable.
> 
> For example, when a user lands on a product detail page where a `variant` item is selected, send the variant in the detail event and ensure the variant is also sent if the user adds the item to their cart and completes a purchase.
> Conversely, when landing on a product detail page where a variant isn't selected, suggests you don't need to send a detail event with the variant.

#### `price` ([Monetary values](#monetary-values))

The price of the product.
The value can't be blank, therefore use `0` when a product has no price.
Price values are only meaningful if accompanied by a [`currencyCode`](https://docs.coveo.com/en/l29e0540#currencycode-string).

Example: `12.34`

#### `quantity` (numeric)

Quantity of the product bought.

Example: `12`

#### `coupon` (string)

The name of the coupon used on this specific product.

Example: `PROMO-1234`

#### `position` (numeric) - deprecated

> **Important**
>
> This field has been deprecated.
> You no longer need to send this data when logging analytics events.

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

Example: `2`

> **Note**
>
> For products, only a position greater than or equal to `1` is valid.
> If `position: 0` is passed, it will 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)

A unique transaction identifier used to track a purchase.

Example: `transaction-1234`

#### `affiliation` (string)

The store where a transaction took place. Sent when you want to link a [`purchase`](#product-action-types) to a specific store.

Example: `Shoe Store`

#### `revenue` ([Monetary values](#monetary-values))

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

Example: `123.21`

#### `tax` ([Monetary values](#monetary-values))

The total transaction tax.

Example: `8.23`

#### `shipping` ([Monetary values](#monetary-values))

The transaction shipping cost.

Example: `5.00`

#### `coupon` (string)

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)

An identifier used to track a specific transaction.

#### `affiliation` (string)

The store where a quote took place. Sent when you want to link a [`quote`](#product-action-types) 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)

An identifier used to track a specific transaction.

#### `rating` (numeric)

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)

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

```js
  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

```js
coveoua('send', 'event');
```

It will send the following data

```text
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
```

## Product action types

When capturing a commerce event that requires a product data payload, you must use the `ec:setAction` command to specify a product action type.
Product action types are the actions that users can perform on products.
They're used to specify event types to Coveo UA and to track the user's behavior on the site.

The following table lists the required product action types supported by the Coveo UA library for a complete implementation.
These actions feed Coveo ML models and out-of-the-box advanced commerce reports.

[%header,cols="2,4"]
|===
|Action
|Description

|`'click'`
|The user clicked a product.

|`'add'` or `'remove'`
|The user added or removed a product from their cart.

|`'detail'`
|The user accessed a product detail page.

|`'purchase'`
|The user completed the purchase of one or more products.
|===

## Monetary values

Currency is a specification of a monetary amount.
The following table lists the acceptable currency data types.

[%header,cols="~,~"]
|===
|Currency data type
|Examples

|A positive or negative integer.
|`12`, `22`, `0` or `-5`

|A positive or negative decimal value with up to 6 decimal places using `.` as a decimal separator. (Recommended)
|`1337.123456`, `-1.2` or `.97`

|A string, which may contain a non-numeric prefix in front of an integer or decimal value.
In this case, Coveo interprets the number by stripping away the prefix up to the first numeric, `-`, or `.` character.
|Acceptable strings include `"€20.78"`, `"$-15.78"`, `"ZWL100000000"`, but not `"15.99EUR"`, `"$2,275.00"` or `"(0.075)"`
|===

> **Note**
>
> Coveo doesn't support numbers using different decimal separators other than `.`.
> Currency amounts passed in numbers with thousand separators, numbers in parentheses, or numbers in scientific notation formats will be ignored.
> Coveo also doesn't interpret any currency symbols or currency codes in currency fields. If needed, the explicit currency code should be indicated in the [`currencyCode`](https://docs.coveo.com/en/l29e0540#currencycode-string) field.

## Search hub

The name or identifier of the search interface from which a given UA event originates.

Depending on the type of interface from which the event originates, the value of the search hub must contain:

[%header,cols="2"]
|===
|Type of interface
|Contains the string

|A search page
|`search`

|A product listing page
|`listing`
|===

> **Note**
>
> For recommendation components, the [attribution](https://docs.coveo.com/en/m7l98577/) mechanism is automatically managed by tracking a unique ID throughout the actions leading to a product being added to a cart or purchased.
> Therefore, there's no specific naming convention to use when choosing a search hub value for your recommendation component, but note that it's a good practice to add `recs` in the component's search hub value (for example, `home_page_recs`).
> 
> However, the identifier value of the recommendation component is used for reporting purposes.
> Specifically, the Coveo Analytics service utilizes the [`recommendation`](https://docs.coveo.com/en/13#operation/searchUsingPost-recommendation) parameter value from queries originating from a particular recommendation component to generate reports on the performance of that specific component.
> 
> To ensure clarity and easy recognition, we strongly recommend assigning a meaningful and recognizable value as the identifier for your recommendation component.
> 
> You can achieve this by setting the `id` property for your recommendation component. If you're using Headless, for instance, you can specify the component's ID by utilizing the [`id` property](https://docs.coveo.com/en/headless/latest/reference/interfaces/Recommendation.RecommendationListOptions.html#id) when initializing the [`RecommendationList` controller](https://docs.coveo.com/en/headless/latest/reference/interfaces/Recommendation.RecommendationList.html).

**Example**

```html
  coveoua('send', 'event', {
  "searchHub": "<SEARCH_HUB>"
  });
```

Where `<SEARCH_HUB>` is the name of your search hub (for example, "storefront_search" for a search page or "MyBrand_listing" for a product listing page).

If `searchHub` isn't specified and the request is authenticated with a search token, the service tries to extract the `[searchHub](https://docs.coveo.com/en/1342/)` value from the access token that authenticated the request to log a search event (see [Set the Search Hub](https://docs.coveo.com/en/365#set-the-search-hub)).

> **Important**
>
> Coveo ML models use the `searchHub` value as a default filter field.
> These filters don't affect how the models learn, but they must be logged correctly for recommendations to work.
> When Coveo ML models make suggestions, items which don't meet the right filters are ignored (see [Get query suggestions - Troubleshooting](https://docs.coveo.com/en/1459#troubleshooting)).