Skip to content

Minimum margins

The profit floor every rule respects: the account default, cost bands, and product-group tables with their own bands.


Minimum Margins

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.

GET/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"
        }
      ]
    }
  ]
}
PATCH/v1/min-margins margins:write

Set the account default (0–100).

Request body

default_percentThe 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

POST/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_costLower cost edge, ex tax.
max_costUpper cost edge, ex tax (must be above min_cost).
margin_percent0–100.
min_cash_marginOptional £ floor.
group_idOptional 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"
        }
      ]
    }
  ]
}
PATCH/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

idBand 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"
        }
      ]
    }
  ]
}
DELETE/v1/min-margins/bands/{id} margins:write

Delete a band; costs it covered fall to the next band or the default. 204.

Parameters

idBand 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.

POST/v1/min-margins/groups margins:write

Create a table. It needs at least one supplier or tag.

Request body

nameRequired.
suppliersSupplier names.
tagsTag names.
tag_matchany (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"
        }
      ]
    }
  ]
}
PATCH/v1/min-margins/groups/{id} margins:write

Edit, reprioritise or switch a table on/off.

Parameters

idGroup id.

Request body

name
suppliers
tags
tag_match
priorityHigher wins.
enabledOff = 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"
        }
      ]
    }
  ]
}
DELETE/v1/min-margins/groups/{id} margins:write

Delete a table and its bands. 204.

Parameters

idGroup id.