Products
List, look up and update your products: identifiers, cost, prices, stock, tags, pricing rule and competitor position, plus your own price history.
The product object
A product is one of your SKUs as Pricemaster holds it. Prices are money objects; market is the daily rollup the app's grid shows; rule is the rule that would price the product today (null for monitor-only products and products with no eligible rule).
{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"id": 48213,
"sku": "DCD796N-XJ",
"title": "DeWalt DCD796N 18V XR Brushless Combi Drill (Body Only)",
"brand": "DeWalt",
"supplier": "Toolbank",
"gtin": "05035048613948",
"mpn": "DCD796N-XJ",
"asin": null,
"image_url": "https://cdn.example.com/dcd796n.jpg",
"category": "Power Tools",
"subcategory": "Combi Drills",
"psin": 1177302,
"enabled": true,
"monitor_only": false,
"taxable": true,
"stock": 14,
"cost": {
"ex_tax": "62.5000",
"inc_tax": "75.0000"
},
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"special_price": null,
"rrp": {
"ex_tax": "124.99",
"inc_tax": "149.99"
},
"map_price": null,
"market": {
"competitors": 9,
"cheapest": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"cheapest_seller": "Toolstation"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"tags": [
{
"id": 311,
"name": "DeWalt"
},
{
"id": 402,
"name": "Best sellers"
}
],
"created_at": "2026-07-14T06:02:11.000Z",
"updated_at": "2026-10-26T05:41:09.000Z"
}
}
| Field | Meaning |
|---|---|
price | What your store charges now, as last recorded by import, sync or a completed push. |
cost | Your cost price, 4 dp. The basis of every margin calculation. |
rrp, map_price | Recommended retail and minimum advertised price, where your catalogue carries them. |
special_price | A sale price recorded from the store, when one is active. |
monitor_only | Tracked and shown but never repriced. |
psin | The global product identity. Read-only; shared across Pricemaster. |
market | Competitor count, cheapest offer and cheapest seller from the daily rollup. |
/v1/products
products:read
The workspace's products in id order, 50 per page by default (up to 200).
With updated_since the order becomes (updated_at, id) and only changed products are returned, which is the way to keep another system in step. Filters combine.
Parameters
limit | Page size, 1–200. Default 50. |
cursor | From the previous page's next_cursor. |
q | Free text over SKU, title and barcode. |
sku | Exact SKU, case and punctuation insensitive. |
gtin | Barcode, any length. |
tag | Only products carrying this tag name. |
brand | Exact brand, case insensitive. |
psin | Only products matched to this global product id. |
enabled | true / false. |
monitor_only | true / false. |
updated_since | ISO-8601. Only products changed at or after this time. |
expand | rule, tags, comma-separated. |
Example
curl "https://api.pricemaster.ai/v1/products?tag=Best%20sellers&expand=rule,tags&limit=2" \
-H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"data": [
{
"id": 48213,
"sku": "DCD796N-XJ",
"title": "DeWalt DCD796N 18V XR Brushless Combi Drill (Body Only)",
"brand": "DeWalt",
"supplier": "Toolbank",
"gtin": "05035048613948",
"mpn": "DCD796N-XJ",
"asin": null,
"image_url": "https://cdn.example.com/dcd796n.jpg",
"category": "Power Tools",
"subcategory": "Combi Drills",
"psin": 1177302,
"enabled": true,
"monitor_only": false,
"taxable": true,
"stock": 14,
"cost": {
"ex_tax": "62.5000",
"inc_tax": "75.0000"
},
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"special_price": null,
"rrp": {
"ex_tax": "124.99",
"inc_tax": "149.99"
},
"map_price": null,
"market": {
"competitors": 9,
"cheapest": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"cheapest_seller": "Toolstation"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"tags": [
{
"id": 311,
"name": "DeWalt"
},
{
"id": 402,
"name": "Best sellers"
}
],
"created_at": "2026-07-14T06:02:11.000Z",
"updated_at": "2026-10-26T05:41:09.000Z"
},
"…"
],
"next_cursor": "eyJpZCI6NDgyMTN9",
"has_more": true
}
/v1/products/{id}
products:read
One product with its tags and pricing rule.
Parameters
id | Product id. |
Example
curl https://api.pricemaster.ai/v1/products/48213 -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"id": 48213,
"sku": "DCD796N-XJ",
"title": "DeWalt DCD796N 18V XR Brushless Combi Drill (Body Only)",
"brand": "DeWalt",
"supplier": "Toolbank",
"gtin": "05035048613948",
"mpn": "DCD796N-XJ",
"asin": null,
"image_url": "https://cdn.example.com/dcd796n.jpg",
"category": "Power Tools",
"subcategory": "Combi Drills",
"psin": 1177302,
"enabled": true,
"monitor_only": false,
"taxable": true,
"stock": 14,
"cost": {
"ex_tax": "62.5000",
"inc_tax": "75.0000"
},
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"special_price": null,
"rrp": {
"ex_tax": "124.99",
"inc_tax": "149.99"
},
"map_price": null,
"market": {
"competitors": 9,
"cheapest": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"cheapest_seller": "Toolstation"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"tags": [
{
"id": 311,
"name": "DeWalt"
},
{
"id": 402,
"name": "Best sellers"
}
],
"created_at": "2026-07-14T06:02:11.000Z",
"updated_at": "2026-10-26T05:41:09.000Z"
}
}
/v1/products/by-sku/{sku}
products:read
The same, looked up by SKU. URL-encode the SKU; matching ignores case and punctuation.
Parameters
sku | e.g. DCD796N-XJ or dcd796nxj. |
Example
curl https://api.pricemaster.ai/v1/products/by-sku/DCD796N-XJ -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"id": 48213,
"sku": "DCD796N-XJ",
"title": "DeWalt DCD796N 18V XR Brushless Combi Drill (Body Only)",
"brand": "DeWalt",
"supplier": "Toolbank",
"gtin": "05035048613948",
"mpn": "DCD796N-XJ",
"asin": null,
"image_url": "https://cdn.example.com/dcd796n.jpg",
"category": "Power Tools",
"subcategory": "Combi Drills",
"psin": 1177302,
"enabled": true,
"monitor_only": false,
"taxable": true,
"stock": 14,
"cost": {
"ex_tax": "62.5000",
"inc_tax": "75.0000"
},
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"special_price": null,
"rrp": {
"ex_tax": "124.99",
"inc_tax": "149.99"
},
"map_price": null,
"market": {
"competitors": 9,
"cheapest": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"cheapest_seller": "Toolstation"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"tags": [
{
"id": 311,
"name": "DeWalt"
},
{
"id": 402,
"name": "Best sellers"
}
],
"created_at": "2026-07-14T06:02:11.000Z",
"updated_at": "2026-10-26T05:41:09.000Z"
}
}
/v1/products/{id}
products:write
Update the facts Pricemaster holds about a product. Needs the write scope and API writes enabled for the workspace.
This never changes a price on your store. price here means what my store charges now, an observation that keeps Pricemaster's view current between imports; pushing a new price to the store stays in the app. Money fields accept a bare number (ex tax) or {"ex_tax": …} / {"inc_tax": …}; null clears a value. Unknown fields are refused. Send an Idempotency-Key so a retry cannot apply twice. Every change is written to the workspace audit log.
Parameters
id | Product id. |
Idempotency-Key (header) | Optional, recommended. |
Request body
cost | Cost price. |
price | Your current selling price (observation). |
special_price | Active sale price, or null. |
rrp | Recommended retail price. |
map_price | Minimum advertised price. |
stock | Units on hand, integer ≥ 0. |
enabled | false hides the product from pricing and reports. |
monitor_only | true keeps it tracked but never repriced. |
Example
curl -X PATCH https://api.pricemaster.ai/v1/products/48213 \
-H "Authorization: Bearer $PRICEMASTER_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-2026-10-26-48213" \
-d '{"cost": 61.90, "stock": 11, "rrp": {"inc_tax": 124.99}}'{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"id": 48213,
"sku": "DCD796N-XJ",
"title": "DeWalt DCD796N 18V XR Brushless Combi Drill (Body Only)",
"brand": "DeWalt",
"supplier": "Toolbank",
"gtin": "05035048613948",
"mpn": "DCD796N-XJ",
"asin": null,
"image_url": "https://cdn.example.com/dcd796n.jpg",
"category": "Power Tools",
"subcategory": "Combi Drills",
"psin": 1177302,
"enabled": true,
"monitor_only": false,
"taxable": true,
"stock": 11,
"cost": {
"ex_tax": "61.9000",
"inc_tax": "74.2800"
},
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
},
"special_price": null,
"rrp": {
"ex_tax": "124.99",
"inc_tax": "149.99"
},
"map_price": null,
"market": {
"competitors": 9,
"cheapest": {
"ex_tax": "82.49",
"inc_tax": "98.99"
},
"cheapest_seller": "Toolstation"
},
"rule": {
"id": 84,
"name": "Catch all: 1% above cheapest"
},
"tags": [
{
"id": 311,
"name": "DeWalt"
},
{
"id": 402,
"name": "Best sellers"
}
],
"created_at": "2026-07-14T06:02:11.000Z",
"updated_at": "2026-10-26T05:41:09.000Z"
}
}
/v1/products/{id}/price-history
products:read
bucket: historyYour own price for the product, one row per day it was recorded. Default: the last 90 days; at most 400 days per call.
Parameters
id | Product id. |
from | Start date. Default 90 days before to. |
to | End date. Default today. |
Example
curl "https://api.pricemaster.ai/v1/products/48213/price-history?from=2026-10-01&to=2026-10-26" -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"product_id": 48213,
"sku": "DCD796N-XJ",
"from": "2026-10-01",
"to": "2026-10-26",
"data": [
{
"date": "2026-10-01",
"price": {
"ex_tax": "84.99",
"inc_tax": "101.99"
}
},
{
"date": "2026-10-02",
"price": {
"ex_tax": "84.16",
"inc_tax": "100.99"
}
},
"…"
]
}