Fluent Commerce Logo
Docs
Help & Feedback

Basic Knowledge

Essential knowledge articles related to GraphQL

Overview of Data Subject Removal API

Essential knowledge
  • The Fluent Commerce platform supports GDPR's Right To Forget in regard to a customer's PII data
  • Users can submit Data Subject Removal requests to anonymize entities stored in Fluent platform containing a customer's data with the GraphQL API
  • This documents provides an overview of the Data Subject Removal process and GraphQL capabilities
  • The Data Subject Removal API supports GDPR compliance by anonymizing customer PII data stored in the Fluent Commerce platform.
  • An asynchronous, event-driven pipeline ensures scalable and fault-tolerant processing of anonymization requests.
  • The API allows bulk requests, with individual items progressing through statuses such as CREATED, PENDING, RUNNING, COMPLETED, and FAILED.
  • GraphQL permissions are required for creating and viewing Data Subject Removal requests, ensuring secure access.

AI Assisted UI Component Building

Essential knowledgeFluent Skills extends beyond back-end workflow management into front-end development, enabling teams to design, preview, and inject UI components into a live Fluent environment conversationally, without needing React expertise or deep knowledge of the UX Framework.
  • AI-assisted UI component building eliminates the need for specialized React expertise, enabling teams to focus on design rather than technical implementation.
  • Spec-driven design allows users to describe components in plain language, with the system handling data structure investigation and implementation proposals.
  • Live UI preview through Chrome DevTools MCP integration ensures accurate representation of components before committing to a build.
  • Framework-aware code generation guarantees compliance with existing conventions and minimizes unnecessary new code introduction.

Introduction to Integrations and Connections

Essential knowledgeWelcome! This course talks about the various Integrations and Connections of the Fluent Platform.
  • Some common interfaces, and the information shared between these interfaces and the Fluent Platform
  • GraphQL, and understand its benefits over REST APIs.
  • Events API, Inventory Batches, Webhooks, and Connectors
  • Some recommended practices around the use of these methods.

Sourcing Auditability GraphQL API Overview

Essential knowledgeThis article provides technical users with information about the Sourcing Auditability GraphQL API, which writes and reads Sourcing Audit records within the Responsive Sourcing Framework.
  • Prerequisites: You should have knowledge of: GraphQL API, Responsive Sourcing Framework, and the Sourcing Auditability Overview
  • The API exposes two operations: the `createSourcingAudit` mutation (write) and the `sourcingAudits` query (read) 
  • Specific permissions are required: `SOURCINGAUDIT_CREATE` for the mutation, `SOURCINGAUDIT_VIEW` for the query, and `SOURCINGPROFILE_VIEW` to resolve the Sourcing Profile on a returned record
  • The write path enforces one payload limit - at most 100 Locations for the Strategy that produced the Fulfillments - so records stay bounded
  • The query returns a Relay-style connection with `cursor` pagination; the default page size is 10 and each `cursor` is an opaque Base64 pagination token
  • Positional quantity arrays align to the master `items` list by 0-based index: `missingItemQuantities` (per Location) and `itemQuantities` (per Fulfillment) each carry one entry per Item

Responsive Sourcing Framework Overview

Essential knowledgeThe Responsive Sourcing Framework is a configurable, scalable alternative to custom Workflows and Rules for managing sourcing strategies. You’ll learn how to define and optimize sourcing logic using Sourcing Profiles, Strategies, Conditions, and Criteria. The Framework empowers both technical and business users with faster implementation, greater control, and transparency into how sourcing decisions are made and why.
  • Prerequisites: You should have knowledge of Order Management and Order lifecycle, Order Reference Module, and GraphQL API
  • The Responsive Sourcing Framework is designed for both technical and business users - logic is transparent and comes with a configurable User Experience (UX)
  • Enables faster implementation by reusing modular sourcing logic building blocks such as Sourcing Profiles, Strategies, Conditions, and Criteria
  • Sourcing Profile GraphQL API is required to correctly set up your sourcing logic
  • Supports custom Sourcing Conditions and Criteria through externally developed extensions for advanced or domain-specific logic

Sourcing Auditability Overview

Essential knowledgeSourcing Auditability records why the Responsive Sourcing Framework made each sourcing decision. For each Sourcing Request, it records the inputs evaluated and the outcome reached, so you can review the decision later.It helps teams understand:
  • Which Strategies and Conditions were evaluated
  • Which Locations were considered and how they scored against their Criteria
  • The Location(s) selected, and why
