Handle dynamic and customer-specific pricing

This is for:

System Administrator Developer

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, 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, as it plays a crucial role in various Coveo features, including:

In Coveo for Commerce, two commerce standard 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. 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, so 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 is optional, and it doesn’t affect the functionality of Coveo features, as opposed to the ec_price field, which is used by Coveo ML models 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 (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 a fallback value in the ec_price field to ensure Coveo ML models can use it.

  • Index a fallback price: If you can’t index 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 and other features, while still allowing for dynamic pricing at query time.

  • No indexing: If you can’t index pricing data at all, you can omit it. However, you won’t be able to use pricing in Coveo ML models and merchandising rules. Your visitors won’t be able to sort or filter products by price.

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

Strategy Pros Cons

Dictionary field on the product (recommended)

  • The correct price is shown at all times.

  • 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 time.

No indexing

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

If you can index all possible prices for a product, the recommended approach is to use a dictionary field on the Product catalog object.

This approach requires you to:

  1. Define a custom dictionary field to store pricing values.

  2. 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 price values as a distinct metadata and store them in a custom dictionary field.

Tip

When configuring a dictionary field, make sure to follow the best practices and keep in mind the limitations.

  1. In your catalog data, 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:

    {
    [...]
    "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.

  2. Make sure you’ve created the custom dictionary field in your Coveo organization, and that:

  3. Update your search configuration to include the custom dictionary field in the additionalFields array. For example:

    {
[...]
"queryConfiguration": {
    "additionalFields": [
        "price_list"
    ]
}
[...]
}

  4. Configured search token authentication to include, in the dictionaryFieldContext object, the user information needed to extract the correct price from the dictionary field. For example:

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

    This allows Coveo to extract the proper price value from the price_list dictionary field based on the visitor’s context at query time.

  5. Make sure to use your custom dictionary field (for example, price_list) in all customer-facing interfaces to ensure that visitors see the correct price. This prevents the fallback value from the ec_price field, which may not reflect buyer-specific pricing, from being displayed. 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, 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:

  1. Make sure that your catalog product data is configured to index the ec_price field. For example, your product data could look like this:

    [...]
{
    [...]
    "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.

  2. Make sure that your catalog configuration in your catalog entity maps the pricing metadata to the ec_price field.

Strategy 2: Index a fallback price

If you can’t index 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:

  1. Make sure that your catalog product data is configured to index the ec_price field. For example, your product data could look like this:

    [...]
{
    [...]
    "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.

  2. Make sure that your catalog configuration in your catalog entity maps the pricing metadata to the ec_price field.

Strategy 3: No indexing

If you can’t index the ec_price field at all, you can choose to leave it out entirely.

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

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 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 the ec_price field. See Log commerce events for more information on usage analytics tracking in Coveo for Commerce.