How Comment GraphQL API works
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
- You should have knowledge of the GraphQL API, including:
- You should have knowledge of Users, Roles, and Permissions
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:
- Create Comment
The`createComment`
Mutation allows the creation of a Comment against a known Entity.
- Update Comment
The`updateComment`
Mutation allows for the updating of an existing Comment object. - Get Comment by Id
The`commentById`
Query retrieves a Comment based on a provided Id. - Query Comments
The`comments`
Query retrieves Comments based on various filter criteria.
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
- Store managers can add Comments about:
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.
Related content
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 |
| String! | Type of the | For example:
Max character limit: 255 |
| ID | Id of the | While the type of this field is ID, it currently only supports Integer values |
| String | Reference of the | Max character limit: 255 |
| 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
- Case is ignored (e.g.,
- 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
- For Entity Types with the direct Retailer association, e.g.,
- 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`
- The associated Entity
2. Compare the querying User `retailerId`
to the associated Entity `retailerId`
The User `retailerId`
is defined with the User Role Context Id:

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 of the Comment | |
| String! | Type of the | For example:
|
| ID | Id of the | |
| String | Reference of the | |
| String! | Comment text | Max character limit: 200 |
| DateTime | Time of the Comment creation | |
| DateTime | Time of the Comment last update | |
| User | The author of the Comment |
|
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 of the Comment | |
| 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 of the Comment | |
| String! | Type of the | For example:
|
| ID | Id of the | |
| String | Reference of the | |
| String! | Comment text | Max character limit: 200 |
| DateTime | Time of the Comment creation | |
| DateTime | Time of the Comment last update | |
| User | The author of the Comment |
|
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 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 of the Comment | |
| String! | Type of the | For example:
|
| ID | Id of the | |
| String | Reference of the | |
| String! | Comment text | Max character limit: 200 |
| DateTime | Time of the Comment creation | |
| DateTime | Time of the Comment last update | |
| User | The author of the Comment |
|
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 |
| [String!] | Type of the | For example:
|
| [ID] | Id of the | |
| [String] | Reference of the | |
| [String!] | Comment text | |
| DateRange | Date range for Comments creation | |
| DateRange | Date range for Comments last update | |
| Int | the first n elements from the list | |
| Int | the last n elements from the list | |
| String | the elements in the list that come before the specified global Id | This is a cursor (the value is used for pagination) |
| 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`
- The Comments for which the mentioned (User and Comment)
Response
The response consists of the details of the Comment:
Field | Type | Description | Notes |
| ID! | Id of the Comment | |
| String! | Type of the | For example:
|
| ID | Id of the | |
| String | Reference of the | |
| String! | Comment text | Max character limit: 200 |
| DateTime | Time of the Comment creation | |
| DateTime | Time of the Comment last update | |
| User | The author of the Comment |
|
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}