Requests, responses and conventions
Base URL and versioning, JSON shapes, pagination and change polling, the money object, errors, rate limits, idempotency and request ids.
https://api.pricemaster.ai/v1
All endpoints live under /v1, over HTTPS only. Within v1 changes are additive: new fields, new endpoints, new optional parameters, new enum values (treat enums as open). A breaking change would ship as /v2 with at least six months of overlap, announced on this page and by email to every workspace with a live key.
Requests and responses are JSON (application/json; charset=utf-8). Request bodies may be up to 1 MB.
Ids are integers; SKUs are strings
Products, rules, tags, sellers, listings and pushes are addressed by their Pricemaster id, an integer that never changes. Products can also be looked up by SKU at /v1/products/by-sku/{sku}, matched without regard to case or punctuation. Every product carries a psin: the global Pricemaster product identity it is matched to, shared across all customers who sell the same item. It is read-only and useful for telling that two of your SKUs are one product.
An id that belongs to another workspace is not found (404), never forbidden: the API does not reveal what exists elsewhere.
Cursor paging on every list
Lists take limit (default 50, maximum 200) and cursor. Each page carries next_cursor and has_more; pass the cursor back unchanged to get the next page. Cursors are opaque and specific to the list and filters that produced them.
GET /v1/products?limit=200
GET /v1/products?limit=200&cursor=eyJpZCI6NDgyMTN9
{
"currency": "GBP",
"tax_rate": "20.00",
"data": [
"…200 products…"
],
"next_cursor": "eyJpZCI6NDg0MTN9",
"has_more": true
}
Fetch only what changed with updated_since
Product listing accepts updated_since=<ISO-8601>. The order then becomes (updated_at, id) and the pages carry every product changed at or after that time, including changes to price, cost, stock, match and settings. Store the time you started the run and use it as the next run's updated_since.
GET /v1/products?updated_since=2026-10-25T06:00:00Z&limit=200&expand=rule
Avoid N+1 with expand
Product lists accept expand=rule,tags to include each product's pricing rule and tags in the same response. Single-product reads always include both.
Every price carries both tax bases
Pricemaster stores prices ex tax. The API never makes you guess which basis a figure is in: every monetary attribute is an object with both, as decimal strings (two places; four for cost), and every response names the currency and the workspace's tax rate.
{
"currency": "GBP",
"tax_rate": "20.00",
"data": {
"price": {
"ex_tax": "41.66",
"inc_tax": "49.99"
},
"cost": {
"ex_tax": "31.2500",
"inc_tax": "37.5000"
}
}
}
Products flagged taxable: false (zero-rated goods) have equal ex_tax and inc_tax. Competitor prices are the seller's price converted to the same two bases with your workspace's rate, so they compare directly with yours. null means unknown.
When you send money (PATCH /v1/products/{id}) a bare number is taken as ex tax; {"ex_tax": 41.66} or {"inc_tax": 49.99} are accepted too and converted for you.
UTC, ISO-8601
Timestamps are ISO-8601 in UTC with a Z suffix (2026-10-26T05:41:09.000Z); history rows are dated YYYY-MM-DD. Query parameters accept either form.
One error shape, stable codes
{
"error": {
"code": "insufficient_scope",
"message": "This endpoint needs the \"market:read\" scope; the key does not carry it.",
"details": {
"required": "market:read",
"granted": [
"workspace:read",
"products:read"
]
},
"request_id": "req_7f3a9c1d2e4b6a8f9c0d1e2f"
}
}
| HTTP | Meaning |
|---|---|
| 400 | Malformed request or invalid parameter (bad_request). The message says which. |
| 401 | No key, unknown key, key_revoked or key_expired. |
| 403 | The key or workspace is not allowed: insufficient_scope, api_not_enabled, writes_not_enabled, module_not_enabled, workspace_disabled, ip_not_allowed. |
| 404 | Not found in this workspace, including ids that belong to another workspace. |
| 409 | Idempotency-Key reused with a different body. |
| 429 | Rate limited. Wait for Retry-After seconds. |
| 503 | Pricemaster is deploying an update (a few seconds). Retry after Retry-After. |
| 500 | Our fault. Quote the request_id to support. |
Error codes
| Code | Meaning |
|---|---|
unauthorised | No usable API key was sent. Send `Authorization: Bearer pmk_live_…`. |
key_revoked | The key has been revoked. |
key_expired | The key has passed its expiry date. |
api_disabled | The API is switched off for the moment (maintenance). |
api_not_enabled | The API is not enabled for this workspace. Ask Pricemaster to switch it on. |
workspace_disabled | The workspace is disabled. |
insufficient_scope | The key does not carry the scope this endpoint needs. |
writes_not_enabled | Write access is not enabled for this workspace. |
pushes_not_enabled | Price pushes by API are not enabled for this workspace. |
push_refused | The store push gate refused the request (the message says why: store not live, trial limit, push in flight, nothing to send…). |
module_not_enabled | The feature this endpoint reads is not enabled for the workspace. |
ip_not_allowed | The request came from an address outside the key's allow-list. |
bad_request | The request is malformed or a parameter is invalid. |
not_found | No such resource in this workspace. |
conflict | The Idempotency-Key was already used with a different request body. |
rule_locked | The rule is part of a running A/B test and cannot be changed until the test ends. |
validation_failed | The request is well-formed but a value is not acceptable (the message says why). |
rate_limited | Too many requests. Wait for the window to reset and retry. |
server_error | Something went wrong on our side. Quote the request id to support. |
Per key, per minute and per day
Each endpoint belongs to a bucket. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the minute window; a 429 adds Retry-After. Limits can be raised for a workspace on request.
| Bucket | Per minute | Per day | |
|---|---|---|---|
read | 600 | 100,000 | lists and single reads |
write | 120 | 20,000 | PATCH requests |
engine | 60 | 10,000 | recommendation (runs the pricing engine) |
history | 300 | 50,000 | price history ranges |
Safe retries on writes
Send an Idempotency-Key header (8–128 characters of your choosing, unique per operation) on any write. If the request is retried with the same key and body within 24 hours you receive the original response again, marked Idempotent-Replayed: true, and nothing is applied twice. The same key with a different body is refused with 409.
Every response carries Pricemaster-Request-Id. Log it with your own records: it is the fastest way for support to find a request.
Generate a client from the live description
https://api.pricemaster.ai/openapi.json describes the deployed build in OpenAPI 3.1, including every scope, parameter and response shape on these pages. Import it into Postman or Bruno, or generate a typed client (for example openapi-typescript for TypeScript). GET /v1/health answers {"ok":true} without a key for your monitoring.
Postman: every endpoint in one import
https://api.pricemaster.ai/postman.json is a Postman collection (v2.1) generated from the same description, so it always matches the deployed build. It needs no key to download.
- In Postman choose Import, paste
https://api.pricemaster.ai/postman.jsonas a link, and confirm. (Bruno, Insomnia and Hoppscotch import the same file.) - Open the collection's Variables tab and paste your key into
api_key(current value). Bearer authentication is already wired to it, so no request needs editing. - Send Workspace → GET /me. It confirms the key and lists its scopes.
- Send Products → List products, copy an
idinto theproduct_idvariable, and every product request uses it.rule_id,tag_id,listing_id,push_id,band_idandgroup_idwork the same way.
Each request carries its scope and a short description; write requests come with a valid example body to edit, and an optional Idempotency-Key header you can switch on. A test on every response stores the Pricemaster-Request-Id in last_request_id for support. Keep the key in the collection variable only: never export the collection with the key filled in.