Skip to content

Requests, responses and conventions

Base URL and versioning, JSON shapes, pagination and change polling, the money object, errors, rate limits, idempotency and request ids.


Base URL

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.

Identifiers

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.

Pagination

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
}
Change Polling

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
Prefer polling to scraping the whole catalogue. A nightly full read of 30,000 products is 150 requests; the same run with updated_since is usually a handful. Webhooks are on the roadmap for the events that should not wait for a poll.
Expansion

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.

Money

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.

Time

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.

Errors

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"
  }
}
HTTPMeaning
400Malformed request or invalid parameter (bad_request). The message says which.
401No key, unknown key, key_revoked or key_expired.
403The key or workspace is not allowed: insufficient_scope, api_not_enabled, writes_not_enabled, module_not_enabled, workspace_disabled, ip_not_allowed.
404Not found in this workspace, including ids that belong to another workspace.
409Idempotency-Key reused with a different body.
429Rate limited. Wait for Retry-After seconds.
503Pricemaster is deploying an update (a few seconds). Retry after Retry-After.
500Our fault. Quote the request_id to support.

Error codes

CodeMeaning
unauthorisedNo usable API key was sent. Send `Authorization: Bearer pmk_live_…`.
key_revokedThe key has been revoked.
key_expiredThe key has passed its expiry date.
api_disabledThe API is switched off for the moment (maintenance).
api_not_enabledThe API is not enabled for this workspace. Ask Pricemaster to switch it on.
workspace_disabledThe workspace is disabled.
insufficient_scopeThe key does not carry the scope this endpoint needs.
writes_not_enabledWrite access is not enabled for this workspace.
pushes_not_enabledPrice pushes by API are not enabled for this workspace.
push_refusedThe store push gate refused the request (the message says why: store not live, trial limit, push in flight, nothing to send…).
module_not_enabledThe feature this endpoint reads is not enabled for the workspace.
ip_not_allowedThe request came from an address outside the key's allow-list.
bad_requestThe request is malformed or a parameter is invalid.
not_foundNo such resource in this workspace.
conflictThe Idempotency-Key was already used with a different request body.
rule_lockedThe rule is part of a running A/B test and cannot be changed until the test ends.
validation_failedThe request is well-formed but a value is not acceptable (the message says why).
rate_limitedToo many requests. Wait for the window to reset and retry.
server_errorSomething went wrong on our side. Quote the request id to support.
Rate Limits

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.

BucketPer minutePer day
read600100,000lists and single reads
write12020,000PATCH requests
engine6010,000recommendation (runs the pricing engine)
history30050,000price history ranges
Idempotency

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.

OpenAPI

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.

  1. In Postman choose Import, paste https://api.pricemaster.ai/postman.json as a link, and confirm. (Bruno, Insomnia and Hoppscotch import the same file.)
  2. 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.
  3. Send Workspace → GET /me. It confirms the key and lists its scopes.
  4. Send Products → List products, copy an id into the product_id variable, and every product request uses it. rule_id, tag_id, listing_id, push_id, band_id and group_id work 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.