Fluent Commerce Logo
Docs
Sign In

Understanding IDs and Refs in GraphQL Entities

Essential knowledge

Authors:

Ben Harrison, Mubarra Khan

Changed on:

15 July 2024

Overview

The Fluent platform generates unique IDs internally, which serve as the primary key for each new record. They are unique and enforced to avoid ambiguity. Users cannot set these via API. Whereas refs are typically from third-party integrations, they represent external system IDs and occasionally are generated internally with guaranteed uniqueness. It is the integrator's responsibility to ensure refs are unique in Fluent Commerce.

Key points

  • IDs are generated by the Fluent platform and are guaranteed to be unique at the time of creation. 
  • Refs are typically values passed in via third-party integrations and should represent the IDs from external systems.
  • Despite the system not enforcing the uniqueness of refs, it is highly recommended to have unique refs for all entities. Every ref should be unique within it's nearest container, for example Retailer refs need to be unique across all . Catalogue or Account.
  • If your refs are not unique then there are API's that will not work as expected. This means that our reference modules may not work as expected if you set ref's as non-unique values.
IDs

IDs are generated by the Fluent platform and are guaranteed to be unique at the time of creation. The system enforces this uniqueness to ensure that each entity can be distinctly identified without any ambiguity. Users can not set this value via API. 

Refs 

Typically refs are values passed in via third-party integrations and should represent the IDs from external systems. On occasion when internal rules and workflows generate refs they are guaranteed to be unique e.g. Fulfilments.

  • Order/fulfilment/article (Refs): The system does not enforce the uniqueness of refs across retailers for these entities at the time of creation and only enforces uniqueness at the retailer level. However, queries such as getOrderByRef will fail if they are not unique across retailers. 
  • Product/Inventory/Virtual Catalogues (Refs): Within the context of product, inventory, or virtual catalogues, refs are unique only within the specific catalogue. This means that the same ref can exist in multiple catalogues, allowing the same position to be used in various virtual catalogues, for example.
  • Uniqueness Assumption: Many rules and workflows within the system assume that refs are unique. Maintaining this uniqueness is important to ensure the proper functioning of these rules and workflows.
Why Refs?

Fluent is typically integrated with many other services, so orders will come from one service, products from another, and inventory from a third.

While Fluent generates unique identifiers for each of these, tracking those across many services would mean updating each one (e.g., adding a table column to store the Fluent ID, updating the REST endpoint to return it, etc.).

However, those services will usually already have a unique identifier for the order/product/inventory position. To simplify things, Fluent provides a second unique identifier for each entity in the ref field.

Rather than being auto-generated, the ref can be set by the service or connector creating the entity. This means that integrations can use the existing ID from the external service to retrieve and update the entity without making changes on the other end.

Recommended Practices
  • Unique Refs: Despite the system not enforcing the uniqueness of refs, it is highly recommended to have unique refs for all entities. Changing the data model structure to fetch refs specific to a retailer is not an option. 
  • Unique Refs in Catalogues: While refs can be duplicated across different catalogues, strive to maintain their uniqueness within each specific catalogue to facilitate easier tracking and management.
  • Child Entities: Use the unique identifier of the parent entity when creating refs for child entities. This can be done by incorporating the parent entity's ID into the ref, such as using "<order_id>-some-ref-value" for fulfillments created from an order. 
  • Fields: The username field for user and customer entities should follow the same practices of being unique to the nearest container.
  • Consistency: Adopting a consistent approach to handling refs and IDs can greatly simplify entity management and reduce the risk of errors.
Ben Harrison

Ben Harrison

Contributors:
Mubarra Khan

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