---
title: Handle dynamic and customer-specific pricing
slug: n3uf0361
canonical_url: https://docs.coveo.com/en/n3uf0361/
collection: coveo-for-commerce
source_format: adoc
---
# Handle dynamic and customer-specific pricing
Many ecommerce ecosystems, including B2B businesses and multi-location retailers such as grocery chains, support multiple prices per product.
These prices may vary based on various factors, including buyer groups, contracts, regions, individual stores, or even promotional programs and rewards.

Pricing variations can be defined in structured price lists stored in the [catalog data](https://docs.coveo.com/en/obcf0333/), or determined dynamically at runtime by external pricing systems.
External pricing systems are typically used when prices must be calculated dynamically, based on custom logic, real-time data, or complex conditions.

Coveo provides best practices and flexible strategies to support both static and dynamic pricing models.

## Why you should index pricing data

You should always make pricing data available in your [Coveo organization](https://docs.coveo.com/en/185/), as it plays a crucial role in various Coveo features, including:

* Sorting and filtering in Coveo-powered interfaces, allowing [visitors](https://docs.coveo.com/en/nbub9475/) to sort products by price or filter results based on price ranges.

* [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) merchandising rules, which can use price attributes to define conditions and actions.

* Search result templates, which can display product prices in search results.

* [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) models, such as the [Session-Based Product Recommendations (SBPR)](https://docs.coveo.com/en/m7db5404/) model use price attributes to improve relevance and personalization.

In Coveo for Commerce, two [commerce standard fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields) are used to store product prices:

* `ec_price`: This field is used to store the base price of a product.
This field is essential for the proper functioning of some Coveo features, such as ML [models](https://docs.coveo.com/en/1012/).
Therefore, it should always contain a single value.

* `ec_promo_price`: This field is used to store the promotional price of a product, if applicable.

However, these fields don't support storing multiple values.
It's important to adopt a strategy to manage multiple prices per product, while still providing a value for the `ec_price` field.

> **Note**
>
> Providing a value for the `ec_promo_price` [field](https://docs.coveo.com/en/200/) is optional
> It doesn't affect the functionality of Coveo features, as opposed to the `ec_price` [field](https://docs.coveo.com/en/200/), which is used by Coveo ML [models](https://docs.coveo.com/en/1012/) and other features.

## Indexing strategies for dynamic pricing

Consider the following strategies when implementing customer-specific or dynamic pricing in Coveo for Commerce:

* [**Dictionary field on the product**](#strategy-1-dictionary-field-on-the-product-recommended) (recommended): This strategy allows you to store multiple prices in a dictionary field on the product, enabling Coveo to extract the correct price at query time based on user context.
In this strategy, you must also [index](https://docs.coveo.com/en/204/) a fallback value in the `ec_price` field to ensure that Coveo ML [models](https://docs.coveo.com/en/1012/) can use it.

* [**Index a fallback price**](#strategy-2-index-a-fallback-price): If you can't [index](https://docs.coveo.com/en/204/) all possible prices, or if the pricing logic is too complex to represent as dictionary keys, you can store a fallback value in the `ec_price` field.
This allows you to provide a price value for Coveo ML [models](https://docs.coveo.com/en/1012/) and other features, while still allowing for dynamic pricing at query time.

* [**No indexing**](#strategy-3-no-indexing): If you can't [index](https://docs.coveo.com/en/204/) pricing data at all, you can omit it.
However, you won't be able to use pricing in Coveo ML [models](https://docs.coveo.com/en/1012/) and merchandising rules.
Your [visitors](https://docs.coveo.com/en/nbub9475/) won't be able to sort or filter products by price.

The following table summarizes the pros and cons of each strategy:

[%header,cols="1,1a,1a"]
|===
|Strategy
|Pros
|Cons

|Dictionary field on the product (recommended)
|* The correct price is always shown.

* No query lag, because the price is extracted from the dictionary.

* Pricing logic is enforced securely.
|* With a high number of price entries, updates may result in noticeable delays before the new prices are reflected.

|Index a fallback price
|* Simple to implement.

* Always displays the correct price retrieved from an external system.
| * Facets and sorting may not match the actual price displayed on the product.

* You'll need to fetch the actual price from an external system at query time.

* Possible lag when retrieving the correct price.

* May require logic to calculate the fallback price at [indexing](https://docs.coveo.com/en/204/) time.

|No [indexing](https://docs.coveo.com/en/204/)
|* Always displays the correct price retrieved from an external system.
|* You can't use pricing in ML, merchandising, sorting, or faceting.

* You'll need to fetch the actual price from an external system at query time.

* Possible lag when retrieving the correct price.
|===

### Strategy 1: Dictionary field on the product (recommended)

If you can [index](https://docs.coveo.com/en/204/) all possible prices for a product, the recommended approach is to use a [dictionary field](https://docs.coveo.com/en/2036/) on the `Product` [catalog object](https://docs.coveo.com/en/ncig0154/).

This approach requires you to:

. Define a custom dictionary field to store pricing values.

. Index the `ec_price` field with a fallback value.

#### Step 1: Define a custom field to store prices

The `ec_price` standard field doesn't support dictionary values.
Therefore, you must [index](https://docs.coveo.com/en/204/) price values as distinct [metadata](https://docs.coveo.com/en/218/) values and store them in a custom [dictionary field](https://docs.coveo.com/en/2036/).

> **Tip**
>
> When configuring a dictionary field, make sure to follow the [best practices](https://docs.coveo.com/en/2036#leading-practices) and keep in mind the [limitations](https://docs.coveo.com/en/2036#limitations).

. In your [catalog data](https://docs.coveo.com/en/obcf0333/), store all price values in a dictionary object (for example `price_list`) so that Coveo can extract the correct price at query time.


**Example**

In the following catalog data sample, `price_list` is a dictionary object with key-value pairs.
It defines different prices based on the user's subscription level:

```json
{
  [...]
  "ec_product_id": "12345",
  "ec_name": "Example Product",
  "price_list": {
    "Default": 4000.00, <1>
    "Vip": 3750.00, <2>
    "Premium": 3900.00 <3>
  }
  [...]
}
```

<1> The `Default` key defines the default price for all users.

<2> The `Vip` key defines a special price for VIP users.

<3> The `Premium` key defines a price for Premium users.

. Make sure you've created the custom dictionary field in your [Coveo organization](https://docs.coveo.com/en/185/), and that:

** The field is [set as a dictionary field by enabling the `keyValue` option](https://docs.coveo.com/en/2036/).

** You [created the source mapping](https://docs.coveo.com/en/1640/) that links your product [metadata](https://docs.coveo.com/en/218/) (for example, `price_list`) to the custom [field](https://docs.coveo.com/en/200/) in your [Coveo organization](https://docs.coveo.com/en/185/).

. [Update your query configuration](https://docs.coveo.com/en/pbbf0247/) to include the custom dictionary field in the `additionalFields` array.
For example:

```json
{
  [...]
  "configurationModel": {
    "additionalFields": [
      "price_list"
    ]
  }
  [...]
}
```

. Configure [search token authentication](https://docs.coveo.com/en/o8ld0051/) to include, in the [`dictionaryFieldContext`](https://docs.coveo.com/en/56#dictionaryfieldcontext-object-optional) object, the user information needed to extract the correct price from the dictionary field.
For example:

```json
{
  [...]
  "dictionaryFieldContext": {"price_list": "Vip"}
  [...]
}
```

This lets Coveo extract the proper price value from the `price_list` dictionary field based on the [visitor](https://docs.coveo.com/en/nbub9475/)'s context at query time.

. Make sure to use your custom dictionary field (for example, `price_list`) in all customer-facing interfaces to ensure that [visitors](https://docs.coveo.com/en/nbub9475/) see the correct price.
This prevents the fallback value for the `ec_price` field from being displayed.
The fallback value may not reflect buyer-specific pricing,
You'll typically want the following features to rely on the value of the dictionary field:

* Result templates

* Facets and sorting

* Attributes to define merchandising rules in the CMH.

#### Step 2: Index the `ec_price` field with a fallback value

To ensure that the `ec_price` field is [indexed](https://docs.coveo.com/en/204/), you must still provide a fallback value.
For example, you could use a static price such as the manufacturer's suggested retail price (MSRP) or an average price.
This value will be used by Coveo ML models and other features that rely on the `ec_price` field.
For `ec_price` to be indexed as a fallback value:

. Make sure that your [catalog product data](https://docs.coveo.com/en/m53g7119/) is configured to index the `ec_price` field.
For example, your product data could look like this:

```json
[...]
{
    [...]
    "documentId": "product://001-red",
    "ec_product_id": "001-red",
    "ec_price": 28.00, <1>
    "objecttype": "Product",
    [...]
},
    [...]
{
    [...]
    "documentId": "product://002-blue",
    "ec_product_id": "002-blue",
    "ec_price": 32.00, <1>
    "objecttype": "Product",
    [...]
},
[...]
```
<1> The `ec_price` field is indexed with a fallback value.

. Make sure that your [catalog configuration](https://docs.coveo.com/en/l5if0520/) in your [catalog entity](https://docs.coveo.com/en/3143/) [maps the pricing metadata](https://docs.coveo.com/en/3139#commerce-standard-fields) to the `ec_price` field.

### Strategy 2: Index a fallback price

If you can't [index](https://docs.coveo.com/en/204/) all possible prices for a product, or if the pricing logic is too complex to represent as dictionary keys, you can store a fallback value in the `ec_price` field.
For example, you could use a static price such as the manufacturer's suggested retail price (MSRP) or an average price.
This value will be used by Coveo ML models and other features that rely on the `ec_price` field.

This strategy will require you to fetch the actual price from an external system at query time.

For `ec_price` to be indexed as a fallback value:

. Make sure that your [catalog product data](https://docs.coveo.com/en/m53g7119/) is configured to index the `ec_price` field.
For example, your product data could look like this:

```json
[...]
{
    [...]
    "documentId": "product://001-red",
    "ec_product_id": "001-red",
    "ec_price": 28.00, <1>
    "objecttype": "Product",
    [...]
},
    [...]
{
    [...]
    "documentId": "product://002-blue",
    "ec_product_id": "002-blue",
    "ec_price": 32.00, <1>
    "objecttype": "Product",
    [...]
},
[...]
```
<1> The `ec_price` field is indexed with a fallback value.

. Make sure that your [catalog configuration](https://docs.coveo.com/en/l5if0520/) in your [catalog entity](https://docs.coveo.com/en/3143/) [maps the pricing metadata](https://docs.coveo.com/en/3139#commerce-standard-fields) to the `ec_price` field.

### Strategy 3: No indexing

If you can't [index](https://docs.coveo.com/en/204/) the `ec_price` field at all, you can choose to leave it out entirely.

However, you won't be able to use the following:

* The Coveo ML [Session-Based Product Recommendations (SBPR)](https://docs.coveo.com/en/m7db5404/) model.

* The price attribute in merchandising rules.

* Price values for filtering or sorting in Coveo-powered interfaces.

* Price values in search result templates.

This strategy will require you to fetch the actual price from an external system at query time.

## About reporting

Coveo's revenue-based reporting features, such as CMH reports and Advanced Reports in the Administration Console, don't rely on the [indexed](https://docs.coveo.com/en/204/) `ec_price` field.
Instead, they calculate revenue based on the price value provided in purchase events.

As long as your purchase events include the price actually paid by the customer, revenue reporting will work as expected, even if you don't [index](https://docs.coveo.com/en/204/) the `ec_price` field.
See [Log commerce events](https://docs.coveo.com/en/3188/) for more information on usage analytics tracking in Coveo for Commerce.