Fluent Commerce Logo
Docs

Recently Updated

Some of the recently updated content.

Stock Segmentation - Data Model and API Overview

Essential knowledgeCore knowledge to understand Fluent Commerce
Stock 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 stored as Inventory Quantities. You can segment them with these fields: `condition`, `expiresOn`, `countryOfOrigin`, `channel`, `manufacturer`, `manufacturerBatchNumber`, `supplier`, `storageAreaRef`, `segment1`, `segment2`, and `segment3`.
  • Inventory Quantities support parent-child hierarchies. Use the parent relationship to model multi-level segmentation trees.
  • Inventory Quantities can be linked to operational entities using `associationType` and `associationRef. `The main use cases are linking reservations and tracing stock.
  • Use Virtual Segments to expose customer-facing segments in virtual availability.
  • Segmentation fields only support exact match. Partial matching isn't supported. 
    • Exception: the `inventoryQuantities` query supports wildcard search on `condition` and `storageAreaRef`.
  • Filter values ignore case, except `type` and `status` in `updateInventoryQuantitiesStatus`.

Webhook Retries and Inline Events

Essential knowledgeCore knowledge to understand Fluent Commerce
This page explains how the Orchestration Engine retries a webhook that is reached through inline events, and helps you decide which value of `fc.rubix.webhook.retry.event` to use for your account.It describes how each workflow pattern is affected, what each value does, and what to check before you change the setting.
  • Prerequisites: Webhooks, Inline Event, Understanding Event Execution
  • A webhook action is retried only when its request fails with a network error, such as a timeout. This happens most often when the receiving system is under load, for example during peak trading
  • With `webhook-event`, the retry uses the webhook event, which is the event that triggered the ruleset in which the webhook action was produced:
    • The retry is posted to the same endpoint with the same event as the original call
    • If the receiving system responds, with any HTTP status code, the retry counts as delivered and retries stop
    • If all retries fail, the Exception event is raised for the ruleset and entity of the webhook event
  • With `initial-event`, the retry uses the initial event, which is the event that started the event context:
    • The retry is posted to the same endpoint, but with the initial event, so the event name, the entity, and the attributes can differ from the original call
    • If the receiving system responds, with any HTTP status code, the retry counts as delivered and retries stop. The original call isn’t sent again, and the Send Webhook audit event shows `SUCCESS`, so the failure goes unnoticed
    • If all retries fail, the Exception event is raised for the ruleset and entity of the initial event, not for the ruleset of the webhook event
  • The values differ only when the webhook event is an inline event. When the webhook action is produced in the ruleset triggered by the initial event, both values give the same retry
  • Accounts created before the setting was introduced keep `initial-event` until you change it. Accounts created since then use `webhook-event`. Check your workflows with this page, then switch to `webhook-event`
  • For custom webhook rules and the reference `SendWebhook` rule, also add `preserve-event-details` to the workflow, so the retry reruns the rule that produced the webhook action. Without it, the retry is sent by the built-in platform webhook rule. See `fc.rubix.sdk.webhook.retry.method`.

Fluent CLI Reference (v2.x.x)

