Fluent Commerce Logo
Docs
Sign In

Product GraphQL API Overview

Essential knowledge

Author:

Kirill Gaiduk

Changed on:

12 June 2025

Overview

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


Prerequisites

You should have knowledge of:

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.

What is the Product GraphQL API for?

The Product 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.

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

Features

The Product API provides the following functionalities:

Mutations

Create Product
Update Product

Queries

Get Product
Search Product(s)