Stock Segmentation - Data Model and API Overview

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Essential knowledge

Intended Audience:

Technical User

Author:

Kirill Gaiduk

Changed on:

27 Mar 2026

Overview

Stock Segmentation extends Fluent’s Inventory and Virtual Catalog data models to represent multiple logical segments for the same product and location using explicit, queryable factors.Stock Segmentation supports scenarios such as channel-specific reservations, manufacturing batch traceability, compliance restrictions (for example by country of origin), and supplier-level inventory management while preserving a single physical inventory model per product and location.This document explains the data model and GraphQL API capabilities introduced for Stock Segmentation.

Key points

Physical stock in the Inventory Catalog is represented through Inventory Quantities that can be segmented using dedicated fields such as `condition`, `expiresOn`, `countryOfOrigin`, `channel`, `manufacturer`, `manufacturerBatchNumber`, `supplier`, and `segment1/2/3`
Inventory Quantities support parent-child hierarchies, allowing multi-level segmentation trees to be modeled explicitly via the parent relationship
Inventory Quantities can be linked to operational entities using `associationType` and `associationRef`, particularly for reservation linkage and traceability
Virtual availability can expose a single customer-facing segment using Virtual Segments
Segmentation fields are exact-match searchable to ensure predictable query behavior (partial matching is not supported)

Data Model

The following mind map shows where the Stock Segmentation solution sits in the Fluent platform. No alt provided

Physical inventory is segmented by Country of Origin into Inventory Quantity hierarchies (Country A and Country B)
- Retail orders are eligible to source only from Country A inventory
- Web orders may source from both Country A and Country B inventory
Allocation follows a first-expiry-first-out (FEFO) principle within the eligible segmentation scope
- Reservations are created directly against the earliest-expiring eligible `LAST_ON_HAND` Inventory Quantity
- Grey Virtual Segments indicate that no inventory is Available-to-Promise for that channel at the specified date, based on eligibility and expiry constraints

This demonstrates how a single physical stock can be logically segmented while enforcing channel-specific sourcing and regulatory constraints.

Note

Use this mind map as a navigation aid:

Stock Segmentation builds on the existing physical inventory model, but extends Inventory Quantities with dedicated factors and hierarchical relationships
Physical segmentation (for example by supplier, country of origin, or manufacturing batch number) is modeled through parent-child Inventory Quantity hierarchies
Channel differentiation is expressed at the reservation level and through Virtual Segments in the Virtual Catalog
Virtual Segments expose customer-facing availability projections derived from the underlying segmented physical inventory

The following data model outlines the entities available to manage Stock Segmentation. No alt provided

Recommended practice

For the up-to-date data model we recommend to always refer back to the GraphQL Explorer.

Entities

These are the core entities involved in Stock Segmentation.

Entity	Description
`InventoryPosition`¹	Inventory Position is the core aggregate entity representing the complete inventory state for a specific product (SKU) at a specific inventory node: a warehouse, store, fulfillment centre, or drop-ship supplier. It is the primary unit of inventory tracking in the platform. A single Inventory Position consolidates all the granular stock information for that product-location combination into one addressable record.
`InventoryQuantity`²	Represents a portion of physical inventory within an Inventory Position. In Stock Segmentation, Inventory Quantities may include segmentation attributes (for example `condition`, `supplier`, `countryOfOrigin`, `manufacturer`, `manufacturerBatchNumber`, `expiresOn`, `segment1/2/3`) that logically partition stock without creating multiple physical positions.
`VirtualPosition`³	Represents baseline Available-to-Sell inventory for a product at a location. Availability is derived from the underlying segmented Inventory Quantities and reflects the aggregation logic applied across those quantities.
`VirtualSegment`⁴	Represents customer-facing availability scoped to a single segmentation dimension (`type` and `value`). Virtual Segments allow segmented availability to be exposed without duplicating the physical inventory model.

Note

The superscript number for each Entity, references the entities in the data model above.

Relationship Details

The following relationship patterns are foundational in the Stock Segmentation model.

Relationship	Type	Description
Position to Quantities	One `InventoryPosition` to many `InventoryQuantity`	A single Inventory Position holds all Inventory Quantities for a product at a location, including segmented quantities. This preserves a single physical anchor while allowing multiple logical partitions of the same stock to coexist and be aggregated consistently.
Quantity to Quantities	One `InventoryQuantity` to many `InventoryQuantity`	Inventory Quantities support explicit parent–child relationships via the `parent` reference. This allows derived lifecycle states (such as reservations or other operational states) to be anchored to a specific segmented quantity, ensuring availability is reduced at the correct segmentation scope.
Quantities to Associated Entity	Many `InventoryQuantity` to one associated entity	Inventory Quantities can be linked to operational records using `associationType` and `associationRef`. In Stock Segmentation, this is primarily used to tie reservations or other lifecycle records to a specific segmented quantity for traceability and accurate availability calculations.
Virtual Position to Segments	One `VirtualPosition` to many `VirtualSegment`	A single Virtual Position represents baseline availability. Virtual Segments expose availability scoped to a single segmentation dimension (`type` and `value`), enabling channel, market, or customer-facing views without altering the physical inventory structure.

