Configure Location Switching and Default Location in Fluent Store

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Fluent Commerce

Changed on:

26 Feb 2026

Key Points

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

Prerequisites

Enable Fluent Store on your Existing Account

Steps

Enable Location Switcher in the Manifest

The location switcher is controlled through the `fc.mystique.manifest.store` setting.Navigate to:Fluent OMS → Settings → `fc.mystique.manifest.store`Ensure the manifest includes a `context` section similar to the following:

1{
2  "context": {
3    "level": "location",
4    "role": [
5      "STORE",
6      "STORE_ASSISTANT"
7    ],
8    "switcher": true
9  }
10}

Recommended practice

Only enable the switcher for roles that require multi-location access to reduce unnecessary UI complexity.

Assign Location Contexts to User Roles

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

Verify Existing User Contexts

Use GraphQL to confirm the user has multiple location 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 Location 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": "STORE"
25      },
26      "contexts": [
27        {
28          "contextType": "AGENT",
29          "contextId": "123"
30        },
31        {
32          "contextType": "AGENT",
33          "contextId": "321"
34        }
35      ]
36    }
37  }
38}
39

Note

The user must have more than one location context assigned for the switcher to appear.

Configure a Predefined Location Using URL Parameter

If each physical store uses dedicated devices, Fluent Store can automatically open in a predefined location when the application loads.To ensure a device always opens Fluent Store in the correct location, you can append the `user.location.ref` parameter to the application URL. This allows location-specific devices to be configured with a predefined default context.The parameter format is:`user.location.ref=<LOCATION_REF>`For example:`https://<store-app-url>?user.location.ref=5000299_SYD`When `user.location.ref` is provided:

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

Understand Context Resolution

When Fluent Store loads, the active location is determined in the following order:

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

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

Access Restriction and Fallback Behavior

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

The system automatically switches the user to an authorized location.

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

Important

The `user.location.ref` parameter defines only the initial context. It does not override role-based access control. User permissions are always enforced.

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Enable Location Switcher in the Manifest

1{
2  "context": {
3    "level": "location",
4    "role": [
5      "STORE",
6      "STORE_ASSISTANT"
7    ],
8    "switcher": true
9  }
10}

Recommended practice

Only enable the switcher for roles that require multi-location access to reduce unnecessary UI complexity.

Assign Location Contexts to User Roles

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

Verify Existing User Contexts

Use GraphQL to confirm the user has multiple location 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 Location 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": "STORE"
25      },
26      "contexts": [
27        {
28          "contextType": "AGENT",
29          "contextId": "123"
30        },
31        {
32          "contextType": "AGENT",
33          "contextId": "321"
34        }
35      ]
36    }
37  }
38}
39

Note

The user must have more than one location context assigned for the switcher to appear.

Configure a Predefined Location Using URL Parameter

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

Understand Context Resolution

When Fluent Store loads, the active location is determined in the following order:

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

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

Access Restriction and Fallback Behavior

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

The system automatically switches the user to an authorized location.

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

Important

The `user.location.ref` parameter defines only the initial context. It does not override role-based access control. User permissions are always enforced.

Configure Location Switching and Default Location in Fluent Store

Key Points

Prerequisites

Enable Fluent Store on your Existing Account

Steps

Enable Location Switcher in the Manifest

Assign Location Contexts to User Roles

Verify Existing User Contexts

Add Location Context to a User

Configure a Predefined Location Using URL Parameter

Understand Context Resolution

Access Restriction and Fallback Behavior

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links

Enable Location Switcher in the Manifest

Assign Location Contexts to User Roles

Verify Existing User Contexts

Add Location Context to a User

Configure a Predefined Location Using URL Parameter

Understand Context Resolution

Access Restriction and Fallback Behavior