Fluent Commerce Logo
Docs
Sign In

commercetools connector - Consignment Updates

Feature

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.

No alt provided

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.

No alt provided
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.

No alt provided

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

No alt provided

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

No alt provided
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}