Fluent Commerce Logo
Docs
Sign In

How Comment GraphQL API works

Topic

Author:

Kirill Gaiduk

Changed on:

9 Dec 2024

Overview

The Comment API enables you to Create, Update, and Query comments linked to various entities within the Fluent platform.


Prerequisites

Comment GraphQL API Overview

Authors:

Girish Padmanabha, Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The Comment API allows customers to manage Comments across various Entities.

Multiple Comments can be added against the same , with each Comment automatically capturing:

  • The timestamp
  • The User who created it (`USER_VIEW` Permission is required to access the User data)

This feature allows Users to record specific business actions and events, providing a comprehensive history of interactions and updates.

Key points

  • Add Comments to any Entity Type, enabling detailed documentation of business actions
  • Specific Permissions are required for Comment operations
  • Use the `createComment` and `updateComment` Mutations to manage Comments
  • Use the `commentById` and  `comments` Queries to retrieve Comments

What are Comments for?

A Comment provides an additional piece of information to the it is related to. 

When creating a Comment, you can associate it with:

  • An Entity Type
  • Entity Id or Entity Reference

Making it retrievable via the `comments` Query.

Permissions

The following Permissions are required for different operations on Comments:

  • `COMMENT_CREATE`
  • `COMMENT_UPDATE`
  • `COMMENT_VIEW`
  • `USER_VIEW`

Features

The Comment API enables the following functionality:

Reference Usage

Here is a collection of common scenarios for the Comment API usage:

  • Order Entity:
    • Customer service representatives can add Comments regarding customer interactions or actions taken on an Order
    • Comments can document the business status updates or any issues related to the Order processing
  • Fulfillment Entity:
    • Store Users can add Comments when fulfilling Orders, noting any special instructions or issues encountered during the fulfillment process
  • Credit Memo Entity:
    • Financial teams can document reasons for issuing Credit Memos and any follow-up actions required
  • Return Order Entity:
    • Comments can be added detailing the reasons for Returns and the steps taken to process them
  • Location Entity:
    • Store managers can add Comments about: 
      • Inventory status
      • Store operations
      • Or any Location-specific updates

This flexibility allows the capture of essential information at various stages of business processes, ensuring that all relevant data is saved and can be retrieved when needed.

Create Comment

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The `createComment` Mutation allows the creation of a Comment against a known .


Prerequisites

Specific Permissions are required for creating Comments:

  • `COMMENT_CREATE`
  • `COMMENT_VIEW`

Key points

  • Use the `createComment` Mutation to create a Comment against a known Entity
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)
  • Created Comments inherit the `retailerId` of the associated Entity

Inputs

The Input fields for creating a Comment are defined with the `createCommentInput`:

Field

Type

Description

Notes

`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

Max character limit: 255

`entityId`

ID

Id of the

While the type of this field is ID, it currently only supports Integer values

`entityRef`

String

Reference of the

Max character limit: 255

`text`

String!

Comment text

Max character limit: 200

Validation

Comment Permissions could be managed at the or Retailer level, which is controlled via the `fc.graphql.comment.access` Setting

The `retailer` Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the `createComment` Mutation - "Retailer-specific Comment Permission Check":

1. Determine the `retailerId` of the Entity (associated with the Comment)

Entity Type Validation
  • The given `entityType` (Input) is compared with the existing Types (from the GraphQL Schema):
    • Case is ignored (e.g., `ORDER` matches `Order`
    • Underscore is ignored (e.g., `CREDIT_MEMO` matches `CreditMemo`)
    • Known exception: `FULFILMENT_OPTIONS` will be recognized as `FulfilmentOption` Type
  • The corresponding Database Entity Class is determined for the found GraphQL Type (e.g., `ORDER` Type corresponds to the `CustomerOrderEntity` Class)
Entity Id or Reference Validation
  • The Create Comment Payload could contain:
    • `entityId` only
    • `entityRef` only
    • Both `entityId` and `entityRef`
  • `entityId` is always considered first (to define the corresponding Entity for Comment creation)
  • `entityRef` is considered when `entityId` was not provided
Entity Retailer Id Validation
  • The `retailerId` value of the Entity found with the provided `entityType`, `entityId` / `entityRef` is automatically retrieved:
    • For Entity Types with the direct Retailer association, e.g., `retailerId` is taken from the `order.retailer` field value for Orders
    • For Entity Types without the direct Retailer association, the `retailerId` is attempted to be taken from a "Parent" Entity. For example, find the Fulfillment (with the provided `entityType`, `entityId` / `entityRef`) --> find its "Parent" Order --> get the `retailerId` from the Order
  • Comment `retailerId` field is filled in with the associated Entity Retailer value found.
  • Comment `retailerId` field remains empty when:
    • The associated Entity `retailerId` was not found
    • The associated Entity is a cross-Retailer one (e.g., Inventory Domain Entities, like Inventory Position, Virtual Catalog, etc.)
    • The `fc.graphql.comment.access` Setting value is set to `account`

2. Compare the querying User `retailerId` to the associated Entity `retailerId`

The User `retailerId` is defined with the User Role Context Id:

No alt provided

A Comment is created upon the mentioned (User and ) `retailerId`-s match.


Response

The response consists of the details of the Comment:

Field

Type

Description

Notes

`id`

ID!

Id of the Comment


`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

