Docs
Author:
Fluent Commerce staff
Changed on:
21 June 2024
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:
Query operations are used for retrieving data. Fluent's GraphQL API has two types of query 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.
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 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.
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]To pass schema complexity validation, all Graphql API operation queries must meet the following standards:
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.
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 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).
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]
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.
