Fluent OMS: Inventory Accuracy & Soft Reservation Guide

Published: 29-06-2025

25 min read

#Json

Overview

Fluent Order Management System (OMS) implements a three-layer inventory architecture designed to provide real-time inventory accuracy and prevent order cancellations during high-traffic scenarios. This guide documents the platform's core concepts, integration patterns, and implementation details.

Key Benefits:

99.0% inventory accuracy with real-time stock management
<5% order cancellation rate (down from 50%)
35% reduction in cart abandonment
+$X revenue increase per flash sale

Business Value & Impact

Problem: Traditional Inventory Systems Fail During Peak Traffic

Metrics Before vs After

Metric	Before	After
Order Cancellation	50%	<5%
Cart abandonment	-	-35%
Revenue per flash sale	-	+$X

Industry Use Cases

Fashion: Seasonal variants, store transfers
Electronics: Launch protection, trade-ins
Luxury: Limited drops, VIP allocation

Key Concepts: IP, IQ, VP

To make sense of the architecture and flows described in this guide, it's important to understand the core inventory entities:

Inventory Position (IP): Represents the combination of a specific product and location. It is the foundational data point for calculating real-time stock levels using all associated inventory transactions (IQs).
Inventory Quantity (IQ): A detailed transaction ledger that records every stock-affecting event — such as LAST_ON_HAND (initial stock), SOFT_RESERVE (cart hold), RESERVED (confirmed order), and other types like RETURNED, SALE, CORRECTION AND DELTA. Each IQ is tied to a specific IP.
Virtual Position (VP): A channel-specific abstraction that calculates available-to-sell inventory by applying business rules such as buffer percentages or channel exclusions to the onHand value from the corresponding IP.

These entities are foundational to how Fluent OMS models inventory in real time for multiple channels and user journeys.

Core Architecture & Data Model

Fluent OMS uses a three-layer inventory architecture to ensure high availability and transactional accuracy.

Architecture Layers

Key Data Relationships:

IP → IQ (1:many): Each Inventory Position has multiple IQ transaction records. IQs reference their parent IP via
```
`ipRef`
```
IP ↔ VP (loose coupling): Virtual Positions find their corresponding IP by matching
```
`productRef + locationRef`
```
, not via direct foreign key
IP is the foundation: All inventory calculations start from IP, which aggregates IQ records to calculate
```
`onHand`
```

How IP, IQ, and VP Interact

The three entities work together in a layered approach to provide real-time, channel-specific inventory availability:

Data Flow Summary

IP aggregates IQ records: All ACTIVE status IQ transaction types (LAST_ON_HAND, SOFT_RESERVE, RESERVED, SALE, RETURNED, DELTA, CORRECTION) contribute to the onHand calculation
VP applies channel rules: Different channels can have different buffer strategies (Mobile 5%, Web 10%, Store 0%)
Real-time updates: New IQ records immediately affect all related VPs across all channels

Virtual Position Calculation Example

Step-by-step calculation for ACME Sneaker Black US9 at Main DC for ECOMMERCE channel:

Calculation Breakdown:

IP Aggregation: 50 (initial) - 2 (soft reserve) - 3 (reserved) = 45 onHand
Buffer Calculation: 45 × 10% = 4.5 units
Buffer Rounding: 4.5 → 5 units (round up for safety)
Final ATS: 45 - 5 = 40 units available to sell

Result: Customer sees "40 units available" on the ECOMMERCE channel

Data Model Examples

Inventory Position (IP)

The foundational record for a product at a specific location

1{
2  "ref": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT",
3  "productRef": "ACME_SNEAKER_BLK_US9",
4  "locationRef": "MAIN_DC",
5  "onHand": 45
6}

Language: json

Name: The foundational record for a product at a specific location

Description:

The foundational record for a product at a specific location

Inventory Quantity (IQ) Records

Transaction ledger showing all stock-affecting events