This document explains:
  • What Sourcing Auditability captures and why it matters
  • What you can see and answer with it
  • Where audit data appears, and where to find interface and API detail
  • Prerequisites: You should have knowledge of the Responsive Sourcing Framework and How Sourcing Utilities work
  • A Sourcing Audit is an immutable record of a single Sourcing Request, created at the end of each completed sourcing attempt
  • Recording an audit never changes the sourcing outcome - if an audit cannot be recorded, the sourcing result still proceeds
  • Audit records are shown only to users who hold the appropriate permissions
  • Sourcing Auditability keeps the detailed Location scoring for the Sourcing Strategy that produced the Fulfillments

GraphQL Permissions

Essential knowledgeThe 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.
  • 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.

GraphQL Query Limits

Essential knowledgeThe following guidelines and specifications apply to the entire schema, with any exceptions documented in the schema of the relevant entity.
  • The GraphQL request size is limited to 2MB
  • There is no validation on any of the GraphQL fields (except for enums)
  • The GraphQL query complexity is limited and checked in accordance with the Query Complexity Calculation Algorithm (11,111 Total Complexity is Max)

Users, Roles, and Permissions

Essential knowledgeThe Fluent platform provides a comprehensive user role management system, allowing for the assignment of diverse permissions via roles to regulate platform access and functionalities. Custom roles can be created and fine-tuned, ensuring users only have access to appropriate functionality and data. The system provides flexibility to specify the scope for a role at different context levels, such as Accounts, Retailers, and Locations.
  • A role can be assigned to multiple users, and a user can be assigned multiple roles.
  • Permissions are granular access controls and protect every GraphQL or REST API operations. GraphQL permissions follow specific naming conventions.
  • Context plays a pivotal role in access levels, allowing users to have role-based access to data for specific Accounts, Retailers, or Locations.

Create or Update Sourcing Profile

Essential knowledgeThe `createSourcingProfile` mutation creates a Sourcing Profile (or its newer version, i.e., updates) for a Retailer:
  • If the provided `ref` is unique, it creates the first version with `ACTIVE` status
  • If a `SourcingProfile` with the same `ref` already exists, it creates a new version with `DRAFT` status
  • Prerequisites: User should have `SOURCINGPROFILE_CREATE` and `SOURCINGPROFILE_VIEW` permissions
  • Retailer association is permanent: After a Retailer is assigned to a Profile, reassignment to another Retailer is not possible
  • Use clear refs and names: Follow recommended formats (e.g., `GLOBAL_DEFAULT`)
  • Order defines priority: The order of Sourcing Strategies and Criteria determines their application

GraphQL API Error Codes Overview

Essential knowledgeThis document explains the GraphQL Error Codes used by Fluent Commerce.
  • Understand the Error Code structure: Each code follows the Prefix + 4-digit Code + Suffix format (e.g., C0001E), which instantly reveals the source (Client/Server/Third-party) and type (Error/Warning) of the issue
  • Quick diagnosis and resolution: Error Codes are grouped by category and purpose, helping developers diagnose and resolve issues faster without deep debugging or guesswork
  • Self- vs. support-resolvable issues: 
    • Codes with a C prefix usually point to issues clients can fix on their own 
    • While S prefixed Codes may require platform support

Stock Segmentation - Data Model and API Overview

Essential knowledgeStock Segmentation extends Fluent’s Inventory and Virtual Catalog data models to represent multiple logical segments for the same product and location using explicit, queryable factors.Stock Segmentation supports scenarios such as channel-specific reservations, manufacturing batch traceability, compliance restrictions (for example by country of origin), and supplier-level inventory management while preserving a single physical inventory model per product and location.This document explains the data model and GraphQL API capabilities introduced for Stock Segmentation.
  • Physical stock in the Inventory Catalog is represented through Inventory Quantities that can be segmented using dedicated fields such as `condition`, `expiresOn`, `countryOfOrigin`, `channel`, `manufacturer`, `manufacturerBatchNumber`, `supplier`, and `segment1/2/3`
  • Inventory Quantities support parent-child hierarchies, allowing multi-level segmentation trees to be modeled explicitly via the parent relationship
  • Inventory Quantities can be linked to operational entities using `associationType` and `associationRef`, particularly for reservation linkage and traceability
  • Virtual availability can expose a single customer-facing segment using Virtual Segments
  • Segmentation fields are exact-match searchable to ensure predictable query behavior (partial matching is not supported)

Future Inventory - Data Model and API Overview

