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: Inventory Modeling Guide

Essential knowledge

Author:

Kirill Gaiduk

Changed on:

11 Mar 2026

Overview

This document explains the foundational concepts behind stock segmentation in Fluent Commerce and provides guidance on how to approach segmentation when designing inventory models.Stock segmentation is not a single feature or configuration option. It emerges from how inventory data is modeled and how stock attributes are preserved throughout the data flow from ingestion to availability calculation.The goal is to establish a shared mental model to clarify when different segmentation approaches should be considered, understand their trade-offs, and avoid common anti-patterns.

Key points

Stock segmentation is a modeling decision, not just a configuration shortcut
Effective solutions:
- Place segmentation at the correct level of the model
- Avoid forcing different concerns into the same abstraction
A clear segmentation strategy enables scalable, maintainable inventory and availability solutions as business requirements evolve

What is Stock Segmentation?

Stock segmentation means representing and managing distinct portions of inventory so that availability, allocation, and sourcing decisions can vary based on business rules.Segmentation may be driven by:

Customer-facing product differences, where buyers explicitly choose between variants (for example, size or color)
Business context, such as sales channel or target market, where the same stock must be exposed differently
Future inventory context, where stock is expected to become available at a later point in time and must be tracked separately
Physical characteristics of inventory, such as condition (e.g., perfect / damaged stock), manufacturing batch, or expiry date
Supply chain characteristics, such as supplier or country of origin, which require stock to be managed and allocated differently

Mental Model

Stock segmentation can be achieved at different levels of the data model.

Level	Entities	Segmentation Options
Product	Product Catalog Standard Product Variant Product	Multiple variant products
Inventory	Inventory Catalog Inventory Position Inventory Quantity	Multiple inventory catalogs, inventory positions (via variants), or inventory quantities (and their hierarchies)
Virtual	Virtual Catalog Virtual Position Virtual Segment	Multiple virtual catalogs, virtual positions (via variants), or virtual segments

Choosing the wrong level is the most common cause of over-complex or fragile solutions.

Segmentation Patterns and Recommended Practices

Stock segmentation is commonly implemented using a set of well-understood architectural patterns. Each pattern reflects a deliberate decision about where segmentation lives in the model and how it shapes availability, allocation, and sourcing behavior.The patterns below are not mutually exclusive, but they operate at different levels of the model and address different sets of requirements.

Recommended practice

When selecting an inventory modeling pattern, consider how the chosen approach affects inventory ingestion and availability updates, and how this is reflected in Inventory Position Update (IPU) and Inventory Position Change (IPC) usage.Evaluating these considerations early helps align the inventory model with expected data volumes, update frequency, and operational usage.

Pattern 1: Product Variant Segmentation

Use when

The customer explicitly chooses between alternatives (size, color, configuration)
Inventory must be tracked separately per option (position)
Availability does not depend on business context

Examples

Apparel:
T-shirt in Small / Medium / Large with different inventory per size
Electronics:
Laptop in Silver / Space Gray where customers select color
Furniture:
Sofa in Leather/Fabric where material choice affects availability

What is segmentedProduct identity (`VariantProduct`).How it worksEach variant is modeled as a distinct product. Inventory Positions and Virtual Positions are isolated per variant.Why this works well

Simple and explicit
Fully supported across all workflows
No additional aggregation complexity

Trade-offs

Does not support dynamic or contextual segmentation
Not suitable for regulatory or operational differences

Avoid when

The same SKU must be allocated differently by sales channel or region
Segmentation depends on non-customer-facing attributes

Pattern 2: Inventory Catalog Isolation

Use when

Inventory data comes from fundamentally different sources
Ingestion, ownership, or SLAs differ
Reconciliation between sources is undesirable

Examples

Multi-region retailer:
Separate catalogs for North America vs. EMEA due to different suppliers and fulfillment SLAs
Third-party logistics:
Client's owned inventory vs. 3PL-managed consignment stock with separate ingestion pipelines
Franchise model:
Corporate-owned inventory vs. franchisee-owned inventory with different ownership and reconciliation rules