ID

Id of the


`entityRef`

String

Reference of the


`text`

String! 

Comment text

Max character limit: 200

`createdOn`

DateTime

Time of the Comment creation


`updatedOn`

DateTime

Time of the Comment last update


`user`

User

The author of the Comment

  • Filled in upon the Comment creation
  • Updated upon the Comment update
  • `USER_VIEW` Permission is required

Sample Payload

1mutation createComment ($input: CreateCommentInput) {
2    createComment (input: $input) {
3        id
4        entityType
5        entityRef
6        entityId
7        text
8        createdOn
9        updatedOn
10    }
11}
1{
2    "input": {
3        "entityType": "ORDER",
4        "entityId": "123",
5        "text": "Sample Comment for the Order"
6    }
7}
1{
2    "data": {
3        "createComment": {
4            "id": "26963",
5            "entityType": "ORDER",
6            "entityRef": null,
7            "entityId": "123",
8            "text": "Sample Comment for the Order",
9            "createdOn": "2024-12-09T09:15:57.396Z",
10            "updatedOn": "2024-12-09T09:15:57.396Z"
11        }
12    }
13}

Update Comment

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The `updateComment` Mutation allows for the updating of an existing Comment object.


Prerequisites

Specific Permissions are required for updating Comments:

  • `COMMENT_UPDATE`
  • `COMMENT_VIEW`

Key points

  • Use the `updateComment` Mutation to update an existing Comment
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Inputs

The Input fields for updating a Comment are defined with the `UpdateCommentInput`:

Field

Type

Description

Notes

`id`

ID!

Id of the Comment


`text`

String!

Comment text

Max character limit: 200

Validation

Comment Permissions could be managed at the or Retailer level, which is controlled via the `fc.graphql.comment.access` Setting

The `retailer` Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the `updateComment` Mutation - "Retailer-specific Comment Permission Check":

  • A target Comment is found by its Id (input)
  • A Comment Entity `retailerId` field stores a Retailer of the associated Entity
  • The Comment `retailerId` is compared to the querying User `retailerId` (defined with the User Role Context Id)
  • The Comment is updated upon the mentioned (User and Comment) `retailerId`'s match


Response

The response consists of the details of the Comment:

Field

Type

Description

Notes

`id`

ID!

Id of the Comment


`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

ID

Id of the


`entityRef`

String

Reference of the


`text`

String! 

Comment text

Max character limit: 200

`createdOn`

DateTime

Time of the Comment creation


`updatedOn`

DateTime

Time of the Comment last update


`user`

User

The author of the Comment

  • Filled in upon the Comment creation
  • Updated upon the Comment update
  • `USER_VIEW` Permission is required

Sample Payload

1mutation updateComment ($input: UpdateCommentInput) {
2    updateComment (input: $input) {
3        id
4        entityType
5        entityRef
6        entityId
7        text
8        createdOn
9        updatedOn
10    }
11}
1{
2    "input": {
3        "id": "26963",
4        "text": "Sample Comment"
5    }
6}
1{
2    "data": {
3        "updateComment": {
4            "id": "26963",
5            "entityType": "ORDER",
6            "entityRef": null,
7            "entityId": "123",
8            "text": "Sample Comment",
9            "createdOn": "2024-12-09T09:15:57.396Z",
10            "updatedOn": "2024-12-09T09:22:57.791Z"
11        }
12    }
13}

Get Comment by Id

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The `commentById` Query retrieves a Comment based on a provided Id.


Prerequisites

  • `COMMENT_VIEW` Permission is required for retrieving a Comment

Key points

  • Use the `commentById` Query to retrieve an existing Comment
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Inputs

The Input arguments for retrieving a single Comment:

Argument

Type

Description

`id`

ID!

Id of the Comment

Validation

Comment Permissions could be managed at the or Retailer level, which is controlled via the `fc.graphql.comment.access` Setting

The `retailer` Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the `commentById` Query - "Retailer-specific Comment Permission Check":

  • A target Comment is found by its Id (input)
  • A Comment Entity `retailerId` field stores a Retailer of the associated Entity
  • The Comment `retailerId` is compared to the querying User `retailerId` (defined with the User Role Context Id)
  • The Comment is retrieved upon the mentioned (User and Comment) `retailerId`'s match


Response

The response consists of the details of the Comment:

Field

Type

Description

Notes

`id`

ID!

Id of the Comment


`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