1[
2  {
3    "ipRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT",
4    "iqRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT:LAST_ON_HAND",
5    "type": "LAST_ON_HAND",
6    "quantity": 50,
7    "status": "ACTIVE"
8  },
9  {
10    "ipRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT",
11    "iqRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT:SOFT_RESERVE:FO_1234",
12    "type": "SOFT_RESERVE",
13    "quantity": -2,
14    "status": "ACTIVE"
15  },
16  {
17    "ipRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT",
18    "iqRef": "ACME_SNEAKER_BLK_US9:MAIN_DC:DEFAULT:RESERVED:FUL_456",
19    "type": "RESERVED",
20    "quantity": -3,
21    "status": "ACTIVE"
22  }
23]

Language: json

Name: Transaction ledger showing all stock-affecting events

Description:

Transaction ledger showing all stock-affecting events

Virtual Position (VP)

Channel-specific availability calculation

1{
2  "ref": "ACME_SNEAKER_BLK_US9:MAIN_DC:ECOMMERCE",
3  "productRef": "ACME_SNEAKER_BLK_US9",
4  "locationRef": "MAIN_DC",
5  "quantity": 40
6}

Language: json

Name: Channel-specific availability calculation

Description:

Channel-specific availability calculation

VP Business Rules (applied during calculation):

Channel: ECOMMERCE
Buffer Strategy: 10% PERCENTAGE buffer
Source onHand: 45 units (from matching IP)
Buffer Calculation: 45 × 10% = 4.5 → 5 units (rounded up)
Final ATS: 45 - 5 = 40 unit

Data Relationship Summary

Entity	Purpose	Key Fields	Calculation
IP	Product + Location base	`onHand` , `productRef` , `locationRef`	`SUM(ACTIVE status IQ records)`
IQ	Transaction records	`type` , `quantity` , `status`	Individual stock events
VP	Channel availability	`channel` , `buffer` , `availableToSell`	`IP.onHand - buffer`

Soft Reservation Deep Dive

Soft Reservation is a temporary hold on inventory when a customer adds items to cart. It prevents overselling by reserving stock in real time while ensuring inventory doesn't get locked up indefinitely.

Configurable Timer Mechanism

Timer Configuration:

Range: 5-15 minutes (configurable per client)
Flexibility: Can be configured per product, product category, or globally
Use Cases: High-demand items (5 min), regular items (15 min), luxury items (30 min)
Example: Flash sale items might use 5-10 minutes for urgency
Purpose: Automatically releases inventory from abandoned carts

Why the Timer is Essential:

Prevents inventory lockup: Without timer, abandoned carts would hold inventory forever
Maximizes availability: Releases inventory back to other customers quickly
Balances user experience: Gives customers enough time to checkout without being rushed
Handles edge cases: Browser crashes, network issues, or customer distraction

Soft Reservation Lifecycle

IQ Status Management & ATS Impact

Critical Detail: IP calculations only use

`ACTIVE`

status IQ records. When soft reservations convert to orders, the status changes maintain inventory accuracy.

Example: 2-Unit Cart → Order Flow

Initial State: IP has 45 onHand, VP shows 40 ATS

Step 1 - Cart Add:

Create: SOFT_RESERVE IQ (-2 units, ACTIVE status)
Result: IP onHand = 43, VP ATS = 38

Step 2 - Order Confirmation:

Update: SOFT_RESERVE IQ (-2 units, INACTIVE status)
Create: RESERVED IQ (-2 units, ACTIVE status)
Result: IP onHand = 43 (unchanged), VP ATS = 38 (unchanged)

Key Insight: ATS doesn't change during checkout because the same quantity moves from SOFT_RESERVE to RESERVED, both impacting availability equally.

API Comparison: virtualPositions vs fulfilmentOptions

Fluent OMS provides two key APIs for accessing inventory:

`virtualPositions`

and

`fulfilmentOptions`

. Choosing the right one depends on whether you're reading availability or actively managing reservations.

virtualPositions — Use When:

✅ You only need to display availability (no hold on inventory)
✅ Ideal for product listing pages, search results, and PDP views
❌ Cannot prevent oversells in high-velocity or concurrent scenarios

fulfilmentOptions — Use When:

