Fluent Commerce Logo
Docs

Order Sync - commercetools Connector

Essential knowledge

Intended Audience:

Technical User

Author:

Fluent Commerce

Changed on:

30 June 2026

Overview

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.

Key points

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

Data Pipeline Execution

No alt provided

1. Storefront Trigger (Subscription/External Queue)

Order exports follow a real-time event-driven trigger mechanism:
  • Stage 1 (Subscription): commercetools emits an `OrderCreated` event. The platform’s Subscription service captures this and publishes it to the `CT-Queue` (e.g., AWS EventBridge or SQS).
  • Stage 2 (Listener): The `CT Queue Listener` consumes the message, verifying the event origin, and pushes the message to the internal `Event Queue` for processing.

2. Route Filtering & Message Routing

  • Stage 3 (Routing): The `Message Router` reads the message name (`commercetools.connect.order.create`) and filters based on the `inclusion-filter` property defined in `application-connector.yml`. Only resources matching `ResourceCreated` proceed to the execution layer.

3. Fluent API Delivery (GraphQL Mutation)

  • Stage 4 (Handler Execution): The `OrderCreateHandler` fetches detailed order data (including tax breakdowns and custom fields) from the commercetools SDK. It calculates the `orderType` (HD or CC) based on the shipping method, generates a patterned order number if required, ensures the customer exists in Fluent, and dispatches the `createOrder` mutation.

Data Storage & Schema Mapping

commercetools AttributeFluent OMS TargetLogic/Pattern
`orderNumber``ref`Auto-generated if blank (e.g., `order-CC20...`)
`shippingInfo``shippingMethod`Mapped via `fc.connect...shipping-method-mapping`
`customer``customerRef`Identified/Created in Fluent via GraphQL
`customFields``attributes`Serialized into Fluent attribute list

Developer Extension Points

For more details on how to extend please refer to the extend guidelines

1. Message Routing Configuration (`application-connector.yml`)

2. Auto Order Number Creation Logic

3. Customer GraphQL Mutation Logic

4. Custom Message Handler Implementation

5. Order Queries and Mutations