# Best prior price

> Best prior price is a feature that calculates the lowest prior price for an item from the price history you provide to Talon.One. This feature is intended to support you in your obligations under Article 6a of the European Union's Omnibus Directive. These price transparency regulations generally require retailers to display the lowest price of an item in a preceding period of 30 days or more alongside any sale price they advertise.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

You can use this feature when using [strikethrough pricing](/docs/product/rules/strikethrough-pricing) in your
campaigns. Talon.One calculates the best prior price based on the data you input.

:::note Legal compliance
Talon.One makes no representation as to compliance with any price transparency regulation
and does not offer legal advice regarding the same.
Talon.One provides its users with a tool to create a price history for an item and
calculate a best prior price value from the price history collected by or provided to
Talon.One. As a Talon.One user, you are responsible for the configuration of
these tools and for compliance with any regulations that apply.

For additional support and information, contact your Customer Success Manager.
:::

## Prerequisites

To calculate the best prior price for an item, ensure the following:

- You have connected a [cart item catalog](/docs/product/account/dev-tools/manage-cart-item-catalogs)
  to your Application.
- You have set up a campaign with [strikethrough rules](/docs/product/rules/create-and-manage-rules#create-a-strikethrough-rule).
- The [closed beta](/docs/product/release-cycle#closed-beta) best prior price feature
  is enabled for your Application. To access this feature, contact your Customer
  Success Manager.

:::note
[Promotional rules](/docs/product/rules/overview#promotion-rules) are not taken into account when [creating a price history](#how-talonone-creates-the-price-history-for-an-item).
:::

## Price history

Talon.One calculates the [best prior price](/integration-api#tag/Catalogs/operation/bestPriorPrice)
for an item from the price history you provide through campaigns and price adjustments.

The price history is a collection of price changes for an item over time. Each price
change logged in an item's price history is called a **price record**.

Talon.One keeps a price history for every item in a cart item
catalog. Each time an item's price changes, Talon.One adds a new price record to its
price history.

A price record can result from either of the following:

- A [price adjustment](/docs/dev/integration-guides/set-up-price-types#price-adjustments),
  whether set directly or synced from your system through a catalog update.
- A [strikethrough pricing](/docs/product/rules/strikethrough-pricing) campaign that includes [discount effects](/docs/product/rules/effects/available-strikethrough-effects#discount-individual-items-effect). [Custom effects](/docs/product/account/dev-tools/manage-custom-effects) are not considered.

:::note
Any custom prices set in the `cartItems` object in [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint requests are not recorded in an item's price history.
:::

:::note Items without a price
A cart item is not required to have a base price or a price adjustment. If neither
is set, Talon.One does not consider the item to be for sale, and no price
record is created. The base price refers to the `base` price value in the catalog,
which is the regular price of the item.
:::

### Price adjustments

[Price adjustments](/docs/dev/integration-guides/set-up-price-types#price-adjustments)
are specific price values assigned to a cart item. They work in
conjunction with [price types](/docs/dev/integration-guides/set-up-price-types), which
are named categories of price for an individual item in a cart item catalog.

A price adjustment lets you sync an item's price from an external pricing engine to
Talon.One through the [Sync cart item catalog](/integration-api#tag/Catalogs/operation/syncCatalog)
endpoint. You can sync several concurrent prices for the same item, with each price
targeting a distinct [audience](/docs/product/audiences/overview). For example:

| Price type    | Price adjustment | Audience        |
| ------------- | ----- | ------------- |
| Base price    | €100  | All customers |
| Sale price    | €80   | All customers |
| Member price  | €70   | Members only  |
| VIP price     | €65   | VIPs only     |

When several prices overlap for the same audience, the lowest price always
wins. In the example above, members have access to the base, sale, and
member prices, but they can purchase the item at the member price.

### Strikethrough pricing campaigns

A [strikethrough pricing](/docs/product/rules/strikethrough-pricing) campaign
can further reduce the price of an item. When a strikethrough pricing
campaign runs, Talon.One sends a [notification](/docs/product/applications/application-notifications/overview#strikethrough-pricing-updates)
to a URL you configure. This notification contains the final price information for the
item in the catalog, which is the price to display for the item on your ecommerce website.

### Factors that affect price history

The following settings directly influence the
price history, and therefore the best prior price calculated for an item:

- **Context ID**: When you [add a price adjustment](/integration-api#tag/Catalogs/operation/syncCatalog)
  or create a strikethrough pricing campaign, provide a context ID to relate the
  adjustment to a specific sales event. This ID can be new or can come from your system.

  Adding a context ID is important for handling [progressive price reductions](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52021XC1229%2806%29&qid=1640961745514), where the
  item's price is lowered further during the same sales
  event, for example, €100 → €80 → €60.

  :::note
  Talon.One logs the context ID when it creates
  a price record, but the context ID itself is only relevant when price history is
  retrieved, not when it is created.
  :::

- **Audience**: When you [create a price type](/docs/product/account/dev-tools/manage-price-types#create-a-price-type),
  add a price adjustment, or use [strikethrough pricing](/docs/product/rules/strikethrough-pricing)
  in a campaign, you can define which [audience](/docs/product/audiences/overview)
  can access the price.

## How Talon.One creates the price history for an item

Talon.One creates a new price record for an item when its price changes. This happens
when you do the following:

- Use the [Sync a catalog](/integration-api#tag/Catalogs/operation/syncCatalog) endpoint to provide new pricing
  information for an item in one of the following ways:

  - Update the base price by using the `PATCH` sync action type.
  - Assign a price adjustment to the item using the `ADD_PRICE_ADJUSTMENT` sync
    action type.
- Create or update a campaign with strikethrough rules that target the item.

The Rule Engine then [evaluates](/docs/product/rules/strikethrough-pricing#strikethrough-rule-evaluation)
any strikethrough pricing campaigns in your
Application that contain the item and triggers any [discount effects](/docs/product/rules/effects/available-strikethrough-effects#discount-individual-items-effect)
that apply.

Talon.One then logs a
price record for each audience, depending on the scenario:

- **No discount effect applies to the item**: Talon.One records the lowest price
  adjustment. If there are no
  price adjustments, Talon.One records the item's base price.
- **A campaign applies a discount effect to the item**:
  Talon.One records the lowest applicable price. This is the price adjustment value or, if
  none exists, the base price. It sums the value of every discount effect that
  applies to that audience, and subtracts the total from the lowest applicable price.
  The resulting value is the price record.
- **A campaign applies a custom effect to the item**: Talon.One ignores custom effects entirely.
  They do not affect price history.

Since a price adjustment and a strikethrough pricing campaign are each
optional, and can occur in any combination, the following permutations are
possible:

| Price adjustment | Strikethrough pricing campaign | Price record logged in price history |
| --- | --- | --- |
| No | No | The item's base price. |
| Yes | No | The price adjustment value for each audience. |
| No | Yes | The base price minus the sum of the campaign's discount effects. |
| Yes | Yes | The price adjustment value minus the sum of the campaign's discount effects. |

Collectively, the price records for an item make up its price history.

### Retrieve the best prior price for an item

To retrieve the best prior price for an item, use the [Fetch best prior price](/integration-api#tag/Catalogs/operation/bestPriorPrice)
endpoint. Send a request with the item SKU and a defined timeframe to return a single
best prior price value.

#### Best prior price timeframe selection

The best prior price Talon.One selects is based on _when_ the current price began.

When you call the [Fetch best prior price](/integration-api#tag/Catalogs/operation/bestPriorPrice)
endpoint, you select a timeframe for retrieving an item's price records
using the `timeframeEndDateType`
[property](/integration-api#tag/Catalogs/operation/bestPriorPrice). This property
determines which price records Talon.One takes into account when calculating best prior
price.

Select one of the following timeframe values:

- **`strict`**: Talon.One calculates the best prior price according to the
  `timeframeEndDate` values you set.
- **`price`**: Based on when the price value changes. Talon.One calculates the best prior
  price using the price records prior to the start of the current price value.
- **`sale`**: Based on a sales event. Talon.One calculates the best prior
  price using the price records prior to the start of the current sales event.
  It includes price records that are in the same sales event and have the same
  `contextId`. You can select this value in the case of a
  [progressive price reduction](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52021XC1229%2806%29&qid=1640961745514),
  where the item's price is lowered further during the same sales event.

:::note
If there are any increases in price within a single sales event, a new sales event begins.
:::

#### Example

Consider an item with the following price history, where each price is reduced further
within a period. Let's assume today is July 3 and we need the best prior price for
the previous 30 days.

| Price | Context ID    | Price first available |
| ----- | ------------- | ------------------ |
| €100  | (none)        | June 1             |
| €80   | `summer-sale` | June 15            |
| €70   | `summer-sale` | July 1             |

The current price is €70. Depending on the timeframe selection value, the best prior
price Talon.One returns is different:

- **`strict`**: The timeframe ends at the `timeframeEndDate` value you set,
  regardless of price or context ID changes. Talon.One returns the lowest
  price recorded in a specified number of days before that date, which is either
  €100, €80, or €70, depending on when the `timeframeEndDate` falls.
- **`price`**: Since €70 is a new price value, the timeframe starts when €70
  began, and Talon.One starts looking backwards from July 1. The previous price
  records for the 30-day period are €100 and €80. Talon.One returns
  **€80** as the best prior price, since it is the lowest price in that period.
- **`sale`**: Because €80 and €70 share the context ID, `summer-sale`,
  Talon.One views them as the same sale event. The timeframe starts when
  the price record for `summer-sale` began at €80, so it looks back from June 15 and
  returns **€100** as the best prior price.

### Retrieve the price history for an item

You can use the [Get summary of price history](/management-api#tag/Catalogs/operation/priceHistory)
endpoint to retrieve all the price records Talon.One has logged for an item over a given
period. This endpoint is useful for auditing purposes and for ensuring that evaluation
produced correct price records.

Also, since Talon.One logs a separate price record per audience, you can inspect the
`target` field on each entry, for example, to compare the price history of a member price
compared to a base price.

## Related pages

- [Set up price types](/docs/dev/integration-guides/set-up-price-types)
- [Strikethrough pricing](/docs/product/rules/strikethrough-pricing)
- [Manage cart item catalogs](/docs/product/account/dev-tools/manage-cart-item-catalogs)