Fluent Commerce Logo
Docs

Basic Knowledge

Essential knowledge articles on integration.

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`.

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.

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.

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.

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