Skip to content
OmniRetailConnect Docs
Main site Demo aanvragen

Commerce · Getting started

Overview

What the Commerce MCP server and REST API are, what they can and cannot do, and who sets them up.

View as Markdown

What it is

Every OmniRetail Commerce installation can offer two interfaces to the products, stock, orders, discount codes, pages and operational sales figures of that one installation:

Both live on the shop's own domain, for example https://<your-shop-domain>/mcp/commerce and https://<your-shop-domain>/api/v1. There is no shared, central endpoint. They serve the same capabilities: the data of each REST endpoint equals the structured result of the matching MCP tool, and tokens, scopes, masking and limits are shared.

What they can and cannot do

  • Read-only by default. A token without a write scope only reads: it cannot write shop data, delete, refund, import or send mail. The only outbound call of a read is the stock lookup for product and availability data, and only when the shop uses an external inventory provider.
  • Writes with separate scopes. The MCP server has forty-five write tools, and the REST API the same writes as endpoints: product content, SEO, web address, variants, properties, labels, prices, sale prices, price breaks, stock, new products, images, brands, the label set and the category tree (commerce.write.products, commerce.write.collections); discount codes (commerce.write.discounts); confirming an offline payment, cancelling an unpaid order, internal notes and shipments with track and trace (commerce.write.orders); and CMS pages (commerce.write.content). A write token created in the shop admin lives at most 30 days, and every change is recorded against the token. No tool refunds money, cancels a paid order or changes customers, and no tool deletes a product or the home page. See Write tools and the REST write endpoints.
  • Bearer tokens. Clients send a token in the Authorization header. There is no OAuth, no dynamic client registration and no login screen. A token is enabled for the interfaces it may use (its channels).
  • One installation. There is no store or tenant parameter: a token sees the data of the installation that issued it.
  • Off by default. Until OmniRetail switches an interface on for the shop, it does not exist: while it is switched off, GET answers the shop's normal 404 and POST, PUT, PATCH and DELETE answer 405 (Allow: GET, HEAD), as for any unknown path.
  • MCP for AI clients, REST for servers. The REST API sends no CORS headers, so it is for server-to-server use only; keep tokens on the server.

Who sets it up

OmniRetail switches the MCP server and the REST API on per shop. The shop owner creates tokens in the shop admin under Settings (Instellingen) > API tokens (API-tokens), see Authentication and tokens. Only shop administrators can do this. If you are an integrator or an AI client user, ask the shop administrator for the base URL and a token, and say which access level and channel you need.

What you can look up

The read capabilities on both interfaces:

Capabilities
MCP tool REST endpoint Purpose
search_products GET /products Find products by text, category or brand.
get_product GET /products/{id}, GET /skus/{sku} One product with its variants, prices and availability.
check_sku_availability GET /availability Bulk stock check for up to 50 SKUs.
search_orders GET /orders Find orders, newest first.
get_order GET /orders/{reference} One order with totals, lines, payment, fulfilment and refunds.
list_categories GET /categories The product category tree.
get_sales_summary GET /sales-summary Operational sales metrics for a date range.

Next steps

  1. Read Authentication and tokens to understand scopes, channels, expiry and how tokens are handled.
  2. Connect an AI client (Claude Code or any other client), call the REST API from your server, or let an AI agent set up the MCP connection from these docs.
  3. Before you connect a hosted AI service or another system to real order data, or give a client a write token, read Privacy and security.