Skip to content

Rules and tags

Create, edit, switch on and off, reorder and delete pricing rules; assign products and simulate; manage tags and which products carry them.


Rules

Pricing rules

A rule's settings is its engine configuration, in the same shape you read it back: one block named after the strategy (follow the market, flat price or margin, flash sale) plus the price ending. When several rules cover a product, the lowest priority number wins (ties by id); only enabled rules whose schedule window is open take part. Rules with a channel_id price one selling channel and form their own ladder; the rest price the store.

Every rule write goes through the same path as the Rules page. Settings are validated against what the engine can read, the creep cap is checked against the products' minimum margins before anything is written (422 validation_failed if it would sit below a floor), a revision is recorded, and product assignments are rebuilt from the targeting. A rule in a running A/B test is locked (409 rule_locked). Nothing here sends a price: a new or changed rule takes effect at the next push the workspace itself runs.
GET/v1/rules rules:read

The workspace's rules in id order.

Parameters

limit1–200, default 50.
cursorNext page.
enabledtrue / false.

Example

curl https://api.pricemaster.ai/v1/rules -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": [
    {
      "id": 84,
      "name": "Catch all: 1% above cheapest",
      "strategy": "follow",
      "priority": 10,
      "enabled": true,
      "channel_id": null,
      "applies_to_all_products": true,
      "assigned_products": 31272,
      "targeting": {
        "suppliers": [],
        "tags": [],
        "tag_match": "any"
      },
      "schedule": null,
      "settings": {
        "priceEnding": "99",
        "follow": {
          "type": "cheapest_position",
          "cheapestPosition": 1,
          "competitorId": null,
          "modifierDirection": "above",
          "modifierValue": 1,
          "modifierType": "percentage",
          "applyMinMargin": true,
          "applyCreep": true,
          "creepDirection": "above",
          "creepValue": 1,
          "creepType": "percentage",
          "creepCapEnabled": false,
          "creepCapMarginPct": null
        }
      },
      "created_at": "2026-09-18T10:02:00.000Z",
      "updated_at": "2026-10-14T09:11:30.000Z"
    },
    "…"
  ],
  "next_cursor": null,
  "has_more": false
}
GET/v1/rules/{id} rules:read

One rule.

Parameters

idRule id.

Example

curl https://api.pricemaster.ai/v1/rules/84 -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 84,
    "name": "Catch all: 1% above cheapest",
    "strategy": "follow",
    "priority": 10,
    "enabled": true,
    "channel_id": null,
    "applies_to_all_products": true,
    "assigned_products": 31272,
    "targeting": {
      "suppliers": [],
      "tags": [],
      "tag_match": "any"
    },
    "schedule": null,
    "settings": {
      "priceEnding": "99",
      "follow": {
        "type": "cheapest_position",
        "cheapestPosition": 1,
        "competitorId": null,
        "modifierDirection": "above",
        "modifierValue": 1,
        "modifierType": "percentage",
        "applyMinMargin": true,
        "applyCreep": true,
        "creepDirection": "above",
        "creepValue": 1,
        "creepType": "percentage",
        "creepCapEnabled": false,
        "creepCapMarginPct": null
      }
    },
    "created_at": "2026-09-18T10:02:00.000Z",
    "updated_at": "2026-10-14T09:11:30.000Z"
  }
}

Create a rule

POST/v1/rules rules:write

Create a pricing rule. It lands at the top of its ladder (priority 1) unless you give a priority.

Create it enabled: false, simulate it, then switch it on with a PATCH: that is the order the app's own guidance follows. channel_id scopes the rule to one selling channel and is fixed for its life.

Request body

nameRequired.
strategyfollow, flat or flash. Required.
enabledDefault true.
priorityPosition in the ladder (1 = top). Absent = top.
channel_idA rule-capable selling channel; absent = the store.
settingsThe engine configuration (below). Absent fields take the engine defaults.
targetingsuppliers[], tags[], tag_match (any/all), apply_to_all, segments[] (fast, average, slow, non_mover). Products matching are assigned at once and re-synced nightly.
schedule{enabled, mode (one_off|weekly), start, end_type (no_end|date|stock_level), end, end_stock_level, switch_to_rule_id, recurring_*}. A scheduled rule prices only while its window is open.

Example

