Essential knowledgeCore knowledge to understand Fluent Commerce
Intended Audience:
Technical User
Authors:
Fluent Commerce, Kirill Gaiduk
Changed on:
31 Aug 2026
Overview
The GraphQL Permissions define the access rights that control every operation in the Fluent platform’s GraphQL API. Each permission represents a single, specific action a user can perform on an entity, ensuring secure access management across all services.By assigning permissions to roles, organizations can control user capabilities at a granular level. This ensures that users only access and modify data relevant to their role and business context.
Key points
Permission Structure: GraphQL queries and mutations are secured by permissions that follow the ENTITY_ACTION naming convention (for example, ORDER_VIEW, ORDER_UPDATE). This ensures precise and predictable access control across all API operations
Nested and Partial Mutations: Nested mutations require separate permissions. Partial mutations are not allowed — if one permission check fails, the entire operation is rolled back
Plugin Management Access: Plugin-related operations are governed by specific permissions such as PLUGIN_VIEW, PLUGIN_UPLOAD, and PLUGIN_INSTALL. Only users with these permissions can manage plugin
Error Handling and Troubleshooting: Operations attempted without proper permissions return the error code C0020E. Users must obtain the required permissions before retrying the operation
Analytics Permissions: Domain-level permissions (for example, ORDER_REPORT, INVENTORY_REPORT) control access to analytics capabilities across business domains via the GraphQL API.
Naming Convention
Permissions follow a NOUN_VERB naming convention (for example, `ORDER_UPDATE`) and align with common actions such as:
VIEW - allows querying data
CREATE - allows creating new records
UPDATE - allows modifying existing records
In addition, domain-level analytics permissions follow the `<<DOMAIN>>_REPORT` pattern to control access to analytics capabilities for specific business domains.
Viewing All Permissions
The complete list of GraphQL permissions available in the Fluent platform can be retrieved using the `permissions` query.
Query Permissions
Query permissions on entities follow the `<<ENTITY>>_VIEW` naming convention. For example:
The Order entity is protected by the `ORDER_VIEW` permission
The Location entity is protected by the `LOCATION_VIEW` permission
Use the `permissions` query with the `name` filter to retrieve all query-related permissions.
Analytics Report Permissions
Analytics report permissions control access to analytics capabilities by business domain.The following permissions are available:
`ORDER_REPORT` -> access to Order-related analytics, including Orders, Fulfilments, and Returns analytics
`INVENTORY_REPORT` -> access to Inventory analytics
Mutation Permissions
Create, update and remove operations are protected by the `<<ENTITY>>_CREATE`, `<<ENTITY>>_UPDATE`, and `<<ENTITY>>_REMOVE` permissions, respectively. For example:
Use the `permissions` query to retrieve the mutation permissions lists using the following `name` filters:
`name: ["%_CREATE"]`
`name: ["%_UPDATE"]`
`name: ["%_REMOVE"]`
Nested Mutations
All nested mutation operations require their own permissions, based on the entity being modified. For example:The `updateLocation` mutation supports nested updates such as:
Each nested input type within a mutation requires its corresponding permission to execute successfully.
Partial Mutations
Partial mutations are not allowed.If a mutation fails due to a missing or invalid permission, the entire operation will fail and return an error.For example, when updating a location’s opening schedule using the `updateLocation` mutation, both permissions are required:
`LOCATION_UPDATE`
`OPENINGSCHEDULE_UPDATE`
If the second permission is missing, the entire mutation fails, even if the first permission is valid.
Plugin Permissions
Plugin management operations are controlled by the following permissions:
`PLUGIN_VIEW`
`PLUGIN_UPLOAD`
`PLUGIN_INSTALL`
Error Handling
Error Code: C0020EDescription: The user does not have the required permission for the attempted operation.Possible Cause: The permission is missing or incorrect.Solution: Contact your administrator or support team to obtain the necessary permissions.
Every GraphQL operation is protected by a corresponding permission. Ensure the required permissions are configured before executing any GraphQL queries or mutations.
Reminder
Ensure the `PERMISSION_VIEW` permission is assigned to your user’s role before proceeding.
`Error code: C0020E Error message: Your request failed due to insufficient permissions. You will need OPENINGSCHEDULE_UPDATE for executing this request. Please contact your support to get the required permissions and try again.`
Parameter Limitation
The values for the `first` and `last` parameters of a query must be within 1 - 5,000.If the specified value exceeds 5,000, it will automatically be replaced by 5,000.