The cart timer expired while they were paying. Now what?

that tracks both the browse deadline and the grace period. The frontend requests a reservation and receives a payload containing the expiry time. The frontend displays a countdown but never triggers inventory release.

TypeScript Implementation

// Domain Models
interface ReservationPayload {
    reservationId: string;
    itemId: string;
    browseExpiresAt: number; // Unix timestamp
    graceExpiresAt: number;  // Unix timestamp
    status: 'ACTIVE' | 'GRACE' | 'EXPIRED' | 'COMMITTED';
}

interface PaymentWebhookEvent {
    eventId: string;
    reservationId: string;
    status: 'AUTHORIZED' | 'CAPTURED' | 'FAILED';
    amount: number;
    currency: string;
}

// Reservation Service
class ReservationService {
    private inventoryRepo: InventoryRepository;
    private reservationStore: ReservationStore;

    async createReservation(itemId: string, userId: string): Promise<ReservationPayload> {
        // Atomic check: Is item available?
        const available = await this.inventoryRepo.checkAvailability(itemId);
        if (!available) {
            throw new Error('ITEM_UNAVAILABLE');
        }

        const now = Date.now();
        const config = await this.getConfig();

        const reservation: ReservationPayload = {
            reservationId: generateId(),
            itemId,
            userId,
            browseExpiresAt: now + config.browseHoldMs,
            graceExpiresAt: now + config.browseHoldMs + config.paymentGraceMs,
            status: 'ACTIVE',
        };

        // Deduct available count atomically
        await this.inventoryRepo.holdItem(itemId, reservation.reservationId);
        await this.reservationStore.save(reservation);

        return reservation;
    }

    async processPaymentWebhook(event: PaymentWebhookEvent): Promise<OrderResult> {
        const reservation = await this.reservationStore.findById(event.reservationId);
        
        if (!reservation) {
            // Reservation never existed or was purged
            return this.handleOrphanPayment(event);
        }

        const now = Date.now();

        // Phase 1: Active or Grace Period
        if (now <= reservation.graceExpiresAt) {
            // User is within the grace window.
            // Honor the payment.
            return this.finalizeOrder(reservation, event);
        }

        // Phase 2: Expired
        if (now > reservation.graceExpiresAt) {
            // Grace period passed. Check if inventory was re-allocated.
            const currentHold = await this.inventoryRepo.getCurrentHold(reservation.itemId);
            
            if (currentHold?.reservationId === reservation.reservationId) {
                // Inventory is still held by this reservation (race condition on release).
                // Honor payment.
                return this.finalizeOrder(reservation, event);
            }

            // Inventory was released and potentially sold to another user.
            // This is a true oversell scenario.
            return this.handleOversell(reservation, event);
        }
    }

    private async finalizeOrder(reservation: ReservationPayload, event: PaymentWebhookEvent): Promise<OrderResult> {
        // Create order, mark reservation as committed.
        // Do NOT re-lock inventory. Payment is the terminal state.
        const order = await this.orderRepo.create({
            reservationId: reservation.reservationId,
            paymentId: event.eventId,
            itemId: reservation.itemId,
        });

        await this.reservationStore.updateStatus(reservation.reservationId, 'COMMITTED');
        return { success: true, orderId: order.id };
    }

    private async handleOversell(reservation: ReservationPayload, event: PaymentWebhookEvent): Promise<OrderResult> {
        // Critical: Auto-reverse payment immediately.
        // Notify user of inventory failure, not timer expiry.
        await this.paymentProvider.refund(event.eventId, 'Inventory sold to another customer.');
        return { success: false, reason: 'OVERSELL_AUTO_REFUNDED' };
    }
}

Architecture Decisions

• Why graceExpiresAt? The grace period extends the reservation validity specifically for payment reconciliation. If the browseExpiresAt passes but the user is in the payment flow, the server continues to accept the webhook as valid until graceExpiresAt. This covers 3-D Secure latency without keeping the item locked indefinitely for browsing users.
• Why no re-locking? Once finalizeOrder is called, the transaction is complete. Re-acquiring the item creates a phantom hold on an already sold asset. The order record is the source of truth post-capture.
• Why atomic inventory check on webhook? The grace window prevents timer-based releases, but it does not prevent a second user from purchasing the item if the first user's payment fails and the grace expires. The webhook handler must verify the inventory state at the moment of arrival to detect true oversells.

Pitfall Guide