curl -X POST https://api.pricemaster.ai/v1/rules -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"DeWalt: match the cheapest","strategy":"follow","enabled":false,"settings":{"priceEnding":"99","follow":{"type":"cheapest_position","cheapestPosition":1,"modifierDirection":"match","modifierValue":0,"modifierType":"value","applyMinMargin":true}},"targeting":{"suppliers":["Toolbank"],"tags":["DeWalt"],"tag_match":"any"}}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 91,
    "name": "DeWalt: match the cheapest",
    "strategy": "follow",
    "priority": 1,
    "enabled": false,
    "channel_id": null,
    "applies_to_all_products": false,
    "assigned_products": 1842,
    "targeting": {
      "suppliers": [
        "Toolbank"
      ],
      "tags": [
        "DeWalt"
      ],
      "tag_match": "any"
    },
    "schedule": null,
    "settings": {
      "priceEnding": "99",
      "follow": {
        "type": "cheapest_position",
        "cheapestPosition": 1,
        "modifierDirection": "match",
        "modifierValue": 0,
        "modifierType": "value",
        "applyMinMargin": true
      }
    },
    "created_at": "2026-09-18T10:02:00.000Z",
    "updated_at": "2026-10-14T09:11:30.000Z"
  }
}

Settings by strategy

StrategyFields
allpriceEnding (99, 95, 50, 00, 05, 09, none), priceEndingDirection (nearest, up, down), pushToSalePrice (send to the store's sale / compare-at field).
followtype (cheapest_position, competitor, market = median), cheapestPosition, competitorId (seller id, for type competitor), modifierDirection (below/match/above), modifierValue, modifierType (value/percentage), applyMinMargin, applyCreep, creepDirection, creepValue, creepType, creepCapEnabled, creepCapMarginPct.
flatstartPoint (cost/retail), percentageValue, applyMinMargin, plus the same creep and creep-cap fields.
flashnegativeMarginPercentageValue (the margin floor, may be negative), applyCreep, creepDirection, creepValue, creepType.

Settings that only the app may set (creepCapHeld, noCompetitorMaxMargin*, velocity) are refused by name and carried across unchanged on an edit. Unknown fields are refused, so a typo cannot silently do nothing.

Edit, enable, disable, delete

PATCH/v1/rules/{id} rules:write

Change any of name, enabled, priority, strategy + settings, targeting, schedule. Fields left out keep their value.

Switching a rule off is {"enabled": false}; on is {"enabled": true}. settings replaces the strategy block (send the whole block). Changing strategy needs settings for the new one. priority moves one rule; to rearrange the ladder use PUT /v1/rules/order.

Parameters

idRule id.

Example

curl -X PATCH https://api.pricemaster.ai/v1/rules/91 -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"enabled": true}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 91,
    "name": "Catch all: 1% above cheapest",
    "strategy": "follow",
    "priority": 10,
    "enabled": true,
    "channel_id": null,
    "applies_to_all_products": true,
    "assigned_products": 31272,
    "targeting": {
      "suppliers": [],
      "tags": [],
      "tag_match": "any"
    },
    "schedule": null,
    "settings": {
      "priceEnding": "99",
      "follow": {
        "type": "cheapest_position",
        "cheapestPosition": 1,
        "competitorId": null,
        "modifierDirection": "above",
        "modifierValue": 1,
        "modifierType": "percentage",
        "applyMinMargin": true,
        "applyCreep": true,
        "creepDirection": "above",
        "creepValue": 1,
        "creepType": "percentage",
        "creepCapEnabled": false,
        "creepCapMarginPct": null
      }
    },
    "created_at": "2026-09-18T10:02:00.000Z",
    "updated_at": "2026-10-14T09:11:30.000Z"
  }
}
DELETE/v1/rules/{id} rules:write

Delete a rule and its product assignments. Other rules' schedules that switched to it are cleared. 204 on success; 409 while in a running A/B test.

Parameters

idRule id.

Example

curl -X DELETE https://api.pricemaster.ai/v1/rules/91 -H "Authorization: Bearer $PRICEMASTER_KEY"

(204, no body)

Reorder the ladder

PUT/v1/rules/order rules:write

Send the rule ids top first; priorities are rewritten 1, 2, 3… in that order. Lower wins.

All ids must belong to one ladder: the store's rules, or one channel's. Rules of that ladder you leave out keep their old number, so send the whole ladder (read it with GET /v1/rules first). The response echoes the rules in their new order.

Request body

rule_idsUp to 500 ids, top first.

Example

