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.Request
Endpoint:POST /v1/products/price-history
Headers
Body parameters
Must contain exactly 1 item. The array shape is kept so the limit can be raised later without a breaking change.
Inclusive start date,
YYYY-MM-DD. Defaults to 90 days before to. See Dates and the retention window.ISO alpha-3 currency code. Restricts the response to that currency; case-insensitive, uppercased on input.
Set
false to drop the product header from each item (returned as null) for a lighter payload.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.Items per page, up to
25. Each item is a full series, so the default and cap are lower than other list endpoints.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
meta.price_history
found, no_history, or not_found: see Misses.One entry per requested id, keyed by the id itself. See Misses.
The time of day (UTC) the daily snapshot completes. A given day’s point is not available before this time.
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.
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.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).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.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 a200 with a status that tells you why.
meta.price_history.targets carries a per-target breakdown keyed by the id you sent:
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 aproduct_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
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 ownproduct, 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, andmeta.price_history.currencies lists everything present. Pass currency to keep only one:
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.
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 answers422.- Only one id per request:
target_idsmust 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 explicitfrom/to pairs, each one’s to picking up where the previous one’s from left off:
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.