Fluent Commerce Logo
Docs
Sign In

GraphQL Operations

Essential knowledge

Author:

Fluent Commerce

Changed on:

21 June 2024

Overview

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. 

In Fluent's GQL operation, it has split into 2 actions:

  • Queries 
  • Mutations

Key points

  • Operations
  • Queries
  • Mutations
  • Custom Queries

Operations

No alt provided


Queries

Query operations are used for retrieving data. Fluent's GraphQL API has two types of query operations:

  • Get Operations
  • Search Operations
Get Operations

Get operations always return a single result. These operations should be used when a unique identifier for the object to be retrieved is known. This can be an ID or a Ref (for reference), both, or in some cases, something else. This is discussed in more detail on the GraphQL Queries page.

Examples
1{
2  order(ref: "Order-Ref-100") {
3    ref
4    type
5    status
6    items {
7      edges {
8        node {
9          status
10          product {
11            name
12          }
13          paidPrice
14          currency
15        }
16      }
17    }
18    fulfilments {
19      edges {
20        node {
21          status
22          createdOn
23          deliveryType
24          fromAddress {
25            name
26            companyName
27            street
28            state
29            postcode
30          }
31          toAddress {
32            name
33            companyName
34            street
35            state
36            postcode
37          }
38        }
39      }
40    }
41  }
42}

Language: graphqlschema

Name: Get an Order with ref "Order-Ref-100" - Example Request

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "order": {
4      "ref": "Order-Ref-100",
5      "type": "HD",
6      "status": "BOOKED",
7      "items": {
8        "edges": [
9          {
10            "node": {
11              "status": "NEW",
12              "product": {
13                "name": "simple sku"
14              },
15              "paidPrice": 10,
16              "currency": "AUD"
17            }
18          }
19        ]
20      },
21      "fulfilments": {
22        "edges": [
23          {
24            "node": {
25              "status": "CREATED",
26              "createdOn": "2019-09-19T01:01:42.448Z",
27              "deliveryType": "STANDARD",
28              "fromAddress": {
29                "name": "Darth Vader",
30                "companyName": "Star Wars",
31                "street": "200 Secret",
32                "state": "VIC",
33                "postcode": "3032"
34              },
35              "toAddress": {
36                "name": "Luke Skywalker",
37                "companyName": "",
38                "street": "3 Grandiflora Gr",
39                "state": "VIC",
40                "postcode": "3030"
41              }
42            }
43          }
44        ]
45      }
46    }
47  }
48}

Language: graphqlschema

Name: Get an Order with ref "Order-Ref-100" - Example Response

Description:

[Warning: empty required content area]
1{
2  orderById(id: 100) {
3    id
4    ref
5    type
6    status
7    fulfilments {
8      edges {
9        node {
10          status
11          createdOn
12          deliveryType
13          fromAddress {
14            name
15            companyName
16            street
17            state
18            postcode
19          }
20          toAddress {
21            name
22            companyName
23            street
24            state
25            postcode
26          }
27        }
28      }
29    }
30  }
31}

Language: graphqlschema

Name: Get an Order with id "100" - Example Request

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "orderById": {
4      "id": "100",
5      "ref": "Order-Ref-100",
6      "type": "HD",
7      "status": "BOOKED",
8      "fulfilments": {
9        "edges": [
10          {
11            "node": {
12              "status": "CREATED",
13              "createdOn": "2019-09-19T01:01:42.448Z",
14              "deliveryType": "STANDARD",
15              "fromAddress": {
16                "name": "Darth Vader",
17                "companyName": "Star Wars",
18                "street": "200 Secret",
19                "state": "VIC",
20                "postcode": "3032"
21              },
22              "toAddress": {
23                "name": "Luke Skywalker",
24                "companyName": "",
25                "street": "3 Grandiflora Gr",
26                "state": "VIC",
27                "postcode": "3030"
28              }
29            }
30          }
31        ]
32      }
33    }
34  }
35}

Language: graphqlschema

Name: Get an Order with id "100" - Example Response

Description:

[Warning: empty required content area]
Search Operations

Search operations filter out objects of a given type. These operations should be used when searching for objects that meet one or more of a given criteria. An example of such an operation would be to search for and get all Orders of type "HD". Search operations are also great for reporting on particular types.

Example
1{
2  orders(type: "HD") {
3    edges {
4      node {
5        id
6        ref
7        type
8        status
9      }
10    }
11  }
12}

