Customer Sync - commercetools Connector
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
30 June 2026
Overview
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.Key points
- 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.
Data Pipeline Execution
1. Storefront Trigger (Subscription/External Queue)
The customer synchronization pipeline runs automatically in the background when changes occur on the storefront:- Stage 1 (CT-Queue Ingestion): Any customer creation or modification fires a native commercetools subscription event that pushes the notification payload out to an external
`ct-queue`. Out of the box, the connector implements AWS EventBridge for this layer but it can be implemented with other cloud native queue services such as GCP Pub/Sub or any other subscriptions supported by commercetools. More details on commercetools subscription. - Stage 2 (Internal Queueing): The
`CT Queue Listener`class constantly monitors and reads incoming messages directly from the`ct-queue`and pushes them directly to the internal Event Queue, which safely holds the transient event messages to prepare them for downstream evaluation.
2. Route Filtering & Message Routing
- Stage 3 (Message Routing): The internal Message Router evaluates the message name and
`typeId`extracted from the Event Queue to pass it to the appropriate handler. In the case of customer updates, the message`typeId`resolves to`customer`, which dynamically triggers a match against the`commercetools.connect.customer.upsert`route. Please refer commercetools Customer Messages for more information on supported messages.
3. Fluent API Delivery (GraphQL Mutation)
- Stage 4 (Handler Processing & Delivery): The Customer Updates Handler reads the payload from the internal queue. Based on the unique customer identifier, the handler extracts extra details from the core Commercetools-SDK (which interacts directly with commercetools APIs), transforms and maps the attributes to the Fluent data model, and dispatches the profile directly to Fluent Order Management.
Data Storage & Schema Mapping
Core commercetools Customer API Endpoints
The integration leverages the following endpoints to collect enriched profile details during pipeline execution:`GET : {{host}}/{{project-key}}/customers``GET : {{host}}/{{project-key}}/customers/{{Customer-id}}`
Developer Extension Points
For more details on how to extend please refer to the extend guidelines.Message Routing Configuration (`application-connector.yml`)
Partners can override default handlers or filter incoming message types by adjusting the route definitions:1- route: "commercetools.connect.customer.upsert"
2 props:
3 name: "customer"
4 inclusion-filter:
5 - "ResourceUpdated"
6 - "ResourceCreated"Custom Message Handler Implementation
Developers can introduce custom profile data adjustments by extending the base`MessageHandler` class within a package residing under the main SDK package directory `com.fluentcommerce.connect`:1@Slf4j
2@Component
3@HandlerInfo(name = "FluentCustomerUpsert")
4public class FluentCustomerCreateHandler extends MessageHandler {
5 private static final String CUSTOMER_ATTRIBUTE = "customer";
6 // write your logic
7}Customer Message Payload Reference
The following JSON schema demonstrates the structure of a raw message notification pushed onto the`ct-queue` when a customer event occurs:1{
2 "notificationType": "Message",
3 "projectKey": "fluent-ct-dev",
4 "id": "85c1c53e-75c8-413a-b8f5-08701292486e",
5 "version": 1,
6 "sequenceNumber": 3,
7 "resource": {
8 "typeId": "customer",
9 "id": "14a4ef54-957d-4148-b0be-de8d0fbc411d"
10 },
11 "resourceVersion": 3,
12 "resourceUserProvidedIdentifiers": {},
13 "type": "CustomerDeleted",
14 "createdAt": "2022-07-27T06:11:11.021Z",
15 "lastModifiedAt": "2022-07-27T06:11:11.021Z"
16}