GraphQL Operations

This section summarizes the GraphQL queries and mutations commonly used to work with Stock Segmentation.

Mutations

Operation	Description	Common Stock Segmentation Inputs	Returns	Comment
`createInventoryQuantity`	Creates an Inventory Quantity record representing a segmented portion of physical inventory or a derived lifecycle record	Segmentation attributes: `condition` `supplier` `countryOfOrigin` `manufacturer` `manufacturerBatchNumber` `segment1/2/3` Lifecycle constraints: `expiresOn` Derived quantities: `parent` Reservations / commitments: `channel` `associationType` `associationRef`	`InventoryQuantity`	Use to create segmented quantities and derived quantities anchored to a specific segment
`updateInventoryQuantity`	Updates an existing Inventory Quantity as inventory progresses through its lifecycle	State transitions: `status`	`InventoryQuantity`	Use to maintain segmentation data and derived records over time
`updateInventoryQuantityChildren`	Bulk updates direct child Inventory Quantities under a specified parent Supports filtering by segmentation attributes and updating status or parent relationships	Filter criteria - `UpdateInventoryQuantityChildrenFilterInput`: `parent` identifies the parent Inventory Quantity that scopes the operation Child quantities to update selection filters: `type` `status` `expectedOn` `expiresOn` `associationType` `associationRef` Segmentation filters: `countryOfOrigin` `channel` `manufacturer` `manufacturerBatchNumber` `supplier` `segment1` `segment2` `segment3` Updates to apply definition - `UpdateInventoryQuantityChildrenPatchInput`: `status` `parent`	List of updated `InventoryQuantity`	Recommended for bulk operations on segmented inventory, such as updating or reassigning a specific subset of quantities based on segmentation attributes Supersedes `updateInventoryQuantitiesStatus` for new implementations
`createVirtualPosition`	Creates a Virtual Position and its Virtual Segments used for customer-facing segmented availability	Segmented availability: `segments: [UpsertVirtualSegmentInput]` Each segment typically includes: `segment: SegmentInput` `type` `value` `quantity` optional `availableOn`	`VirtualPosition` (with segments)	Preferred way to create segmented availability projections
`updateVirtualPosition`	Updates a Virtual Position and its availability segments	Segment updates: `segments` with revised values: `segment` `type` `value` `quantity`	`VirtualPosition` (updated segments)	Use to maintain segmented availability projections as they change

Queries

Operation	Description	Common Stock Segmentation Filters	Returns	Comment
`inventoryPosition.quantitiesAggregate`	Aggregates Inventory Quantities under a specific Inventory Position based on lifecycle and segmentation filters	Lifecycle state: `type` `status` Segmentation attributes: `condition` `supplier` `countryOfOrigin` `manufacturer` `manufacturerBatchNumber` `segment1/2/3` Time window: `expectedOn` `expiresOn` Reservation context: `channel` `associationType` `associationRef`	Aggregate totals (quantity summary)	Primary pattern for position-scoped segment totals
`inventoryQuantity.quantities`	Retrieves the direct child quantities for a given parent Inventory Quantity	Hierarchy anchor: Parent `InventoryQuantity` reference	List of child `InventoryQuantity`	Returns one hierarchy level (direct children only). Useful for tracing derived states
`inventoryQuantity.quantitiesAggregate`	Aggregates the direct child quantities for a given parent Inventory Quantity	Hierarchy anchor: Parent `InventoryQuantity` reference Lifecycle state: `type` `status` Segmentation attributes: `condition` `supplier` `countryOfOrigin` `manufacturer` `manufacturerBatchNumber` `segment1/2/3` Time window: `expectedOn` `expiresOn` Reservation context: `channel` `associationType` `associationRef`	Aggregate totals (child summary)	Use to summarize derived quantities anchored under a specific segmented quantity (for example reservations)
`inventoryQuantities`	Searches inventory quantities at a catalog level using filter criteria	Lifecycle state: `type` `status` Segmentation attributes: `condition` `supplier` `countryOfOrigin` `manufacturer` `manufacturerBatchNumber` `segment1/2/3` Time window: `expectedOn` `expiresOn` Reservation context: `channel` `associationType` `associationRef`	List of `InventoryQuantity`	Useful for reporting or reconciliation patterns not constrained to a single position
`inventoryQuantityAggregate`	Aggregates inventory quantities at a position level	Hierarchy anchor: `position` Lifecycle state: `type` `status` Segmentation attributes: `condition` `supplier` `countryOfOrigin` `manufacturer` `manufacturerBatchNumber` `segment1/2/3` Time window: `expectedOn` `expiresOn` Reservation context: `channel` `associationType` `associationRef`	Aggregate totals	Use when totals are needed without retrieving records
`virtualPosition`	Retrieves virtual availability, including segmented availability evaluation	Segmentation: `segment` `type` `value` Optional time evaluation: `availableOn`	`VirtualPosition` (+ selected segment availability)	Returns either baseline Virtual Position quantity or a matching Virtual Segment quantity depending on inputs
`virtualPositions`	Retrieves virtual availability across multiple positions	Segmentation: `segment` `type` `value` Optional time evaluation: `availableOn`	List of `VirtualPosition`	Use in sourcing and promising flows requiring multi-position evaluation
`virtualPosition.segments`	Retrieves the Virtual Segment records attached to a specific Virtual Position	Segmented availability: `segment` `type` `value` `quantity` `createdOn` `updatedOn` optional `availableOn`	`VirtualSegmentConnection`	Use when underlying segment records are needed instead of only the resolved quantity returned by `virtualPosition`