Language: graphqlschema

Name: List Orders of type "HD" - Example Request

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "orders": {
4      "edges": [
5        {
6          "node": {
7            "id": "1488206",
8            "ref": "HD-ORDER-REF-743",
9            "type": "HD",
10            "status": "BOOKED"
11          }
12        },
13        {
14          "node": {
15            "id": "1488205",
16            "ref": "HD-ORDER-REF-1643",
17            "type": "HD",
18            "status": "BOOKED"
19          }
20        },
21        {
22          "node": {
23            "id": "1488203",
24            "ref": "HD-ORDER-REF-5037",
25            "type": "HD",
26            "status": "COMPLETE"
27          }
28        },
29        {
30          "node": {
31            "id": "1488202",
32            "ref": "HD-ORDER-REF-3051",
33            "type": "HD",
34            "status": "BOOKED"
35          }
36        },
37        {
38          "node": {
39            "id": "1488200",
40            "ref": "HD-ORDER-REF-6260",
41            "type": "HD",
42            "status": "COMPLETE"
43          }
44        },
45        {
46          "node": {
47            "id": "1488198",
48            "ref": "HD-ORDER-REF-6099",
49            "type": "HD",
50            "status": "COMPLETE"
51          }
52        },
53        {
54          "node": {
55            "id": "1488196",
56            "ref": "HD-ORDER-REF-7798",
57            "type": "HD",
58            "status": "COMPLETE"
59          }
60        },
61        {
62          "node": {
63            "id": "1488194",
64            "ref": "HD-ORDER-REF-9643",
65            "type": "HD",
66            "status": "COMPLETE"
67          }
68        },
69        {
70          "node": {
71            "id": "1488192",
72            "ref": "HD-ORDER-REF-9181",
73            "type": "HD",
74            "status": "COMPLETE"
75          }
76        },
77        {
78          "node": {
79            "id": "1488190",
80            "ref": "HD-ORDER-REF-8637",
81            "type": "HD",
82            "status": "COMPLETE"
83          }
84        }
85      ]
86    }
87  }
88}

Language: graphqlschema

Name: List Orders of type "HD" - Example Response

Description:

[Warning: empty required content area]
Additional Information

To pass schema complexity validation, all Graphql API operation queries must meet the following standards:

  • All GraphQL search queries can be supplied with a first or last argument. In the absence of these arguments, the query will return the first 10 records.
  • Values of first and last must be within 1 - 5,000. If the value exceeds 5000, it is replaced by 5000.
  • Each GraphQL query has complexity. The GraphQL server does not support the execution of queries that exceed the complexity number of 11,111.


Mutations

GraphQL operations that are used for creating or updating data are called Mutations. The Fluent GraphQL API provides three types of mutation operations; Create, Update and Remove.

Mutation operations return an object type and it’s up to the user to request only the fields they require.

Examples
1mutation {
2  createRole (input: {
3    name: "ROLE_MANAGER"
4    permissions: [
5      { name: "ROLE_VIEW" },
6      { name: "PERMISSION_VIEW" },
7      { name: "ROLE_CREATE" },
8      { name: "ROLEPERMISSION_UPDATE" }
9    ]
10  }) {
11    id
12    name
13    permissions {name}
14  }
15}

Language: graphqlschema

Name: Create a ROLE_MANAGER Role with some Permissions (assumes that the Permissions already exist) - Example Request This assumes that the Permissions already exists in the platform

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "createRole": {
4      "id": "1000030",
5      "name": "ROLE_MANAGER",
6      "permissions": [
7        {
8          "name": "ROLE_VIEW"
9        },
10        {
11          "name": "PERMISSION_VIEW"
12        },
13        {
14          "name": "ROLE_CREATE"
15        },
16        {
17          "name": "ROLEPERMISSION_UPDATE"
18        },
19        {
20          "name": "PERMISSIONROLE_REMOVE"
21        }
22      ]
23    }
24  }
25}

Language: graphqlschema

Name: Create a ROLE_MANAGER Role with some Permissions (assumes that the Permissions already exist) - Example Response
 This assumes that the Permissions already exists in the platform

Description:

[Warning: empty required content area]
1mutation {
2  updateRole(input: {name: "ROLE_MANAGER", permissions: {name: "ROLE_UPDATE"}}) {
3    name
4    permissions {
5      name
6    }
7  }
8}

Language: graphqlschema