✅ You need to reserve stock temporarily (soft reservation)
✅ Customer is in add-to-cart or checkout state
✅ Required for workflows where inventory accuracy directly affects conversion

Summary Table

Use Case	API to Use	Reason
Browse/search listings	`virtualPositions`	Lightweight read, no inventory impact
Add to Cart	`fulfilmentOptions`	Initiates soft reservation, prevents overselling
Begin Checkout	`fulfilmentOptions`	Ensures held inventory for this customer
Confirm Order	`fulfilmentOptions`	Converts soft reservation to firm allocation

Integration Flow Examples

`virtualPositions`

Query (Read-Only)

Used for availability display and product search.

`fulfilmentOptions`

Mutation (Transactional)

Used during checkout and reservation creation. FO is an extensible workflow - clients can customize logic including SOFT_RESERVE behavior.

Real-World Example: Flash Sale Success Story

Flash Sale Timeline

Timer Logic Explained:

Each customer gets exactly 15 minutes from when they add to cart:

Customer A: Adds at 10:15:00 → Timer expires at 10:30:00
Customer B: Adds at 10:15:05 → Timer expires at 10:30:05
Customer C: Adds at 10:15:10 → Timer expires at 10:30:10

Different expiry times are correct - each customer gets the same duration, but starting from their individual cart add time.

Visual Story: Race for the Last Item

Final Results:

3 soft reservations created simultaneously
1 successful order (Customer A won)
2 timer expirations (B and C were too slow)
0 oversells - inventory accuracy maintained
100% customer satisfaction for the successful buyer

Key Insights:

Customer A was fastest to checkout (1 minute) and secured 1 item
Customers B and C lost due to slow checkout (15+ minutes) - their items went back to inventory
3 items were available - all got soft reservations, but only fastest customer converted
Soft reservation prevented overselling while allowing fair competition

Demand Signals & Analytics

Key Architecture Note:

FulfilmentOption Ref Creation: The calling layer (your application) owns the

`ref`

creation for FulfilmentOptions. This design enables:

Easy Analytics: Use the same ref to query FulfilmentOption status and analytics data
Seamless Order Integration: Include the FO ref in order payload during checkout
Automated Cleanup: Efficiently deactivate soft reserve IQ types using the ref

Best Practice: Generate meaningful refs (e.g., "cart-{cartId}-{timestamp}") for easier tracking and debugging.

Platform Scope & Responsibility:

Fluent OMS provides the raw data signals through FulfilmentOptions calls, order payloads, and fulfillment plan responses. The platform captures and stores:

FulfilmentOption call patterns and responses
Order correlations via FO refs
Stock availability and fulfillment plan data
Timer events and soft reservation lifecycle

The specific analytics, inferences, and business intelligence engines are outside the scope of Fluent OMS. These are typically implemented by:

Client-side analytics platforms (e.g., Adobe Analytics, Google Analytics)
Business intelligence tools (e.g., Tableau, Power BI)
Custom ML/AI engines for demand forecasting
Marketing automation platforms (e.g., Salesforce, HubSpot)

Fluent OMS focuses on providing accurate, real-time inventory data - the analytics layer is your competitive advantage!

Business Intelligence Flow

Detailed Analytics Use Cases

Completed Purchases → Revenue Analytics

Detection Method: Correlate FO ref found in order payload with original FO call
Conversion Tracking: Match soft reservation timestamp to order creation time
Product Performance: Which SKUs convert from FO call to actual order
Channel Analysis: CC vs HD success rates by correlating order fulfillment type
Location Insights: Which locations from fulfillment plans actually fulfill orders

Abandoned Carts → Remarketing Triggers

Detection Method: FO ref exists but NO corresponding order payload after timer expiry
Timing Analysis: Track time between FO call and timer expiry with no order
Product Affinity: Which product combinations are frequently abandoned together
Recovery Campaigns: Target customers with unfulfilled FO refs
Price Sensitivity: Correlation between fulfillment costs and abandonment

Out of Stock → Restocking Intelligence

