Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

Fluent Big Inventory - Features Overview

Getting Started with Fluent Big Inventory

How to Submit Inventory Batches

Future Inventory - Data Model and API Overview

Stock Segmentation - Data Model and API Overview

Metrics usage for Platform Observability

End Of Track

Content in this track: Future Inventory - Data Model and API Overview

Essential knowledge

Author:

Kirill Gaiduk

Changed on:

27 Mar 2026

Overview

Future Inventory extends the Inventory and Virtual Catalog data models to represent inventory that is not yet physically available but is expected to arrive at a known point in time. It enables availability and reservation decisions against future stock using explicit dates and quantities.Future Inventory supports scenarios such as pre-orders and wholesale commitments, where inventory must be promised before receipt, while preserving a single physical inventory model per product and location.This document explains the data model and GraphQL API capabilities introduced for Future Inventory.

Key points

Prerequisites: You should have knowledge of Inventory Module, GraphQL API (Fluent Platform Integrations), and Workflow Framework
Future Inventory represents expected stock with defined arrival dates, not forecasts
Future Inventory can be reserved and committed prior to physical receipt
Available-to-Promise (ATP) quantities can be queried as of a future date, accounting for on-hand, expected, and already-reserved inventory
Inventory lifecycle states (for example: on order → in transit → received) are represented explicitly within the data model

Data Model

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

Note

Use this mind map as a navigation aid:

Future Inventory builds on the existing physical inventory model, but extends Inventory Quantities with new relationship and traceability capabilities. Inventory Quantities can now:
- form explicit hierarchies through the `parent` field
- be linked to upstream and downstream operational records through `associationType` and `associationRef` (for example purchase orders, in-transit shipments, or fulfillment reservations)
Virtual Catalog extension: Virtual Positions can expose time-series Available-to-Promise through the new Virtual Segment child entity, enabling date-based availability retrieval via `availableOn` (optionally combined with `segment`)

The following data model outlines the entities available to manage Future Inventory. 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 Future Inventory.

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`²	A single inventory state record within a position, representing a lifecycle state such as on-hand, on-order, in-transit, or reserved. Quantities can nest under a parent quantity to model derived states, for example a reservation against an on-hand or on-order quantity.
`VirtualPosition`³	Virtual availability record for a product at a location. Represents the current Available-to-Sell quantity after reservations and buffers, and serves as the point from which future availability segments project forward.
`VirtualSegment`⁴	Time-based availability projection for a virtual position. It creates a logical subdivision within a virtual position, enabling multiple distinct availability records to exist for the same product-location combination

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 Future Inventory model.

Relationship	Type	Description
Position to Quantities	One `InventoryPosition` to many `InventoryQuantity`	A single position holds all inventory quantities for a product at a location across the full lifecycle, including on-hand, on-order, in-transit, and reserved. This is the foundation for cross-state aggregation at a product-location level.
Quantity to Quantities	One `InventoryQuantity` to many `InventoryQuantity`	A parent quantity can hold child quantities representing derived states. For example, a `RESERVED` quantity sits under an `ON_HAND` or `ON_ORDER` parent to track a commitment against that specific stock. The link is maintained via `InventoryQuantity.parent`.
Quantities to Associated Entity	Many `InventoryQuantity` to one associated entity	Links a quantity to an external entity via two fields that work as a pair: `associationType` identifies the kind of entity (for example `PURCHASE_ORDER` or `FULFILMENT`) `associationRef` identifies which specific one
Virtual Position to Segments	One `VirtualPosition` to many `VirtualSegment`	Each segment is anchored to a specific date via `availableOn` and represents the total available-to-promise quantity at that point in time. Together they project availability forward from the position's current available-to-sell quantity.

GraphQL Operations

This section summarizes the GraphQL queries and mutations commonly used to work with Future Inventory.

Mutations

Operation	Description	Common Future Inventory Inputs	Returns	Comment
`createInventoryQuantity`	Creates an Inventory Quantity record, including future-dated and association-linked quantities	Future arrivals: `expectedOn` `quantity` Derived quantities: `parent` Reservations / commitments: `associationType` `associationRef` Lifecycle constraints: `expiresOn`	`InventoryQuantity`	Use to represent planned arrivals, reservations, and other lifecycle events
`updateInventoryQuantity`	Updates an existing Inventory Quantity as inventory progresses through its lifecycle	State transitions: `status`	`InventoryQuantity`	Use when arrival dates shift, quantities change, or reservations are created/released
`updateInventoryQuantityChildren`	Bulk updates direct child Inventory Quantities under a specified parent Supports updating status and reassigning children to a different parent using filter criteria	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` Updates to apply definition - `UpdateInventoryQuantityChildrenPatchInput`: `status` `parent`	List of updated `InventoryQuantity`	Recommended for bulk operations on child quantities in future inventory hierarchies, including: reservation reassignment lifecycle status transitions Supersedes `updateInventoryQuantitiesStatus` for new implementations
`createVirtualPosition`	Creates a Virtual Position and its future availability projections through Virtual Segments	Future projections: `segments: [UpsertVirtualSegmentInput]` Each segment typically includes: `availableOn` `quantity` optional `segment`	`VirtualPosition` (with segments)	Preferred way to create virtual availability together with future segments
`updateVirtualPosition`	Updates a Virtual Position and its future availability segments	Segment updates: `segments` with revised values: `availableOn` `quantity`	`VirtualPosition` (updated segments)	Use to maintain or adjust future availability projections over time

