Product GraphQL API Overview

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Kirill Gaiduk

Changed on:

12 June 2025

Overview

This article is intended to provide technical users with information about the Product GraphQL API, describing its functionalities within the Fluent Platform.

Prerequisites

You should have knowledge of:

Products, Product Catalogs, and Product Management
Inventory Reference Module, including the Product Catalog Workflow Interface Contracts
GraphQL API

Key points

GraphQL API for Product Management:
- Supersedes REST
- Supports creating, updating, and querying Products
Permission-Driven Access: Type- and Retailer-specific
```
`CREATE`
```
,
```
`UPDATE`
```
, and
```
`VIEW`
```
Permissions are strictly enforced for all operations
Type-Agnostic Updates:
```
`updateProduct`
```
simplifies updates without needing Product Type, but correct Permissions and unique
```
`ref`
```
+
```
`catalogue`
```
are required.

Reminder

The recommended methods for user interaction with Products in the Fluent Platform are described in the Product Management article.
For technical details, see the Product Catalog Workflow Interface Contracts.
The Product REST API has been superseded by the GraphQL API.

What is the Product GraphQL API for?

The Product GraphQL API allows technical users to manage Products within the Fluent Platform:

Create
Update
Get
Search

Permissions

The following Permissions are required for different operations on Products:

Permission Group

Create

Update

View

Type-specific:

Standard
Variant
Group

```
`STANDARDPRODUCT_CREATE`
```
```
`VARIANTPRODUCT_CREATE`
```
```
`GROUPPRODUCT_CREATE`
```

```
`STANDARDPRODUCT_UPDATE`
```
```
`VARIANTPRODUCT_UPDATE`
```
```
`GROUPPRODUCT_UPDATE`
```

```
`STANDARDPRODUCT_VIEW`
```
```
`VARIANTPRODUCT_VIEW`
```
```
`GROUPPRODUCT_VIEW`
```

Type-agnostic

`PRODUCT_VIEW`

(used for accessing

`inventoryPosition.product`

and

`virtualPosition.product`

sub-queries)

Product Update Permission Handling

Type-specific
```
`UPDATE`
```
Permissions are required for the Product update operation.
Type-specific
```
`VIEW`
```
Permissions are required to return the updated Product entity as part of the update operation response.

Note

The Product update will still be executed, but an “insufficient permissions” error will appear if:

The user has the appropriate
```
`UPDATE`
```
Permission
But lacks the corresponding
```
`VIEW`
```
Permission

Retailer-specific Permission Handling

To ensure your User has the correct rights for a particular Product-related operation, a Retailer-specific Product Permission Check is performed:

Determine required Permissions for the target Product(s):
- Extract Retailers from the
```
`retailerRefs`
```
  field of the Product Catalog
- (Optional) Identify the Product Type
Determine the querying User’s access rights:
- Check the Retailer - Product Type combinations from the User’s Roles (within the relevant Contexts) that contain Product-related Permissions
The permission check is successful when the User’s access rights match the required values.

Explanation through an example

The following Product Catalogs are created:
- ProductCatalogue1 with
```
`retailerRefs`
```
  field containing the RetailerRef1
- ProductCatalogue2 with
```
`retailerRefs`
```
  field containing the RetailerRef2
User1 has been assigned the following User Roles:
- Standard Product Manager Role in the RetailerRef1 Context, with Permissions:
  - ```
  `STANDARDPRODUCT_UPDATE`
```
- ```
`STANDARDPRODUCT_VIEW`
```
- Variant Product Manager Role in the RetailerRef2 Context, with Permissions:
  - ```
  `VARIANTPRODUCT_UPDATE`
```
- ```
`VARIANTPRODUCT_VIEW`
```
As a result, User1:
- can update and query:
  - Standard Products from the ProductCatalogue1
  - Variant Products from the ProductCatalogue2
- and does not have access to:
  - Variant Products from the ProductCatalogue1
  - Standard Products from the ProductCatalogue2

Reminder

A User Role in the
```
`ACCOUNT`
```
Context (containing Product-related Permissions) grants access to Product operations across all Retailer Product Catalogs.
Retailer(s) should be listed in the
```
`retailerRefs`
```
field of the Product Catalog.

Features

The Product GraphQL API provides the following functionalities:

Mutations

Create Product

Update Product

```
`updateStandardProduct`
```
```
`updateVariantProduct`
```
```
`updateGroupProduct`
```
```
`updateProduct
`
```
Enables updates without being limited to a reference Product Type (
```
`STANDARD`
```
,
```
`VARIANT`
```
, or
```
`GROUP`
```
).

Note

The optional
```
`productType`
```
input field is used to identify the target Product (to be updated) as part of the composite key:
```
`ref!`
```
+
```
`catalogue!`
```
+
```
`productType`
```
. It:
- is not mapped to the
```
`type`
```
  field
- accepts reference Product Types only:
```
`STANDARD`
```
  ,
```
`VARIANT`
```
  , and
```
`GROUP`
```
- is relevant only in edge cases where the Product Reference is not unique within a Catalog
The optional
```
`type`
```
input field is used to update the Product Type value.

Recommended Practice

Ensure Product Reference uniqueness within a Product Catalog. Avoid using the same

`ref!`

`catalogue!`

combination for different Product Types (e.g.,

`STANDARD`

and

`VARIANT`

Otherwise, the

`updateProduct`

mutation will fail with the Error Code: C0128E.

Queries

Get Product

```
`product`
```

Search Product(s)

```
`products`
```

Note

Find more details in the GraphQL Product Queries.

Product GraphQL API Overview

Overview

Key points

What is the Product GraphQL API for?

Permissions

Product Update Permission Handling

Retailer-specific Permission Handling

Explanation through an example

Features

Mutations

Create Product

Update Product

Queries

Get Product

Search Product(s)

Related content

Products Overview

GraphQL API

GraphQL Product Queries

Kirill Gaiduk

Building Blocks

By Type

Helpful Resources

Quick Links