curl -X PUT https://api.pricemaster.ai/v1/rules/order -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"rule_ids": [91, 84]}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "ordered": 2,
  "data": [
    {
      "id": 91,
      "name": "Catch all: 1% above cheapest",
      "strategy": "follow",
      "priority": 1,
      "enabled": true,
      "channel_id": null,
      "applies_to_all_products": true,
      "assigned_products": 31272,
      "targeting": {
        "suppliers": [],
        "tags": [],
        "tag_match": "any"
      },
      "schedule": null,
      "settings": {
        "priceEnding": "99",
        "follow": {
          "type": "cheapest_position",
          "cheapestPosition": 1,
          "competitorId": null,
          "modifierDirection": "above",
          "modifierValue": 1,
          "modifierType": "percentage",
          "applyMinMargin": true,
          "applyCreep": true,
          "creepDirection": "above",
          "creepValue": 1,
          "creepType": "percentage",
          "creepCapEnabled": false,
          "creepCapMarginPct": null
        }
      },
      "created_at": "2026-09-18T10:02:00.000Z",
      "updated_at": "2026-10-14T09:11:30.000Z"
    },
    {
      "id": 84,
      "name": "Catch all: 1% above cheapest",
      "strategy": "follow",
      "priority": 2,
      "enabled": true,
      "channel_id": null,
      "applies_to_all_products": true,
      "assigned_products": 31272,
      "targeting": {
        "suppliers": [],
        "tags": [],
        "tag_match": "any"
      },
      "schedule": null,
      "settings": {
        "priceEnding": "99",
        "follow": {
          "type": "cheapest_position",
          "cheapestPosition": 1,
          "competitorId": null,
          "modifierDirection": "above",
          "modifierValue": 1,
          "modifierType": "percentage",
          "applyMinMargin": true,
          "applyCreep": true,
          "creepDirection": "above",
          "creepValue": 1,
          "creepType": "percentage",
          "creepCapEnabled": false,
          "creepCapMarginPct": null
        }
      },
      "created_at": "2026-09-18T10:02:00.000Z",
      "updated_at": "2026-10-14T09:11:30.000Z"
    }
  ]
}

Assigned products

Targeting (suppliers, tags, demand groups, apply-to-all) assigns products automatically and is re-synced nightly. On top of that, products can be assigned by hand; a hand assignment survives targeting changes.

GET/v1/rules/{id}/products rules:read

The products assigned to a rule (id and SKU), 100 per page.

Parameters

idRule id.
limit1–200, default 100.
cursorNext page.

Example

curl "https://api.pricemaster.ai/v1/rules/84/products?limit=2" -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": [
    {
      "product_id": 48213,
      "sku": "DCD796N-XJ"
    },
    {
      "product_id": 48214,
      "sku": "DCD796P2-GB"
    }
  ],
  "next_cursor": "eyJpZCI6NDgyMTR9",
  "has_more": true
}
POST/v1/rules/{id}/products rules:write

Assign products by hand (up to 500 per call). Ids from another workspace are 404 and nothing is written.

Parameters

idRule id.

Request body

product_idsProduct ids.

Example

curl -X POST https://api.pricemaster.ai/v1/rules/84/products -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"product_ids": [48213, 50122]}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "rule_id": 84,
  "added": 1,
  "already_assigned": 1
}
POST/v1/rules/{id}/products/remove rules:write

Unassign many products.

Parameters

idRule id.

Request body

product_idsProduct ids.

Example

curl -X POST https://api.pricemaster.ai/v1/rules/84/products/remove -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"product_ids": [50122]}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "rule_id": 84,
  "removed": 1
}
DELETE/v1/rules/{id}/products/{product_id} rules:write

Unassign one product. 204.

Parameters

idRule id.
product_idProduct id.

Simulate a rule

POST/v1/rules/{id}/simulate rules:read bucket: engine

Run the rule over its assigned products with today's offers and report what it would set. Nothing is sent.

Up to 2,000 products per call (default 500); the first 500 rows come back and the summary covers them all. This is the Rules page's Simulate, so the figures agree with the app.

Parameters

idRule id.
limitProducts to simulate, 1–2000.

Example