Essential knowledgeFuture Inventory extends the Inventory and Virtual Catalog data models to represent inventory that is not yet physically available but is expected to arrive at a known point in time. It enables availability and reservation decisions against future stock using explicit dates and quantities.Future Inventory supports scenarios such as pre-orders and wholesale commitments, where inventory must be promised before receipt, while preserving a single physical inventory model per product and location.This document explains the data model and GraphQL API capabilities introduced for Future Inventory.
  • Prerequisites: You should have knowledge of Inventory Module, GraphQL API (Fluent Platform Integrations), and Workflow Framework
  • Future Inventory represents expected stock with defined arrival dates, not forecasts
  • Future Inventory can be reserved and committed prior to physical receipt
  • Available-to-Promise (ATP) quantities can be queried as of a future date, accounting for on-hand, expected, and already-reserved inventory
  • Inventory lifecycle states (for example: on order → in transit → received) are represented explicitly within the data model

ICP, Qualification Criteria and Additional Use Cases

Essential knowledgeThe article provides a comprehensive guide to identifying the Ideal Customer Profile (ICP) for an Order Management System (OMS), highlighting key criteria and red flags to ensure successful implementation. It also explores Fluent OMS use cases, showcasing its capabilities in order capture, fulfillment, tracking, promising, shipping, and inventory management.
  • Ideal Customer Profile (ICP) based on specific industries, company maturity, and high order volumes
  •  Poor fit indicators, such as outdated legacy infrastructure or a lack of executive buy in
  • Fast Qualification Framework to rapidly assess a prospect's Budget, Systems, Volume, and Channels.

Customer Service

Essential knowledgeLearn how implementing partners can configure Fluent Commerce to empower Customer Service Representatives with comprehensive post-purchase order management capabilities. By enabling real time order modifications and seamless returns, businesses can reduce unnecessary appeasement discounts and significantly improve the overall customer experience.
  • Learn how to equip customer service teams with tools to convert home deliveries to Click and Collect.
  • Understand how order management functionalities can be embedded directly into preferred external platforms like Salesforce Service Cloud.
  • Observe real time synchronization where actions taken in an external platform instantly update to maintain an accurate system of record.

Dynamic Mutations

Essential knowledge`DynamicUpdateMutation` automatically derives the correct update Mutation for the primary Entity based on the `RulesetContext` and then performs the update on one or more fields.
  • Automatic Mutation Selection: GraphQL mutations are automatically selected from the `RulesetContext` based on entity type.
  • Flexible Field Updates: Update single fields or multiple fields in bulk using simple key-value pairs.
  • Type-Based Safety: Use POJO classes for strongly-typed updates with automatic field derivation.
  • Runtime Validation: Built-in validation ensures only valid fields are included in mutations.
  • Universal Application: Works across different entity types without requiring entity-specific mutation code.

Dynamic Queries and Utils

Essential knowledge`DynamicEntityQuery`, with the help of the `DynamicUtils` class, automatically derives the correct GraphQL query operation for the primary Entity from the `RulesetContext`. It dynamically retrieves fields related to that Entity, removing the need for pre-compiled queries while preserving type safety and performance.
  • Runtime Query Generation: Automatically builds GraphQL queries at runtime based on entity context, eliminating pre-compiled queries.
  • Dual Usage Patterns: Type-based mapping with POJO classes for strong typing, or path-based queries for maximum flexibility.
  • Universal & Validated: Works across different entity types with automatic schema validation and connection pattern handling.
  • Flexible Access: Results accessible as typed objects, JsonNode, or flattened maps with Lombok integration.
  • Connection Handling: Built-in support for paginated connections with automatic pagination handling via `queryList()` methods.
  • Dynamic Mutations: Update entity properties dynamically using key-value pairs without pre-compiled mutation queries.
  • Unified Data Access: `getJsonPath()` method provides unified access to both event and entity data using consistent path syntax.

How to Handle Amount, Scale, and Unscaled Values

Essential knowledgeThis article explains how to manage large monetary values accurately in Fluent OMS using `scale` and `unscaledValue`, rather than relying solely on a floating-point `amount`. Floating-point types (`Float`, `Double`) cannot accurately represent decimal currency values, leading to rounding errors and inconsistent financial results. Fluent OMS applies a consistent precision model across API, business logic, and storage to ensure deterministic, lossless monetary calculations.
  • Avoid floating-point inaccuracies by using `scale` and `unscaledValue` for large amounts.
  • Treat `unscaledValue` and `scale` as the source of truth for exact monetary values.
  • Adjust `scale` to handle very large amounts while maintaining precision.
  • For display and reporting, always reconstruct amounts from `unscaledValue` and `scale`.
  • Monetary values are stored and processed using deterministic decimal representations to avoid rounding loss.
  • New development should use the precise representation model as the primary monetary format.

