Configure Retailer Switching and Default Retailer in Fluent OMS

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Fluent Commerce

Changed on:

26 Feb 2026

Key Points

Retailer switching requires both manifest configuration and retailer context assignment to the user.
The switcher is visible only to users with multiple assigned retailer contexts.
Devices can automatically open Fluent OMS in a predefined retailer using a URL parameter.
URL-based configuration does not override role-based access permissions.

Steps

Enable Retailer Switcher in the Manifest

Retailer switching is controlled through the OMS manifest setting.Navigate to:OMS → Settings → `fc.mystique.manifest.oms`Ensure the manifest includes a `context` section similar to the following.

1{
2    "context": {
3        "level": "retailer",
4        "role": [
5      "ADMIN"
6    ],
7        "switcher": true
8    }
9}

Recommended practice

Enable retailer switching only for roles that require multi-retailer operations to reduce UI complexity and the risk of working in the wrong retailer.

Assign Retailer Contexts to User Roles

The switcher appears only if the user has access to multiple retailers.You need to assign retailer contexts to the user role.

Verify Existing User Contexts

Use GraphQL to confirm the user has multiple retailer contexts assigned.

1query userById ($id: ID!) {
2    userById (id: $id) {
3        id
4        ref
5        username
6        roles {
7            contexts {
8                contextId
9                contextType
10            }
11        }
12    }
13}

Add Retailer Context to a User

If required, update the user role configuration.

1mutation updateUser ($input: UpdateUserInput) {
2  updateUser (input: $input) {
3    id
4    ref
5    username
6    roles {
7      contexts {
8        contextId
9        contextType
10      }
11      role {
12        name
13      }
14    }
15  }
16}
17
18Variables Example:
19{
20  "input": {
21    "id": 33333,
22     "roles": {
23      "role": {
24        "name": "ADMIN"
25      },
26     "contexts": [
27        {
28          "contextType": "RETAILER",
29          "contextId": "123"
30        },
31        {
32          "contextType": "RETAULER",
33          "contextId": "321"
34        }
35      ]
36    }
37  }
38}
39

Note

The retailer switcher is visible only if the user has more than one assigned `RETAILER` context.

Configure a Predefined Retailer Using a URL Parameter

If needed to reduce the risk of working in the wrong retailer, Fluent OMS can be configured to automatically open in a predefined retailer when the application loads.To ensure a device always opens Fluent OMS in the correct retailer, append the `user.retailer.ref` parameter to the application URL.The parameter format is:
`user.retailer.ref=<RETAILER_REF>`Example:
`https://<oms-app-url>?user.retailer.ref=123`When `user.retailer.ref` is provided:

The specified retailer is automatically applied on application load.
No manual interaction is required.
The predefined retailer is applied independently of the logged-in user.
Standard permission checks are still enforced.

Understand Context Resolution

When Fluent OMS loads, the active retailer is determined in the following order:

`user.retailer.ref` provided in the URL
Previously selected location (from the user's previous session)
First accessible retailer from the user’s assigned retailer list

If no URL parameter is provided, the system applies the previously selected retailer, or the first assigned retailer if no prior selection exists.

Access Restriction and Fallback Behavior

If a user does not have permission to access the retailer specified via `user.retailer.ref`:

The system automatically switches the user to a retailer they are authorized to access.

The fallback retailer follows the standard context resolution logic described above.

Important

The `user.retailer.ref` parameter defines only the initial context. It does not override role-based access control.

Configure Retailer Switching and Default Retailer in Fluent OMS

Key Points

Steps

Enable Retailer Switcher in the Manifest

Assign Retailer Contexts to User Roles

Verify Existing User Contexts

Add Retailer Context to a User

Configure a Predefined Retailer Using a URL Parameter

Understand Context Resolution

Access Restriction and Fallback Behavior

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links