Queries

Reminder

Future availability is exposed through Virtual Segments, while inventory state and lifecycle changes are managed through Inventory Quantities.

Operation	Description	Common Future Inventory Filters	Returns	Comment
`inventoryPosition.quantitiesAggregate`	Aggregates physical inventory quantities for a specific Inventory Position across lifecycle states and time windows	Lifecycle state: `type` `status` Future window: `expectedOn` `expiresOn` Reservation context: `associationType` `associationRef`	Aggregate totals (quantity summary)	Use to calculate on-hand vs future totals at a product-location level
`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` Future window: `expectedOn` `expiresOn` Reservation context: `associationType` `associationRef`	Aggregate totals (child summary)	Summarizes lifecycle-derived layers such as reservations under an arrival quantity
`inventoryQuantities`	Searches inventory quantities at a catalog level using filter criteria	Lifecycle state: `type` `status` Future window: `expectedOn` `expiresOn` Reservation context: `associationType` `associationRef`	List of `InventoryQuantity`	Useful for cross-position reporting and reconciliation scenarios
`inventoryQuantityAggregate`	Aggregates inventory quantities at a position level	Hierarchy anchor: `position` Lifecycle state: `type` `status` Future window: `expectedOn` `expiresOn` Reservation context: `associationType` `associationRef`	Aggregate totals	Use when totals are needed with scoping to a single Inventory Position
`virtualPosition`	Retrieves virtual availability, including future availability evaluation	Time evaluation: `availableOn` Optional segmentation: `segment`	`VirtualPosition` (+ selected segment availability)	Returns availability “as of” a specific date when `availableOn` is provided
`virtualPositions`	Retrieves virtual availability across multiple positions	Time evaluation: `availableOn` Optional segmentation: `segment`	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	Future projections: `availableOn` `quantity` `createdOn` `updatedOn` optional `segment`	`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 physical inventory quantities and future availability are intended to be represented for a single product and location.

High-Level Example

Product GamingChair-Black is managed at location WH_EU.The business has inventory available today, additional inventory expected in the future, and existing reservations already created against upcoming fulfillments. No alt provided

Narrative Overview

Q001 represents 100 units of on-hand inventory.
Two reservations are created under it: R001 for 5 units and R002 for 10 units, both linked to fulfillments.
As a result, Available-to-Sell is reduced from 100 to 85, which is reflected in the base Virtual Position (VP001).
In parallel, two purchase-order-backed inventory quantities represent future supply arriving on different dates.
Reservations can also be created directly against these future quantities, reducing what can be promised once the inventory is received.

Calculation Walkthrough

Available now (VP001)
`LAST_ON_HAND` inventory is reduced by reservations already committed against it: VP001 = 100 − 5 − 10 = 85
Available as of 2026-01-01 (VS001)
Availability builds on the baseline by adding the first purchase order quantity and subtracting reservations linked to that inbound supply: VS001 = 85 + (80 − 10) = 155
Available as of 2026-02-01 (VS002)
Availability further increases once the second purchase order arrives: VS002 = 155 + 200 = 355

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:

future arrivals and reservations via `createInventoryQuantity` mutation
availability “now” and “as of a date” via `virtualPosition` / `virtualPositions` queries

Reminder

When a `virtualPosition` / `virtualPositions` query is made with an `availableOn` date, the platform automatically selects the appropriate `VirtualSegment` and returns the correct future availability for that point.
Use `updateInventoryQuantityChildren` to manage lifecycle transitions at scale within a future inventory hierarchy. Instead of updating quantities one by one, you can update or reassign all relevant child quantities in a single request.
- This is especially useful when:
  - moving reservations from an inbound quantity to a received quantity
  - updating the lifecycle status of multiple future quantities
  - applying changes to a filtered subset of child quantities
- This approach reduces operational complexity and keeps the hierarchy consistent

Key Insights

Future Inventory models future supply using standard Inventory Quantities with dates and hierarchy
Reservations can be created before inventory is received and explicitly linked to a specific inbound quantity, ensuring future promise is reduced correctly
Virtual Segments represent cumulative availability at a point in time, not individual arrivals

Note

The given example is just one of the use cases. Future Inventory is intentionally flexible and supports a wide range of business and operational scenarios where availability must be reasoned about before stock is physically received. For example:

Pre-orders and forward commitments
Promise inventory to customers before it is received, while maintaining accurate delivery expectations based on known arrival dates
Wholesale and B2B scenarios
Allocate future inventory to large or contractual orders ahead of receipt, without blocking unrelated demand
Inventory with planned lifecycle transitions
Represent inventory that will change state over time (for example expiring, being released, or becoming available in phases) using date-based quantities and virtual availability projections
Multi-level inventory quantity hierarchies
Model complex inventory lifecycles using hierarchical Inventory Quantities, such as:
- purchase order → in-transit shipments → received stock
- planned arrivals → partial receipts → reservations and fulfillments
Future Inventory combined with Stock Segmentation
Future Inventory can be used together with Stock Segmentation to represent more granular availability:
- at the Inventory Catalog level, by applying segmentation fields on Inventory Quantities (for example supplier-, manufacturing batch-, or compliance-driven segments)
- at the Virtual Catalog level, by exposing segmented availability through Virtual Segments using the segment input (e.g., sales channel)

Future Inventory focuses on when inventory becomes available and how much can be promised at any point in time.Rules for who can access specific inventory or how inventory is prioritized across channels and markets are addressed through complementary capabilities such as Stock Segmentation and Responsive Sourcing.

Content in this track:

Fluent Big Inventory - Features Overview

Getting Started with Fluent Big Inventory

Inventory Ingestion

Inventory Batch

How to Submit Inventory Batches

Inventory Modeling Guide

Future Inventory - Data Model and API Overview

Stock Segmentation - Data Model and API Overview

Fluent Big Inventory Web App

Metrics Overview

How Metrics works

Metrics usage for Platform Observability

Inventory Feeds

How do Inventory Feeds work

End Of Track

Future Inventory - Data Model and API Overview

Future Inventory - 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

Stock Segmentation - Data Model and API Overview

Kirill Gaiduk

Knowledge Tracks Related To This Topic

Building Blocks

Browse By Type

Helpful Resources

Quick Links