GraphQL Payment Queries

Essential knowledgeSample Payment and Order payment-related GraphQL queries that can be used on a daily basis, with examples focused on precise amount fields.
  • Sample queries on the following:
    • Order by ID with precise amount details
    • Payments with a precise amount

BigDecimal Precision & Rounding Principles

Essential knowledgeThis document defines the core principles for using `BigDecimal` in monetary and high-precision calculations. After reading, developers can apply the appropriate constructors, division rules, and rounding strategies to ensure consistent numeric representation across services, APIs, and storage. These principles reduce defects caused by floating-point arithmetic, undefined division, rounding errors, and incorrect value comparisons.
  • Monetary calculations rely on deterministic precision across all services.
  • Precision is preserved using `NUMERIC` (DB), `BigDecimal` (Java), and (`unscaledValue`, `scale`) (API).
  • Division requires explicit scale and rounding to avoid runtime exceptions.
  • Most defects originate from constructing from `double`, confusing scale vs precision, or misusing `equals()`.

Search Sourcing Profiles

Essential knowledgeThe `sourcingProfiles` query retrieves existing Sourcing Profiles. It supports multiple filters and pagination.
  • Prerequisites: User should have `SOURCINGPROFILE_VIEW` permission
  • Flexible Filtering: Multiple filters are supported, including `ref`, `version`, `versionComment`, `name`, `description`, `status`, `defaultMaxSplit`, and date ranges (`createdOn`, `updatedOn`). This lets you target specific Profiles or narrow results down by lifecycle state and time window
  • Pagination Support: The query supports cursor-based pagination (`first`, `last`, `before`, `after`), making it efficient to handle large sets of Sourcing Profiles 

Get Sourcing Profile

Essential knowledgeThe `sourcingProfile` query retrieves a Sourcing Profile by its Reference:
  • If a version is provided, the query returns that specific version
  • If no version is provided, the query returns the latest available version
  • Prerequisites: User should have `SOURCINGPROFILE_VIEW` permission
  • Version Handling: If a version is provided, that exact version is returned. If no version is specified, the query automatically retrieves the latest available version, regardless of status
  • Status Filter: An optional `status` argument lets you filter results (e.g., `ACTIVE`, `INACTIVE`, `DRAFT`) so you can target Profiles in a specific lifecycle state

Activate Sourcing Profile

Essential knowledgeThe `activateSourcingProfile` mutation activates a specific version of a Sourcing Profile. When called, it performs the following actions:
  • Sets the specified version status to `ACTIVE`
  • Updates the previously `ACTIVE` version to `INACTIVE`
  • Prerequisites: User should have `SOURCINGPROFILE_UPDATE` and `SOURCINGPROFILE_VIEW` permissions
  • Version Control: Activating a new version automatically deactivates the previously `ACTIVE` version, ensuring that only one Sourcing Profile version remains active at any time

Sourcing Profile GraphQL API Overview

Essential knowledgeThis article provides technical users with information about the Sourcing Profile GraphQL API, which enables configuration and querying of Sourcing Profiles within the Fluent Platform.
  • Specific permissions are required for Sourcing Profile operations
  • Use the `createSourcingProfile` mutation to create new Sourcing Profiles or generate updated versions
  • Activate a profile version with the `activateSourcingProfile` mutation; this sets it to `ACTIVE` and automatically sets the previous `ACTIVE` profile version to `INACTIVE`
  • Retrieve Profiles using the `sourcingProfile` query (single Sourcing Profile by Reference) or `sourcingProfiles` query (multiple, with filters)
  • Every update creates a new version of the Sourcing Profile, ensuring full version history is preserved

Create multi order payload example

Essential knowledge
  • Example createOrder mutation payload for MULTI order type
  • The example is just a reference payload only which can be used with order module reference workflow.

REST Event API