virtualPosition(s) Quantity Resolution Logic

These queries accept two optional inputs:

`segment: VirtualSegmentKey`
`availableOn: DateTime`

When one or both inputs are provided, the platform may return a quantity from a matching Virtual Segment (VS) instead of the base Virtual Position (VP) quantity. 1) No `segment` and no `availableOn`Return base VP quantity (“now”). 2) Only `segment` is providedConsider only VS records (with `null` availableOn) matching the same segment:

If a matching VS exists → return that VS quantity
If no matching VS exists → return 0

3) Only `availableOn` is providedConsider only VS records (with `null` segment) with availableOn in the range [now … availableOn] and select the one with the maximum availableOn within that range:

If such a VS exists → return that VS quantity
If none exist in the range → return parent VP quantity

4) Both `segment` and `availableOn` are providedConsider only VS records matching the same segment and with availableOn in the range [now … availableOn]. Select the one with the maximum availableOn within that range:

If such a VS exists → return that VS quantity
If none exist in the range → try to return the VS with the same segment and availableOn = null:
- If that “segment baseline” VS exists → return its quantity
- Otherwise → return 0

Important Usage Considerations

When queries include `availableOn` or `segment` filters, the platform resolves quantity from Virtual Segments associated with the Virtual Position
Query performance depends on the number of Virtual Segments that match the request window
For best performance, design Virtual Segments so that only a limited number of segments (around 10 - 20) match a typical operational time window (for example, a few weeks)
Avoid modeling time with very high-frequency segments across long horizons (for example daily segments across multiple years)

Recommended practice

Inventory queries in the Inventory Reference Module are primarily optimized for position-scoped access patterns, where Inventory Quantities are retrieved and aggregated through an Inventory Position. This approach allows the platform to efficiently leverage existing indexes and provide predictable performance for common inventory and future availability scenarios.

Queries that operate across multiple positions or segments (for example, inventory searches not constrained by an Inventory Position) follow different access patterns and may have varying performance characteristics depending on data volume and query structure.

When implementing inventory logic that relies on such cross-position or cross-segment queries, it is recommended to validate performance through testing in realistic data scenarios before using these queries in production.

Explanation Through An Example

This example serves as a practical walkthrough of how segmented physical inventory quantities and channel-scoped availability are intended to be represented for a single product and location.

High-Level Example

Product PainRelief-500mg is managed at location WH_EU
Physical stock is segmented by country of origin and expiry date
Retail and Web channels have different sourcing eligibility rules

Narrative Overview

A single Inventory Position anchors all stock for PainRelief-500mg @ WH_EU.
The physical model contains three sibling Inventory Quantities:
- EU stock: 100 units, expires 2026-02-01
- US stock: 20 units, expires 2026-01-01
- US stock: 20 units, expires 2026-03-01
Reservations are anchored directly to specific segmented quantities with two important behaviors illustrated:
- Channel-scoped eligibility
  - Retail reservations can only be created against EU stock
  - Web reservations can be created against EU or US stock
- Expiry-driven allocation (FEFO)
  - Inventory is consumed from the earliest eligible expiry first
  - However, expiry eligibility is evaluated relative to the order’s delivery window. For example, fulfillment FF003 (deliver after 2026-01-01) cannot reserve against the US batch expiring on 2026-01-01, so it reserves against EU stock instead
Virtual Segments then expose this segmented physical model as channel-specific availability projections without duplicating the physical inventory.

Calculation Walkthrough