Detection Method: Empty or insufficient fulfillment plans in FO response (immediate)
Real-time Alerts: Instant notification when FO returns no viable fulfillment options
Location Analysis: Which locations consistently show zero availability
Demand Intensity: Frequency of out-of-stock FO calls per product/location
Supplier Integration: Automated reorder triggers based on stockout patterns

Channel Preferences → Personalization

Fulfillment Preferences: Customer preference for CC vs HD by product category
Location Loyalty: Preferred pickup locations and delivery addresses
Timing Patterns: When customers prefer to collect/receive orders
Experience Optimization: Customize UI based on historical preferences

Data Signal Workflow (Fluent OMS Scope):

Cart → FulfilmentOption → Order Flow:

Cart Creation: Generate FO ref (e.g., "cart-abc123-20240315")
Soft Reservation: Create FulfilmentOption with client-owned ref
Data Capture: Fluent OMS logs FO call, fulfillment plans, and inventory events
Order Checkout: Include FO ref in order payload
Correlation Data: Fluent OMS provides FO ref → Order mapping
Cleanup: Deactivate soft reserve IQ using FO ref

Analytics Implementation (Client Scope):

Query Fluent OMS data via APIs
Build conversion funnels using FO ref correlation
Implement ML models for demand forecasting
Trigger marketing campaigns based on abandonment patterns

Fluent OMS provides the foundational data signals - you build the intelligence layer!

KPIs & Technical Metrics

Important Note:

The metrics below are indicative figures based on typical implementations. Actual KPIs and technical performance metrics vary significantly depending on:

Client-specific requirements and business models
Implementation complexity and customization level
Infrastructure setup and hosting environment
Transaction volume and peak load patterns
SLA agreements and performance targets

Contact your Fluent OMS representative for client-specific performance benchmarks and SLA commitments.

Metric	Indicative Value
Inventory Accuracy	99.0%
Fulfillment SLA	99.5%
Uptime	99.99%
API Response Time	<200ms
Cart Abandonment Drop	35%
Support Ticket Reduction	65%

Girish Padmanabha

Product at Fluent Commerce

Fluent OMS: Inventory Accuracy & Soft Reservation Guide

Overview

Business Value & Impact

Metrics Before vs After

Key Concepts: IP, IQ, VP

Core Architecture & Data Model

Architecture Layers

How IP, IQ, and VP Interact

Virtual Position Calculation Example

Data Model Examples

Inventory Position (IP)

Inventory Quantity (IQ) Records

Virtual Position (VP)

Data Relationship Summary

Soft Reservation Deep Dive

Soft Reservation Lifecycle

IQ Status Management & ATS Impact

API Comparison: virtualPositions vs fulfilmentOptions

Summary Table

Integration Flow Examples

1.
`virtualPositions`
Query (Read-Only)

2.
`fulfilmentOptions`
Mutation (Transactional)

Real-World Example: Flash Sale Success Story

Flash Sale Timeline

Visual Story: Race for the Last Item

Demand Signals & Analytics

Business Intelligence Flow

KPIs & Technical Metrics

Fluent OMS: Inventory Accuracy & Soft Reservation Guide

Overview

Business Value & Impact

Metrics Before vs After

Key Concepts: IP, IQ, VP

Core Architecture & Data Model

Architecture Layers

How IP, IQ, and VP Interact

Virtual Position Calculation Example

Data Model Examples

Inventory Position (IP)

Inventory Quantity (IQ) Records

Virtual Position (VP)

Data Relationship Summary

Soft Reservation Deep Dive

Soft Reservation Lifecycle

IQ Status Management & ATS Impact

API Comparison: virtualPositions vs fulfilmentOptions

Summary Table

Integration Flow Examples

1. `virtualPositions` Query (Read-Only)

2. `fulfilmentOptions` Mutation (Transactional)

Real-World Example: Flash Sale Success Story

Flash Sale Timeline

Visual Story: Race for the Last Item

Demand Signals & Analytics

Business Intelligence Flow

KPIs & Technical Metrics

1.
`virtualPositions`
Query (Read-Only)

2.
`fulfilmentOptions`
Mutation (Transactional)