Price Books API

Use the Developer Platform price books endpoints to manage marketplace channel list-price markup rules. Semantics match the workspace Price book UI (/app/{organizationId}/pricebook) and the OmniBot manage_price_book tool. Price books do not change canonical product prices in Omni. They rewrite channel list price at publish/catalog time by platform (and optional store/country).

Authentication

Send an OmniCommerce API key or OAuth client-credentials token:

Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

Endpoint	Required scope
`GET /api/v1/price-books`	`price_books:read`
`GET /api/v1/price-books/{ruleId}`	`price_books:read`
`POST /api/v1/price-books/preview`	`price_books:read`
`POST /api/v1/price-books`	`price_books:write`
`PATCH /api/v1/price-books/{ruleId}`	`price_books:write`
`DELETE /api/v1/price-books/{ruleId}`	`price_books:write`

OAuth clients must include the scope on the client. API keys created from organization settings receive all developer scopes by default. Session-authenticated calls must include organizationId in the query (GET) or JSON body (writes). OpenAPI reference: API reference · Spec: openapi.json

List rules

GET /api/v1/price-books

Query parameters

Parameter	Description
`organizationId`	Organization scope for session auth. Optional for single-org OAuth/API keys.
`platform`	Filter: `shopee`, `lazada`, `tiktok`, `shopify`, or `whatsapp`.
`enabledOnly`	When `true`, only enabled rules.

Response

{
  "rules": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "organizationId": "org_1",
      "platform": "shopee",
      "storeId": null,
      "country": "singapore",
      "base": "list_price",
      "marginType": "markup_percent",
      "marginValue": 10,
      "rounding": "currency_minor",
      "currency": "SGD",
      "enabled": true,
      "createdAt": "2026-07-01T00:00:00.000Z",
      "updatedAt": "2026-07-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

Create rule

POST /api/v1/price-books

Request body

{
  "platform": "shopee",
  "marginValue": 10,
  "country": "singapore",
  "rounding": "currency_minor",
  "currency": "SGD",
  "enabled": true
}

Field	Notes
`platform`	Required. `shopee`, `lazada`, `tiktok`, `shopify`, or `whatsapp`
`marginValue`	Required markup percent (0–500)
`storeId`	Optional store scope; omit/`null` = all stores for platform
`country`	Optional country scope
`rounding`	`none`, `currency_minor` (default), `nearest_0_05`, `nearest_1`
`currency`	Optional ISO 4217 for `currency_minor` rounding
`enabled`	Defaults to `true`

Scope uniqueness: one rule per platform + storeId + country combination. Returns 201 with { "rule": { ... } }.

Get / update / delete

GET    /api/v1/price-books/{ruleId}
PATCH  /api/v1/price-books/{ruleId}
DELETE /api/v1/price-books/{ruleId}

Update accepts partial fields (storeId, country, marginValue, rounding, currency, enabled). Platform cannot be changed after create.

Preview channel list price

POST /api/v1/price-books/preview

{
  "platform": "shopee",
  "listPrice": 100,
  "country": "singapore",
  "currency": "SGD"
}

Optional ruleId forces a specific rule instead of most-specific matching.

Response

{
  "listPrice": 100,
  "channelListPrice": 110,
  "applied": true,
  "source": "price_book",
  "markupPercent": 10,
  "rule": { "id": "…", "platform": "shopee", "marginValue": 10 }
}

When no enabled rule matches, applied is false, source is canonical, and channelListPrice equals listPrice.

Matching priority

Most specific enabled rule wins for a given platform/store/country:

platform + store + country
platform + store
platform + country
platform only

Workspace UI: /app/{organizationId}/pricebook
OmniBot tool: manage_price_book (default Omnibot tool)
Product base price writes: POST /api/v1/sync (see API reference) or workspace product price update
Promotions (discounts/campaigns): Promotions API

Get started

Guides

MCP

Authentication

List rules

Query parameters

Response

Create rule

Request body

Get / update / delete

Preview channel list price

Response

Matching priority

​Authentication

​List rules

​Query parameters

​Response

​Create rule

​Request body

​Get / update / delete

​Preview channel list price

​Response

​Matching priority

​Related

Authentication

List rules

Query parameters

Response

Create rule

Request body

Get / update / delete

Preview channel list price

Response

Matching priority

Related