What is segmentedInventory source and lifecycle (`InventoryPosition`)How it worksSeparate Inventory Catalogs maintain independent Inventory Positions and Inventory Quantities.Why this works well

Strong isolation of data pipelines
Clear operational boundaries

Trade-offs

Increased integration complexity
Limited flexibility once catalogs diverge

Avoid when

Segmentation is purely business-driven
Inventory must be shared across contexts

Pattern 3: Segmented Inventory Quantities

Use when

Segmentation reflects physical or temporal properties of stock
Multiple segments must coexist within the same SKU and location
Segmentation participates in allocation, sourcing or recall logic

Examples

Physical Segmentation:
- Perfect stock vs. damaged stock sold at discount
- Pharmaceutical:
  Same medication with different expiry dates requiring separate tracking
Supply Chain Segmentation:
- Multi-supplier fashion:
  Same dress from Supplier A (fast delivery) vs. Supplier B (bulk order)
- Electronics:
  Components from USA vs. China requiring country-of-origin tracking for tariffs
- Luxury goods:
  Different manufacturing batches for product recall capability
Future Inventory Segmentation:
- Pre-orders:
  Reserved inventory from upcoming shipment (PO001, arriving March 1)
- Seasonal:
  Summer collection inventory in-transit vs. current spring inventory on-hand

What is segmentedInventory Quantities (`InventoryQuantity`) and their relationships (`parentId`) within an Inventory Position.How it worksInventory Quantities are organized into a segmented hierarchy, allowing multiple logical sub-stocks to exist under the same Product and Location.Why this works well

Enables segmentation without multiplying catalogs or variants
Preserves physical and lifecycle differences at the inventory level
Allows multiple segments to coexist within the same Inventory Position
Aligns segmentation with sourcing and allocation decisions

Trade-offs

Requires a more expressive inventory data model
Increases complexity of aggregation and sourcing logic
Requires custom extensions to define the segmentation logic

Avoid when

Segmentation is purely customer-facing
Differences only affect availability presentation, not physical stock
A simpler (e.g., Virtual Catalog-based) approach is sufficient

Pattern 4: Virtual Catalog Segmentation

Use when

The same physical stock should present different availability views
Availability differs by sales channel (for example, B2C vs B2B)
Business rules affect ATS calculation, not physical stock

Examples

Marketplace seller:
Same warehouse inventory shown differently on .com vs. marketplaces with different buffer rules
Member tiers:
Same inventory with different availability for Gold members (see full stock) vs. Silver members (limited view)
Sales channel inventory allocation:
Physical stores see 90% of stock, online sees 80% (10% held as safety stock)
Regional websites:
US website shows availability after US shipping buffers; UK website applies UK shipping buffers to same stock

What is segmentedAvailability view (`VirtualPosition`).How it worksEach Virtual Catalog maintains its own set of Virtual Positions, independently recalculated from the same Inventory Catalog.Why this works well

Strong isolation between business contexts
Clear ownership of rules per channel
Mature and widely adopted pattern

Trade-offs

Each additional Virtual Catalog increases operational overhead
Potential data duplication
Does not scale well for high-cardinality segmentation (for example, per individual country)

Avoid when

Segmentation attributes are numerous or frequently changing
Segmentation reflects physical stock reality

Pattern 5: Virtual Segments

Use when

Segmentation is required at the availability layer
Segments are dynamic
Creating one Virtual Catalog per segment is not viable

Examples

Time-Based Availability:
- Wave 1 chairs available February 1 (200 units), Wave 2 available March 15 (300 units)
- Fashion pre-orders:
  Spring collection shows "50 available now, 200 more arriving April 1"
- Electronics launch:
  iPhone pre-orders against future shipments with specific delivery dates