Essential knowledgeEvents are a fundamental part of the Fluent Platform. Not only are they used to trigger workflow logic, but they also capture everything that happens within the system. Events are categorized by type.
  • Event Types: Understand the different event categories such as ORCHESTRATION, ORCHESTRATION_AUDIT, API, and GENERAL events, each serving distinct purposes within the Fluent Platform.
  • Event Retrieval: Use the GET methods with appropriate parameters to retrieve specific events or a filtered list of events, ensuring you handle possible 404 errors for not found items.
  • Event Creation: Leverage the POST methods to create new events either asynchronously (/event/async) or synchronously (/event/sync) based on the workflow requirements.
  • Authentication: Remember that authentication is required for all operations within the Event API, ensuring secure access and interaction with the event system.
  • Request Size: The request size is limited to `10MB`. Requests over `10MB` will return `HTTP 413 Request Entity Too Large` response.

GraphQL Date Utilities

Essential knowledgeThe `GqlDateUtils` class in the `util-core` bundle provides a simple and effective set of functions for handling the specific date format required by the Fluent Commerce GraphQL API. The platform uses the ISO 8601 format (`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`), and this utility ensures you can easily parse and format dates to be compatible.
  • GraphQL Compatibility: This utility ensures that dates are always in the precise ISO 8601 string format required by the Fluent Commerce GraphQL API (`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`).
  • Parsing (`parseGqlDate`): Safely parses a string from an event or external system into a standard Java `Date` object, preventing common parsing errors.
  • Formatting (`toGqlDate`): Converts a Java `Date` object into the specific string format required when passing dates as variables in GraphQL queries or mutations.
  • Centralized Logic: Centralizes date handling to avoid bugs and ensure consistency across your entire implementation.

Dynamic Pagination

Essential knowledge`DynamicConnectionQuery` automatically derives the Connection fields (arrays) for the primary Entity based on the `RulesetContext` and can dynamically load all connection items, with pagination handled internally.
  • Automatic Pagination: `DynamicUtils.queryList` completely automates fetching paginated data from a GraphQL connection. You get a simple `Iterable`, and the library handles fetching subsequent pages in the background as you iterate.
  • Lazy Loading: The utility is highly efficient because it uses a "lazy loading" approach. It only fetches the next page of data when you have iterated through the current one.
  • POJO-Driven: You define the data you need by creating a simple POJO class. The utility dynamically builds the GraphQL query to fetch only the fields defined in your POJO.
  • Server-Side Filtering: You can pass a `Map` of parameters to `queryList` to filter the connection on the server. This is much more efficient than fetching all the data and filtering it in your rule.

Fluent Platform Integrations and Connections

Essential knowledgeFluent platform functionalities are designed to be flexible by integrating with other APIs and Connectors and provides a real time view of the Inventory to the sales channels, enables integration with Warehouse Management Systems (WMS), carrier services, ERPs, etc.
  • Some common interfaces, and the information shared between these interfaces and the Fluent Platform
  • GraphQL, and understand its benefits over REST APIs.
  • Events API, Inventory Batches, Webhooks, and Connectors

Product GraphQL API Overview

Essential knowledgeThis article is intended to provide technical users with information about the Product GraphQL API, describing its functionalities within the Fluent Platform.
PrerequisitesYou should have knowledge of:
  • Products, Product Catalogs, and Product Management
  • Inventory Reference Module, including the Product Catalog Workflow Interface Contracts
  • GraphQL API
  • GraphQL API for Product Management: 
    • Supersedes REST
    • Supports creating, updating, and querying Products
  • Permission-Driven Access: Type- and Retailer-specific `CREATE`, `UPDATE`, and `VIEW` Permissions are strictly enforced for all operations
  • Type-Agnostic Updates: `updateProduct` simplifies updates without needing Product Type, but correct Permissions and unique `ref` + `catalogue` are required.

GraphQL Product Queries

Essential knowledgeSample Product Queries that can be used on a daily basis
  • Sample Queries on the following:
    • Variant Product (SKU) by Reference
    • Variant Product (SKU) by Details
    • Variant Products (SKU)
    • Product by Name and Reference

GraphQL Queries

Essential knowledgeQuery operations are used for retrieving data. Fluent's GraphQL API provides two types of query operations:
  • `Get`: To retrieve and display unique results
  • `Search`: To search and display a list of results
  • Get
  • Search
  • Pattern Based Searches
  • Search with Wildcard Characters
  • Performing Pattern-Based Searches
  • DateTime Search Operations
  • Link-Based Query Searches
  • Default Sort Order for Query Results
  • GraphQL Error Handling

GraphQL API

