Fluent Commerce Logo
Docs

GraphQL Permissions

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.