1. Frontend as Source of Truth

   • Explanation: Allowing the browser to delete the reservation or release inventory when the countdown hits zero.
   • Fix: The frontend must only display the time. Release logic must reside in a server-side cron or event-driven handler that checks browseExpiresAt.

2. Post-Capture Re-Locking

   • Explanation: Attempting to re-reserve the item after payment success to "clean up" state.
   • Fix: Payment capture is terminal. The order entity replaces the reservation. Any code path that re-locks after capture indicates a state machine error.

3. Ignoring True Oversell

   • Explanation: Assuming the grace window guarantees inventory. If User A is in 3-D Secure and User B buys the item after User A's grace expires, User A's payment may still succeed.
   • Fix: The webhook handler must perform an atomic inventory check. If the item is no longer held by the reservation, trigger an immediate refund and notify the user of the inventory conflict.

4. Single Timer for All Phases

   • Explanation: Using the same TTL for browsing and payment. A 30-second hold is appropriate for browsing but insufficient for 3-D Secure flows.
   • Fix: Implement distinct durations. browseHoldMs should be tight to maximize turnover. paymentGraceMs should be generous (e.g., 120 seconds) to accommodate banking latency.

5. Webhook Race Conditions

   • Explanation: Processing a webhook before the reservation store has updated the status, or processing duplicate webhooks.
   • Fix: Use idempotency keys on all webhook handlers. Ensure the reservation status transition to COMMITTED is atomic with order creation.

6. Treating 3-D Secure as Instant

   • Explanation: Designing grace windows based on ideal network conditions.
   • Fix: Base paymentGraceMs on P99 latency data from your payment provider, including worst-case 3-D Secure challenges. Monitor grace window utilization to tune this value.

7. Manual Refund Workflows

   • Explanation: Relying on support teams to manually refund phantom orders.
   • Fix: Automate the oversell response. The system should detect the inventory mismatch and trigger a refund via the payment API without human intervention.

Production Bundle

Action Checklist

• Audit Timer Authority: Verify that no frontend code releases inventory. All release logic must be server-side.
• Define Grace Configuration: Establish browseHoldMs and paymentGraceMs values based on business risk and payment latency data.
• Implement Webhook Reconciliation: Ensure payment webhooks check inventory state, not just reservation existence.
• Add Oversell Handler: Create an automated path for immediate refunds when inventory is unavailable at webhook arrival.
• Remove Re-Locking Logic: Scan codebase for post-payment inventory holds and remove them.
• Monitor Grace Utilization: Track how often payments arrive during the grace window to validate configuration.
• Idempotency Enforcement: Guarantee webhook handlers are idempotent to prevent duplicate orders.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-Volume Flash Sale	Short browse hold, generous grace, strict oversell auto-refund.	Maximizes turnover while protecting committed users. Auto-refund prevents support overload.	Low refund cost; high conversion retention.
Low-Volume Luxury Item	Longer browse hold, standard grace.	Inventory scarcity is lower; user experience priority is higher.	Minimal inventory risk.
Perishable Inventory	Server-authoritative hold with real-time sync.	Physical constraints require strict accuracy. Grace window prevents phantom orders without risking spoilage.	Operational efficiency gain.
Legacy Frontend-Driven System	Immediate migration to server holds.	Frontend-driven expiry is a critical defect.	High initial refactor cost; eliminates refund liability.

Configuration Template

{
  "reservation_policy": {
    "browse_hold_ms": 30000,
    "payment_grace_ms": 120000,
    "max_concurrent_holds_per_user": 3,
    "oversell_action": "AUTO_REFUND",
    "webhook_timeout_ms": 5000,
    "idempotency_window_ms": 60000
  },
  "monitoring": {
    "alert_on_grace_utilization_gt_percent": 15,
    "alert_on_oversell_rate_gt_percent": 0.1
  }
}

Quick Start Guide

1. Schema Update: Add graceExpiresAt and status fields to your reservation table. Ensure browseExpiresAt is indexed for cleanup jobs.
2. Service Implementation: Deploy the ReservationService logic. Replace frontend release triggers with server-side expiration handlers.
3. Webhook Integration: Update payment webhook handlers to use the reconciliation logic. Implement the oversell auto-refund path.
4. Testing: Simulate a race condition by triggering a payment webhook after browseExpiresAt but before graceExpiresAt. Verify the order is created. Simulate an oversell by releasing inventory mid-grace and verify the refund triggers.
5. Rollout: Enable the new policy for a percentage of traffic. Monitor grace_utilization and oversell_rate metrics. Adjust paymentGraceMs if utilization is excessively high or low.