Skip to content

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.


Market Data

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.

GET/v1/products/{id}/offers market:read

Live competitor offers for one product.

Parameters

idProduct 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"
    }
  ]
}
GET/v1/products/{id}/offers/{listing_id}/history market:read bucket: history

One competitor listing's recorded price per day, with stock state. The listing must be among the product's current offers.

Parameters

idProduct id.
listing_idFrom /offers.
fromStart date. Default 90 days before to.
toEnd 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.

GET/v1/products/{id}/recommendation market:read bucket: engine

The 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

idProduct 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

PATCH/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

idSeller id from /v1/sellers.

Request body

enabledtrue 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
  }
}
PUT/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

idProduct id.
listing_idListing id from /offers.

Request body

statedisabled, preferred or clear.
scopeseller 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"
}
POST/v1/products/{id}/offers/{listing_id}/rescrape market:write bucket: engine

Ask 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

idProduct id.
listing_idListing 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
}
GET/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

enabledtrue only sellers switched on for the workspace; false only switched off.
qFilter 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"
    },
    "…"
  ]
}