Skip to content

Products

List, look up and update your products: identifiers, cost, prices, stock, tags, pricing rule and competitor position, plus your own price history.


Products

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"
  }
}
FieldMeaning
priceWhat your store charges now, as last recorded by import, sync or a completed push.
costYour cost price, 4 dp. The basis of every margin calculation.
rrp, map_priceRecommended retail and minimum advertised price, where your catalogue carries them.
special_priceA sale price recorded from the store, when one is active.
monitor_onlyTracked and shown but never repriced.
psinThe global product identity. Read-only; shared across Pricemaster.
marketCompetitor count, cheapest offer and cheapest seller from the daily rollup.
GET/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

limitPage size, 1–200. Default 50.
cursorFrom the previous page's next_cursor.
qFree text over SKU, title and barcode.
skuExact SKU, case and punctuation insensitive.
gtinBarcode, any length.
tagOnly products carrying this tag name.
brandExact brand, case insensitive.
psinOnly products matched to this global product id.
enabledtrue / false.
monitor_onlytrue / false.
updated_sinceISO-8601. Only products changed at or after this time.
expandrule, 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
}
GET/v1/products/{id} products:read

One product with its tags and pricing rule.

Parameters

idProduct 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"
  }
}
GET/v1/products/by-sku/{sku} products:read

The same, looked up by SKU. URL-encode the SKU; matching ignores case and punctuation.

Parameters

skue.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"
  }
}
PATCH/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

idProduct id.
Idempotency-Key (header)Optional, recommended.

Request body

costCost price.
priceYour current selling price (observation).
special_priceActive sale price, or null.
rrpRecommended retail price.
map_priceMinimum advertised price.
stockUnits on hand, integer ≥ 0.
enabledfalse hides the product from pricing and reports.
monitor_onlytrue 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"
  }
}
GET/v1/products/{id}/price-history products:read bucket: history

Your own price for the product, one row per day it was recorded. Default: the last 90 days; at most 400 days per call.

Parameters

idProduct id.
fromStart date. Default 90 days before to.
toEnd 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"
      }
    },
    "…"
  ]
}