Consignment Updates - commercetools Connector

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Essential knowledge

Intended Audience:

Technical User

Author:

Fluent Commerce

Changed on:

17 June 2026

Overview

The Consignment Updates module tracks shipping and delivery events from Fluent Order Management and synchronizes them to commercetools. When fulfillment actions conclude on the backend, the module processes outbound consignment statuses using secure webhooks. The connector captures these real-time operational milestones to automatically generate matching delivery structures, parcel data, and tracking identification links within the storefront interface.

Key points

What You Will Learn: You will understand how the connector processes Fluent Order Management consignment webhooks, translates data into storefront delivery objects, and injects parcel carrier tracking data.
Structural Entity Mapping: The consignment entity on the Fluent Order Management side maps directly onto the fulfillment entity model, which translates into native delivery records within commercetools.
Two-Stage Processing Framework: Inbound webhook payloads undergo initial signature verification and parameter validation in Stage 1 before passing to an internal queue. Stage 2 executes the specific named handler logic asynchronously.
Data Enrichment Mechanism: Because inbound webhooks transmit minimal data payloads to minimize overhead, the connector performs an automated backend GraphQL query to pull comprehensive shipment attributes from Fluent Order Management.
Granular Architectural Extensibility: Developers can extend code functionality or override default logic by registering custom message handlers within the `commercetools-connector` framework to track specialized downstream data points.

Data Pipeline Execution

commercetools Connector Integration Categories Guide

Here are the 3 different categories for commercetools connector integration articles, this article is part of the inbound pipeline category:

Inbound Pipelines: Data flows into the commercetools environment from an external source (e.g., Fluent Commerce). The connector acts as a listener, receiving and processing incoming requests to update commercetools resources.
Outbound Pipelines: Data flows out of the commercetools environment to an external destination (e.g., Fluent OMS). These are event-driven processes where changes in commercetools trigger the connector to export data to an external API.
Framework Utilities: These are foundational components that do not represent a specific data flow. They manage the internal mechanics of the connector, such as logging, scheduling background tasks, security configuration, and authentication.

1. Ingestion (Webhook/Batch Job)

Consignment tracking operates via an event-driven inbound webhook pipeline structured into a technical two-stage validation flow:

Stage 1 (Ingestion & Queueing): The first stage validates the incoming payload security signature and checks the content to ensure it has the required parameters. If all goes well, the request is added to the internal message queue to be processed asynchronously; otherwise, the connector will return an error to Fluent to signal that it was unable to accept the request.

2. Processing & Payload Extraction

Stage 2 (Handler Processing): The second stage is the actual processing of the webhook message. The message name is key to drive how the message is going to be processed, as these are mapped to specific internal handlers in the commercetools-connector. Partners can utilize this same approach by adding their own custom handlers and enabling the processing of different messages that are specific to their end goals.
All webhooks carry minimal information and require the commercetools-connector to fetch extra details from Fluent in order to complete processing the message received. The system achieves this by running a comprehensive GraphQL statement (`GetConsignmentById`) to extract package dimensions, carrier matrices, and product identifiers.

3. Target State Mapping (commercetools Mutation/Fields)

Once the complete consignment data model is extracted, the fields are mapped down to commercetools entities:

Delivery Create Mechanism: In commercetools, delivery is based on fulfillment items. Each delivery can be created for an item, and a Parcel will be created against item quantity. The system uses the fulfillment item list with fulfillment quantity to create Delivery and parcels in commercetools.

Consignment to Fulfillment Alignment: The consignment entity is mapped to the fulfillment entity on the Fluent side. Each Consignment will be created against the fulfillment (i.e., if there is more than one fulfillment, then there will be more than one consignment). In commercetools, the ordered item can show multiple fulfillments and multiple deliveries against each fulfillment. Inside the delivery tab, order items hold clear parcel details like provider name, measurements, and tracking URLs.

Data Storage & Schema Mapping

Delivery and Consignment Field Mapping Layout

Header parameters map between systems according to the following framework:

commercetools Fields	Fluent Fields	Description
Item SKU	Product Ref	Stock keeping unit reference matching across environments
Item Name	Product Name	Human-readable product description
Item Quantity	Filled Quantity	The physical quantity verified and packed
`flConsignmentRef`	Consignment Ref	Fluent Consignment Group key reference
`flConsignmentStatus`	Status	Fluent Consignment Status

Parcel and Article Field Mapping Layout

Package-level parameters map down onto custom tracking elements using the following data fields:

commercetools Fields	Fluent Fields	Description
Tracking ID	Label	Direct tracking code identifier
Parcel Ref	Article Ref	Unique item package line reference
Carrier	Carrier Name	Carrier company name
Provider	Fluent Account ID	Source system account identification string
Measurements	maxWeight	Physical weight and structural metrics
`flConsignmentTrackingUrl`	Label Url	Direct link to carrier tracking details

Developer Extension Points

Consignment Retrieval Query

The following statement is utilized by background handlers to extract delivery information from Fluent:

1query GetConsignmentById($consignmentId: ID!) {
2  consignmentById(id: $consignmentId) {
3    id
4    status
5    trackingLabel
6    consignmentReference
7    retailer {
8      id
9      ref
10    }
11    carrier {
12      name
13      id
14      type
15    } 
16    consignmentArticles {
17      consignmentArticleEdges: edges {
18        consignmentArticleNode: node {
19          article {
20            id
21            type
22            status
23            quantity
24            attributes {
25              name
26              type
27              value
28            }
29            description
30            height
31            weight
32            length
33            width
34            fulfilments {
35              fulfilmentEdges: edges {
36                fulfilmentNode: node {
37                  id
38                  status
39                  deliveryType
40                  type   
41                  items {
42                    fulfilmentItemEdges: edges {
43                      fulfilmentItemNode: node {
44                        ref
45                        filledQuantity
46                        requestedQuantity
47                        rejectedQuantity
48                        orderItem {
49                          ref
50                          id
51                        }
52
53                      }
54                    }
55                  }
56                }
57              }
58            }
59          }
60        }
61      }
62    }
63  }
64}

Inbound Webhook Consignment Payload

The JSON notification body transferred into internal queues follows this structural model:

1{
2  "id": "c321a113-9307-4269-9a91-a2f99cefe07b",
3  "name": "fc.connect.order.webhook.consignment-status-update",
4  "accountId": "CNCTDEV",
5  "retailerId": "1",
6  "rootEntityId": "127",
7  "rootEntityType": "ORDER",
8  "rootEntityRef": "CC_G_FROM_POSTMAN_929",
9  "entityId": "137",
10  "entityRef": "cf45b633-d91a-4eb2-84c9-36495dd3fec3",
11  "entityType": "CONSIGNMENT",
12  "entityStatus": "COMPLETE",
13  "type": "NORMAL",
14  "attributes": {}
15}