[Phase 1] Inventory Reservation & Hold System

[Copilot]

Implements short-lived inventory reservations to prevent overselling between cart and payment. Available stock is now calculated as currentStock - activeReservations.

Database Schema

• InventoryReservation model with store/product/variant relations, status, cartId, orderId, expiresAt
• ReservationStatus enum: ACTIVE, CONSUMED, EXPIRED, RELEASED

Service: inventory-reservation.service.ts

• createReservations() - Batch reserve with availability validation
• releaseReservation() / releaseCartReservations() - Manual release
• consumeReservations() - Atomic conversion during order creation
• extendReservation() - One-time extension (max 15 min)
• expireReservations() - Sweeper for cron job
• getAvailableStock() - Stock minus active reservations

API Routes

• POST /api/inventory/reserve - Batch reservation
• POST /api/inventory/release - Single or cart release
• POST /api/inventory/extend - Extend TTL once

Integration

• CheckoutService.createOrder() consumes reservations when cartId provided
• InventoryService.getLowStockItems() excludes reserved qty from alerts

Usage

// Reserve inventory
const result = await reservationService.createReservations({
  storeId,
  items: [{ productId, quantity: 2 }],
  cartId: 'cart_123',
  ttlMinutes: 15,
});

// On order creation, reservations are consumed atomically
await checkoutService.createOrder({ ...orderData, cartId: 'cart_123' });

Note: expireReservations() should be invoked via cron every minute.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Phase 1] Inventory Reservation & Hold System</issue_title>
<issue_description>## Priority: P0 (Critical)
Phase: 1 - E-Commerce Core
Epic Link: Product / Checkout (#15, #19, Order Processing placeholder #24)
Estimate: 3 days
Type: Story

Context

Implement short-lived inventory reservations to prevent overselling between cart and final payment, enabling accurate stock display and reducing race conditions under concurrent demand.

Scope

• InventoryReservation model (productId / variantId, quantity, storeId, cart/session reference, expiresAt)
• API: POST /api/inventory/reserve (batch reservation with validation)
• API: POST /api/inventory/release (manual release)
• Automatic expiration job (sweeper) every minute
• Integration with Order creation to convert reservation → decrement

Acceptance Criteria

• Reservation creation fails if insufficient available stock (currentStock - activeReservations >= requested)
• Expired reservations released (stock availability recalculated) within < 60s of expiry
• Order creation consumes reservations atomically (transaction) & prevents double decrement
• Reservation TTL configurable (default 15 minutes)
• Ability to extend reservation once (e.g. payment delay)
• Audit log entry: action: inventory_reservation_created / released / consumed
• Low stock alert logic excludes reserved quantity for proactive alert accuracy

Data Model (Draft)

model InventoryReservation {
  id          String   @id @default(cuid())
  storeId     String
  productId   String
  variantId   String?
  quantity    Int
  status      ReservationStatus @default(ACTIVE)
  cartId      String? // if cart session
  orderId     String? // set when consumed
  expiresAt   DateTime
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@index([storeId, productId])
  @@index([expiresAt])
}

enum ReservationStatus {
  ACTIVE
  CONSUMED
  EXPIRED
  RELEASED
}

Dependencies

• Blocks: Accurate stock display, prevents oversell incidents
• Blocked By: [Phase 1] Inventory Management #18 Inventory Management implementation
• Enhances: Multi-channel sync ([Phase 3] Epic: Multi-Channel Sales #35) future deduplication

Metrics

• Overselling incidents reduced to 0/month
• Reservation latency < 150ms p95
• Expiration sweep accuracy > 99%

Testing Checklist

• Concurrent reservations for same product (race-free)
• Expiration release job frees stock
• Conversion on order creation removes reservation & decrements stock once
• Extension updates expiresAt

Risk

High integrity risk if absent (score: 16). Supports scaling & channel sync.

References

• docs/GITHUB_ISSUES_COMPARISON_ANALYSIS.md
• Industry pattern: cart hold / soft allocation
  </issue_description>

<agent_instructions>read all the codebase and implemet carefully</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Phase 1] Inventory Reservation & Hold System #64

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
stormcomui	Error			Nov 29, 2025 3:17am