curl -X POST "https://api.pricemaster.ai/v1/rules/91/simulate?limit=1000" -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "rule_id": 91,
  "summary": {
    "products": 1000,
    "changed": 412,
    "increased": 97,
    "decreased": 315,
    "unchanged": 540,
    "skipped": 48,
    "out_of_stock": 61
  },
  "data": [
    {
      "product_id": 48213,
      "sku": "DCD796N-XJ",
      "current_price": {
        "ex_tax": "84.16",
        "inc_tax": "100.99"
      },
      "new_price": {
        "ex_tax": "82.49",
        "inc_tax": "98.99"
      },
      "store_price": "98.99",
      "direction": "decrease",
      "changed": true,
      "margin_percent": "24.23",
      "competitors": 9,
      "reason": null
    },
    "…"
  ]
}
Tags

Tags

Tags group products for rules, reports and filters. Manual tags are yours to create and fill; dynamic tags are rebuilt by Pricemaster from criteria set in the app, so their membership is read-only here (422 on an attempt). A tag marked hides_products disables everything carrying it. Filter products by tag with GET /v1/products?tag=….

GET/v1/tags tags:read

Every tag with its product count.

Example

curl https://api.pricemaster.ai/v1/tags -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": [
    {
      "id": 311,
      "name": "DeWalt",
      "colour": "#f2c200",
      "dynamic": false,
      "hides_products": false,
      "products": 1842,
      "created_at": "2026-07-14T06:05:00.000Z"
    },
    {
      "id": 402,
      "name": "Best sellers",
      "colour": null,
      "dynamic": true,
      "hides_products": false,
      "products": 500,
      "created_at": "2026-07-14T06:05:00.000Z"
    }
  ]
}
GET/v1/tags/{id} tags:read

One tag.

Parameters

idTag id.

Example

curl https://api.pricemaster.ai/v1/tags/311 -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 311,
    "name": "DeWalt",
    "colour": "#f2c200",
    "dynamic": false,
    "hides_products": false,
    "products": 1842,
    "created_at": "2026-07-14T06:05:00.000Z"
  }
}
POST/v1/tags tags:write

Create a manual tag. 409 if the name exists.

Request body

nameRequired, up to 80 characters.
colourOptional hex colour.

Example

curl -X POST https://api.pricemaster.ai/v1/tags -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"name": "Clearance Q4", "colour": "#e11d48"}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 455,
    "name": "Clearance Q4",
    "colour": "#e11d48",
    "dynamic": false,
    "hides_products": false,
    "products": 0,
    "created_at": "2026-07-14T06:05:00.000Z"
  }
}
PATCH/v1/tags/{id} tags:write

Rename or recolour a tag.

Parameters

idTag id.

Request body

nameNew name.
colourNew colour, or null.

Example

curl -X PATCH https://api.pricemaster.ai/v1/tags/455 -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"name": "Clearance"}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": {
    "id": 455,
    "name": "Clearance",
    "colour": "#e11d48",
    "dynamic": false,
    "hides_products": false,
    "products": 0,
    "created_at": "2026-07-14T06:05:00.000Z"
  }
}
DELETE/v1/tags/{id} tags:write

Delete a tag; products keep their other tags. 204.

Parameters

idTag id.
GET/v1/tags/{id}/products tags:read

The products carrying a tag (id and SKU), 100 per page.

Parameters

idTag id.
limit1–200.
cursorNext page.

Example

curl https://api.pricemaster.ai/v1/tags/311/products -H "Authorization: Bearer $PRICEMASTER_KEY"
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "data": [
    {
      "product_id": 48213,
      "sku": "DCD796N-XJ"
    },
    "…"
  ],
  "next_cursor": "eyJpZCI6NDgzMTB9",
  "has_more": true
}
POST/v1/tags/{id}/products tags:write

Add products to a manual tag (up to 500).

Parameters

idTag id.

Request body

product_idsProduct ids.

Example

curl -X POST https://api.pricemaster.ai/v1/tags/455/products -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"product_ids": [48213, 50122]}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "tag_id": 455,
  "added": 2,
  "already_tagged": 0
}
POST/v1/tags/{id}/products/remove tags:write

Take many products off a manual tag.

Parameters

idTag id.

Request body

product_idsProduct ids.

Example

curl -X POST https://api.pricemaster.ai/v1/tags/455/products/remove -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"product_ids": [50122]}'
{
  "currency": "GBP",
  "tax_rate": "20.00",
  "tag_id": 455,
  "removed": 1
}
DELETE/v1/tags/{id}/products/{product_id} tags:write

Take one product off a manual tag. 204.

Parameters

idTag id.
product_idProduct id.