> ## Content Index
> Fetch the complete content index at: https://blog.affiliate.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Price History API: How to Tell Readers Whether a Black Friday Deal Is Real
- URL: https://blog.affiliate.com/price-history-api-black-friday-deal-real/
- Published: 2026-10-28T20:00:00.000Z
- Updated: 2026-10-28T19:59:59.000Z
- Description: A Black Friday listing claims a sale price against a higher regular price. Three checks on real daily price history show whether that higher price was ever charged, plus a short script a deal page can use.
- Author: Dylan Bertalli

A Black Friday listing usually makes one claim: a price now, and a higher price it supposedly replaces. A reader who has seen the product before may wonder whether that higher price was ever real. The Price History API gives a page the daily record it needs to answer, using the product’s barcode and covering every store that sells it.

This article runs three checks on one real product, a robot vacuum with price history at 9 stores, and turns them into a short script. It is written for marketing teams who work with a developer on deal pages. Earlier posts cover [how price history helps a reader trust a deal](https://blog.affiliate.com/how-price-history-helps-a-reader-trust-a-deal/) and [comparing regular price with final price](https://blog.affiliate.com/compare-regular-price-vs-final-price-via-api/). This one applies both to the weeks before Black Friday, which falls on November 27 this year.

## The request

A barcode returns one history for every store that sells the product. This request asks for the daily series, which the checks below need.

```
{
  "target_type": "barcode",
  "target_ids": ["885155046420"],
  "currency": "USD",
  "include_series": true,
  "per_page": 25
}
```

One call covers up to 91 days. Here the window runs from July 30 to October 27, 2026\. A series is roughly 8 KB per store, so a barcode with many stores returns a few dozen KB. Of the 16 listings that matched this barcode, 9 had price history.

## What comes back

Each store returns a `stats` summary and a daily `series`. This is one store’s entry, trimmed to the fields the checks use, with the store name replaced by its type. The two series rows are the days before and after the price jumped.

```
{
  "product": { "merchant": { "name": "Home improvement retailer B" } },
  "stats": {
    "points": 90,
    "first_date": "2026-07-30",
    "current": { "date": "2026-10-27", "final_price": 159.99, "regular_price": 299.99, "on_sale": true },
    "min_final_price": { "date": "2026-08-12", "amount": 149.99 },
    "max_final_price": { "date": "2026-09-08", "amount": 299.99 },
    "avg_final_price": 180.1
  },
  "series": [
    { "date": "2026-09-07", "regular_price": 299.99, "final_price": 149.99, "on_sale": true,  "sale_discount": 50, "availability": "InStock" },
    { "date": "2026-09-08", "regular_price": 299.99, "final_price": 299.99, "on_sale": false, "sale_discount": 0,  "availability": "InStock" }
  ]
}
```

## Check 1: was the regular price ever charged?

Each of the seven stores in the table lists a regular price of $299.99, and each flagged the product on sale on most days. The series shows how many days the price was actually at or near $299.99\. The table covers the stores with at least 40 days of history.

| Store type                        | Regular price | Days charged at regular | Average price | Lowest price | Price on Oct 27 |
| --------------------------------- | ------------- | ----------------------- | ------------- | ------------ | --------------- |
| Home shopping retailer            | $299.99       | 14 of 40                | $202.49       | $149.99      | $149.99         |
| Home improvement retailer A       | $299.99       | 13 of 88                | $178.97       | $149.99      | $159.99         |
| Online pet-supply retailer        | $299.99       | 11 of 90                | $181.77       | $149.99      | $199.99         |
| Home improvement retailer B       | $299.99       | 14 of 90                | $180.10       | $149.99      | $159.99         |
| Electronics retailer A, listing 1 | $299.99       | 13 of 85                | $178.81       | $149.00      | $159.00         |
| Big-box retailer A                | $299.99       | 14 of 89                | $181.68       | $149.99      | $159.99         |
| Electronics retailer A, listing 2 | $299.99       | 24 of 82                | $215.11       | $179.99      | $179.99         |

- **At most stores the regular price was charged on a small share of days.** Five of the seven show it on 11 to 14 days, roughly one day in seven. Two show it more often: the home shopping retailer on 14 of 40 days and the second electronics listing on 24 of 82.
- **Those days came together.** On September 7 the seven stores sat between $149 and $179.99\. On September 8 all seven were at $299.99, and most returned to between $149.99 and $200 within about two weeks.
- **Lowest prices cluster in August.** Five stores reached their low on August 12, the same day.
![Line chart of the daily price of one robot vacuum at three stores from July 30 to October 27, 2026. Prices step down on August 12, jump to $299.99 on September 8 and fall back about two weeks later.](https://storage.ghost.io/c/22/24/222415b9-00f9-4f91-b2be-0ff3f96900ef/content/images/2026/10/Article-chart---robot-vacuum-price-history-Black-Friday-.png) 

## Check 2: how does a sale price compare with the window?

Suppose home improvement retailer B advertises $159.99 with “was $299.99”. That claims 47% off. Across the same 90 days the price averaged $180.10 and reached $149.99 in August. Against the average, the saving is 11%, and $159.99 is $10.00 above the lowest price the store charged. Both statements are true. The history lets a page choose the one that describes what a reader will actually save.

## Check 3: did the price rise shortly before the sale?

When the price rises and then falls, a discount can be measured from a price that stood for only a short time. At the same retailer the price was $149.99 on September 7, $299.99 from September 8 to September 21, and $149.99 again on September 22, which a listing could show as 50% off. The $299.99 price stood for 14 days. The rest of the history sits mostly below $180.

## Turning the checks into a label

The script reads one store’s response and returns the figures a page needs. The one threshold, how often the regular price must appear, is a constant at the top that a team can change.

```
const SHARE_OF_DAYS = 0.25; // regular price should appear on at least a quarter of days

function checkDealClaim(listing, claimedPrice) {
  const days = listing.series;
  const regular = days[days.length - 1].regular_price;
  const prices = days.map(d => d.final_price);
  const price = claimedPrice ?? prices[prices.length - 1];
  const low = Math.min(...prices);
  const average = prices.reduce((a, b) => a + b, 0) / prices.length;
  const regularDays = days.filter(d => d.final_price >= regular * 0.99).length;

  return {
    claimedDiscount: Math.round((1 - price / regular) * 100),   // "47% off"
    regularDays,                                                // days charged at the regular price
    trackedDays: days.length,
    belowAverage: Math.round((1 - price / average) * 100),      // saving against the typical price
    aboveLow: Number((price - low).toFixed(2)),                 // distance from the lowest price seen
    regularPriceWasReal: regularDays / days.length >= SHARE_OF_DAYS,
  };
}
```

Run on home improvement retailer B with a claimed price of $159.99, it returns:

| Field                     | Value   | What a page could say                                     |
| ------------------------- | ------- | --------------------------------------------------------- |
| claimedDiscount           | 47      | The listing claims 47% off.                               |
| regularDays / trackedDays | 14 / 90 | The regular price was charged on 14 of the last 90 days.  |
| belowAverage              | 11      | That is 11% below the average price over the same period. |
| aboveLow                  | 10      | The lowest price seen was $10.00 lower.                   |
| regularPriceWasReal       | false   | Show the average and the low, not the “was” price.        |

## A few things to keep in mind

- **The window is 91 days per call.** A claim made on November 27 can be checked against roughly the 91 days before it, which starts in late August. Prices outside that window are not visible.
- **State what was observed.** “Regular price charged on 14 of 90 days” is a fact from the history. A word such as “fake” is a judgment the data does not need.
- **A missing day is not a zero price.** A day with no observation means the price was not seen that day.
- **Check stock separately.** Three of these listings were out of stock for 13 to 17 days. Confirm availability before sending a reader to a store, as the [holiday content checklist](https://blog.affiliate.com/planning-holiday-content-with-product-data-what-to-check-before-gift-guide-season/) suggests.
- **Match on the barcode first.** The checks are only as reliable as the product match, which is why [barcode-first matching](https://blog.affiliate.com/product-data-api-identifier-rules-barcode-first-then-mpn-fallback-for-accurate-product-matches/) is the starting point.

With a barcode, one request and about 20 lines of logic, a deal page can show what the history says about a price before it tells a reader that the price is a deal.