Essential knowledgeThe Fluent GraphQL API provides powerful access to data, integration, and orchestration-driven business logic. It provides an opportunity to streamline and optimize requests to the Fluent Order Management platform in a way that is more flexible than the REST-based API.
  • Schema Documentation
  • Benefits of GraphQL
  • Why Did We Choose GraphQL?
  • Differences Between REST and GraphQL-based APIs

Order Orchestration Labs

Essential knowledgeThe lab covers creating and managing different order types in Fluent OMS, simulating warehouse and store interactions, and enabling user actions for order cancellation. It focuses on Home Delivery (HD), Click and Collect (CC), split fulfilment, and enhancing workflows with user-configured actions. This lab guide users through hands-on exercises using Postman and the Fluent OMS interface.
  • HD Workflow (Home Delivery): Process and fulfill home delivery orders via a warehouse.
  • CC Workflow (Click and Collect): Understand click and collect orders and simulate stock management and pickup.
  • Split Fulfillment: Explore multi-shipment scenarios when stock is insufficient at one location.
  • Order Cancellation: Configure user actions for order cancellation with reasons before fulfillment starts.
  • Postman Integration: Use Postman to authenticate, create orders, and simulate fulfillment steps.
  • Workflow Customization: Enhance order workflows by adding business rules and user actions.

Support and Operations Labs

Essential knowledgeThese labs focus on debugging and troubleshooting Fluent Order Management workflows using GraphQL and Postman. They cover retrieving detailed data for orders and waves, analyzing audit events, identifying stuck orders, and re-triggering workflows. The goal is to simulate real-world scenarios, understand workflow paths, and resolve issues efficiently.
  • Full Order/Wave Retrieval: Use GraphQL to fetch information on orders and waves.
  • Audit Events: Use Event APIs to trace orchestration activities and errors.
  • Status Transitions: Track entity status changes and time spent in each state.
  • Stuck Orders: Identify and troubleshoot orders stuck in specific statuses.
  • Workflow Debugging: Simulate workflow breaks and resolve stuck entities.
  • Re-trigger Rulesets: Fix workflows and re-trigger events for stuck orders to progress.

Query Comments

Essential knowledgeThe `comments` Query retrieves Comments based on various filter criteria.
Prerequisites
  • `COMMENT_VIEW` Permission is required for retrieving Comments
  • Use the `comments` Query to retrieve existing Comments
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Get Comment by Id

Essential knowledgeThe `commentById` Query retrieves a Comment based on a provided Id.
Prerequisites
  • `COMMENT_VIEW` Permission is required for retrieving a Comment
  • Use the `commentById` Query to retrieve an existing Comment
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Update Comment

Essential knowledgeThe `updateComment` Mutation allows for the updating of an existing Comment object.
PrerequisitesSpecific Permissions are required for updating Comments:
  • `COMMENT_UPDATE`
  • `COMMENT_VIEW`
  • Use the `updateComment` Mutation to update an existing Comment
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Create Comment

Essential knowledgeThe `createComment` Mutation allows the creation of a Comment against a known Entity.
PrerequisitesSpecific Permissions are required for creating Comments:
  • `COMMENT_CREATE`
  • `COMMENT_VIEW`
  • Use the `createComment` Mutation to create a Comment against a known Entity
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)
  • Created Comments inherit the `retailerId` of the associated Entity

Comment GraphQL API Overview

Essential knowledgeThe Comment GraphQL API allows customers to manage Comments across various Entities.Multiple Comments can be added against the same Entity, with each Comment automatically capturing:
  • The timestamp
  • The User who created it (`USER_VIEW` Permission is required to access the User data)
This feature allows Users to record specific business actions and events, providing a comprehensive history of interactions and updates.
  • Add Comments to any Entity Type, enabling detailed documentation of business actions
  • Specific Permissions are required for Comment operations
  • Use the `createComment` and `updateComment` Mutations to manage Comments
  • Use the `commentById` and  `comments` Queries to retrieve Comments

Fulfilment Options improvements enablement

Essential knowledgeIn the September 2023 release, we improved our Fulfilment Options response times by up to 50%. These improvements are disabled by default for accounts created before the release. This section will detail how to turn on this setting.
  •  Enhance Fulfilment Option speed
  • Customise setting for speed

Plugin Structure & JS GraphQL

Essential knowledgeIn this module, you will learn about a Plugin Project structure and JS GraphQL within the Plugin Project.  You will also learn how to modify and run a JS GraphQL query.
  • Installed SDK
  • GQL Basics

Introduction to Webhooks

