Minimum margins
The profit floor every rule respects: the account default, cost bands, and product-group tables with their own bands.
The floor beneath every rule
Before a rule's price is accepted it is checked against the product's minimum margin. The floor resolves in this order: a per-product override set in the app; a band of an enabled product-group table whose suppliers or tags select the product; a band of the base table; otherwise the account default. A band covers a range of cost (ex tax) and names the margin percentage for it; an optional min_cash_margin raises the floor to at least cost plus that amount.
/v1/min-margins
margins:read
Everything: default, base bands, every group table with its bands.
Example
curl https://api.pricemaster.ai/v1/min-margins -H "Authorization: Bearer $PRICEMASTER_KEY"{
"currency": "GBP",
"tax_rate": "20.00",
"default_percent": "20.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
/v1/min-margins
margins:write
Set the account default (0–100).
Request body
default_percent | The percentage. |
Example
curl -X PATCH https://api.pricemaster.ai/v1/min-margins -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"default_percent": 22}'{
"currency": "GBP",
"tax_rate": "20.00",
"default_percent": "22.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
Cost bands
/v1/min-margins/bands
margins:write
Add a band, fitted into its table so bands never overlap.
Bands the new one covers are replaced, bands it cuts into are trimmed, a band it sits inside is split around it (the same plan the app's "+ Add band" shows). group_id targets a product-group table; absent = the base table. The whole table comes back.
Request body
min_cost | Lower cost edge, ex tax. |
max_cost | Upper cost edge, ex tax (must be above min_cost). |
margin_percent | 0–100. |
min_cash_margin | Optional £ floor. |
group_id | Optional product-group table. |
Example
curl -X POST https://api.pricemaster.ai/v1/min-margins/bands -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"min_cost": 0, "max_cost": 50, "margin_percent": 25}'{
"currency": "GBP",
"tax_rate": "20.00",
"band_id": 701,
"default_percent": "20.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
/v1/min-margins/bands/{id}
margins:write
Edit a band in place: edges, percentage, cash floor. null clears an edge (open-ended) or the cash floor.
Parameters
id | Band id. |
Request body
min_cost | |
max_cost | |
margin_percent | |
min_cash_margin |
Example
curl -X PATCH https://api.pricemaster.ai/v1/min-margins/bands/702 -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"margin_percent": 19.5}'{
"currency": "GBP",
"tax_rate": "20.00",
"default_percent": "20.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
/v1/min-margins/bands/{id}
margins:write
Delete a band; costs it covered fall to the next band or the default. 204.
Parameters
id | Band id. |
Product-group tables
A product-group table carries its own bands for the products its suppliers or tags select, overriding the base table for them. Highest priority wins when two tables select the same product.
/v1/min-margins/groups
margins:write
Create a table. It needs at least one supplier or tag.
Request body
name | Required. |
suppliers | Supplier names. |
tags | Tag names. |
tag_match | any (default) or all. |
Example
curl -X POST https://api.pricemaster.ai/v1/min-margins/groups -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"name": "DeWalt", "tags": ["DeWalt"]}'{
"currency": "GBP",
"tax_rate": "20.00",
"group_id": 9,
"default_percent": "20.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
/v1/min-margins/groups/{id}
margins:write
Edit, reprioritise or switch a table on/off.
Parameters
id | Group id. |
Request body
name | |
suppliers | |
tags | |
tag_match | |
priority | Higher wins. |
enabled | Off = its products fall back to the base table. |
Example
curl -X PATCH https://api.pricemaster.ai/v1/min-margins/groups/9 -H "Authorization: Bearer $PRICEMASTER_KEY" -H "Content-Type: application/json" -d '{"enabled": false}'{
"currency": "GBP",
"tax_rate": "20.00",
"default_percent": "20.00",
"bands": [
{
"id": 701,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"margin_percent": "25.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 702,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "50.00",
"inc_tax": "60.00"
},
"max_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"margin_percent": "18.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
},
{
"id": 703,
"group_id": null,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "200.00",
"inc_tax": "240.00"
},
"max_cost": null,
"margin_percent": "12.00",
"min_cash_margin": {
"ex_tax": "15.00",
"inc_tax": "18.00"
},
"channel_id": null,
"source": "manual"
}
],
"groups": [
{
"id": 9,
"name": "DeWalt",
"enabled": true,
"priority": 0,
"targeting": {
"suppliers": [],
"tags": [
"DeWalt"
],
"tag_match": "any"
},
"bands": [
{
"id": 710,
"group_id": 9,
"filter": {
"type": "default",
"value": null
},
"min_cost": {
"ex_tax": "0.00",
"inc_tax": "0.00"
},
"max_cost": null,
"margin_percent": "15.00",
"min_cash_margin": null,
"channel_id": null,
"source": "manual"
}
]
}
]
}
/v1/min-margins/groups/{id}
margins:write
Delete a table and its bands. 204.
Parameters
id | Group id. |