Available now (VP001)
`LAST_ON_HAND` Inventory Quantities are reduced by reservations already committed against them: VP001 = (100 - 3 - 5) + (20 - 5) + 20 = 127
Baseline Retail Availability (VSR1)
Retail can source EU only: VSR1 = 100 (EU stock) − 3 (Retail reservation) − 5 (Web reservation) = 92
Retail available as of 2026-02-01 (VSR2)
Retail future segment returns 0 because no additional EU inventory becomes eligible: VSR2 = 0
Baseline Web Availability (VSW1)
Web can source EU + US: VSW1 = (100 - 3 - 5) + (20 - 5) + 20 = 127
Web available as of:
- 2026-01-01 (VSW2)
  The US batch expiring on that date is no longer eligible (it is also assumed that the order for which the reservation was made has been fulfilled) --> availability decreases accordingly: VSW2 = (100 - 3 - 5) + 20 = 112
- 2026-02-01 (VSW3)
  EU batch expires (the orders have been fulfilled) --> only remaining eligible stock is reflected: VSW3 = 20
- 2026-03-01 (VSW4)
  All batches expired: VSW4 = 0

API Usage

The inventory quantities and availability shown in this example are created and retrieved using the GraphQL mutations and queries described in the GraphQL Operations section. In particular:

Segmented physical quantities and reservations are created via `createInventoryQuantity` mutation. Reservations are anchored using:
- `parent`
- `associationType`
- `associationRef`
- `channel`
Channel-scoped availability is retrieved via `virtualPosition` / `virtualPositions` queries. Segmented date-based availability is retrieved using the following parameters:
- `segment`
  - `type`
  - `value`
- `availableOn`

Reminder

When a `virtualPosition` / `virtualPositions` query is made with a `segment` filter, the `SegmentInput` requires both `type` and `value`
Use `updateInventoryQuantityChildren` to manage segmented inventory at scale within a hierarchy. Instead of updating quantities one by one, you can update or reassign a targeted subset of child quantities in a single request using segmentation attributes for filtering.
- This is especially useful when:
  - updating quantities from a specific supplier, manufacturer, or manufacturing batch
  - isolating and updating affected inventory (for example, quality issues or recalls)
  - applying changes to a filtered subset of segmented quantities
- This approach reduces operational complexity and ensures consistency across segmented inventory

Key Insights

Reservations are anchored to a specific segmented Inventory Quantity
This ensures that availability is reduced only within the eligible segment, preserving deterministic channel-specific availability and expiry-based allocation

Note

The given example is just one of the use cases. Stock Segmentation is intentionally flexible and supports broader inventory partitioning strategies across physical and commercial dimensions, including:

Market-Specific Inventory Partitioning
Separate inventory pools based on regulatory or geographic eligibility (for example by regulatory approval or compliance flags) ensuring that only qualified stock can be exposed to specific markets or sales channels
Supplier and Batch-Level Traceability
Model parallel Inventory Quantities for the same product and location using attributes such as `supplier`, `manufacturer`, or `manufacturerBatchNumber`. This supports traceability requirements, quality isolation scenarios, and supplier-specific allocation strategies - while preserving aggregation at the Inventory Position level
Contractual or Customer-Dedicated Stock Buckets
Represent logically isolated inventory buckets for wholesale customers, marketplaces, or strategic partners using segmentation attributes and reservation anchoring. This allows committed quantities to be scoped precisely without impacting unrelated commercial flows
Controlled Release and Availability Policies
Expose selected segments to specific channels through Virtual Segments, enabling phased product launches, channel-exclusive assortments, or staged commercial rollouts. Segmentation defines which inventory is visible to whom - without altering the underlying physical stock
Hybrid Physical-Virtual Segmentation Models
Use physical segmentation where required (for example regulatory or traceability constraints), while exposing additional commercial dimensions only in the Virtual Catalog layer. This supports scalable commercial modeling without over-fragmenting physical inventory

High-level Inventory Concepts

Stock Segmentation defines how inventory is partitioned and logically isolated
Future Inventory defines when inventory becomes available over time
Responsive Sourcing defines how eligible inventory is selected during order fulfillment

Together, these capabilities provide a flexible framework for modeling complex inventory governance, compliance, and commercial allocation strategies.

Stock Segmentation - Data Model and API Overview

Overview

Key points

Data Model

Entities

Relationship Details

GraphQL Operations

Mutations

Queries

Explanation Through An Example

High-Level Example

Narrative Overview

Calculation Walkthrough

API Usage

Key Insights

Related content

Inventory Modeling Guide

Future Inventory - Data Model and API Overview

Kirill Gaiduk

Knowledge Tracks Related To This Topic

Building Blocks

Browse By Type

Helpful Resources

Quick Links