Basic Knowledge
Essential knowledge articles on integration.
Stock Segmentation - Data Model and API Overview
Essential knowledgeCore knowledge to understand Fluent CommerceStock 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 CommerceThis 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`.
Connect SDK Libraries
Essential knowledgeCore knowledge to understand Fluent CommerceThe 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.
Customer Sync - commercetools Connector
Essential knowledgeCore knowledge to understand Fluent CommerceExplains 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.
Send Enhanced Inventory Attributes in Your Payloads
Essential knowledgeCore knowledge to understand Fluent CommerceInventory 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
Orchestration Webhooks
Essential knowledgeCore knowledge to understand Fluent CommerceFluent workflows use webhooks for real-time communication with external systems, triggered at specific workflow points. Webhooks provide timely updates for order status, shipping, payments, and inventory movements. The standard SendWebhook rule simplifies outbound communication by sending basic data, allowing external systems to retrieve additional information as needed.- Webhooks enable real-time communication between Fluent workflows and external systems, eliminating the need for frequent API polling.
- The
`sendWebhook` rule simplifies outbound communication by passing essential data that external systems can use to fetch additional details. - Typical use cases include order status updates, shipping notifications, payment captures, and stock transfers.
- Webhooks should not be used for Inventory domain operations due to scalability concerns, performance impacts, and stability risks, so use Inventory Feeds instead.
- In rare cases where inventory-related webhooks are required (e.g., conditional stock change notifications), contact our team to discuss alternatives before implementation.
Inventory Ingestion
Essential knowledgeCore knowledge to understand Fluent CommerceInventory Ingestion in Fluent Commerce ensures that stock levels across all sales channels remain accurate and up-to-date, enabling effective inventory management. It allows businesses to send inventory updates to the platform using two distinct methods: Inventory Batch and Inventory Delta. Each method is tailored to different scenarios, depending on data volume, frequency, and operational needs.- Inventory Batches handle large-scale updates (thousands to millions of records), while Delta updates are ideal for smaller, incremental changes in real time.
- Batches use asynchronous processing for bulk data, grouped into Jobs for tracking, whereas Deltas are processed individually directly by the workflow engine.
- Batches are suited for periodic updates like ERP integrations and stocktakes, while Inventory Deltas are designed for real-time changes to reflect inventory movements such as store sales, returns, or daily adjustments.
- Batches require management of file sizes and grouping, while Deltas focus only on incremental updates, ensuring simplicity and speed for smaller changes.
commercetools Connector Extend Customization
Essential knowledgeCore knowledge to understand Fluent CommerceA Fluent Connector project typically has the structure as defined below :
com.fluentcommerce.connect.custom
Any customizations/extensions can either be done under the custom folder or as a separate module (jar) altogether.
Regardless of which way one chooses to extend it, the key message here is that any custom code should be under the `com.fluentcommerce.connect` package. This is due to how the FluentConnectorApplication is wired to work with Spring, and in its current form, Spring will only scan for components under `com.fluentcommerce.connect`.
During the server start-up, the commercetools-connector will load all handlers found in the spring context and bind them to the correct service they belong to. As part of this binding process, the commercetools-connector also determines which handler has precedence over others of the same name. In other words, it is possible to override existing handlers by assigning a higher priority to the custom handler. By default, all handlers will have a priority of zero, and the commercetools-connector understands the highest priority as the higher number. For example, priority = 100 takes precedence over priority = 1.`@HandlerInfo(name = "CustomCategoryUpsert", priority = 100)`[Warning: empty required content area]Inventory Ingestion
Essential knowledgeCore knowledge to understand Fluent CommerceInventory Ingestion in Fluent Commerce ensures that stock levels across all sales channels remain accurate and up-to-date, enabling effective inventory management. It allows businesses to send inventory updates to the platform using two distinct methods: Inventory Batch and Inventory Delta. Each method is tailored to different scenarios, depending on data volume, frequency, and operational needs.- Inventory Batches handle large-scale updates (thousands to millions of records), while Delta updates are ideal for smaller, incremental changes in real time.
- Batches use asynchronous processing for bulk data, grouped into Jobs for tracking, whereas Deltas are processed individually directly by the workflow engine.
- Batches are suited for periodic updates like ERP integrations and stocktakes, while Inventory Deltas are designed for real-time changes to reflect inventory movements such as store sales, returns, or daily adjustments.
- Batches require management of file sizes and grouping, while Deltas focus only on incremental updates, ensuring simplicity and speed for smaller changes.