Market data: offers, history, recommendations, sellers
Competitor offers per product, daily competitor price history, the pricing engine's recommendation with its reasoning, and the sellers tracked for your workspace.
Competitor offers for a product
The offers are exactly what the pricing engine and the product page see: one per seller, using the seller's live page price. Sellers and listings you have switched off for the workspace, dead and quarantined pages, and offers in the wrong country or currency are already excluded. difference_ex_tax is their price minus yours, ex tax: negative means they undercut you.
/v1/products/{id}/offers
market:read
Live competitor offers for one product.
Parameters
id | Product id. |
Example
curl https://api.pricemaster.ai/v1/products/48213/offers -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"product_id": 48213,
"sku": "DCD796N-XJ",
"psin": 1177302,
"your_price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"data": [
{
"listing_id": 9931021,
"seller": {
"id": 160,
"name": "Toolstation",
"domain": "toolstation.com",
"country": "GB",
"currency": "GBP"
},
"url": "https://www.toolstation.com/dewalt-dcd796n/p12345",
"price": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"in_stock": true,
"via_variant": false,
"variant_sku": null,
"delivery_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"difference_ex_tax": "-1.67",
"last_seen_at": "2026-10-26T04:12:40.000Z"
},
{
"listing_id": 9942110,
"seller": {
"id": 221,
"name": "ITS",
"domain": "its.co.uk",
"country": "GB",
"currency": "GBP"
},
"url": "https://www.toolstation.com/dewalt-dcd796n/p12345",
"price": {
"ex_tax": "85.83",
"inc_tax": "103.00"
},
"in_stock": true,
"via_variant": true,
"variant_sku": "DCD796N-XJ",
"delivery_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"difference_ex_tax": "1.67",
"last_seen_at": "2026-10-26T04:12:40.000Z"
}
]
}
/v1/products/{id}/offers/{listing_id}/history
market:read
bucket: historyOne competitor listing's recorded price per day, with stock state. The listing must be among the product's current offers.
Parameters
id | Product id. |
listing_id | From /offers. |
from | Start date. Default 90 days before to. |
to | End date. Default today. At most 400 days. |
Example
curl "https://api.pricemaster.ai/v1/products/48213/offers/9931021/history?from=2026-10-20" -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"product_id": 48213,
"listing_id": 9931021,
"seller": {
"id": 160,
"name": "Toolstation"
},
"url": "https://www.toolstation.com/dewalt-dcd796n/p12345",
"from": "2026-10-20",
"to": "2026-10-26",
"data": [
{
"date": "2026-10-20",
"price": {
"ex_tax": "84.99",
"inc_tax": "101.99"
},
"in_stock": true
},
{
"date": "2026-10-21",
"price": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"in_stock": true
},
"…"
]
}
What the rule would set right now
Runs the Pricemaster pricing engine for one product with its winning rule and today's offers, exactly as the product page's Apply preview and the store push do. Nothing is sent to your store. explanation is the engine's calculation log; store_price is the figure a push would put on the wire, in your store's own tax basis.
/v1/products/{id}/recommendation
market:read
bucket: engineThe engine's recommended price for one product, with reasoning.
reason is monitor_only, no_rule, not_priced, or the engine's own text when it declined to move. Rate bucket engine (60 a minute).
Parameters
id | Product id. |
Example
curl https://api.pricemaster.ai/v1/products/48213/recommendation -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"product_id": 48213,
"sku": "DCD796N-XJ",
"current_price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"cost": {
"ex_tax": "62.5000",
"inc_tax": "75.0000"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"recommendation": {
"price": {
"ex_tax": "83.31",
"inc_tax": "99.97"
},
"store_price": "99.97",
"changed": true,
"direction": "decrease",
"margin_percent": "24.98",
"competitors_considered": 9,
"cheapest_in_stock": {
"ex_tax": "82.49",
"inc_tax": "98.99"
}
},
"reason": null,
"explanation": [
"Cheapest in-stock competitor: Toolstation 82.49",
"Rule: 1% above cheapest → 83.31",
"Minimum margin 20% → floor 78.13: ok",
"Price ending .99 (inc tax) → 99.97 store price"
]
}
The sellers tracked for your workspace
/v1/sellers/{id}
market:write
Switch a competitor on or off for this workspace.
Your workspace's own setting, the same switch as the Competitors page; the shared seller record and other workspaces are untouched. A seller switched off drops out of every product's offers and out of pricing at once.
Parameters
id | Seller id from /v1/sellers. |
Request body
enabled | true or false. |
Example
curl -X PATCH https://api.pricemaster.ai/v1/sellers/160 -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"enabled": false}'{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"id": 160,
"name": "Toolstation",
"enabled": false
}
}
/v1/products/{id}/offers/{listing_id}/override
market:write
Exclude, prefer or clear one competitor offer on one product.
disabled leaves the offer out of this product's pricing; preferred marks the listing you trust for that seller; clear restores normal. scope is seller (every listing of that seller on this product; the default for disabled and clear) or listing (just this page). The product page's competitor knob does exactly this. The shared listing and its match are never changed.
Parameters
id | Product id. |
listing_id | Listing id from /offers. |
Request body
state | disabled, preferred or clear. |
scope | seller or listing (optional). |
Example
curl -X PUT https://api.pricemaster.ai/v1/products/48213/offers/9931021/override -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"state": "disabled"}'{
"currency": "GBP",
"tax_rate": "20.00",
"product_id": 48213,
"listing_id": 9931021,
"state": "disabled",
"scope": "seller"
}
/v1/products/{id}/offers/{listing_id}/rescrape
market:write
bucket: engineAsk for a fresh read of one competitor page now.
Queues the page for an immediate read, as the product page's ⟳ does, and answers with the request state. Poll the same path with GET …/rescrape?since=<checked_at> (scope market:read) until state is done or failed. Pricemaster limits how often one page can be re-read.
Parameters
id | Product id. |
listing_id | Listing id from /offers. |
Example
curl -X POST https://api.pricemaster.ai/v1/products/48213/offers/9931021/rescrape -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"state": "queued",
"message": "Reading the page now…",
"checked_at": null,
"price": null,
"in_stock": null,
"http_status": null
}
/v1/sellers
market:read
One row per seller with a live listing on a product you sell, with your on/off setting, listing counts and coverage. Refreshed every 10 minutes.
Parameters
enabled | true only sellers switched on for the workspace; false only switched off. |
q | Filter on name or domain. |
Example
curl "https://api.pricemaster.ai/v1/sellers?enabled=true" -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"data": [
{
"id": 160,
"name": "Toolstation",
"domain": "toolstation.com",
"country": "GB",
"currency": "GBP",
"kind": "competitor",
"enabled": true,
"scraped_daily": true,
"listings": 18422,
"out_of_stock_listings": 911,
"products_covered": 17210,
"last_seen_at": "2026-10-26T05:58:02.000Z"
},
"…"
]
}