Location Sync - commercetools Connector
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
17 June 2026
Overview
This module manages the synchronization of fulfillment locations from Fluent Order Management to commercetools. Monitored locations can include physical retail stores, warehouses, drop-ship vendors, lockers, or third-party collection points. The connector tracks these physical nodes and maps them directly to native commercetools`Channel` entities.Key points
- Core Function & Outcome: You will learn how this module utilizes a scheduled batch job to extract fulfillment locations from Fluent Order Management and create or update matching storefront channels.
- Target Entity Translation: The module maps location records to the native commercetools
`Channel`entity type, ensuring backend fulfillment nodes exist within the storefront ecosystem. - Parameter-Driven Filtering: The orchestration pipeline utilizes precise timestamp parameters and network reference settings to isolate and update specific inventory networks.
- Flexible Sync Strategies: The architecture supports comprehensive full or partial database extractions based on manual configurations, alongside automated background delta sync schedules.
Data Pipeline Execution
1. Ingestion (Webhook/Batch Job)
The location data will be synced from Fluent to commercetools via an integration batch job. The job execution window is managed and controlled through a dedicated timestamp parameter to be set in Fluent Settings under the property name`fc.connect.commerce-tools.batch.batch-location-sync`. On behalf of these configured setting values (such as dates and network properties), matching commercetools channel details get created or updated in the Merchant Center.The system supports two primary integration scheduling scenarios:- Full & Partial Sync: Full & Partial sync should be implemented using a setting in the Fluent configuration interface; the commercetools connector fetches all Fluent locations modified since the chosen date against the mapped network.
- Delta Sync: Delta sync can be executed daily on the desired frequency, and it fetches all Fluent locations modified since the timestamp of the last successful sync operation.
2. Processing & Payload Extraction
When the batch job runs, the connector fires an outbound GraphQL request (`GetLocations`) to Fluent Order Management. The query dynamically injects filtering parameters (`after`, `first`, `updatedOnFrom`, `updatedOnTo`) to safely isolate modified location models. The connector receives the GraphQL response payload, extracts physical attributes, evaluates structural hours schedules, reads metadata arrays, and feeds the structured data into the internal execution pipeline.3. Target State Mapping (commercetools Mutation/Fields)
The integration layer processes the extracted dataset and translates the fields directly into corresponding targets. It creates or updates Channel records inside the commercetools Merchant Center, ensuring that contact phone lines, system status values, coordinate geometry, and regional attributes are properly recorded.Data Storage & Schema Mapping
Location Fields Mapping Grid
Data parameters convert from Fluent fields to commercetools Channel layouts according to the following mapping schema:| Fluent Field Name | commercetools Field Name | commercetools Custom Field Identifier |
| Ref | Channel Key | System Native Key |
| Store Name | Channel Name | System Native Name |
| Phone | Phone No. | `flStorePhoneNo` |
| User Email | `flStoreEmail` | |
| Type | Type | `flStoreType` |
| Status | Status | `flStoreStatus` |
| Address Line 1 | Street Name | System Native Field |
| Address Line 2 | City | System Native Field |
| Address Line 3 | State | System Native Field |
| Address Line 4 | Postal Code | System Native Field |
| Address Line 5 | Country | System Native Field |
| Latitude | Latitude | `flStoreLatitude` |
| Longitude | Longitude | `flStoreLongitude` |
| Timezone | Timezone | `flStoreTimezone` |
| Opening Hours | Opening Schedule | `flOpeningSchedule` |
| Attributes | Attributes | `flStoreAttributes` |
Developer Extension Points
Batch Sync Setting Profile Schema
The JSON structure below illustrates how the sync job tracks bounding timestamps and network boundaries:1{
2 "previousEndDate": "2022-10-20T04:12:44.707061681",
3 "props": {
4 "fluentNetworkRef": "BASE_1"
5 },
6 "lastRun": {
7 "param": {
8 "start": "2022-10-19T04:12:45.104341414",
9 "end": "2022-10-20T04:12:44.707061681",
10 "props": {
11 "fluentNetworkRef": "BASE_1"
12 }a
13 },
14 "jobStart": "2022-10-20T04:12:44.615441435",
15 "jobEnd": "2022-10-20T04:12:44.737175454",
16 "status": "SUCCESSFUL"
17 }
18}Outbound Location Retrieval Query
The module dispatches the following statement to poll Fluent for location updates during batch job execution:JSON.
1query GetLocations($after: String, $first: Int, $updatedOnFrom: DateTime, $updatedOnTo: DateTime) {
2 locations(after: $after, first: $first, updatedOn: {from: $updatedOnFrom, to: $updatedOnTo}) {
3 locationEdge: edges {
4 locationNode: node {
5 ref
6 name
7 supportPhoneNumber
8 createdOn
9 updatedOn
10 type
11 status
12 openingSchedule {
13 allHours,
14 monEnd,
15 monStart,
16 tueEnd,
17 tueStart,
18 wedEnd,
19 wedStart,
20 thuEnd,
21 thuStart,
22 friEnd,
23 friStart,
24 satEnd,
25 satStart,
26 sunEnd,
27 sunStart
28
29 }
30 attributes {
31 name
32 type
33 value
34 }
35 primaryAddress {
36 street
37 city
38 state
39 postcode
40 country
41 region
42 latitude
43 longitude
44 timeZone
45 }
46 networks( first:100) {
47 networkEdge: edges {
48 networkNode: node {
49 ref
50 }
51 }
52 }
53 }
54 cursor
55 }
56 pageInfo {
57 hasNextPage
58 }
59 }
60}