Essential knowledgeIn this lesson, we'll look at what Webhooks are, their structure, features and some recommended practices around using Webhooks.
  • Introduction/Recap on what Webhooks are
  • Webhook Structure
  • Webhook Features
  • Types of integrations for Webhooks
  • Webhook best practices

Introduction to GraphQL

Essential knowledgeIn this lesson, we'll look at the benefits of using GraphQL, as well as explore the differences between GraphQL and REST based APIs. We will also look at some examples of a GraphQL query and a GraphQL mutation. 
  • Introduction to GraphQL
  • Differences to REST
  • Benefits of using GraphQL
  • Basic structure of a query
  • A GraphQL mutation
  • Types of common integrations that use GraphQL

API, Integration, and Connectors

Essential knowledgeAPI, Integration, and ConnectorsThis lesson covers the various integrations and connections with the Fluent platform.
  • Fluent is designed to integrate flexibly with other API's and connectors
  • Fluent provides connectivity via Rest and GraphQL API's
  • Webhooks provide outbound connectivity from Fluent

payment graphQL query and mutation

Essential knowledgeThe `payment` is an entity that is required as part of the payment process. 
  • The page provides GQL example of how to use `payment`:
    • Create
    • Update
    • Query

Fluent Commerce Fundamentals

Essential knowledgeThis is a guidepost for Developers highlighting important guides and articles to speed up Fluent Commerce's learning process. 
  • Workflows that consist of states, rulesets, triggers, user actions, and Modules, used for distributing workflows and it's artifacts, are a key part of the Fluent Commerce platform.
  • Settings are used to adjust Workflow execution

GraphQL Operations

Essential knowledgeGraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. It provides a complete and easy-to-understand description of the data in your API. Its ability to return select fields enables it to be used with powerful developer tools and ensures that APIs are easily scalable.Fluent's GraphQL API has two operations:
  • Queries 
  • Mutations
Queries include predefined Queries and Custom Queries, both of which will be covered below.
  • Operations
  • Queries
  • Mutations
  • Custom Queries

Metrics Overview

Essential knowledgeThis document is intended to introduce the Metrics and describe their place within the Fluent Big Inventory product.Pre-requisites:
  • You should have knowledge of the Inventory.
  • You should have knowledge of OMX Workflow Framework.
  • You should have knowledge of Events.
  • You should have knowledge of GraphQL.
  • Metrics are available for all Fluent Order Management and Fluent Big Inventory customers.
  • Metrics data is captured, uploaded, and stored in a monitoring system.
  • Metrics data is retrieved via the Metrics API.
  • Metrics data can be visualized with the OMX UX Framework, Business intelligence tools, and third-party Metrics analytics platforms.

Understanding IDs and Refs in GraphQL Entities

Essential knowledgeThe Fluent platform generates unique IDs internally, which serve as the primary key for each new record. They are unique and enforced to avoid ambiguity. Users cannot set these via API. Whereas refs are typically from third-party integrations, they represent external system IDs and occasionally are generated internally with guaranteed uniqueness. It is the integrator's responsibility to ensure refs are unique in Fluent Commerce.
  • IDs are generated by the Fluent platform and are guaranteed to be unique at the time of creation. 
  • Refs are typically values passed in via third-party integrations and should represent the IDs from external systems.
  • Despite the system not enforcing the uniqueness of refs, it is highly recommended to have unique refs for all entities. Every ref should be unique within it's nearest container, for example Retailer refs need to be unique across all . Catalogue or Account.
  • If your refs are not unique then there are API's that will not work as expected. This means that our reference modules may not work as expected if you set ref's as non-unique values.

Query Create and Update Customer via GraphQL

Essential knowledgeA best practice guide of creating customer entity.
  • A user guide on how to manage customer entities in OMS.
  • Best practice guide on creating Customer entity in OMS before the createOrder mutation.
  • Relationship between user entity and customer entity.

How Metrics works

Essential knowledgeThis document is intended to describe to implementers Metrics technical details within the Fluent Big Inventory product.Pre-requisites:
  • You should have knowledge of Metrics
  • You should have knowledge of OMX Workflow Framework.
  • You should have knowledge of Events.
  • You should have knowledge of GraphQL.
  • All customers' Metrics are isolated in the dedicated workspaces.
  • Metrics are captured from the Fluent APIs, Orchestration Engine (Rubix), Batch Pre-Processing, and Inventory Feeds.
  • Use `metricInstant` and `metricRange` GraphQL queries to retrieve the Metrics data.

GraphQL order by ID with flags in parameter