ID

Id of the


`entityRef`

String

Reference of the


`text`

String! 

Comment text

Max character limit: 200

`createdOn`

DateTime

Time of the Comment creation


`updatedOn`

DateTime

Time of the Comment last update


`user`

User

The author of the Comment

  • Filled in upon the Comment creation
  • Updated upon the Comment update
  • `USER_VIEW` Permission is required

Sample Payload

1query commentById ($id: ID!) {
2    commentById (id: $id) {
3        id
4        entityType
5        entityId
6        entityRef
7        text
8        createdOn
9        updatedOn
10        user {
11           username
12           id
13           ref
14           primaryEmail
15           firstName
16           lastName
17           timezone
18        }
19    }
20}
1{
2  "id": 123
3}

Query Comments

Author:

Kirill Gaiduk

Changed on:

20 Feb 2025

Overview

The `comments` Query retrieves Comments based on various filter criteria.


Prerequisites

  • `COMMENT_VIEW` Permission is required for retrieving Comments

Key points

  • Use the `comments` Query to retrieve existing Comments
  • Manage the Comment Permissions at the Account or Retailer level
  • Apply the "Retailer-specific Comment Permission Check" validation logic with the `fc.graphql.comment.access` Setting (`retailer` value)

Inputs

The Input arguments for retrieving Comments:

Argument

Type

Description

Notes

`entityType`

[String!]

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

[ID]

Id of the


`entityRef`

[String]

Reference of the


`text`

[String!]

Comment text


`createdOn`

DateRange

Date range for Comments creation


`updatedOn`

DateRange

Date range for Comments last update


`first`

Int

the first n elements from the list


`last`

Int

the last n elements from the list


`before`

String

the elements in the list that come before the specified global Id

This is a cursor (the value is used for pagination)

`after`

String

the elements in the list that come after the specified global Id

This is a cursor (the value is used for pagination)

Validation

Comment Permissions could be managed at the or Retailer level, which is controlled via the `fc.graphql.comment.access` Setting

The `retailer` Setting value enables the Retailer-specific access management, so the validation logic is applied to verify that your User has the correct rights to execute the `comments` Query - "Retailer-specific Comment Permission Check":

  • Comments are searched by the given Input Arguments
  • A Comment Entity `retailerId` field stores a Retailer of the associated Entity
  • For all the found Comments, the Comment `retailerId` is compared to the querying User `retailerId` (defined with the User Role Context Id)
  • The list of the retrieved Comments contains:
    • The Comments for which the mentioned (User and Comment) `retailerId`-s matches
    • The Comments with empty `retailerId`


Response

The response consists of the details of the Comment:

Field

Type

Description

Notes

`id`

ID!

Id of the Comment


`entityType`

String!

Type of the

For example:

  • `ORDER`
  • `FULFILMENT`
  • `ORDER_ITEM`
  • `PRODUCT_CATALOGUE`

`entityId`

ID

Id of the


`entityRef`

String

Reference of the


`text`

String! 

Comment text

Max character limit: 200

`createdOn`

DateTime

Time of the Comment creation


`updatedOn`

DateTime

Time of the Comment last update


`user`

User

The author of the Comment

  • Filled in upon the Comment creation
  • Updated upon the Comment update
  • `USER_VIEW` Permission is required

Sample Payload

1query comments($createdOn: DateRange) {
2    comments(createdOn: $createdOn) {
3        edges {
4            node {
5                id
6                entityId
7                entityRef
8                entityType
9                text
10                createdOn
11                updatedOn
12            }
13            cursor
14        }
15    }
16}
1{
2    "createdOn": {
3        "from": "2024-11-16T00:32:28.935Z",
4        "to": "2024-11-16T23:40:28.935Z"
5    }
6}