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.
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.
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./v1/rules
rules:read
The workspace's rules in id order.
Parameters
limit | 1–200, default 50. |
cursor | Next page. |
enabled | true / 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
}
/v1/rules/{id}
rules:read
One rule.
Parameters
id | Rule 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
/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
name | Required. |
strategy | follow, flat or flash. Required. |
enabled | Default true. |
priority | Position in the ladder (1 = top). Absent = top. |
channel_id | A rule-capable selling channel; absent = the store. |
settings | The engine configuration (below). Absent fields take the engine defaults. |
targeting | suppliers[], 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
| Strategy | Fields |
|---|---|
| all | priceEnding (99, 95, 50, 00, 05, 09, none), priceEndingDirection (nearest, up, down), pushToSalePrice (send to the store's sale / compare-at field). |
follow | type (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. |
flat | startPoint (cost/retail), percentageValue, applyMinMargin, plus the same creep and creep-cap fields. |
flash | negativeMarginPercentageValue (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
/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
id | Rule 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"
}
}
/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
id | Rule id. |
Example
curl -X DELETE https://api.pricemaster.ai/v1/rules/91 -H "Authorization: Bearer $PRICEMASTER_KEY"(204, no body)
Reorder the ladder
/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_ids | Up 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.
/v1/rules/{id}/products
rules:read
The products assigned to a rule (id and SKU), 100 per page.
Parameters
id | Rule id. |
limit | 1–200, default 100. |
cursor | Next 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
}
/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
id | Rule id. |
Request body
product_ids | Product 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
}
/v1/rules/{id}/products/remove
rules:write
Unassign many products.
Parameters
id | Rule id. |
Request body
product_ids | Product 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
}
/v1/rules/{id}/products/{product_id}
rules:write
Unassign one product. 204.
Parameters
id | Rule id. |
product_id | Product id. |
Simulate a rule
/v1/rules/{id}/simulate
rules:read
bucket: engineRun 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
id | Rule id. |
limit | Products 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
},
"…"
]
}