Essential knowledgeCore knowledge to understand Fluent Commerce
This guide covers Fluent CLI v2.x.x, the primary tool for managing Fluent Commerce accounts and assets. Implementing partners use it to automate environment setups and integrate workflows into CI/CD pipelines. For the business, the CLI ensures faster deployment cycles and high consistency.Note: From version 2.3.0, requires a patched Node.js release: ^22.23.4 || ^24.22.1 || >=26.12.1 (earlier 2.x versions: >=20.0.0 <25.0.0).
  • Profile Management: Use `profile create` to securely store account IDs, client secrets, and base URLs. Profiles serve as the foundation for all subsequent commands.
  • Module Lifecycle: Supports the full lifecycle: `create` from templates, `config` for environment settings, and `install` for sequential asset deployment.
  • Asset Processing Order: Assets are processed in a specific dependency-aware order (e.g., `rules` and `locations` before `workflows`) to ensure system stability.
  • Workflow Operations: Features robust `download` and `list` commands with `--json` support, enabling advanced data manipulation using tools like `jq.
  • Event Operations: Use `event list` to inspect event history and `event send` to submit an event, for example to recover an order after an issue or to test a workflow during development.
  • Environment Context: Most commands require a `-p` (profile) and `-r` (retailer) flag to define the target environment.
  • Batch Operations: The `blueprint` command allows for high-volume setup tasks, essential for large-scale data migrations or initial account provisioning.
  • Logging & Debugging: Use the `--debug` flag to resolve connectivity or validation issues by viewing the raw communication between the CLI and Fluent APIs.

Solution Integration Partner Program 2026

Essential knowledgeCore knowledge to understand Fluent Commerce
Our Solution Integration (SI) Partner Program is designed to recognize and reward the value that our SI partners bring to our joint success. It provides a clear, transparent way to measure engagement, contributions, and impact across different areas of collaboration, from demand generation and deal contribution to delivery excellence and customer impact. 
  • What this program does: As a Fluent Commerce SI partner, you get a dedicated Channel & Alliances rep for strategic guidance, commercials, marketing collaboration, and training, plus a structured way to earn recognition for the work you do together.
  • How points are earned: Activities like referring qualified leads (5 pts), closing SI partner-sourced deals (15 pts), running joint marketing campaigns (3 pts), completing Functional Practitioner Certification within 2026 (10 pts), providing a customer reference (15 pts), and joint account planning (5 pts) all count toward your total.
  • Certain items need approval or minimum thresholds: Leads must reach "needs identified" stage, customer references require customer approval, and collaboration credit is at the team's discretion, so not every effort automatically qualifies.
  • Bottom line for partners: Engaging across referrals, deals, marketing, certification, and advocacy is how you build points and deepen the partnership, your Channel & Alliances representative is the go-to contact for questions on any of this.

Builders Portal Points System

Essential knowledgeCore knowledge to understand Fluent Commerce
Learn how the Builders Portal points system works so you can understand which activities earn points, how many points each activity is worth and what tiers and badges you can progress through. Implementing partners can use this to track their team's engagement with Fluent Commerce learning resources and recognise individual contributors publicly via the leaderboard. Points reward the behaviours that build product expertise such as certifications, learning milestones, and forum participation, which all translates to faster, better-informed implementations. 
  • Points are earned automatically for six different activities: completing a certification (500), completing a learning milestone (50), commenting on a forum post (15), creating a forum post (10), reading a release note article (5), and logging in (1).
  • There are six tiers, each with its own badge: Trainee (0), Associate (1,000), Practitioner (2,500), Specialist (5,000), Expert (8,500), and Elite (13,000 points).
  • Certifications are the fastest route up the leaderboard: a single certification is worth the equivalent of 10 learning milestones or 500 logins, so learning activity, not portal visits, drives ranking.
  • Points have no connection to the SI Partner Program: they do not affect partner status, partner program tiers, or commercial arrangements, the system exists purely to recognise individual learning and community contribution.
  • Rankings are public: Your position is visible to all Builders Portal users via the 'Leaderboard' button under 'My Rewards'.

GraphQL Permissions

Essential knowledgeCore knowledge to understand Fluent Commerce
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.
  • 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.

Blueprint Install Command

Essential knowledgeCore knowledge to understand Fluent Commerce
The `blueprint install` command is the engine of the Fluent Commerce Accelerator, enabling sequential installation of module collections. Partner developers gain reliable, repeatable deployments, while the business achieves operational stability and faster disaster recovery.Its built-in logic ensures safe production updates by automatically handling upgrades while blocking risky downgrades without explicit confirmation. This prevents accidental data or logic loss, resolving the pain point of manual configuration errors. Note: Installations require retailer-level authentication.
  • Smart Resume & Versioning: The CLI automatically skips identical versions and resumes failed installations from the point of failure. Upgrades are automatic, but downgrades and reinstalls (same version) require the `--force` flag.
  • Selective Deployment: Use `--include` or `--exclude` to install specific subsets of a blueprint—perfect for phased rollouts or excluding test data from production.
  • Safety First: The command performs a "Pre-Flight Check" that validates blueprint structure and checks for incompatible conflicts before making any changes.
  • Snapshot Mode: Perfect for development, this mode resolves `SNAPSHOT` or 4-part build versions (e.g., `2.5.0.125`) to ensure you are always testing the latest code.
  • Offline/Air-Gapped Support: By using `--module-path`, you can install modules directly from a local directory, bypassing the need for an internet connection.
  • Dry Run: Use `--dry-run` to simulate the installation. This validates the blueprint and checks for conflicts without actually modifying the account.

What is a Blueprint?

Essential knowledgeCore knowledge to understand Fluent Commerce
This guide covers the blueprint lifecycle, from design to management, teaching you to deploy pre-configured module collections using the Fluent CLI. Implementing partners gain a consistent, repeatable setup across environments, while businesses benefit from faster deployments and reduced downtime via automated conflict prevention.Key features include Smart Versioning for automatic upgrades and Snapshot Mode for development testing. Note: Production requires exact versions; semver ranges are prohibited to ensure stability.
  • Accelerator Blueprints: JSON manifest files acting as "recipes" to rapidly deploy pre-configured collections of modules to Fluent Commerce accounts.
  • Core Functions: Enables version-controlled installations, rapid environment setup, and automated conflict management.
  • Module Types: Supports official "Reference" shorthand (core, order, etc.), "Namespaced" organizational modules, and "Custom" modules via S3/HTTPS/Local paths.
  • Snapshot Mode: Specific for development; allows automatic resolution of 4-part build numbers or SNAPSHOT versions for latest-build testing.
  • Smart Deployment: Installation logic automatically handles upgrades and resumes interrupted sessions by skipping identical versions unless --force is used.
  • Lifecycle: Follows a clear path: Design → Validate → Config → Install → Manage.
  • Best Practice Supports official "Reference" shorthand (core, order, etc.), "Name-spaced" organizational modules, and "Custom" modules via S3/HTTPS/Local paths.

Connect SDK Libraries

Essential knowledgeCore knowledge to understand Fluent Commerce
The Connect SDK Libraries comprise a modular software development framework designed for building integrations with Fluent Order Management. The architecture centers around a mandatory core module that handles foundational communication, configuration storage, and routing capabilities. Implementation teams can extend this baseline engine using specialized, pluggable add-on libraries to introduce web frameworks, security filters, specific cloud or infrastructure adapters, and isolated simulation testing suites.
  • What You Will Learn: You will understand the structural purpose of each component within the Connect SDK framework and learn how to select the appropriate core, web, cloud infrastructure, or testing dependencies for your implementation project.
  • Mandatory Core Requirement: The `connect-sdk-core` library is a mandatory dependency for all SDK-based implementations. It houses the baseline engine components, including the REST and GraphQL API client, authentication management for sensitive credentials, message routing, and the configuration manager.
  • Asynchronous Processing Boundary: All transactional endpoints and internal processing steps handled by the SDK execute asynchronously in the background. The explicit exception to this design rule is product availability processing, which runs synchronously.
  • Pluggable Architecture Strategy: Advanced technical capabilities are intentionally isolated into decoupled modules. Developers append specialized add-ons like `connect-sdk-core-web-security` for Spring Security filters, `connect-sdk-core-aws` for Amazon Web Services (AWS) deployment services like Amazon Simple Queue Service (SQS) and AWS Secrets Manager, or `connect-sdk-core-kafka` for Apache Kafka support.
  • Isolated Testing Frameworks: The SDK segregates quality assurance utilities into specific test scopes. Teams deploy `connect-sdk-test-core` to mock external API calls with Wiremock, or utilize the AWS and Kafka test extensions to run integration tests inside software containers alongside LocalStack or virtual Kafka brokers.

Bundled Product Handling

Essential knowledgeCore knowledge to understand Fluent Commerce
A bundled product is a single sellable product formed by combining multiple child variant products. The bundle can be fulfilled either from pre-packed stock or by assembling individual child components, which can also be sold independently. This document covers how to model bundles in Fluent OMS, calculate their availability, and determine how they are fulfilled. The approach described in this document reflects a common implementation adopted by clients. Actual implementations may vary based on client-specific business requirements and future product enhancements.
  • A bundle is modelled as a Variant Product with `isBundledProduct: true` and a `childComponents` attribute listing component SKUs.
  • Bundle components can be sold individually or as part of a bundle
  • Bundle ATS is calculated as the bundle's own pre-packed stock plus the minimum available units across all child components.
  • Allocation priority: Pre-packed bundle stock is consumed first; component explosion only occurs when pre-packed stock is exhausted.
  • A MASTER Virtual Catalogue orchestrates all bundle ATS calculations — it receives inventory change events, applies the min-of-components formula, and routes results to BASE and Aggregate catalogues.
  • Selling a component individually automatically reduces the bundle's calculated availability through virtual position recalculation.
  • The `parentBundles` attribute on component products provides reverse-reference for recalculation triggers.

External Webhook Integration Architecture - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector ingests inbound webhooks and dispatches outbound payloads across the integration ecosystem. Partners will learn to configure and apply this shared framework utility, which manages message routing, handler resolution, and internal queue mechanics. For the business, this asynchronous architecture ensures real-time, secure data transmission and protects platform stability by preventing message loss during high-volume storefront traffic spikes.Note: This architectural component serves as a global framework utility rather than a single functional pipeline.
  • Core Function & Outcome: You will learn how the framework utility orchestrates bidirectional ingress and egress loops, serving as the master execution blueprint for all entity-specific data synchronization pipelines.
  • Asynchronous Queue Infrastructure: The architecture processes incoming webhook payloads through an external `ct-queue` and an internal Event Queue sequentially, decoupling network reception tasks from backend data processing to maintain platform throughput.
  • Declarative Route Filtering: Implementing partners can manage message names, configure explicit inclusion filters, and reassign target event pathways directly inside the `application-connector.yml` configuration file.
  • Extensible Handler Architecture: The core message routing and processing layers are completely decoupled, allowing developers to cleanly register custom storefront event handlers by extending the base `MessageHandler` class.

Fulfillment - Adobe Commerce Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the Adobe Commerce Connector ingests fulfillment updates from Fluent Order Management to log milestones at the order line-item level. Partners will learn to manage asynchronous queue consumers, custom validation chains, and built-in troubleshooting tools. For the business, this synchronization details ongoing fulfillment progress to support staff without altering header states.Note: This article forms part of the inbound pipeline category, where data flows into the Adobe Commerce environment from an external source.
  • Core Function & Outcome: You will learn how the Fulfillment framework captures webhook updates from Fluent and processes them asynchronously via Adobe Commerce's message queue to track line-item fulfillment details.
  • Critical Operational Limitation: If you skip the text, you must know that only details at the individual order-line level are logged; it does not automate or drive standard Adobe workflow behaviors like order status changes or shipment updates.
  • Data Storage & UI Visibility: Incoming fulfillment statuses and aggregated quantity metadata are saved into a new custom database entity (`order_item_fulfilment`), which dynamically extends the native Admin Order Details view with real-time tracking notes.
  • CLI & Troubleshooting Tools: For manual interventions, the framework includes CLI commands to manually start the message consumer or force-update a specific order's fulfillment data directly from Fluent Commerce.

Consignment - Adobe Commerce Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the Adobe Commerce Connector ingests inbound consignment updates from Fluent Order Management to update storefront shipments. Partners will learn to manage asynchronous validation chains, message queues, and tracking details. For the business, this automation creates precise full or partial customer shipments and provides real-time carrier tracking links.Note: This article forms part of the inbound pipeline category, where data flows into the Adobe Commerce environment from an external source.
  • Core Functionality & Outcome: You will learn how this pipeline intercepts Fluent consignment webhooks to automatically create and update full or partial shipments, including tracking codes, in Adobe Commerce.
  • Global Scope & Trigger Constraints: If you skip the text, you must know that this framework can only be activated globally across all websites, and shipment generation relies entirely on a configurable, comma-separated list of specified Fluent statuses.
  • Asynchronous Validation Flow: Inbound webhooks undergo a strict multi-step validation chain (verifying accounts, retailer IDs, and entity types) before being offloaded to an asynchronous message queue (`fluentcommerce.consignment.updater`) for safe, decoupled processing.
  • Architecture & Customization: Developers can extend or override webhook handlers, validation rules, and processing commands using standard Adobe Commerce Dependency Injection (DI) (`di.xml`) or tap into two dedicated event hooks (`before`/`after` processing).

Order Status Update - Adobe Commerce Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the Adobe Commerce Connector exports storefront checkout transactions to Fluent Order Management and processes inbound status updates via webhooks. Partners will learn to leverage the plugin architecture to configure automated messaging queues and event-driven handlers. For the business, this real-time link establishes a seamless fulfillment path and eliminates manual order tracking updates.Note: This article forms part of the inbound pipeline category, where data flows into the Adobe Commerce environment from an external source.
  • Core Function & Outcome: You will learn how using the native Adobe Commerce plugin and observer frameworks automates bidirectional data flows, exporting Adobe Commerce orders to Fluent via native message queues and processing inbound status updates through a validated, two-stage webhook handler.
  • Critical Sync Limitations: If you skip the text, you must know retroactive synchronization is not currently supported; it will permanently miss orders created prior to installation or those placed during any period where the sync was temporarily deactivated.
  • Disabled-by-Default Feature: There is a setting that blindly creates shipments for all order items upon a status update regardless of actual fulfillment states; this is disabled by default to prevent data errors, safely deferring specific shipping logic to the Consignment framework.
  • Tracking & Extensibility: Export progress is strictly tracked via custom `publish_status` extension attributes, and the framework provides seven distinct event hooks alongside DI entry points to customize readiness checks and item payloads.

Product Sync - Adobe Commerce Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the Adobe Commerce Connector synchronizes product catalog data outbound to Fluent Order Management. Partners will learn to manage full manual updates alongside database-triggered automated delta synchronizations across multi-retailer configurations. For the business, this automation unifies product listings, eliminates manual catalog duplication steps, and supports simple and configurable product types.Note: This article forms part of the outbound pipeline category, where data flows out of the Adobe Commerce environment to an external destination.
  • Core Functionality: You will learn how the framework exports product catalog data from Adobe Commerce to Fluent asynchronously using Adobe's message queue, supporting multi-retailer and multi-website configurations.
  • Product Type Limitation: A critical constraint to understand if skipping the text is that synchronization is strictly limited to Simple and Configurable product types; other product types are not currently supported.
  • Fail-Safe Delta Sync: The automated background synchronization uniquely relies on a custom indexer and MySQL database triggers across four core tables, ensuring product modifications are captured even when made through direct SQL imports or third-party extensions.
  • Payload Customization: Data payloads are constructed via type-specific builder classes, but developers can safely alter product properties, query builds, or collections prior to synchronization by utilizing eight dedicated event hooks.

Consignment Updates - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector tracks shipping events from Fluent Order Management to update commercetools. Partners will learn to manage the inbound webhook pipeline that automatically generates native delivery records, parcel data, and carrier tracking links. For the business, this sync eliminates manual shipment logging and gives customers instant visibility into order transit via the storefront interface.Note: This article forms part of the inbound pipeline category, where data flows into the commercetools environment from an external source.
  • Core Function & Outcome: You will learn how the commercetools Connector captures consignment updates from Fluent Order Management to automatically generate delivery records, package manifests, and carrier tracking data inside commercetools.
  • Asynchronous Queue Infrastructure: Inbound webhook payloads undergo cryptographic signature and parameter verification in the first stage before entering an internal queue, where a named handler processes the data updates asynchronously in the second stage.
  • Structural Entity Mapping: The system maps Fluent consignment entities directly onto fulfillment models, which translate into native, line-item level delivery records to cleanly support orders split across multiple packages or locations.
  • Data Enrichment Mechanism: Because incoming webhooks carry minimal payloads to reduce network overhead, the connector automatically dispatches a `GetConsignmentById` GraphQL query back to Fluent to pull complete carrier details and package dimensions before updating commercetools.

Customer Sync - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector synchronizes customer profile data from a storefront to Fluent Order Management. Partners will learn to configure, validate, and extend this outbound data pipeline from the storefront trigger to the final GraphQL delivery. For the business, this real-time pipeline removes profile fragmentation, giving customer service agents instant access to accurate records.Note: This article forms part of the outbound pipeline category, where data flows out of the commercetools environment to an external destination.
  • Core Function & Outcome: You will learn how the commercetools Connector detects and processes customer creations and modifications automatically the moment they occur on the storefront, removing the need for manual batch data transfers.
  • Asynchronous Queue Infrastructure: The architecture routes payloads through an external `ct-queue` and an internal Event Queue sequentially, decoupling storefront event triggers from backend database processing to protect platform stability.
  • Declarative Route Filtering: Implementing partners can manage message types, configure explicit inclusion filters, and reassign target data pathways directly within the `application-connector.yml` configuration file without modifying core system code.
  • Extensible Handler Architecture: The core message routing and transformation layers are completely decoupled, enabling developers to cleanly introduce custom profile fields and data-mapping logic by extending the base `MessageHandler` class.

Fulfilment Updates - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector tracks line-item fulfillment events from Fluent Order Management to update commercetools. Partners will learn to configure inbound webhooks that update custom metadata containers and individual product states. For the business, this granular sync handles multi-location split quantities seamlessly, providing customers with real-time visibility into each item in an order.Note: This article forms part of the inbound pipeline category, where data flows into the commercetools environment from an external source.
  • Core Function & Outcome: You will learn how the commercetools Connector processes asynchronous fulfillment updates from Fluent Order Management to update line-item states and custom metadata objects inside commercetools.
  • Two-Stage Validation Framework: Inbound webhooks undergo a mandatory signature and parameter check in the first stage before entering the internal message queue, protecting the system from malformed data payloads.
  • Data Enrichment Mechanism: Since incoming webhooks transmit minimal payload data, the connector automatically queries Fluent Order Management to pull the complete context details required to finish processing.
  • Flexible Sourcing Support: Out-of-the-box functionality handles both basic single-location fulfillment pipelines and complex multi-location split-quantity scenarios.
  • Custom Handler Extensibility: Technical teams can extend the architecture by registering custom message handlers or overriding data-fetching logic to store specialized fields or drive extra business logic inside commercetools.

Aggregate Inventory Sync - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector synchronizes product availability from Fluent Order Management to commercetools at an aggregate level. Partners will learn to run scheduled batch jobs that push calculated stock balances to specific storefront channels. For the business, treating Fluent as the authoritative source of truth prevents digital overselling and ensures product detail pages display accurate stock numbers.Note: This article forms part of the inbound pipeline category, where data flows into the commercetools environment from an external source.
  • Core Function & Outcome: You will learn how the commercetools Connector runs scheduled batch jobs to fetch available product quantities from Fluent Order Management and update aggregate inventory balances within commercetools channels.
  • Single Source of Truth: Fluent Order Management serves as the authoritative master environment for tracking, computing, and distributing all aggregate stock positions down to the storefront.
  • Scheduled Batch Orchestration: The inventory synchronization pipeline runs via a dedicated batch job handler on a configurable frequency. Out-of-the-box orchestration leverages AWS Event Bridge scheduled triggers deployed via cloud formation templates.
  • Custom Handler Adaptability: Technical partners can cleanly alter inventory processing logic or add custom validation metrics by overriding default routing handlers within the standard configuration files.

Order Sync - commercetools Connector

Essential knowledgeCore knowledge to understand Fluent Commerce
Explains how the commercetools Connector manages the two-way pipeline that exports new orders from a storefront to Fluent Order Management and handles asynchronous status updates. Partners will learn to configure event-driven triggers, enable customer profile creations, and apply route filters. For the business, this real-time sync establishes a single source of truth for transactions across Home Delivery and store pickup channels.Note: This article forms part of the outbound pipeline category, where data flows out of the commercetools environment to an external destination.
  • Core Function & Outcome: You will learn how the commercetools Connector handles order exports from commercetools to Fluent Order Management, automates integrated customer profile creation, and establishes the webhook ecosystem for order status processing.
  • Out-of-the-Box Capabilities: Out-of-the-box (OOTB) functionality natively supports Home Delivery (HD) and Click and Collect (CC) order structures, complete with automated type-specific order number generation patterns.
  • System & Sync Limitations: Designed strictly for new transactions and does not synchronize historical orders created prior to extension installation. Additionally, the order update and modification handlers must be customized to fit your specific implementation needs.
  • Extensible Pipeline Architecture: The message routing and handler framework is completely decoupled. Developers can easily update message names, override standard classes, or extend the baseline order creation logic to attach custom operational attributes.

Connect SDK - Fluent Webhooks Integration

Essential knowledgeCore knowledge to understand Fluent Commerce
The Fluent Connect SDK offers seamless integration with Fluent Webhooks, enabling you to receive messages and perform various actions based on incoming calls. This document provides an overview of the core features of the Fluent Connect SDK and outlines the steps to integrate it into your application. Go here to read about Fluent Webhooks.
  • Standardized Webhook Ingestion: You will learn how the Connect SDK natively exposes a dedicated endpoint (`/api/v1/fluent-connect/webhook`) to receive inbound HTTP calls from Fluent Webhooks, automatically transforming raw payloads into the SDK's internal message queue format for scalable processing.
  • Automated Signature Verification: To protect the authenticity and integrity of system interactions, the SDK automatically runs signature validation checks on all incoming messages using environment-specific public keys pre-configured within the `application.yml` file.
  • Routing & Handler Dependencies: An important operational consideration is that an inbound webhook payload will only execute successfully if its event name explicitly corresponds to a designated internal message handler and an active, matching configuration route.
  • Local Development Tunnels: Because local execution environments (`localhost:8080`) are isolated from the internet, developers testing live Fluent workflows locally must utilize a secure tunneling utility like `ngrok` to create a publicly accessible URL that safely routes traffic back to the local webhook endpoint.

Adobe Commerce Connector - Core Authentication & Webhook Infrastructure

Essential knowledgeCore knowledge to understand Fluent Commerce
Establishes the foundational security mechanisms, credential mapping strategies, and inbound validation rules required to securely pass transactional payloads between Adobe Commerce and Fluent Commerce:
  • Safeguards multi-retailer setups by auto-mapping Adobe website scopes to isolated Fluent credentials.
  • Speeds up extensions via a unified API layer and an easily modifiable webhook validation chain (`di.xml`).
  • Webhooks require a strict 3-step signature and data check. Because all modules rely on this, any configuration issue breaks the entire integration.
  • Core Foundation & Outcome: You will learn how the General module acts as the integration's architectural backbone, housing all shared utilities, services, and core API authentication layers that every other module fundamentally depends on.
  • Scoped Multi-Retailer Support: If you skip the text, you must know that credentials are completely isolated per website scope, allowing each distinct Adobe Commerce website to map to and authenticate with its own specific Fluent retailer configuration.
  • Global Webhook Validation: All incoming webhooks share a centralized, 3-step validation chain (`MessageValidatorChain`) configured via `di.xml` that automatically enforces field presence, entity types, and security signature integrity.
  • System-Wide Dependency Risk: Because this module manages the single point of truth for global communication and data validation, any misconfiguration or failure here will break the entire integration ecosystem.

commercetools Connector Extend Configuration

Essential knowledgeCore knowledge to understand Fluent Commerce
The commercetools Connector features a highly adaptable runtime architecture governed by four baseline configuration files: `application-connector.yml`, `application.yml`, `bootstrap.yml`, and `logback-spring.xml`. Together, these files define core connector settings, server/container properties, and logging rules.To manage multi-environment rollouts efficiently, you can override common baseline settings by creating dedicated files that follow standard Spring Boot profile conventions (e.g., `application-dev.yml`) to isolate your development, staging, and production environments.
  • What You Will Learn: You will understand how to safely configure, secure, and scale the bidirectional data flow between commercetools and Fluent Commerce across multi-profile cloud environments without modifying core connector code.
  • Core File Architecture: The connector requires a strict baseline of four configuration files (`application-connector.yml`, `application.yml`, `bootstrap.yml`, and `logback-spring.xml`). You can dynamically override any environment setting by appending standard Spring Boot profile suffixes (e.g., `application-dev.yml`).
  • Critical Operational Guardrails: * Job Serialization: The asynchronous job scheduler enforces strict concurrency control—multiple instances of the same data synchronization job cannot run simultaneously.
    • Data Retention: Manual `customDateRange` overrides are destructive parameters; the connector executes the targeted historical timeframe exactly once and automatically deletes the custom range to prevent looping data.
  • Security and Performance Impact: Moving or updating sensitive external platform endpoints requires configuring the connector's dedicated credential storage layer. Additionally, message processing throughout during peak traffic events is directly governed by adjusting the `pool-size` and queue listener properties.

Integration Tests with the Connect SDK

How-to GuideStep-by-step guides to achieve a specific scenario or setup.
  • End-to-End Test Orchestration: You will learn how to wire, configure, and execute automated integration tests using specialized Connect SDK test modules (`connect-sdk-test-core`, `connect-sdk-test-core-aws`, and `connect-sdk-test-core-kafka`) to validate custom data handlers against simulated API footprints and containerized queue systems.
  • Execution Command Restrictions: Standard unit test triggers like `mvn test` will completely ignore these integration suites. You must invoke the pipeline using `mvn clean integration-test` and explicitly declare or preset the targeted active Spring profiles (such as `aws,localstack` or `kafka`) to instantiate the proper environment dependencies and messaging beans.
  • Isolated Bootstrapping Requirements: When building integration tests inside a decoupled code module that lacks a primary application runner, you must manually deploy an executable bootstrap class annotated with `@SpringBootApplication` and `@EnableScheduling` inside your `src/test/java` directory. Additionally, you must place three mandatory configuration manifests (`application.yml`, `application-connector.yml`, and `bootstrap.yml`) into the `src/test/resources` folder.
  • Automated Environment Isolation: The test suite leverages `Testcontainers` and `WireMock` to manage external asset lifecycles dynamically. Activating specific environment flags like `localstack` inside the configuration settings instructs the SDK to auto-provision localized mock instances of cloud services (including Amazon SQS queues, Amazon S3 buckets, and secrets vaults), eliminating the need to manage external persistent test infrastructure.

CLI Active Profile

Essential knowledgeCore knowledge to understand Fluent Commerce
Learn the technical mechanics of the Active Profile feature and how it streamlines CLI workflows. This article details the shift from rigid "Commander-enforced" validation to a flexible "Defaults-first" resolution, allowing implementing partners to work faster without sacrificing accuracy.For the business, this context-aware CLI reduces the learning curve and prevents manual entry errors. Note: While flags are no longer required at the command level (`required: false`), they remain mandatory for execution; the CLI will exit if no context is found.
  • The Shift: Validation has moved from the Commander parsing stage to the Configuration Utility stage.
  • Precedence: CLI flags always override the Active Profile. If you explicitly pass `--profile`, the active context is ignored for that command.
  • Seamless Integration: The `loadConfigs` utility now calls `resolveDefaults` first to populate missing options before handing them off to existing validation logic.
  • Unchanged Security: Standard validation functions like `loadProfile()` and `checkConfigForAccountProfile()` are still in place; they simply receive their data from a default source if flags are missing.
  • Developer Impact: Task definitions must have `required: true` removed from their options to allow the Active Profile logic to trigger.
  • Error States: If an Active Profile points to a nonexistent profile, the system will catch it during the `loadProfile` phase and exit with a `process.exit(1)`.

Send Enhanced Inventory Attributes in Your Payloads

Essential knowledgeCore knowledge to understand Fluent Commerce
Inventory payloads can include additional Inventory Quantity attributes to capture richer stock context.This article explains how to use the `attributes` object to include additional data in inventory payloads. It supports both simple key-value pairs and custom JSON structures to meet diverse business requirements - whether you’re:
  • managing detailed product information
  • optimizing warehouse processes
  • or integrating with custom workflows
The Inventory Reference Module supports a set of reference attributes that are persisted automatically, while custom attributes provide additional flexibility.
  • Prerequisites: To fully leverage the extended attributes functionality within the inventory payload, ensure that you are using the Inventory Reference Module v2.3.0 or later
  • Flexible attribute structure: The `attributes` object supports any combination of key-value pairs, including complex JSON structures and arrays. This flexibility allows you to customize the data sent in your inventory payloads to meet specific business needs
  • Use reference attributes first: Certain key attributes (such as `associationType`, `associationRef`, `parentRef`, `expectedOn`, `expiresOn`, `condition`, `storageAreaRef`, `supplier`, `manufacturer`, `manufacturerBatchNumber`, `countryOfOrigin`, and `channel`) will be directly updated in the Inventory Quantity associated with the incoming record, facilitating seamless integration with existing fields
  • Use segment fields for flexible key-value extensions: `segment1`, `segment2`, and `segment3` provide flexibility for additional flat classification data without introducing new custom attributes
  • Custom attribute availability: Any custom attributes that you include in the `attributes` object will be available in workflows via `inventoryPosition.inventoryQuantity.attributes.<fieldName>`. This enables you to incorporate custom data into rule-based processes or other logic tailored to your business requirements

User Lockouts: What to Expect After Too Many Failed Login Attempts

Essential knowledgeCore knowledge to understand Fluent Commerce
This article explains what happens when an account is temporarily locked due to multiple failed login attempts, whether caused by a user entering the wrong password or an integration using outdated credentials.After reading this article, you will understand:
  • What triggers a username lockout in Fluent 
  • How the lockout works 
  • What actions users and integration owners should take
Key Points to Know:
  • Lockouts are temporary (15 minutes).
  • Applies to both web console users and API clients.
  • A lockout is enforced even if the correct password is entered after the threshold is reached.
  • Accounts are locked after multiple failed login attempts ( 5 attempts).
  • Lockouts are specific to the username with failed login attempts
  • The lockout period is 15 minutes, starting from the last failed attempt.
  • Lockouts apply across all login methods (web, API, scripts) using the same username.
  • During a lockout for a given username:
    • All logins (even with correct credentials) will return an error
    • The error message will be exactly the same as providing an incorrect username and password (even with correct credentials)
  • The login screen and error messages will clearly reflect lockout status.
  • Technical users maintaining integration code should ensure their code does not retry authentication more than 5 times. 
  • Avoid account sharing between UI users and integrations to prevent cross-impact.
  • Contact Support if you're locked out and need urgent access.

Fetching Data with the useQuery Hook

Essential knowledgeCore knowledge to understand Fluent Commerce
This lesson focuses on fetching data within a custom form field using the `useQuery` hook. We'll move away from relying on page query data and instead directly query the Fluent GraphQL API to retrieve a list of nearby locations with product stock. This involves defining data structures for query results, storing the query in a constant, and using the `useQuery` hook to execute the query with dynamic parameters derived from the form's context and the user's context (via `useAuth`). We will then render the results in a selectable list using radio buttons.
  • Data Independence: Components should fetch their own data using the `useQuery` hook, rather than relying on potentially unavailable page query data.
  • GraphQL Query: A GraphQL query (`searchVirtualInventory`) is used to retrieve nearby locations with stock.
  • Data Structures: Interfaces (SVINode, SVIResult) are defined to structure the query results.
  • `useQuery` Hook: The `useQuery` hook is used to execute the GraphQL query with dynamic parameters.
  • Dynamic Parameters: Query parameters (`productRef`, `locationRef`, `lat`, `lng`) are derived from the form's entity context (product) and the user's context (location) using the `useAuth` hook.
  • Loading State: A loading state is implemented while the query progresses.
  • Result Rendering: The query results are initially logged to the console and then rendered as a list of selectable locations using radio buttons.
  • User Selection: A state variable and event handler are used to track the user's selected location.

Client Scenario: Building a Product Availability Map

Essential knowledgeCore knowledge to understand Fluent Commerce
This lesson introduces a practical client scenario: visualizing product availability on a map. Building upon the foundation laid in the UX Framework course, we'll enhance the Fluent Store app's Product Availability screen by adding a map that displays nearby store locations and stock information for a selected product variant. This hands-on lab will guide you through configuring the product lookup and detail availability pages, setting the stage for creating custom components in subsequent lessons.
  • Client Need: The client requires a visual representation of product availability in nearby stores, which would enable staff to locate items quickly for customers.
  • Map Functionality: The map should be integrated into the Product Availability details screen. It should display pins for the 10 closest stores with stock and show store details (name, product reference, available stock) when a pin is clicked. The map's appearance and behavior should be configurable via the manifest.
  • Product Lookup Configuration: This involves adding a new page to the Fluent Store app, using a List Component to display product variants, configuring list filters, and creating hyperlinks to product details pages.
  • Detail Availability Page Configuration: This includes creating a new page, linking it from the Product Lookup page, and adding card components to display product details and images. A List Component will show data from the search VirtualInventory query.
  • Hands-on Lab Focus: The lab simulates a real-world scenario where a customer seeks a specific shoe size, requiring a store associate to check nearby store inventory. This exercise will prepare you for creating custom components in the following lessons to realize the client's vision fully.

Configure a Data Source for your Page

Essential knowledgeCore knowledge to understand Fluent Commerce
In order to show data in the Storage Areas List, we need to configure a data source.Components on a page can reference a data source from a query defined on the Page Component.First, we'll configure a page query, to retrieve the currently active Location's associated Storage Areas.The `data` object on the Page Route takes a `query` and a `variables` object for defining a GraphQL Query.`"data": {``"query": "query locationStorageAreas ($locationRef: String!) { location (ref: $locationRef) { id ref storageAreas { edges { node { id name status type } } } } }",``"variables": {``"locationRef": "{{activeLocation.ref}}"``}``}`You'll notice the use of a special variable called `{{activeLocation.ref}}` above. Since this Web App Context is "location", you can access the currently active context using the `activeLocation` object. This provides access to the Location Id, Ref, and Primary Address.Once the Page query is defined, go to the Component configuration, and add a `dataSource` field. The `dataSource` for the list should be set to the `storageAreas` connection on the `location` query path: `location.storageAreas` `"dataSource": "location.storageAreas"`With the data source configured, all that's left is to update the fields to be displayed in the list with dynamic values. We'll display the Name, Type, and Status from the Storage Area.This is done by specifying the field of each node in the Storage Areas connection: `{{node.name}}` `"attributes": [``{``"label": "Name",`
`"value": "{{node.name}}"`
`},``{``"label": "Type",`
`"value": "{{node.type}}"`
`},``{``"label": "Status",`
`"value": "{{node.status}}"`
`}``]`See this in action in the video below...Note: This video does not have audio.
[Warning: empty required content area]

Add colours to statuses to highlight important information

Essential knowledgeCore knowledge to understand Fluent Commerce
This document provides an overview of enhancing visual representation within a system by displaying coloured dots. These dots serve as a quick reference to different statuses of orders or items, making it easier to recognize and prioritize tasks at a glance. You will learn how to customize the appearance of these dots by changing their colour through hex codes and understand the default settings. The guide also includes recommendations for a colour palette to optimize the utility of status indicators.
  • Feature Benefits: Utilize colourful dots to easily identify and prioritize different statuses.
  • Status Color Palette: Use recommended hex codes to customize dot colours for optimal status indication.
  • Configuration Guide: Follow step-by-step instructions to implement coloured status dots in your system. notify and prioritize different statuses.
  • Default Settings: The system defaults to a grey colour for statuses that are not configured, ensuring consistency across various status indicators.
  • Customization: Hex codes allow for full customization of dot colours to match your company's branding or to signify specific statuses.
  • Visual Prioritization: Assign colours to statuses based on the level of urgency or importance, aiding in quick decision-making.
  • Colour System Best Practices: Refer to the detailed best practices in the Colour section to effectively apply theming and enhance user experience.