commercetools connector - Consignment Updates
Changed on:
31 Jan 2024
Overview
This tracks the updates from Fluent and pushes it to commercetools. Fluent use webhooks to achieve this.
Consignment updates are about Shipping and Delivery events and processes. Once fulfilment actions are completed at the Fluent side it would push status to commercetools. On commercetools side, the delivery method should be created once the is triggered and the mapped handler is processed
The is mapped to the fulfilment on the fluent side.
Detailed Technical Description
Technical flow
The first stage validates the signature and checks the content has the required parameters. If all goes well, the request is added to the internal message queue to be processed asynchronously otherwise will return an error to Fluent to signal that it was unable to accept the request.
The second stage is the actual processing of the message. The message name is key to drive, how the message is going to be processed as these are mapped to internal handlers in commercetools-connector.
Partners can utilize the same approach by adding their own handlers and enabling the processing of different messages that are specific to their end goals.
All webhooks carry minimal information and require commercetools-connector to fetch extra details from Fluent in to complete processing the message received. The diagram below represents the flow executed for a status update message.

It is possible to override certain parts of the code and extend its functionality. For example, fetching more details from Fluent and either saving it in commercetools or using it to drive extra logic.
Consignment Status
Once the is created at Fluent, it sends the with some custom data along with other details like status to update the status at commercetools.
Below are the custom fields at commercetools :
- flConsignment - Fluent Consignment Group key
- flConsignmentRef - Fluent Consignment Ref
- flConsignmentStatus - Fluent Consignment Status
Delivery Create Mechanism
In commercetools delivery is based on fulfilment items. Each delivery can be created for an item and a Parcel will be created against item quantity.
Use fulfilment item list with fulfilment quantity to create Delivery and parcels in commercetools.

commercetools Delivery fields and Consignment fields Mapping:
commercetools Fields | Fluent Fields |
Item SKU | Product Ref |
Item Name | Product Name |
Item Quantity | Filled Quantity |
flConsignmentRef | Ref |
flConsignmentStatus | Status |
commercetools Parcel fields and Article fields Mapping
commercetools Fields | Fluent Fields |
Tracking ID | Label |
Parcel Ref | Ref |
Carrier | Carrier Name |
Provider | Fluent ID |
Measurements | maxWeight |
flConsignmentTrackingUrl | Label Url |
Consignment Process Example
Each will be created against the fulfilment, i.e. if there is more than one fulfilment then there will be more than one . As shown in the below snapshots in commercetools the ordered item has two fulfilment and two delivery( in fluent) against each fulfilment.

Inside the delivery tab, items have parcel details like provider name, measurements, tracing URL etc. as shown below snapshot.

On the Fluent side, the will look like the below snapshot.

Fluent Consignment Query
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}
Fluent Webhook Consignment payload
The below payload will be pushed to the internal queue.
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}