Merchant, Store, Catalog, and Enrichment Guide
ACP separates agent runtime configuration from merchant commerce data. Realms, merchants, and stores are independent authorization boundaries and must not be treated as interchangeable identifiers.
Isolation Model
| Boundary | Owns | Managed from |
|---|---|---|
| Realm | Runtime identities, prompts, agents, flows, realm AI providers, downstream MCP servers, sessions, and runtime usage. | Realm Dashboard |
| Merchant | Merchant team, merchant access, developer API keys, stores, and enrichment provider registry. | Merchant Dashboard |
| Store | Products, carts, orders, Catalog integrations, enrichment jobs, runs, and store-specific enrichment usage. | Store Dashboard |
A merchant does not belong to a realm. Granting a user access to a realm does not grant access to a merchant, and merchant access does not grant access to realm runtime resources.
Manager Navigation
The global Manager navigation contains Realms, Merchants, and Access. Access is divided into Team Management, Realm Access, and Merchant Access.
Each merchant has its own dashboard with:
- Dashboard
- Stores
- Team Management
- Developers
Merchant Team Management separates active members from invited users. Operators can add a new or already registered user, invite a user, change an eligible member role, remove a member, or revoke an invitation. Primary-owner access is protected.
The Merchant Developers page is the source for merchant API keys. The former global Developers workflow is not used for merchant Catalog credentials. Realm Engine credentials remain under the selected realm's identity area.
Merchant and Store Setup
Merchant creation uses one merchant type and collects operational profile data such as name, description, website, industry, company size, contact email, timezone, and language. There is no package or plan selection in this flow.
Merchant and store language options are English, Turkish, Azerbaijani, Arabic, Spanish, French, German, Italian, Portuguese, Russian, Chinese, and Japanese. Store currencies are USD, EUR, TRY, and AZN.
Each store dashboard exposes:
- Catalog: Overview, Products, Carts, Orders, and Integrations.
- Enrichment: Instant, Jobs, Prompts, AI Providers, and Usage.
Google UCP, Extensions, and Marketplace integration methods are not part of this ACP store surface.
Merchant API Keys and Store Scope
Create merchant API keys from Merchant Dashboard > Developers. A key has one of these scopes:
| Scope | Access |
|---|---|
merchant | Every store owned by the merchant. |
store | One selected store. |
custom | The selected set of stores in the key access configuration. |
Send the key in one of these forms:
Authorization: Bearer {{merchant_api_key}}
x-api-key: {{merchant_api_key}}
The Auth service validates the key and returns its merchant and allowed-store scope through /api/v1/auth/verify and /api/v1/auth/introspect. Catalog uses that result for every store-scoped operation. A valid key for one merchant or store cannot be used to cross into another merchant or an unassigned store.
Catalog
Catalog data is isolated by both merchant_id and store_id. Products, carts, orders, and integrations are managed from the selected store dashboard and can also be accessed through the Catalog REST API or built-in Catalog MCP tools.
Use stable sku or externalId values for product synchronization. Cart items use the product's 10-digit Catalog ID, and order completion uses the checkout ID returned by cart creation.
The normal public REST boundary is ACP Engine at /api/v1/catalog/*. Catalog is also capable of validating merchant API keys directly through Auth. A deployment may therefore expose a dedicated Catalog ingress for approved merchant integrations, but it must be an explicit deployment decision with TLS, network controls, rate limits, and the same Auth integration. The Docker Compose service port 8086 remains private by default.
Enrichment Providers and Usage
Enrichment providers are configured from Store Dashboard > Enrichment > AI Providers, but the provider registry belongs to the merchant. Providers are shared by stores of the same merchant and are isolated from both other merchants and realm runtime AI providers.
Each provider includes a name, description, provider type, endpoint, credential, text and image capabilities, models, pricing, currency, default status, and active status. One provider can support text, image generation, or both. Thyris-managed internal providers are not shown in this customer-managed list.
Store-scoped Enrichment Prompts define reusable instructions, output language, and the product fields a job may edit. Select one prompt when creating a job. A prompt edit applies to later runs; deactivating it pauses its active jobs. The prompt field list overrides the legacy job text-field list. These prompts are distinct from realm behavior prompts.
Instant enrichment and scheduled jobs select an active provider from the merchant registry. Jobs, runs, and usage remain store-specific. Enrichment token, image, and estimated-cost usage is counted separately from realm runtime AI usage.
The Enrichment service is an internal Manager/worker service and is not a customer-facing REST surface. See Store Enrichment for supported fields and job behavior.
REST and MCP Authentication Choices
Use a realm-bound service identity for Engine runtime tools and realm resources. Use a merchant API key for built-in Catalog tools and merchant/store Catalog operations.
The unified mcp-service accepts merchant keys through Authorization: Bearer or x-api-key for Catalog tools. Legacy realm headers remain available for realm-bound Engine tools and legacy compatibility:
X-ACP-Realm-ID: {{realm_id}}
X-ACP-Access-Key: {{service_access_key}}
X-ACP-Secret-Key: {{service_secret_key}}
Do not substitute a realm ID for a merchant or store ID in new integrations.