Organization, store, and seller
How Admin and Storefront determine the scope of each request.
Commerce resources belong to an organization, a store, and, when applicable, a seller. The way you select that context depends on the API.
The three levels
Organization. Groups the account, plan, billing, users, and one or more stores.
Store. Isolates catalog, orders, customers, and settings. It gets an
*.ecomiq.app domain and may connect a custom domain.
Seller. Identifies who owns an offer inside a store. A simple store usually has one seller; a marketplace may have several.
How context is resolved
| API | Store | Seller |
|---|---|---|
| Admin | OAuth application and the token's store_id claim. | OAuth application and the token's seller_id claim. |
| Storefront | Request host: an *.ecomiq.app subdomain or custom domain. | Determined by the store configuration. |
| Auth | Does not use a commerce domain to select a store. | Depends on the application or identity requesting the token. |
A customer token on Storefront identifies the shopper when an operation needs one. It does not replace the domain that selects the store.
Admin context
An application bound to a store receives its authorized context in the token. Send that token as a bearer credential:
curl "https://api.ecomiq.pe/api/v1/catalog/products?limit=25" \
-H "Authorization: Bearer $ECOMIQ_TOKEN"The store_id and seller_id claims, when present, identify the authorized
store and seller. To change stores, request a token with the OAuth application
created for that other context.
Storefront context
Storefront resolves the store from the host:
curl "https://mystore.ecomiq.app/api/v1/products?page=1&pageSize=24"Use the assigned subdomain or the store's custom domain. Admin credentials do not select a public store.
Identifiers and isolation
An identifier is only useful inside its owning context. If a product exists but the request uses another store or seller, the operation must not expose it.
Check the context
After a 403 or 404, verify the token, OAuth application, or Storefront
domain before assuming the resource was deleted.
You cannot move a resource between stores by changing its identifier. To replicate data, create or import the resource in the target store.
Multiple stores
Do not assume one token can operate on several stores. An OAuth application is usually bound to one store and seller.
For another store, create an OAuth application with explicit access in that store and request a token with its credentials. Changing the domain does not change Admin context.
Marketplaces
In Admin, the authorized seller belongs to the application's context and, when
applicable, appears in the seller_id claim. No query parameter expands this
scope.
In Storefront, the store and its configuration determine which offers are published. A shopper session cannot select an administrative seller.