{
  "object": "doc",
  "title": "Price history: GET /api/v1/products/{id}/price-history",
  "description": "Daily lowest price and per-retailer series for 7 to 180 days.",
  "section": "API reference",
  "url": "https://cart-route.com/docs/api/price-history",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/api/products",
  "next": "https://cart-route.com/docs/api/coupons",
  "text": "`GET /api/v1/products/{id}/price-history` returns the daily lowest price across all retailers and a daily series per retailer, for the last 7 to 180 days (default 90). Use it to decide whether today's price is a genuine low. Costs 1 credit.\n\r\n\r\nGET https://cart-route.com/api/v1/products/{id}/price-history?days=90\n\r\n\r\n\n## Which parameters does it take?\n\r\n\r\n  \r\n\n| Name | Type | Default | Description | \r\n    \r\n\n| `id` (path) | string |  | Product id, slug, GTIN or MPN. | \r\n\n| `days` | integer 7–180 | 90 | Window length, ending today. | \r\n    \r\n\n\r\n\n\r\n\r\n\n## What does the response look like?\n\r\n\n```\n{\n  \"object\": \"price_history\",\n  \"data_source\": \"sandbox\",\n  \"history\": {\n    \"object\": \"price_history\",\n    \"product_id\": \"prd_0dophw3\",\n    \"title\": \"Sony WH-1000XM6 Wireless Noise Cancelling Headphones\",\n    \"days\": 30,\n    \"currency\": \"USD\",\n    \"lowest_by_day\": [\n      {\n        \"date\": \"2026-08-25\",\n        \"price_usd\": 369.99\n      },\n      {\n        \"date\": \"2026-08-26\",\n        \"price_usd\": 364.99\n      }\n    ],\n    \"by_retailer\": [\n      {\n        \"retailer_id\": \"amazon\",\n        \"retailer_name\": \"Amazon\",\n        \"points\": [\n          {\n            \"date\": \"2026-08-25\",\n            \"price_usd\": 379.99\n          }\n        ]\n      }\n    ]\n  },\n  \"credits\": {\n    \"charged\": 1,\n    \"remaining\": 197\n  }\n}\n```\n\r\nTruncated: a 30-day response has 30 entries in `lowest_by_day` and in each retailer's `points`.\n\r\n\r\n\n## How should an agent read it?\n\r\n\r\n\n- Is today a low? Compare today's `lowest_by_day` value with the minimum of the series. Search and product responses already do this for 90 days in `price_insight.verdict`; call this endpoint when the user wants the evidence or a different window.\r\n\n- Which retailer discounts? `by_retailer` shows who ran promotions and how deep they went.\r\n\n- Should I wait? A series that dipped 15 to 20% several times in 90 days suggests another promotion is likely; a flat series suggests the price is structural.\r\n\n\r\n\r\n\n## Which errors can it return?\n\r\n`404 not_found` for an unknown product and `422 validation_error` for `days` outside 7–180 (neither is charged), plus `401`, `402` and `429`."
}