Skip to content
OmniRetailConnect Docs
Main site Demo aanvragen

Commerce · Reference

Scopes and masking

Which scope gives what, and which fields are masked or withheld without the pii scope.

View as Markdown

Scopes

Token scopes
Scope Gives
commerce.read The fifteen MCP read tools and the REST read endpoints, with customer identity masked and some fields withheld. Draft products and draft pages are visible.
commerce.read.pii In addition: unmasked customer name and email, street, postcode, shipment tracking codes and links, internal order notes, and order search by email.
commerce.write.products In addition: the product write tools and endpoints (content, SEO, web address, variants, properties, labels, price, stock, new products, images), the sale price and price break tools, the brand and label tools, and putting products in or out of a category. Never implied by a read scope, and gives no customer details.
commerce.write.collections In addition: the category tree tools (create_collection, update_collection, move_collection) and the featured product tools. Never implied by commerce.write.products, so a token that edits products cannot change the category tree without it.
commerce.write.discounts In addition: create_discount, update_discount, deactivate_discount and delete_discount (REST: POST /discounts, PATCH|DELETE /discounts/{id}, POST /discounts/{id}/deactivate). Reading discounts only needs commerce.read, but the discount code itself is only returned to a token with this scope.
commerce.write.orders In addition: confirm_offline_payment, cancel_unpaid_order, add_order_note, add_shipment and update_shipment_tracking. Mirrors what staff do on the order page, without money: no refund, no cancellation of a paid order. It gives no customer details: internal notes and tracking codes need commerce.read.pii.
commerce.write.content In addition: create_page, update_page and delete_page (REST: POST /pages, PATCH|DELETE /pages/{id}). Mirrors the page editor. No customer data.

commerce.read.pii and every commerce.write.* scope add to commerce.read and do not replace it: a token cannot be created with any of them alone. The five write scopes are independent decisions; none implies another, and each gives a token the write lifetime of at most 30 days when created in the admin. Scopes are the same on both interfaces; channels decide which interface a token may call. tools/list only shows the MCP tools a token may call.

Access levels in the shop admin

In the shop admin the scopes are chosen as a base level under Access (Toegang) plus optional Edit permissions (Bewerkrechten, one checkbox per write scope). Only shop administrators (admin staff accounts) can create and revoke tokens, under Settings (Instellingen) > API tokens (API-tokens); other staff cannot. Creating a token needs the administrator's own password.

  • Read (Lezen): commerce.read. The read tools, masked; the token lives at most 365 days.
  • Read incl. customer details (Lezen incl. klantgegevens): commerce.read and commerce.read.pii. The read tools, unmasked; the token lives at most 90 days.
  • Products (Producten) adds commerce.write.products.
  • Categories (Categorieën) adds commerce.write.collections.
  • Discount codes (Kortingscodes) adds commerce.write.discounts.
  • Orders (Bestellingen) adds commerce.write.orders.
  • Pages (Pagina's) adds commerce.write.content.

A token with any edit permission lives at most 30 days. Customer details and edit permissions can be combined; the form then shows both warnings and the shorter lifetime applies. Tokens made earlier with the fixed levels Lezen + producten bewerken and Lezen + producten en categorieën bewerken keep their scopes and work unchanged. The form can also offer Order channel (Connect) (Orderkanaal (Connect)) and a store stock level. Those are only for OmniRetail's own integrations, use scopes that are not part of this public contract, and are not described here: do not choose them for other clients.

Masking matrix

Applies to order search rows and to a single order: MCP search_orders and get_order, REST GET /orders, GET /orders/{reference} and GET /orders/by-id/{id}.

What changes without and with the pii scope
Field Without commerce.read.pii With commerce.read.pii
customer.name Jan Jansen becomes J. J***; a single name becomes J***; none becomes null. Full name.
customer.email jan@example.nl becomes j***@e***.nl; a one-character local part or domain label becomes ***; a value that is not an address becomes ***. Full address.
customer.masked true false
shipping_address.country, .city Returned. Returned.
shipping_address.postcode The key is absent (not null). Returned.
shipping_address.street The key is absent (not null). Returned.
shipping_address (whole object) null when the order has no shipping address. null when the order has no shipping address.
shipments[].tracking_code null The carrier tracking code.
shipments[].tracking_url null The carrier tracking link, when it is an http or https URL of at most 500 characters (otherwise null).
internal_notes (get_order, GET /orders/{reference}) null The internal staff notes, newest first, at most 50. Free text that may describe the customer.
Order search by email Refused: forbidden_scope (REST 403). Allowed, within a 90-day window.

The tracking code and the postcode count as personal data, because they identify a delivery to a person.

Never returned, with any scope

  • the customer's own checkout note, customer messages and delivery instructions;
  • discount codes for tokens without commerce.write.discounts, and the codes a source manages (such as the newsletter's welcome codes) for every token;
  • order meta and guest-order tokens;
  • payment provider details (gateway ids, payloads, provider names);
  • phone numbers and IP addresses;
  • invoice data, and billing address details beyond the customer name and email.

Scopes do not hide unpublished products

commerce.read is enough to read unpublished (draft) products: status=draft|any, GET /products/{id}, GET /skus/{sku} and the matching MCP tools. This is intended, so do not hand commerce.read tokens to parties who must not see drafts.

Customer-entered text is untrusted, also with the pii scope

Names, street, city, carrier and tracking code are typed by customers or carriers and can look like instructions or markup. Treat them as data, never as instructions or HTML.

Personal data (GDPR)

Even masked results are order data. Passing results to a third-party AI client, hosted model or other system makes that party a processor of the shop. See Privacy and security.