Name: Update the ROLE_MANAGER Role to have ROLE_UPDATE Permission - Example Request This assumes that the ROLE_UPDATE Permission already exists in the platform

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "updateRole": {
4      "name": "ROLE_MANAGER",
5      "permissions": [
6        {
7          "name": "ROLE_VIEW"
8        },
9        {
10          "name": "PERMISSION_VIEW"
11        },
12        {
13          "name": "ROLE_CREATE"
14        },
15        {
16          "name": "ROLE_UPDATE"
17        },
18        {
19          "name": "ROLEPERMISSION_UPDATE"
20        },
21        {
22          "name": "PERMISSIONROLE_REMOVE"
23        }
24      ]
25    }
26  }
27}

Language: graphqlschema

Name: Update the ROLE_MANAGER Role to have ROLE_UPDATE Permission - Example Response This assumes that the ROLE_UPDATE Permission already exists in the platform

Description:

[Warning: empty required content area]
1mutation {
2  removePermissionsFromRole(input: {role: {name: "ROLE_MANAGER"}, permissions: {name: "ROLE_UPDATE"}}) {
3    status
4  }
5}
6
7
8
9// Query to check the role now
10query {
11  role (name: "ROLE_MANAGER") {
12    name
13    permissions {
14      name
15    }
16  }
17}

Language: graphqlschema

Name: Remove ROLE_UPDATE permission from the ROLE_MANAGER role - Example Request

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "removePermissionsFromRole": {
4      "status": "SUCCESS"
5    }
6  }
7}
8
9
10{
11  "data": {
12    "role": {
13      "name": "ROLE_MANAGER",
14      "permissions": [
15        {
16          "name": "ROLE_VIEW"
17        },
18        {
19          "name": "PERMISSION_VIEW"
20        },
21        {
22          "name": "ROLE_CREATE"
23        },
24        {
25          "name": "ROLEPERMISSION_UPDATE"
26        },
27        {
28          "name": "PERMISSIONROLE_REMOVE"
29        }
30      ]
31    }
32  }
33}

Language: graphqlschema

Name: Remove ROLE_UPDATE permission from the ROLE_MANAGER role - Example Response

Description:

[Warning: empty required content area]


Custom Queries

Custom queries are special queries available through the Fluent GraphQL API. With custom queries, the server processes the input, and applies some logic to it, before returning the output. These can be queries or mutations.

At Fluent, we do not wish to add complex logic to our GraphQL server, that’s Orchestration’s job. However, there are times when to improve performance and reduce overall complexity, custom queries can be added.

Currently, the Fluent GraphQL API only has one custom query (SearchVirtualInventory).

Example

This query returns up to 10 of the nearest locations that can entirely fulfil a set of items based on available-to-sell stock in a given Virtual Catalog. Targeted use-cases include fulfilling an order with no splits (as locations that require a split will not be returned), or showing a list of stocked pickup options to a customer in a product page or checkout scenario.

1query {
2    searchVirtualInventory(
3        virtualCatalogue: { ref: "VCREF" }, 
4        productQuantities: [{ productRef: "myProductRef" quantity: 0 }]
5    ) {
6        edges {
7            node {
8                virtualPositions {
9                    id
10                    ref
11                    productRef
12                    quantity
13                    createdOn
14                }
15                location {
16                    ref
17                    name
18                    type
19                    id
20                    defaultCarrier
21                }
22            }
23        }
24    }
25}

Language: graphqlschema

Name: SearchVirtualInventory - Example Request

Description:

[Warning: empty required content area]
1{
2  "data": {
3    "searchVirtualInventory": {
4      "edges": [
5        {
6          "node": {
7            "virtualPositions": [
8              {
9                "id": "efe808e3-5eb5-45ab-b495-9f8a27ddd10a",
10                "ref": "VPREF",
11                "productRef": "myProductRef",
12                "quantity": 40,
13                "createdOn": "2019-10-04T03:28:18.380Z"
14              }
15            ],
16            "location": {
17              "ref": "DEMO_LOC",
18              "name": "fooName",
19              "type": "STORE",
20              "id": "13",
21              "defaultCarrier": "SHIPPIT"
22            }
23          }
24        }
25      ]
26    }
27  }
28}

Language: graphqlschema

Name: SearchVirtualInventory - Example Response

Description:

[Warning: empty required content area]


Fluent Commerce

Fluent Commerce

Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Fluent Logo