Skip to main content
Access to individual endpoints can be restricted per account. If a request to this endpoint returns 403 with error code endpoint_not_enabled and you expect to have access, contact your account representative.
Daily price history for one product or one barcode, over a rolling retention window. Give it a product id or a barcode, get back one price point per observed day, plus summary stats.

Request

Endpoint: POST /v1/products/price-history

Headers

string
required
Must be application/json.
string
required
Your API key as a Bearer token: Bearer {your_api_key}.

Body parameters

string
required
product or barcode.
array
required
Must contain exactly 1 item. The array shape is kept so the limit can be raised later without a breaking change.
string
Inclusive start date, YYYY-MM-DD. Defaults to 90 days before to. See Dates and the retention window.
string
Inclusive end date, YYYY-MM-DD. Defaults to today (UTC). Must not be before from.
string
ISO alpha-3 currency code. Restricts the response to that currency; case-insensitive, uppercased on input.
boolean
default:"true"
Set false to drop the product header from each item (returned as null) for a lighter payload.
boolean
default:"true"
Set false to omit stats from each item.
boolean
default:"true"
Set false to omit series from each item.
array | string
Dot-notation paths into the item shape — product.id, product.name, stats.min_final_price, series.date, series.final_price, currency, product_status, etc. Accepts an array or a comma-separated string. An unknown path is a 422.
integer
default:"10"
Items per page, up to 25. Each item is a full series, so the default and cap are lower than other list endpoints.
integer
default:"1"
Page number.

Dates and the retention window

meta.price_history.retention_days tells you how far back the retention window reaches overall, so don’t hardcode it. A single call, however, is capped to a 90-day-wide range regardless of how deep the retention window goes: omit both from and to to get the most recent 90 days, and a wider request is served by pushing from forward to to − 90 days rather than being rejected. To reach further back within the retention window, send additional calls with explicit from/to pairs stepping back through it. A range that falls partly or wholly before the retention window’s start is clamped to [today − retention_days, today]; only a malformed date or from after to is a 422.

Response

object
Pagination and query metadata, plus the price history report.
array
One item per (product, currency) pair with at least one point in range.

meta.price_history

string
found, no_history, or not_found: see Misses.
string
Echoes the request.
object
One entry per requested id, keyed by the id itself. See Misses.
object
{from, to}: the effective, clamped date range actually served.
integer
How many days back the window currently reaches.
string
The time of day (UTC) the daily snapshot completes. A given day’s point is not available before this time.
array
Every currency present across data. Empty on a miss.

data item shape

A single product id normally yields one item; a barcode fans out to one item per merchant carrying it, and a product whose feed price switched currency inside the window splits into one item per currency.
object | null
Standard product header (id, name, barcode, brand, merchant, network, image_url, direct_url, regular_price, final_price, availability). null when include_product: false, or reduced to {"id": …}: see product_status.
string
Only present when abnormal: not_indexed (the product has left the catalog but its history is retained) or unavailable (the product header could not be loaded even though the series could).
string
ISO alpha-3.
object
Summary over the served range. Omitted when include_stats: false.
array
One point per observed day. Omitted when include_series: false.
A day with no snapshot is simply absent from series: it is never null-padded or interpolated. stats.points, first_date, and last_date make a sparse or gappy series self-describing without you having to walk every date in the range.
Note the gap on 2026-08-28: no snapshot ran for that merchant that day, so there is no point, consistent with the “absent, never null-padded” rule above.

Misses are 200s

A request for an id that doesn’t resolve to history is not an error: it’s a 200 with a status that tells you why. meta.price_history.targets carries a per-target breakdown keyed by the id you sent:
On no_history, the product header rides along in the target entry so you can identify and display the item even though data is empty (meta.total: 0). On not_found there is no product key: nothing is known about that id. For a barcode target, targets carries three extra fields instead: not_found for a barcode means no product carries it at all; no_history means products do (products_matched > 0) but none of them has history collected (products_with_history: 0).

A product that has left the catalog

History outlives the product listing itself. If a product is no longer in the catalog but still has retained history, the series is still served, with a reduced header and a product_status flag:
product_status: "unavailable" is the same idea for a temporary lookup failure on the header while the series itself was already available. product_status is otherwise absent: it only appears when something is abnormal.

Barcode lookups

One barcode fans out across every merchant that carries it. data[] holds one item per (product, currency) with at least one point in range, ordered by product id: a barcode listed by three merchants yields up to three items. Leading zeros in the barcode don’t matter: 0028199276358 and 28199276358 resolve the same products.

Example response

A barcode carried by three merchants returns three items, each with its own product, stats, and series — one merchant’s price differs from the other two, so only its item shows a discount:
Because each item is a full series (roughly 12–15 KB), per_page defaults to 10 and caps at 25 for barcode fan-outs. Use the links in the response and re-send the same body with the linked page.

Multiple currencies

Series are never merged or converted across currencies. If a barcode is sold in more than one currency, each currency becomes its own item, and meta.price_history.currencies lists everything present. Pass currency to keep only one:
For a single product this is a no-op unless its own feed switched currency inside the window, in which case its rows split by currency the same way a barcode fan-out’s do.

Lightweight calls

Three flags — include_product, include_stats, include_series — each default to true. Switch any off to shrink the response: product becomes null, and stats/series are omitted. This is the cheapest way to get just a current-price-and-range summary:
fields goes further, selecting individual paths instead of whole sections: useful for a chart payload that only needs a couple of series fields.
Accepts an array or a comma-separated string. The requested list is echoed back at meta.fields; an unknown path is a 422.

Error codes

Common 422 messages, shaped like standard field-errors plus a trace id:
A 503 is shaped differently: a typed error object, not a field-errors list.
type is history_unavailable or search_unavailable. A 503 is never billed.

Not available yet

  • target_type: "asin" is reserved and currently answers 422.
  • Only one id per request: target_ids must contain exactly 1 item.
  • Only daily granularity.

Examples

Minimal call — most recent 90 days

A date range

Same item, found by barcode

Chart payload — sparse fields, one currency

Paging back through the full retention window

A single call is capped at 90 days, so reaching further back within the retention window means sending non-overlapping calls with explicit from/to pairs, each one’s to picking up where the previous one’s from left off:
Keep stepping from/to back by 90 days at a time until from reaches today − retention_days — a window that starts earlier than that is clamped up to it.