Channel Segmentation (High Cardinality):
- Geographic markets:
  Same product with availability segmented across 50 country-specific sites
- Membership levels:
  Bronze/Silver/Gold/Platinum customers each with different allocations
- B2B wholesale:
  10 different partner tiers each seeing different availability
Dynamic Segments:
- Promotional campaign:
  "First 100 customers" segment that depletes as orders come in
- Loyalty program:
  "VIP early access" segment before general availability
- Bundle availability:
  Product available standalone vs. as part of bundle (different quantities)

What is segmentedLogical sub-views within a Virtual Position (`VirtualSegment`).How it worksVirtual Segments subdivide a Virtual Position into multiple logical segments, enabling differentiated availability.Why this works well

Reduces the need for Virtual Catalog proliferation
Supports high-cardinality or dynamic segmentation
Complements inventory-level segmentation

Trade-offs

Requires careful design of aggregation and querying

Cardinality and Query Performance Guardrails

Virtual Segments provide flexible modeling for future availability and segmentation scenarios. However, queries that resolve availability records using segments and time filters may need to evaluate multiple segments per Virtual Position. To ensure predictable query performance, follow these guidelines:

Keep segment density low within operational windows
Design Virtual Segments so that only a small number of segments (around 10 - 20 per Virtual Position) match a typical query window (for example, a few weeks)
Avoid high-frequency time segmentation
Do not represent time using very granular segments over long horizons (for example, daily segments spanning several years). Instead, prefer event-based segments, such as:
- arrivals
- releases
- expirations
Use operational time windows in queries
Queries that include `availableOn` should typically focus on operational planning windows (for example 7–30 days). Very large time horizons can significantly increase the number of segments evaluated during availability resolution
Use moderate pagination sizes when querying Virtual Positions
When quantity resolution depends on segments, using extremely large page sizes may impact performance. Recommended practice is to keep pagination sizes moderate (for example, around 100) and retrieve additional pages when needed

Must align with sourcing and allocation expectations
Requires custom extensions

Avoid when

segmentation reflects physical stock differences
a small number of static Virtual Catalogs is sufficient

Common Anti-Patterns

The following approaches are commonly used as workarounds and should generally be avoided:

using virtual or pseudo-locations to represent stock types, such as condition, manufacturing batch, supplier, or channel allocation
duplicating inventory catalogs to separate stock that belongs to the same product and physical location
forcing physical or lifecycle stock differences into product variants, when those differences are not customer-facing
modeling physical stock differences only at the availability layer, without representing them in the inventory model
introducing complex custom allocation or sourcing logic to compensate for missing segmentation in the data model

These patterns often increase operational complexity, reduce transparency, and make solutions fragile as segmentation requirements evolve.

How to Choose the Right Approach

Use the following questions as a starting point:

Is the difference explicitly chosen by the customer? → Product Variant Segmentation
Does the difference represent a physical or lifecycle property of stock? → Segmented Inventory Quantities or Inventory Catalog Isolation
Does the difference affect how availability is presented, rather than the stock itself? → Virtual Catalog Segmentation or Virtual Segments
Is the segmentation high in cardinality or expected to change frequently? → Virtual Segments

Answering these questions early helps avoid unnecessary complexity and rework.

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

Inventory Modeling Guide

Inventory Modeling Guide

Overview

Key points

What is Stock Segmentation?

Mental Model

Segmentation Patterns and Recommended Practices

Pattern 1: Product Variant Segmentation

Pattern 2: Inventory Catalog Isolation

Pattern 3: Segmented Inventory Quantities

Pattern 4: Virtual Catalog Segmentation

Pattern 5: Virtual Segments

Common Anti-Patterns

How to Choose the Right Approach

Related content

Stock Segmentation - Data Model and API Overview

Future Inventory - Data Model and API Overview

Kirill Gaiduk

Knowledge Tracks Related To This Topic

Building Blocks

Browse By Type

Helpful Resources

Quick Links