Category Sync - commercetools Connector
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
17 June 2026
Overview
The 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.Key points
- 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.
Data Pipeline Execution
1. Storefront Trigger (Subscription/External Queue)
Category record exports can be initiated via two distinct operational trigger paths:- Manual Batch Job: Triggered with the help of an external job scheduler. The number of records pushed depends on the date windows configured within
`Fluent Settings > Product Catalog Sync`. The extension pulls items modified from that designated date until the synchronization starts, implicitly adding categories mapped against those products. - Automatic Delta Sync: An automated background synchronization driven by commercetools subscriptions. Any category creation, modification, or removal pushes messages (supporting
`ResourceCreated`and`ResourceUpdated`variants) directly to the external`ct-queue`. More details on commercetools Subscription.
2. Route Filtering & Message Routing
- Stage 2 (Ingestion & Listening): For automated deltas, the
`CT Queue Listener`reads messages from the`ct-queue`and forwards them to the internal Event Queue. - Stage 3 (Routing Evaluation): The Message Router reads the message name from the Event Queue and routes it to the designated handler. In the case of category updates, the message name resolves to
`category`, which routes to`commercetools.connect.category.upsert`. Bulk requests instead route from a Batch Queue down onto a dedicated Category Batch Handler.
3. Fluent API Delivery (GraphQL Mutation)
- Stage 4 (Payload Delivery): The Category Updates Handler reads message data from the internal queue. Based on the target identifier, it extracts deep category structures from the Commercetools-SDK, transforms the parameters to align with the Fluent data model, and streams the finished configuration outbound to Fluent OMS.
Data Storage & Schema Mapping
Core commercetools Category API Endpoints
The connector queries the following endpoints to pull structural data during processing:`GET: {{host}}/{{project-key}}/categories``GET: {{host}}/{{project-key}}/categories/{{category-id}}`
Developer Extension Points
For more details on how to extend, please refer to the extend guidelines.Message Routing Configuration (`application-connector.yml`)
Please refer to commercetools Category Messages for more information on supported messages from CT.1fluent-connect:
2 - route: "commercetools.connect.category.upsert"
3 props:
4 name: "category"
5 inclusion-filter:
6 - "ResourceUpdated"
7 - "ResourceCreated"
8 - route: "commercetools.connect.category.deactivate"
9 props:
10 name: "category"
11 inclusion-filter:
12 - "ResourceDeleted"Custom Message Handler Implementation
Custom data transformation strategies can be introduced by creating a class extending`MessageHandler` registered under the main SDK package directory:1@Slf4j
2@Component
3@HandlerInfo(name = "FluentCategoryUpsert", description = "Upsert a category at Fluent OMS")
4public class FluentCategoryCreateHandler extends MessageHandler {
5 private static final String CATEGORY_ATTRIBUTE = "category";
6 // write your logic
7}Category Message Payload Reference
The following schema payload illustrates the structure of a category update event notice as delivered to the internal queues:1{
2 "notificationType": "Message",
3 "projectKey": "fluent-ct-dev",
4 "id": "96be0961-6b89-4ea8-b9e7-3c367e769f68",
5 "version": 1,
6 "sequenceNumber": 1,
7 "resource": {
8 "typeId": "category",
9 "id": "3f1d5cf9-e5f3-47eb-aa97-a845279c26f4"
10 },
11 "resourceVersion": 1,
12 "resourceUserProvidedIdentifiers": {
13 "slug": {
14 "en": "heel-shoes"
15 }
16 },
17 "type": "ResourceCreated",
18 "category": {
19 "id": "3f1d5cf9-e5f3-47eb-aa97-a845279c26f4",
20 "version": 1,
21 "versionModifiedAt": "2022-07-29T02:30:57.180Z",
22 "lastMessageSequenceNumber": 1,
23 "createdAt": "2022-07-29T02:30:57.180Z",
24 "lastModifiedAt": "2022-07-29T02:30:57.180Z",
25 "lastModifiedBy": {
26 "isPlatformClient": true,
27 "user": {
28 "typeId": "user",
29 "id": "0b28d312-6263-4fba-a0a4-da389fa7aef7"
30 }
31 },
32 "createdBy": {
33 "isPlatformClient": true,
34 "user": {
35 "typeId": "user",
36 "id": "0b28d312-6263-4fba-a0a4-da389fa7aef7"
37 }
38 },
39 "name": {
40 "en": "Heel Shoes"
41 },
42 "slug": {
43 "en": "heel-shoes"
44 },
45 "description": {
46 "en": "All Heel Shoes"
47 },
48 "ancestors": [],
49 "parent": {
50 "typeId": "category",
51 "id": "a122bf5e-feb4-4378-a37e-44306078d7ce"
52 },
53 "orderHint": "c2",
54 "assets": []
55 },
56 "createdAt": "2022-07-29T02:30:57.180Z",
57 "lastModifiedAt": "2022-07-29T02:30:57.180Z"
58}