Essential knowledgeRetrieve an order by `id` with flags to drive the retrieval of sub-entities.
  • Sample query on how to use flags as part of the query parameter

GraphQL All-In-One Inventory Queries

Essential knowledgeRetrieve inventory position, variant product, virtual base position and virtual aggregate position records based on input parameters.
  • Sample GraphQL query that extracts inventory position, variant product, virtual position and virtual aggregate position. 

Virtual Position Queries

Essential knowledgeSample Virtual Position Queries that can be used on a daily basis
  • Query sample on extract virtual position by updatedOn

GraphQL Inventory Queries

Essential knowledgeSample Inventory Queries that can be used on a daily basis.
  • An actual example of a GraphQL query on the following:
    • Inventory Position by Details
    • Inventory Position by Reference
    • Inventory Positions
    • Inventory Quantity Updated

GraphQL Reference

Essential knowledgeThese docs were generated by graphql-docs. Just starting out with GraphQL? Check out GraphQL's official documentation!
  • The schema docs are generated as part of a product release process and therefore are up-to-date.

Getting Started with Metrics API

Essential knowledgeThis guide is intended to provide implementers with information about the Metrics API within the Fluent Big Inventory product, describing its functionalities and utilization principles within the Fluent Platform.Pre-requisites:
  • You should have knowledge of How Metrics works.
  • You should have knowledge of Metrics usage for Platform Observability.
  • You should have knowledge of GraphQL.
  • You should configure your User role with `METRICS_VIEW` permission for Metrics data access.
  • Metrics data is fetched and visualized for the Fluent Platform Observability enablement.
  • Use `metricInstant` and `metricRange` GraphQL queries to retrieve the Metrics data.
  • Prometheus Query Language is utilized for the Metrics API queries construction.

createFinancialTransaction GraphQL mutation Example

Essential knowledgecreateFinancialTransaction GraphQL mutation Example
  • createFinancialTransaction GraphQL mutation Example

GraphQL (GQL) Mutations

Essential knowledgeMutations in GraphQL are operations designed to modify server-side data, encompassing the creation, updating, or deletion of records. They play a critical role in dynamic data management within GraphQL applications, allowing for precise and controlled data manipulation.
  • Mutations in GraphQL are used for creating, updating, or deleting data, and are crucial for any operation that changes server-side information.
  • Create mutations always generate data with a "CREATED" status, which can trigger orchestration events for workflow processes.
  • Update mutations require mandatory parameters to uniquely identify and modify existing data entries.

APIs Overview

Essential knowledgeFluent provides both REST and GraphQL APIs. However, REST APIs are limited to specific Platform operations, while the GraphQL API provides the core Domain Model.
  • Common Authentication Token: Both Platform REST and Domain GraphQL APIs utilize a shared authentication token, ensuring a unified authentication approach.
  • Platform REST APIs: Various Platform-level APIs, including Event, Workflow, Job, Plugin, and User Action APIs, are implemented in REST format with version 4.1.
  • GraphQL API Advantages: The actively supported GraphQL API offers significant benefits over REST, while deprecated Domain-based REST APIs are in maintenance mode for existing clients, with documentation available for reference.

financialTransaction graphQL query and mutation

Essential knowledgeThe `financialTransaction` is an entity used for capturing financial transactional made by the customer.
  • The page provides GQL example of how to use `financialTransaction`:
    • Create
    • Update
    • Query

paymentServiceProvider graphQL query and mutation

Essential knowledgeThe `paymentServiceProvider` is an entity that is required as part of the payment process. 
  • The page provides GQL example of how to use `paymentServiceProvider`:
    • Create
    • Update
    • Query

orderBillingAddress graphQL query and mutation

Essential knowledgeThe `orderBillingAddress` (aka `billingAddress`) is a sub-entity of the Order entity. A customer can optionally add a billing address while ordering items from a store, so an Order can store one `billingAddress` as an attribute.
  • The page provides GQL example of how to use `orderBillingAddress`:
    • Create
    • Update
    • Query

paymentTransaction graphQL query and mutation

Essential knowledgeThe `paymentTransaction` is an entity that is required as part of the payment process. 
  • The page provides GQL example of how to use `paymentTransaction`:
    • Create
    • Update (not available)
    • Query

billingAccount graphQL query and mutation

Essential knowledgeThe `billingAccount` is an entity used for linking customer entities with `payment`, `creditMemo` and `invoice`.
  • The page provides GQL example on how to use `billingAccount`:
    • Create
    • Update
    • Query
Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

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.

Fluent Logo