Fluent Commerce Logo
Docs
Help & Feedback

Basic Knowledge

Essential knowledge articles on Connect SDK

Category Sync - commercetools Connector

Essential knowledgeThe Category Sync module is responsible for synchronizing categories from commercetools outbound to Fluent Commerce to establish matching catalog structures and navigation nodes across both environments.
  • Core Function & Outcome: Coordinates the export of category trees from commercetools down to Fluent OMS using event consumers and batch pipelines.
  • Dual-Trigger Execution: Supports manual, scheduler-driven complete catalog extraction alongside automatic background delta tracking.
  • Subscription Management: Relies on core commercetools subscriptions to stream real-time creation and modification alerts into the integration layers.
  • Extensible Routing Architecture: Allows business rules, message paths, and handler logic maps to be safely overridden via central YAML configurations.

External Webhook Integration Architecture - commercetools Connector

Essential knowledgeEnables the system to receive and process payloads from external webhooks, integrating them into the Fluent Commerce ecosystem.
  • Sync Type: Automatic, based on incoming webhook events.
  • Payload Handling: External systems push data to the connector, which acts as the ingestion point.
  • CT Queue Listener: Reads messages from the queue and facilitates the routing of the payload.
  • Event Queue: Holds event messages for processing by the appropriate handlers.

Consignment Updates - commercetools Connector

Essential knowledgeThe Consignment Updates module tracks shipping and delivery events from Fluent Order Management and synchronizes them to commercetools. When fulfillment actions conclude on the backend, the module processes outbound consignment statuses using secure webhooks. The connector captures these real-time operational milestones to automatically generate matching delivery structures, parcel data, and tracking identification links within the storefront interface.
  • What You Will Learn: You will understand how the connector processes Fluent Order Management consignment webhooks, translates data into storefront delivery objects, and injects parcel carrier tracking data.
  • Structural Entity Mapping: The consignment entity on the Fluent Order Management side maps directly onto the fulfillment entity model, which translates into native delivery records within commercetools.
  • Two-Stage Processing Framework: Inbound webhook payloads undergo initial signature verification and parameter validation in Stage 1 before passing to an internal queue. Stage 2 executes the specific named handler logic asynchronously.
  • Data Enrichment Mechanism: Because inbound webhooks transmit minimal data payloads to minimize overhead, the connector performs an automated backend GraphQL query to pull comprehensive shipment attributes from Fluent Order Management.
  • Granular Architectural Extensibility: Developers can extend code functionality or override default logic by registering custom message handlers within the `commercetools-connector` framework to track specialized downstream data points.

Customer Sync - commercetools Connector

Essential knowledgeCustomer Sync is responsible for synchronizing customers from commercetools to Fluent.
  • Automatic detection and synchronization of customers Created/Modified.

Aggregate Inventory Sync - commercetools Connector

Essential knowledgeThe Aggregate Inventory Sync module enables product inventory synchronization from Fluent Order Management to commercetools at an aggregate level. Under this architecture, Fluent Order Management acts as the master single source of truth for all inventory data. When aggregate quantities change, the connector distributes those updates to matching storefront network configurations.
  • Core Function & Outcome: You will learn how the module 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 knowledgeThe Order Sync module manages the two-way pipeline responsible for exporting newly placed orders from commercetools to Fluent Order Management and receiving asynchronous order updates back. This module acts as the core operational anchor for the integration, exposing a foundational webhook that downstream extensions—such as fulfillment and consignment—leverage to track and synchronize order lifecycles across platforms.
  • Core Function & Outcome: You will learn how the module 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: The module is 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 knowledgeThe 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.

Connect SDK Libraries

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

Customization Guidelines for Connect SDK

Essential knowledgeThe SDK's handling mechanism involves loading and prioritizing handlers during server startup. It provides transparency with special spring actuators for listing active routes and handlers. Message handlers follow error-handling protocols, while job handlers process data polled from external systems. Configuration handlers react to changes, and the SDK supports various ways of receiving messages from external systems.
  • Handler Prioritization: Customize execution order by assigning priorities during startup.
  • Message Handling Protocols: Follow specific rules for retries, dead letter queue forwarding, and managing multiple items within a message.
  • Implementation Guidelines: Adhere to guidelines, use annotations like @HandlerInfo and @Component, and configure routes. Extensibility is seen in job handlers, configuration handlers, and product availability enrichments.
  • Receiving External Messages: Support diverse methods, including HTTP requests with authentication filters and external listeners like SQS and Kafka. Custom controllers enhance authentication through the SDK's security module.

Connect SDK Overview

Essential knowledgeConnect SDK is the launchpad to connect any external system with Fluent Commerce in a predictable way. It reduces implementation timelines and costs so customers can see faster ROI. Technically, Connect SDK is a Java Maven Archetype and Java Library Utils that form a toolkit for building Spring Boot micro-service applications that communicate with the Fluent Order Management System and any external system.
  • Connect SDK helps partners and customers quickly start building ad hoc connectors with consistency, better security, and short implementation time.
  • A deployed Connect SDK-based integration simplifies middleware setup and support 
  • It offers incredible flexibility in building synchronous and asynchronous endpoints with a common credential, logging, and configuration interface
  • In regards to hosting responsibility, any connector built using Connect SDK is cloud-agnostic, and the integration layer is still owned and maintained by the solution integrator, becoming part of the project codebase.

commercetools connector - Fluent Settings

Essential knowledgeThe connector requires the settings below to process data being transmitted from Fluent to commercetools and vice versa. It contains a mix of settings and data mapping tables.
  • Account Mapping
  • General Mapping
  • Product Catalog Sync
  • Inventory Sync
  • Location Sync
  • Order Status
  • Shipping Method
  • Shipping Status
  • Payment Status
  • Fulfilment Status
  • Unit Conversion

Connector Deployment Cloudformation

Essential knowledgeAttached to this page is the “connectors.yaml” template which is used to create Cloudformation Stack for the Connectors API. The resulting stack deploys ECS Fargate containers that run the API and produce a public endpoint. This public endpoint is secured with an SSL certificate which is applied to the Application Load Balancer.
  • Disclaimer
  • Prerequisites
  • Manual Deployments
  • Stack Provisioned

commercetools Connector Project Configuration

Essential knowledgecommercetools Connector Project Configuration
  • Configuration files
  • Route Mappings
  • Routes
  • Listeners

Fluent Connect SDK Architecture

Essential knowledgeThis article will cover the high-level design and features of the SDK.
  • The Connect SDK architecture consists of core, cloud, and additional libraries, enabling the building and extension of connectors. 
  • Key features include configurations, a secret manager for sensitive information, a scheduler for periodic operations, listeners/subscribers, web services/webhooks, an event log, product availability options, and SDK handlers for custom business logic. 
  • The message lifecycle follows a specific flow, and there are two integration approaches: Pull and Push. The SDK offers patterns for scheduled operations and receiving external requests, and it includes dead letter queues, metrics, and logs for monitoring and observability.
  • Build and deployment use SpringBoot, generating a deployable JAR with an embedded Tomcat.
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