Fluent Commerce Logo
Docs
Sign In

commercetools connector - Order Status 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. processing happens in 2 stages.

Detailed Technical Description

The first stage is the validation of 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, the 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 driving 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 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 an status update message.

No alt provided

It is possible to override certain parts of the code and extend its functionality. For example, it can fetch more details from Fluent and either save them in commercetools or use them to drive extra logic.

Technical Flow

In commercetools, there are 3 different level status mappings:

  • Order Status Mapping
  • Payment Status Mapping
  • Shipment Status Mapping
Order Status Mapping

The status between Fluent and commercetools is kept in Fluent settings. The cardinality for status mapping is Many-to-one; N number of Fluent statuses can be mapped to the same commercetools status.

Fluent Mapping for Order Status

Add a property for the status mapping in the fluent setting.

`order-status-mapping: "fc.connect.commercetools.order.order-status-mapping"`

1{
2  "fluent": {
3    "RECEIVED": "Open",
4    "PENDING_PAYMENT": "Open",
5    "ESCALATED": "Open",
6    "BOOKED": "Confirmed",
7    "PICK_PACK": "Confirmed",
8    "PICK_PACK_CC": "Confirmed",
9    "AWAITING_COURIER_COLLECTION": "Confirmed",
10    "AWAITING_CUSTOMER_COLLECTION": "Confirmed",
11    "COMPLETE": "Complete",
12    "CANCELLED": "Cancelled"
13  }
14}
Payment Status Mapping

The payment status between Fluent and commercetools is kept in Fluent settings. The cardinality for payment status mapping is Many-to-one, N number of Fluent statuses can be mapped to the same commercetools payment status. In commercetools, payment status is at the header level so Out-of-the-box(OOTB) implementation is mapped against relevant Fluent status.

Fluent Mapping for Payment Status

Add a property for the payment mapping in the fluent setting.

`payment-status-mapping: "fc.connect.commerce-tools.order.payment-status-mapping"`

1{
2    "fluent": {
3        "RECEIVED": "pending",
4        "PENDING_PAYMENT": "pending",
5        "BOOKED": "paid"
6    }
7}
Shipping Status Mapping

The shipping status between Fluent and commercetools is kept in Fluent settings. The cardinality for shipping status mapping is Many-to-one, N number of Fluent statuses can be mapped to the same commercetools shipping status. In commercetools, overall shipping status is at the header level so OOTB implementation is mapped against relevant Fluent status.

Fluent Mapping for Shipping Status

Add a property for the Shipping mapping in a fluent setting.
`shipping-status-mapping: "fc.connect.commerce-tools.order.shipping-status-mapping"`

1{
2    "fluent": {
3        "RECEIVED": "Pending",
4        "BOOKED": "Pending",
5        "PICK_PACK": "Pending",
6        "AWAITING_COURIER_COLLECTION": "Shipped",
7        "COMPLETE": "Shipped"
8    }
9}

Order Update Mutation

Mutation to update the in commercetools `fc-commercetools-module/src/main/resources/ct-updateorderNumber.graphql`

1mutation Search($id: String!, $version: Long!, $actions: [OrderUpdateAction!]!) {
2  search: updateOrder(id: $id, version: $version, actions: $actions) {
3    id
4  }
5}

Out-of-the-box(OOTB) above mutations are provided, and partners can override it as per their requirement.

Fluent Webhook Order status payload

The below payload will be pushed to the internal queue.

1{
2    "id": "b34281d0-ada4-11e9-a1a7-5da7a83b9sd97cd",
3    "name": "fc.connect.order.webhook.order-status-update",
4    "accountId": "ACME",
5    "retailerId": "1",
6    "rootEntityId": "123",
7    "rootEntityRef": "O_123",
8    "rootEntityType": "ORDER",
9    "entityId": "123",
10    "entityRef": "O_123",
11    "entityType": "ORDER",
12    "entityStatus": "SHIPPED",
13    "type": "NORMAL",
14    "attributes": {}
15}