Orders Management Quickstart Guide

Welcome to the StateSet Orders Management Quickstart! This comprehensive guide will walk you through building a production-ready order management system using the StateSet API. You’ll learn how to handle the complete order lifecycle, from creation through fulfillment and delivery. Imagine you’re an e-commerce business selling products through your online store, marketplaces, and physical locations. You need to efficiently manage orders, keep track of inventory, and make sure your customers get their products on time, no matter where they ordered them from. StateSet helps you achieve this with its powerful DOM features.

Introduction
Getting Started
Core Concepts of DOM
API Walkthrough: End-to-End DOM Workflow
Integration with Other Systems
Real-Time Order Monitoring
Error Handling and Logging
Troubleshooting and Maintenance
Support Resources
Conclusion

Introduction

Distributed Order Management (DOM) is crucial for businesses managing orders across multiple channels and fulfillment locations. StateSet One provides a powerful API that simplifies DOM workflows, allowing you to manage your entire operation efficiently. What You’ll Learn:

How to set up your StateSet environment and use the SDK.
Core DOM concepts, including order management, inventory control, and fulfillment.
How to use the StateSet API to manage your order process from start to finish.
Strategies for cross-channel synchronization and real-time monitoring.
How to handle errors and integrate with other systems.

Prerequisites

Before you begin, ensure you have:

A StateSet account (Sign up here)
API credentials from the StateSet Cloud Console
Node.js 16+ installed
Basic understanding of REST APIs and JavaScript/TypeScript
Your eCommerce platform credentials (if integrating)

Getting Started

Install SDK

Install the StateSet SDK and required dependencies:

npm install StateSet-node dotenv
# or
yarn add StateSet-node dotenv

Configure Environment

Create a .env file in your project root:

# StateSet Configuration
STATESET_API_KEY=sk_live_your_actual_key_here
STATESET_ENVIRONMENT=production

# Webhook Configuration (optional)
WEBHOOK_SECRET=whsec_J7xK9mP3nQ5rS8tU...
WEBHOOK_URL=https://api.yourstore.com/webhooks/StateSet

# Integration Keys (if applicable)
SHOPIFY_API_KEY=shpat_c7e4b2f1a...
STRIPE_API_KEY=sk_live_your_stripe_key_here

Initialize Client

Create a robust client with error handling and retry logic:

import { StateSetClient } from 'StateSet-node';
import winston from 'winston';
import dotenv from 'dotenv';

dotenv.config();

// Configure structured logging
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'orders.log' }),
    new winston.transports.Console({
      format: winston.format.simple()
    })
  ]
});

class OrderManagementClient {
  constructor() {
    this.logger = logger;
    this.client = new StateSetClient({
      apiKey: process.env.STATESET_API_KEY,
      environment: process.env.STATESET_ENVIRONMENT,
      maxRetries: 3,
      timeout: 30000
    });
    
    this.initializeWebhooks();
  }
  
  async verifyConnection() {
    try {
      const health = await this.client.health.check();
      this.logger.info('Successfully connected to StateSet API', { status: health.status, timestamp: new Date().toISOString() });
      return true;
    } catch (error) {
      this.logger.error('StateSet API connection failed', { error: error.message, stack: error.stack });
      throw new Error('Unable to connect to StateSet API');
    }
  }
  
  async initializeWebhooks() {
    if (process.env.WEBHOOK_URL) {
      try {
        await this.client.webhooks.create({
          url: process.env.WEBHOOK_URL,
          events: [
            'order.created',
            'order.updated',
            'order.fulfilled',
            'inventory.updated'
          ],
          secret: process.env.WEBHOOK_SECRET
        });
        this.logger.info('Webhooks configured successfully', { url: process.env.WEBHOOK_URL });
      } catch (error) {
        this.logger.warn('Webhook configuration failed', { error: error.message, url: process.env.WEBHOOK_URL });
      }
    }
  }
}

// Initialize and verify connection
const orderClient = new OrderManagementClient();
await orderClient.verifyConnection();

Core Concepts of DOM

Before diving into the API, it’s important to understand the key concepts behind a Distributed Order Management system. Here is a simplified view of the process:

Order Management: This encompasses the entire lifecycle of an order, from the moment a customer places it to its successful delivery. This includes capturing the order, routing, tracking status, and handling any modifications. Why is it important? Centralized order management improves efficiency by managing all orders in one platform. It also enhances the customer experience by providing accurate and timely information.
Inventory Management: This involves tracking and managing inventory levels across multiple locations. Accurate inventory data is key to ensuring products are available when they are needed, minimizing stockouts or overstocks. Why is it important? Proper inventory control is needed to fulfill orders and make sure your products are available. It also helps prevent delays in fulfillment.
Fulfillment Orchestration: This is the process of coordinating and executing the fulfillment of orders. It includes selecting the right fulfillment locations, picking and packing items, and shipping them to the customer. Why is it important? Proper fulfillment orchestration helps ensure products get to your customer quickly and efficiently.
Cross-Channel Synchronization: This ensures that order status and inventory levels are consistent across all sales channels. This will help create a seamless experience for the customers. Why is it important? Without it, inconsistencies will frustrate customers. For example, a customer could order an item online and find out it is out of stock at the physical store.
Reporting and Analytics: This provides insights into order trends, fulfillment performance, and inventory management. It enables data-driven decision-making and optimization of the overall process. Why is it important? Analysis of your data will allow you to make more informed decisions about your business.

Understanding these core components will be essential as we explore the StateSet API and its functionalities.

API Walkthrough: End-to-End DOM Workflow

Let’s dive into the end-to-end workflow with the StateSet API.

Workflow 1: Order Capture and Routing

In this section, we’ll cover capturing orders from various sources and intelligently routing them to the best fulfillment location.

Example 1: Capture an Order

async function captureOrder(orderData) {
    try {
      let order;
      switch(orderData.type) {
        case 'standard':
          // See https://docs.StateSet.com/StateSet-commerce-api-reference/orders/create for details on the create order endpoint
          order = await client.order.create({
            source: orderData.channel,
            channel_order_id: orderData.channelOrderId,
           customer: orderData.customer,
            line_items: orderData.lineItems,
            total_price: orderData.totalPrice,
             currency: orderData.currency,
           shipping_address: orderData.shippingAddress,
           status: 'received'
         });
         break;
       case 'pre-order':
          order = await createPreOrder(orderData);
          break;
        case 'backorder':
          order = await createBackOrder(orderData);
          break;
        case 'subscription':
           order = await createSubscriptionOrder(orderData);
         break;
        default:
          throw new Error('Unsupported order type');
      }
     logger.info("Order Created:", order);
      return order;
    } catch (error) {
      logger.error("Error capturing order:", error);
      throw error;
    }
}

const order = await captureOrder({
  type: 'standard',
  channel: 'web',
  channelOrderId: 'WEB-001',
  customer: { id: 'cust_001' },
   lineItems: [
    { product_id: 'prod_001', quantity: 2, price: 20, weight: 1, length: 5, width: 5, height: 5 },
    { product_id: 'prod_002', quantity: 1, price: 30, weight: 2, length: 10, width: 10, height: 10 }
    ],
  totalPrice: 70,
  currency: 'USD',
  shippingAddress: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345'
    }
})

This function demonstrates how to capture an order using the client.order.create() method. The order details include customer information, line items, shipping address, and the source channel. This captures data from different types of orders, and can be easily expanded to include different order scenarios.

Example 2: Route an Order

async function routeOrder(orderId) {
    try {
      // See https://docs.StateSet.com/StateSet-commerce-api-reference/orders/get for details
      const order = await client.order.get(orderId);
    const fulfillmentLocations = await client.location.list({ type: 'fulfillment' });

        if (!order || !fulfillmentLocations.length) {
           throw new Error('Invalid order or no fulfillment locations available');
        }

        // Placeholder: This is where you would use a machine learning algorithm to predict the best fulfillment location
       const mlPrediction = {
         confidence: 0.95,
         locationScores: fulfillmentLocations.reduce((acc, location) => {
         acc[location.id] = Math.random();
         return acc;
        }, {})
       }

        const inventoryLevels = await getInventoryLevels(order.line_items.map(item => item.product_id));
       const shippingRates = await getShippingRates(order);

      const optimalLocation = determineOptimalLocation(order, fulfillmentLocations, mlPrediction, shippingRates, inventoryLevels);

      if (!optimalLocation) {
       throw new Error('Unable to determine optimal fulfillment location');
    }
     // See https://docs.StateSet.com/StateSet-commerce-api-reference/orders/update for details
     const updatedOrder = await client.order.update(orderId, {
       assigned_location: optimalLocation.id,
        status: 'routed',
        routing_metadata: {
            prediction_confidence: mlPrediction.confidence,
            selected_shipping_rate: optimalLocation.selectedRate
          }
       });

    await logRoutingDecision(orderId, optimalLocation, mlPrediction);
    logger.info("Order Routed:", updatedOrder);
    return {
      optimalLocation,
      updatedOrder
   };
  } catch (error) {
      logger.error(`Error routing order ${orderId}:`, error);
    await client.order.update(orderId, { status: 'routing_failed' });
      throw error;
    }
}

function determineOptimalLocation(order, locations, mlPrediction, shippingRates, inventoryLevels) {
  const scoredLocations = locations.map(location => {
     const inventoryScore = calculateInventoryScore(location, order, inventoryLevels);
     const shippingScore = calculateShippingScore(location, shippingRates);
    const mlScore = mlPrediction.locationScores[location.id] || 0;
       const fulfillmentCost = estimateFulfillmentCost(location, order);

    const totalScore = (inventoryScore * 0.4) + (shippingScore * 0.3) + (mlScore * 0.2) - (fulfillmentCost * 0.1);

     return {
       ...location,
     score: totalScore,
        selectedRate: shippingRates[location.id].cheapestRate
      };
   });

   return scoredLocations.reduce((best, current) =>
      current.score > best.score ? current : best
    , scoredLocations[0]);
}

function calculateInventoryScore(location, order, inventoryLevels) {
    return order.line_items.reduce((score, item) => {
      const availability = inventoryLevels[location.id]?.[item.product_id] || 0;
      return score + (availability >= item.quantity ? 1 : 0);
   }, 0) / order.line_items.length;
}

function calculateShippingScore(location, shippingRates) {
  const locationRates = shippingRates[location.id];
   const cheapestRate = locationRates.cheapestRate;
  const fastestRate = locationRates.fastestRate;
   return 1 - (cheapestRate.price / fastestRate.price);
}

function estimateFulfillmentCost(location, order) {
    // Simplified cost estimation
  const baseCost = location.fulfillmentCostFactor || 1;
    return baseCost * order.line_items.reduce((total, item) => total + item.quantity, 0);
}

async function getShippingRates(order) {
  try {
      const carriers = await client.carrier.list();
    const fulfillmentLocations = await client.location.list({ type: 'fulfillment' });

     const rates = {};
    for (const location of fulfillmentLocations) {
     const locationRates = await Promise.all(carriers.map(carrier =>
        carrier.getRates({
            origin: location.address,
          destination: order.shipping_address,
          packages: convertOrderToPackages(order)
        })
      ));

      const flatRates = locationRates.flatMap(rate => rate);
     rates[location.id] = {
        allRates: flatRates,
        cheapestRate: flatRates.reduce((min, rate) => rate.price < min.price ? rate : min),
        fastestRate: flatRates.reduce((fastest, rate) => rate.deliveryDays < fastest.deliveryDays ? rate : fastest)
       };
      }

      return rates;
    } catch (error) {
     logger.error("Error fetching shipping rates:", error);
        throw error
  }
}

function convertOrderToPackages(order) {
   // Simplified conversion - in reality, this would involve a more complex packing algorithm
   return [{
      weight: order.line_items.reduce((total, item) => total + (item.weight * item.quantity), 0),
     dimensions: {
       length: Math.max(...order.line_items.map(item => item.length)),
       width: Math.max(...order.line_items.map(item => item.width)),
        height: Math.max(...order.line_items.map(item => item.height))
     }
   }];
}

async function getInventoryLevels(productIds) {
    const inventoryRecords = await client.inventory.list({ product_id: { in: productIds } });
   return inventoryRecords.reduce((acc, record) => {
      acc[record.location_id] = acc[record.location_id] || {};
       acc[record.location_id][record.product_id] = record.available_quantity;
        return acc;
     }, {});
}

async function logRoutingDecision(orderId, optimalLocation, mlPrediction) {
  await client.log.create({
     type: 'order_routing',
      order_id: orderId,
    selected_location: optimalLocation.id,
    ml_confidence: mlPrediction.confidence,
     routing_score: optimalLocation.score
   });
}

// Example usage
const routedOrder = await routeOrder(order.id);
logger.info("Routed Order:", routedOrder);

This function illustrates a more complex process, using a combination of inventory data, shipping rates, and an ML prediction (placeholder) to determine the optimal fulfillment location for the order. It includes placeholders for you to expand to include your own logic. This helps to understand the decision making process that goes into routing.

Workflow 2: Inventory Management and Allocation

This section focuses on managing inventory levels, allocating stock to orders, and rebalancing inventory across locations.

Example 1: Get a Global Inventory View

async function getGlobalInventory(productId) {
  try {
    const inventoryList = await client.inventory.list({ product_id: productId });
      const globalInventory = inventoryList.reduce((acc, inv) => {
      acc[inv.location_id] = {
        quantity: inv.quantity,
          type: inv.inventory_type, // 'owned', 'dropship', or 'jit'
        safetyStock: inv.safety_stock_level
      };
        return acc;
     }, {});
      logger.info("Global Inventory:", globalInventory);
    return globalInventory;
  } catch (error) {
      logger.error("Error fetching global inventory:", error);
      throw error;
  }
}

//Example of use
const globalInventory = await getGlobalInventory('prod_001')

This function retrieves a global view of inventory for a specific product across all locations, using the client.inventory.list() method. This will give you a snapshot of all the inventory, including the type and safety stock levels.

Example 2: Allocate Inventory for an Order

async function allocateInventory(orderId) {
   let allocatedItems = [];
  try {
   const order = await client.order.get(orderId);
   const allocationResults = await Promise.all(order.line_items.map(async (item) => {
     const allocation = await determineOptimalAllocation(item, order.assigned_location);
      return { item, allocation };
    }));

      for (const { item, allocation } of allocationResults) {
        for (const alloc of allocation) {
        if (alloc.quantity > 0) {
          await client.inventory.allocate({
           product_id: item.product_id,
           location_id: alloc.location_id,
           quantity: alloc.quantity,
            allocation_type: alloc.type,
            order_id: orderId,
            item_id: item.id
           });
        allocatedItems.push({
            item_id: item.id,
            product_id: item.product_id,
           allocated_quantity: alloc.quantity,
          location_id: alloc.location_id,
           allocation_type: alloc.type
           });
        }
       }
      }

    const fullyAllocated = allocatedItems.every(ai =>
        ai.allocated_quantity === order.line_items.find(li => li.id === ai.item_id).quantity
     );
    await client.order.update(orderId, {
        status: fullyAllocated ? 'fully_allocated' : 'partially_allocated',
      inventory_allocations: allocatedItems
     });

      await logAllocationResult(orderId, allocatedItems, fullyAllocated);
      logger.info("Allocation Results:", { orderId, allocatedItems, fullyAllocated });
      return { orderId, allocatedItems, fullyAllocated };
  } catch (error) {
     logger.error(`Error allocating inventory for order ${orderId}:`, error);
    await client.order.update(orderId, {
       status: 'allocation_failed',
        allocation_error: error.message
     });
    throw error;
  }
}

async function determineOptimalAllocation(item, preferredLocation) {
  const inventory = await getInventoryLevels(item.product_id);
  const reservations = await getActiveReservations(item.product_id);
  const safetyStockLevels = await getSafetyStockLevels(item.product_id);

  let remainingQuantity = item.quantity;
    let allocations = [];

   // Try to allocate from the preferred location first
    if (inventory[preferredLocation]) {
     const preferredAllocation = allocateFromLocation(
       preferredLocation,
     remainingQuantity,
      inventory[preferredLocation],
       reservations[preferredLocation],
       safetyStockLevels[preferredLocation]
   );
      if (preferredAllocation.quantity > 0) {
        allocations.push(preferredAllocation);
          remainingQuantity -= preferredAllocation.quantity;
    }
    }

    // If we couldn't fully allocate from the preferred location, try others
   if (remainingQuantity > 0) {
     for (const [locationId, quantity] of Object.entries(inventory)) {
     if (locationId === preferredLocation) continue;

       const allocation = allocateFromLocation(
          locationId,
          remainingQuantity,
          quantity,
           reservations[locationId],
         safetyStockLevels[locationId]
     );

    if (allocation.quantity > 0) {
       allocations.push(allocation);
     remainingQuantity -= allocation.quantity;
      if (remainingQuantity === 0) break;
       }
     }
  }

    // If we still couldn't allocate everything, create a backorder
   if (remainingQuantity > 0) {
      allocations.push({
        location_id: 'backorder',
          quantity: remainingQuantity,
          type: 'backorder'
       });
     }
  return allocations;
}

function allocateFromLocation(locationId, requiredQuantity, availableQuantity, reservations, safetyStock) {
  const effectiveQuantity = Math.max(availableQuantity - reservations - safetyStock, 0);
  const allocatedQuantity = Math.min(requiredQuantity, effectiveQuantity);

  return {
     location_id: locationId,
      quantity: allocatedQuantity,
      type: allocatedQuantity > 0 ? 'standard' : 'none'
   };
}

async function getActiveReservations(productId) {
    const reservations = await client.reservation.list({ product_id: productId, status: 'active' });
    return reservations.reduce((acc, reservation) => {
      acc[reservation.location_id] = (acc[reservation.location_id] || 0) + reservation.quantity;
      return acc;
    }, {});
}

async function getSafetyStockLevels(productId) {
  const safetyStockRecords = await client.safetyStock.list({ product_id: productId });
    return safetyStockRecords.reduce((acc, record) => {
      acc[record.location_id] = record.quantity;
       return acc;
   }, {});
}

async function logAllocationResult(orderId, allocatedItems, fullyAllocated) {
    await client.log.create({
      type: 'inventory_allocation',
      order_id: orderId,
       allocated_items: allocatedItems,
      fully_allocated: fullyAllocated,
      timestamp: new Date().toISOString()
     });
}

//Example of use
const allocatedOrder = await allocateInventory(order.id)
logger.info("Allocated order:", allocatedOrder);

This code shows how inventory is allocated to an order, based on the preferred location and available inventory. This function also demonstrates how to allocate from other locations if the primary location does not have sufficient stock.

Example 3: Rebalance Inventory

async function rebalanceInventory() {
  const rebalancingLog = [];
  try {
    const inventory = await client.inventory.list();
    const locations = await client.location.list();
    const salesVelocity = await getSalesVelocityByLocation();
    const seasonalTrends = await getSeasonalTrends();
    const shippingCosts = await getShippingCostMatrix();
    const storageCapacity = await getStorageCapacityByLocation();

      const rebalancingPlan = generateRebalancingPlan(
          inventory,
        locations,
       salesVelocity,
        seasonalTrends,
          shippingCosts,
           storageCapacity
      );
    for (const transfer of rebalancingPlan) {
      try {
        await client.inventory.transfer(transfer);
          rebalancingLog.push({
              status: 'success',
            transfer: transfer
        });
       } catch (transferError) {
         logger.error(`Error executing transfer:`, transferError);
           rebalancingLog.push({
            status: 'failed',
              transfer: transfer,
           error: transferError.message
        });
       }
      }
    const successfulTransfers = rebalancingLog.filter(log => log.status === 'success').length;
      logger.info(`Inventory rebalancing completed. ${successfulTransfers}/${rebalancingPlan.length} transfers successful.`);

    await logRebalancingResult(rebalancingLog);

   return {
     totalTransfers: rebalancingPlan.length,
       successfulTransfers: successfulTransfers,
      rebalancingLog: rebalancingLog
    };
 } catch (error) {
      logger.error("Error in inventory rebalancing process:", error);
    await logRebalancingError(error);
        throw error;
   }
}

function generateRebalancingPlan(inventory, locations, salesVelocity, seasonalTrends, shippingCosts, storageCapacity) {
    const rebalancingPlan = [];

   // Group inventory by product
   const productInventory = groupInventoryByProduct(inventory);

  for (const [productId, productLocations] of Object.entries(productInventory)) {
      const totalInventory = sum(Object.values(productLocations));
    const totalSalesVelocity = sum(Object.values(salesVelocity[productId] || {}));

    if (totalSalesVelocity === 0) continue; // Skip products with no sales

   const idealDistribution = calculateIdealDistribution(
        productId,
        totalInventory,
       locations,
      salesVelocity,
       seasonalTrends,
      storageCapacity
     );

      for (const [fromLocation, fromQuantity] of Object.entries(productLocations)) {
        const idealQuantity = idealDistribution[fromLocation] || 0;
        const difference = fromQuantity - idealQuantity;

      if (difference > 0) { // This location has excess inventory
        for (const [toLocation, toIdealQuantity] of Object.entries(idealDistribution)) {
         if (productLocations[toLocation] < toIdealQuantity) {
              const transferQuantity = Math.min(difference, toIdealQuantity - productLocations[toLocation]);
           if (transferQuantity > 0 && isTransferCostEffective(productId, fromLocation, toLocation, transferQuantity, shippingCosts)) {
           rebalancingPlan.push({
               product_id: productId,
                from_location: fromLocation,
                  to_location: toLocation,
                 quantity: transferQuantity
              });
           productLocations[fromLocation] -= transferQuantity;
            productLocations[toLocation] = (productLocations[toLocation] || 0) + transferQuantity;
            }
          }
         }
        }
     }
   }

  return rebalancingPlan;
}

function calculateIdealDistribution(productId, totalInventory, locations, salesVelocity, seasonalTrends, storageCapacity) {
  const distribution = {};
    const totalSalesVelocity = sum(Object.values(salesVelocity[productId] || {}));

  for (const location of locations) {
   const locationSalesVelocity = salesVelocity[productId]?.[location.id] || 0;
  const seasonalFactor = seasonalTrends[productId]?.[location.id] || 1;
    const adjustedSalesVelocity = locationSalesVelocity * seasonalFactor;

        let idealQuantity = Math.round((adjustedSalesVelocity / totalSalesVelocity) * totalInventory);
      idealQuantity = Math.min(idealQuantity, storageCapacity[location.id]); // Respect storage capacity

        distribution[location.id] = idealQuantity;
  }

  return distribution;
}

function isTransferCostEffective(productId, fromLocation, toLocation, quantity, shippingCosts) {
    const transferCost = shippingCosts[fromLocation]?.[toLocation] * quantity;
    const productValue = getProductValue(productId);
    const transferValueRatio = transferCost / (productValue * quantity);

   // Consider transfer cost-effective if it's less than 10% of the inventory value
    return transferValueRatio < 0.1;
}

function groupInventoryByProduct(inventory) {
    return inventory.reduce((acc, item) => {
       acc[item.product_id] = acc[item.product_id] || {};
     acc[item.product_id][item.location_id] = item.quantity;
        return acc;
   }, {});
}

async function getSalesVelocityByLocation() {
    // Placeholder: In a real implementation you'd use a caching layer
   const cacheKey = 'sales_velocity';
     // let salesVelocity = cache.get(cacheKey);

     //if (salesVelocity) {
   //   return salesVelocity;
     //}

    try {
     // Assume we're fetching data for the last 90 days
      const endDate = new Date();
        const startDate = new Date(endDate.getTime() - (90 * 24 * 60 * 60 * 1000));

     const salesData = await client.analytics.getSales({
          start_date: startDate.toISOString(),
           end_date: endDate.toISOString(),
          group_by: ['product_id', 'location_id']
       });

   let salesVelocity = salesData.reduce((acc, sale) => {
        acc[sale.product_id] = acc[sale.product_id] || {};
       acc[sale.product_id][sale.location_id] = sale.quantity / 90; // Daily sales velocity
            return acc;
   }, {});

     // cache.set(cacheKey, salesVelocity);
     return salesVelocity;
    } catch (error) {
       logger.error('Error fetching sales velocity:', error);
      throw new Error('Failed to fetch sales velocity data');
   }
}

async function getSeasonalTrends() {
   // Placeholder: In a real implementation you'd use a caching layer
     const cacheKey = 'seasonal_trends';
     // let seasonalTrends = cache.get(cacheKey);

    //  if (seasonalTrends) {
       //   return seasonalTrends;
     //  }

    try {
        // Assume we're fetching seasonal data for the next 90 days
     const startDate = new Date();
        const endDate = new Date(startDate.getTime() + (90 * 24 * 60 * 60 * 1000));

        const trendsData = await client.analytics.getSeasonalTrends({
          start_date: startDate.toISOString(),
        end_date: endDate.toISOString(),
        group_by: ['product_id', 'location_id']
       });

        let seasonalTrends = trendsData.reduce((acc, trend) => {
         acc[trend.product_id] = acc[trend.product_id] || {};
         acc[trend.product_id][trend.location_id] = trend.seasonal_factor;
            return acc;
       }, {});

      // cache.set(cacheKey, seasonalTrends);
      return seasonalTrends;
    } catch (error) {
     logger.error('Error fetching seasonal trends:', error);
        throw new Error('Failed to fetch seasonal trend data');
    }
}

async function getShippingCostMatrix() {
  // Placeholder: In a real implementation you'd use a caching layer
    const cacheKey = 'shipping_cost_matrix';
    // let shippingCostMatrix = cache.get(cacheKey);

   // if (shippingCostMatrix) {
       // return shippingCostMatrix;
    // }

    try {
    const locations = await client.location.list();
        let shippingCostMatrix = {};

     for (const fromLocation of locations) {
       shippingCostMatrix[fromLocation.id] = {};
            for (const toLocation of locations) {
                if (fromLocation.id !== toLocation.id) {
                  const shippingRate = await client.shipping.getRate({
                       from: fromLocation.id,
                        to: toLocation.id,
                        weight: 1, // Assume 1 kg as a base weight
                        volume: 1 // Assume 1 cubic meter as a base volume
                    });
                   shippingCostMatrix[fromLocation.id][toLocation.id] = shippingRate.cost;
           }
           }
      }

        //  cache.set(cacheKey, shippingCostMatrix);
    return shippingCostMatrix;
    } catch (error) {
     logger.error('Error fetching shipping cost matrix:', error);
       throw new Error('Failed to fetch shipping cost data');
   }
}

async function getStorageCapacityByLocation() {
    // Placeholder: In a real implementation you'd use a caching layer
    const cacheKey = 'storage_capacity';
    //  let storageCapacity = cache.get(cacheKey);

    // if (storageCapacity) {
      //  return storageCapacity;
     //}

  try {
        const locations = await client.location.list();
      let storageCapacity = {};

        for (const location of locations) {
          const capacityData = await client.warehouse.getCapacity(location.id);
        storageCapacity[location.id] = capacityData.available_capacity;
       }
    // cache.set(cacheKey, storageCapacity);
    return storageCapacity;
    } catch (error) {
        logger.error('Error fetching storage capacity:', error);
       throw new Error('Failed to fetch storage capacity data');
    }
}

function getProductValue(productId) {
    return new Promise((resolve, reject) => {
       // Placeholder: In a real implementation you'd use a caching layer
       const cacheKey = `product_value_${productId}`;
     // const cachedValue = cache.get(cacheKey);

        //if (cachedValue) {
          //  resolve(cachedValue);
      //  } else {
            client.product.get(productId)
            .then(product => {
                const value = product.cost || product.price || 0;
         //     cache.set(cacheKey, value);
                resolve(value);
        })
            .catch(error => {
               logger.error(`Error fetching product value for ${productId}:`, error);
               reject(new Error(`Failed to fetch product value for ${productId}`));
      });
      //  }
  });
}

function sum(numbers) {
   return numbers.reduce((a, b) => a + b, 0);
}

async function logRebalancingResult(rebalancingLog) {
    await client.log.create({
     type: 'inventory_rebalancing',
      result: rebalancingLog,
       timestamp: new Date().toISOString()
    });
}

async function logRebalancingError(error) {
   await client.log.create({
       type: 'inventory_rebalancing_error',
     error: error.message,
        stack: error.stack,
       timestamp: new Date().toISOString()
    });
}
// Example of use
const rebalancedInventory = await rebalanceInventory();
logger.info("Rebalanced Inventory:", rebalancedInventory);

## Support Resources

If you encounter issues or have questions, here are some resources that can help you:

*   **StateSet Documentation:** [https://docs.StateSet.com](https://docs.StateSet.com)
*   **Community:** [https://StateSet.com/community](https://StateSet.com/community)
*   **Email Support:** [support@StateSet.com](mailto:support@StateSet.com)

## Complete Order Lifecycle Implementation

Here's a production-ready implementation that ties everything together:

```javascript
import { StateSetClient } from 'StateSet-node';
import { EventEmitter } from 'events';

class OrderLifecycleManager extends EventEmitter {
  constructor(apiKey) {
    super();
    this.client = new StateSetClient({ apiKey });
    this.setupEventHandlers();
  }
  
  /**
   * Process a complete order from creation to delivery
   */
  async processOrder(orderData) {
    const orderLog = {
      orderId: null,
      steps: [],
      errors: [],
      startTime: Date.now()
    };
    
    try {
      // Step 1: Validate and create order
      this.emit('step:start', 'order_creation');
      const order = await this.createOrderWithValidation(orderData);
      orderLog.orderId = order.id;
      orderLog.steps.push({ step: 'created', timestamp: Date.now() });
      
      // Step 2: Check inventory and allocate
      this.emit('step:start', 'inventory_check');
      const allocation = await this.allocateInventoryWithFallback(order);
      orderLog.steps.push({ step: 'allocated', timestamp: Date.now() });
      
      // Step 3: Route to optimal fulfillment center
      this.emit('step:start', 'routing');
      const routing = await this.routeOrderIntelligently(order, allocation);
      orderLog.steps.push({ step: 'routed', timestamp: Date.now() });
      
      // Step 4: Create fulfillment order
      this.emit('step:start', 'fulfillment');
      const fulfillment = await this.createFulfillmentWithRetry(order, routing);
      orderLog.steps.push({ step: 'fulfillment_created', timestamp: Date.now() });
      
      // Step 5: Generate shipping label
      this.emit('step:start', 'shipping');
      const shipping = await this.generateShippingLabel(fulfillment);
      orderLog.steps.push({ step: 'shipped', timestamp: Date.now() });
      
      // Step 6: Notify customer
      this.emit('step:start', 'notification');
      await this.sendCustomerNotifications(order, shipping);
      orderLog.steps.push({ step: 'customer_notified', timestamp: Date.now() });
      
      // Success!
      orderLog.completionTime = Date.now();
      orderLog.duration = orderLog.completionTime - orderLog.startTime;
      
      this.emit('order:complete', orderLog);
      return {
        success: true,
        order,
        fulfillment,
        shipping,
        log: orderLog
      };
      
    } catch (error) {
      orderLog.errors.push({
        step: this.currentStep,
        error: error.message,
        timestamp: Date.now()
      });
      
      // Attempt recovery
      await this.handleOrderError(orderLog, error);
      
      this.emit('order:failed', orderLog);
      throw error;
    }
  }
  
  async createOrderWithValidation(orderData) {
    // Validate order data
    const validation = this.validateOrderData(orderData);
    if (!validation.valid) {
      throw new Error(`Order validation failed: ${validation.errors.join(', ')}`);
    }
    
    // Check for duplicate orders
    const isDuplicate = await this.checkDuplicateOrder(orderData);
    if (isDuplicate) {
      throw new Error('Duplicate order detected');
    }
    
    // Create order with idempotency key
    const order = await this.client.orders.create({
      ...orderData,
      idempotency_key: this.generateIdempotencyKey(orderData)
    });
    
    return order;
  }
  
  async allocateInventoryWithFallback(order) {
    try {
      // Try primary allocation
      return await this.client.inventory.allocate({
        order_id: order.id,
        items: order.items
      });
    } catch (error) {
      if (error.code === 'INSUFFICIENT_INVENTORY') {
        // Try split fulfillment
        return await this.attemptSplitFulfillment(order);
      }
      throw error;
    }
  }
  
  async routeOrderIntelligently(order, allocation) {
    // Get all potential fulfillment locations
    const locations = await this.client.locations.list({
      type: 'fulfillment',
      active: true
    });
    
    // Score each location
    const scoredLocations = await Promise.all(
      locations.map(async (location) => {
        const score = await this.scoreLocation(location, order, allocation);
        return { location, score };
      })
    );
    
    // Select optimal location
    const optimal = scoredLocations.reduce((best, current) => 
      current.score > best.score ? current : best
    );
    
    // Update order with routing
    await this.client.orders.update(order.id, {
      fulfillment_location: optimal.location.id,
      routing_score: optimal.score
    });
    
    return optimal;
  }
  
  async createFulfillmentWithRetry(order, routing) {
    let attempts = 0;
    const maxAttempts = 3;
    
    while (attempts < maxAttempts) {
      try {
        return await this.client.fulfillment.create({
          order_id: order.id,
          location_id: routing.location.id,
          priority: this.calculatePriority(order)
        });
      } catch (error) {
        attempts++;
        if (attempts >= maxAttempts) throw error;
        
        // Wait with exponential backoff
        await this.sleep(Math.pow(2, attempts) * 1000);
      }
    }
  }
  
  async generateShippingLabel(fulfillment) {
    // Select best carrier
    const carrier = await this.selectOptimalCarrier(fulfillment);
    
    // Generate label
    const label = await this.client.shipping.createLabel({
      fulfillment_id: fulfillment.id,
      carrier: carrier.id,
      service: carrier.recommended_service,
      insurance: fulfillment.total_value > 100
    });
    
    return label;
  }
  
  async sendCustomerNotifications(order, shipping) {
    const notifications = [];
    
    // Email notification
    notifications.push(
      this.client.notifications.send({
        type: 'email',
        to: order.customer_email,
        template: 'order_shipped',
        data: {
          order_number: order.number,
          tracking_number: shipping.tracking_number,
          tracking_url: shipping.tracking_url,
          estimated_delivery: shipping.estimated_delivery
        }
      })
    );
    
    // SMS if opted in
    if (order.customer_phone && order.sms_opt_in) {
      notifications.push(
        this.client.notifications.send({
          type: 'sms',
          to: order.customer_phone,
          message: `Your order ${order.number} has shipped! Track: ${shipping.tracking_url}`
        })
      );
    }
    
    await Promise.all(notifications);
  }
  
  setupEventHandlers() {
    this.on('step:start', (step) => {
      this.currentStep = step;
      logger.info(`📋 Starting: ${step}`);
    });
    
    this.on('order:complete', (log) => {
      logger.info(`✅ Order ${log.orderId} completed in ${log.duration}ms`);
    });
    
    this.on('order:failed', (log) => {
      logger.error(`❌ Order ${log.orderId} failed:`, log.errors);
    });
  }
  
  // Helper methods
  validateOrderData(data) {
    const errors = [];
    
    if (!data.customer_email) errors.push('Missing customer email');
    if (!data.items || data.items.length === 0) errors.push('No items in order');
    if (!data.shipping_address) errors.push('Missing shipping address');
    
    // Validate each item
    data.items?.forEach((item, index) => {
      if (!item.sku) errors.push(`Item ${index}: missing SKU`);
      if (!item.quantity || item.quantity < 1) errors.push(`Item ${index}: invalid quantity`);
      if (!item.price || item.price < 0) errors.push(`Item ${index}: invalid price`);
    });
    
    return {
      valid: errors.length === 0,
      errors
    };
  }
  
  generateIdempotencyKey(orderData) {
    return `${orderData.source}-${orderData.external_id}-${Date.now()}`;
  }
  
  async checkDuplicateOrder(orderData) {
    if (!orderData.external_id) return false;
    
    const existing = await this.client.orders.list({
      external_id: orderData.external_id,
      created_after: new Date(Date.now() - 24 * 60 * 60 * 1000) // Last 24 hours
    });
    
    return existing.length > 0;
  }
  
  calculatePriority(order) {
    // Priority based on shipping method, customer tier, etc.
    if (order.shipping_method === 'express') return 'high';
    if (order.customer_tier === 'vip') return 'high';
    if (order.total_value > 500) return 'medium';
    return 'normal';
  }
  
  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage example
const orderManager = new OrderLifecycleManager(process.env.STATESET_API_KEY);

// Process an order
const result = await orderManager.processOrder({
  source: 'website',
  external_id: 'WEB-12345',
  customer_email: 'customer@example.com',
  customer_phone: '+1234567890',
  sms_opt_in: true,
  shipping_method: 'standard',
  items: [
    {
      sku: 'WIDGET-001',
      quantity: 2,
      price: 29.99,
      name: 'Premium Widget'
    }
  ],
  shipping_address: {
    name: 'John Doe',
    street1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    zip: '94105',
    country: 'US'
  },
  billing_address: {
    // Same as shipping or different
  }
});

logger.info('Order processed:', result);

Webhook Integration

Implement real-time order tracking with webhooks:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

// Webhook endpoint
app.post('/webhooks/StateSet', async (req, res) => {
  try {
    // Verify webhook signature
    const signature = req.headers['x-StateSet-signature'];
    const payload = JSON.stringify(req.body);
    const expectedSignature = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(payload)
      .digest('hex');
    
    if (signature !== expectedSignature) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Process webhook event
    const { event, data } = req.body;
    
    switch (event) {
      case 'order.created':
        await handleOrderCreated(data);
        break;
        
      case 'order.fulfilled':
        await handleOrderFulfilled(data);
        break;
        
      case 'inventory.low':
        await handleLowInventory(data);
        break;
        
      case 'order.delivered':
        await handleOrderDelivered(data);
        break;
        
      default:
        logger.info(`Unhandled event: ${event}`);
    }
    
    res.status(200).json({ received: true });
    
  } catch (error) {
    logger.error('Webhook error:', error);
    res.status(500).json({ error: 'Webhook processing failed' });
  }
});

// Event handlers
async function handleOrderCreated(order) {
  logger.info('New order created:', order.id);
  
  // Send order confirmation
  await sendOrderConfirmation(order);
  
  // Update external systems
  await updateCRM(order);
  
  // Start fulfillment process
  await initiateFulfillment(order);
}

async function handleOrderFulfilled(data) {
  logger.info('Order fulfilled:', data.order_id);
  
  // Update inventory counts
  await updateInventoryCounts(data.items);
  
  // Trigger shipping workflow
  await createShippingLabel(data);
  
  // Notify customer
  await sendShippingNotification(data);
}

async function handleLowInventory(data) {
  logger.info('Low inventory alert:', data);
  
  // Check if reorder needed
  if (data.available < data.reorder_point) {
    await createPurchaseOrder(data.product_id, data.reorder_quantity);
  }
  
  // Alert operations team
  await notifyOperationsTeam(data);
}

async function handleOrderDelivered(data) {
  logger.info('Order delivered:', data.order_id);
  
  // Request customer feedback
  await sendFeedbackRequest(data);
  
  // Update customer lifetime value
  await updateCustomerMetrics(data);
}

app.listen(3000, () => {
  logger.info('Webhook server running on port 3000');
});

Error Recovery Patterns

Implement robust error handling and recovery:

class OrderErrorRecovery {
  constructor(client) {
    this.client = client;
    this.retryQueue = [];
  }
  
  async handleOrderError(order, error) {
    const errorHandlers = {
      'INSUFFICIENT_INVENTORY': this.handleInsufficientInventory,
      'PAYMENT_FAILED': this.handlePaymentFailure,
      'INVALID_ADDRESS': this.handleInvalidAddress,
      'CARRIER_ERROR': this.handleCarrierError,
      'SYSTEM_ERROR': this.handleSystemError
    };
    
    const handler = errorHandlers[error.code] || this.handleGenericError;
    return await handler.call(this, order, error);
  }
  
  async handleInsufficientInventory(order, error) {
    logger.info('Handling insufficient inventory for order:', order.id);
    
    // Option 1: Try to allocate from multiple locations
    const multiLocationAllocation = await this.attemptMultiLocationFulfillment(order);
    if (multiLocationAllocation.success) {
      return multiLocationAllocation;
    }
    
    // Option 2: Create backorder
    const backorder = await this.createBackorder(order, error.items);
    
    // Notify customer of delay
    await this.notifyCustomerOfDelay(order, backorder.estimated_restock_date);
    
    return { success: true, type: 'backorder', backorder };
  }
  
  async handlePaymentFailure(order, error) {
    logger.info('Handling payment failure for order:', order.id);
    
    // Retry payment with fallback method
    const retryResult = await this.retryPayment(order);
    if (retryResult.success) {
      return retryResult;
    }
    
    // Put order on hold
    await this.client.orders.update(order.id, {
      status: 'payment_pending',
      payment_retry_count: (order.payment_retry_count || 0) + 1
    });
    
    // Send payment failure notification
    await this.sendPaymentFailureNotification(order);
    
    // Schedule retry
    this.schedulePaymentRetry(order);
    
    return { success: false, type: 'payment_pending' };
  }
  
  async handleInvalidAddress(order, error) {
    logger.info('Handling invalid address for order:', order.id);
    
    // Try to validate/correct address
    const correctedAddress = await this.validateAndCorrectAddress(order.shipping_address);
    
    if (correctedAddress.valid) {
      // Update order with corrected address
      await this.client.orders.update(order.id, {
        shipping_address: correctedAddress.address
      });
      
      return { success: true, type: 'address_corrected' };
    }
    
    // Request address update from customer
    await this.requestAddressUpdate(order);
    
    return { success: false, type: 'awaiting_address_update' };
  }
  
  async attemptMultiLocationFulfillment(order) {
    const locations = await this.client.locations.list({ type: 'fulfillment' });
    const allocations = [];
    
    for (const item of order.items) {
      const itemAllocations = await this.findInventoryAcrossLocations(item, locations);
      if (itemAllocations.length === 0) {
        return { success: false, missing_item: item };
      }
      allocations.push(...itemAllocations);
    }
    
    // Create split fulfillment orders
    const fulfillmentOrders = await this.createSplitFulfillmentOrders(order, allocations);
    
    return { success: true, fulfillment_orders: fulfillmentOrders };
  }
  
  schedulePaymentRetry(order) {
    // Add to retry queue
    this.retryQueue.push({
      order_id: order.id,
      retry_at: new Date(Date.now() + 2 * 60 * 60 * 1000), // 2 hours
      attempt: order.payment_retry_count || 1
    });
  }
}

Performance Monitoring

Track and optimize your order management performance:

class OrderPerformanceMonitor {
  constructor(client) {
    this.client = client;
    this.metrics = new Map();
  }
  
  async trackOrderMetrics(order, stage, data = {}) {
    const metric = {
      order_id: order.id,
      stage,
      timestamp: Date.now(),
      ...data
    };
    
    // Store in memory (in production, use a proper metrics service)
    const key = `${order.id}-${stage}`;
    this.metrics.set(key, metric);
    
    // Send to analytics
    await this.client.analytics.track({
      event: `order.${stage}`,
      properties: metric
    });
  }
  
  async generatePerformanceReport(startDate, endDate) {
    const report = {
      period: { start: startDate, end: endDate },
      summary: {},
      bottlenecks: [],
      recommendations: []
    };
    
    // Get all orders in period
    const orders = await this.client.orders.list({
      created_after: startDate,
      created_before: endDate
    });
    
    // Calculate key metrics
    report.summary = {
      total_orders: orders.length,
      average_fulfillment_time: this.calculateAverageFulfillmentTime(orders),
      on_time_delivery_rate: this.calculateOnTimeDeliveryRate(orders),
      order_accuracy_rate: this.calculateOrderAccuracyRate(orders),
      inventory_turnover: await this.calculateInventoryTurnover(startDate, endDate)
    };
    
    // Identify bottlenecks
    report.bottlenecks = await this.identifyBottlenecks(orders);
    
    // Generate recommendations
    report.recommendations = this.generateRecommendations(report);
    
    return report;
  }
  
  calculateAverageFulfillmentTime(orders) {
    const fulfilledOrders = orders.filter(o => o.fulfilled_at);
    if (fulfilledOrders.length === 0) return 0;
    
    const totalTime = fulfilledOrders.reduce((sum, order) => {
      const created = new Date(order.created_at);
      const fulfilled = new Date(order.fulfilled_at);
      return sum + (fulfilled - created);
    }, 0);
    
    return totalTime / fulfilledOrders.length / (1000 * 60 * 60); // Hours
  }
  
  async identifyBottlenecks(orders) {
    const bottlenecks = [];
    
    // Check for slow fulfillment locations
    const locationPerformance = await this.analyzeLocationPerformance(orders);
    locationPerformance.forEach((perf, location) => {
      if (perf.avg_fulfillment_time > 48) { // 48 hours
        bottlenecks.push({
          type: 'slow_fulfillment',
          location,
          avg_time: perf.avg_fulfillment_time,
          impact: 'high'
        });
      }
    });
    
    // Check for inventory issues
    const inventoryIssues = await this.analyzeInventoryIssues(orders);
    if (inventoryIssues.stockout_rate > 0.05) { // 5%
      bottlenecks.push({
        type: 'inventory_stockouts',
        rate: inventoryIssues.stockout_rate,
        affected_skus: inventoryIssues.affected_skus,
        impact: 'critical'
      });
    }
    
    return bottlenecks;
  }
  
  generateRecommendations(report) {
    const recommendations = [];
    
    // Based on bottlenecks
    report.bottlenecks.forEach(bottleneck => {
      if (bottleneck.type === 'slow_fulfillment') {
        recommendations.push({
          priority: 'high',
          action: 'Optimize fulfillment center operations',
          location: bottleneck.location,
          expected_impact: '20-30% reduction in fulfillment time'
        });
      }
      
      if (bottleneck.type === 'inventory_stockouts') {
        recommendations.push({
          priority: 'critical',
          action: 'Adjust reorder points and safety stock levels',
          affected_skus: bottleneck.affected_skus,
          expected_impact: '90% reduction in stockouts'
        });
      }
    });
    
    // Based on general metrics
    if (report.summary.on_time_delivery_rate < 0.95) {
      recommendations.push({
        priority: 'medium',
        action: 'Review carrier performance and consider alternatives',
        current_rate: report.summary.on_time_delivery_rate,
        target_rate: 0.98
      });
    }
    
    return recommendations;
  }
}

// Usage
const monitor = new OrderPerformanceMonitor(client);
const report = await monitor.generatePerformanceReport(
  new Date('2024-01-01'),
  new Date('2024-01-31')
);

logger.info('Performance Report:', report);

Best Practices

Always use idempotency keys to prevent duplicate orders
Implement proper retry logic with exponential backoff
Use webhooks for real-time updates instead of polling
Batch operations when processing multiple orders
Monitor performance and set up alerts for anomalies
Validate all input data before processing
Log everything for debugging and audit trails
Handle errors gracefully with customer-friendly messages
Test edge cases including partial fulfillment and backorders
Keep your integration secure with proper authentication

Troubleshooting and Maintenance

Common Issues and Solutions

Authentication Errors (401 Unauthorized)

Symptoms: API calls failing with 401 status codePossible Causes:

Invalid or expired API key
API key not properly set in environment variables
Using sandbox key in production environment

Solutions:

// Verify API key is loaded correctly
if (!process.env.STATESET_API_KEY) {
  throw new Error('STATESET_API_KEY environment variable not set');
}

// Check API key format
const apiKey = process.env.STATESET_API_KEY;
if (!apiKey.startsWith('sk_')) {
  logger.error('Invalid API key format. Keys should start with sk_');
}

// Test connection
try {
  const health = await client.health.check();
  logger.info('API connection verified', { status: health.status });
} catch (error) {
  logger.error('API connection failed', { error: error.message });
}

Order Creation Failures

Symptoms: Unable to create ordersPossible Causes:

Missing required fields
Duplicate order prevention
Invalid customer data
Invalid shipping address format

Solutions:

Verify all required fields are provided
Check for duplicate order prevention
Ensure customer data is valid
Validate shipping address format

Inventory Allocation Issues

Symptoms: Inventory allocation failuresPossible Causes:

Insufficient inventory
Slow inventory updates
Inaccurate inventory data

Solutions:

Check real-time inventory levels
Review safety stock settings
Consider enabling backorders
Implement split fulfillment logic

Fulfillment Delays

Symptoms: Slow fulfillment processPossible Causes:

Fulfillment center capacity
Inefficient routing algorithm
Carrier API issues
Peak time patterns

Solutions:

Monitor fulfillment center capacity
Review routing algorithm efficiency
Check for carrier API issues
Analyze peak time patterns

Webhook Delivery Problems

Symptoms: Webhook events not receivedPossible Causes:

Webhook endpoint not accessible
Incorrect webhook secret configuration
Webhook event logs not available

Solutions:

Verify webhook endpoint is accessible
Check webhook secret configuration
Review webhook event logs
Implement webhook retry logic

Performance Debugging

Slow Order Processing

Diagnostic Tools:

// Performance monitoring
class OrderPerformanceMonitor {
  constructor() {
    this.metrics = new Map();
  }
  
  startTimer(operation, orderId) {
    const key = `${operation}:${orderId}`;
    this.metrics.set(key, {
      start: process.hrtime.bigint(),
      operation,
      orderId
    });
    return key;
  }
  
  endTimer(key) {
    const metric = this.metrics.get(key);
    if (!metric) return;
    
    const duration = Number(process.hrtime.bigint() - metric.start) / 1000000;
    
    logger.info('Operation completed', {
      operation: metric.operation,
      orderId: metric.orderId,
      duration: `${duration.toFixed(2)}ms`
    });
    
    // Alert on slow operations
    if (duration > 5000) {
      logger.warn('Slow operation detected', {
        operation: metric.operation,
        duration: `${duration.toFixed(2)}ms`,
        threshold: '5000ms'
      });
    }
    
    this.metrics.delete(key);
    return duration;
  }
}

Memory Usage Issues

Monitoring and Optimization:

// Memory monitoring
function monitorMemoryUsage() {
  const usage = process.memoryUsage();
  const memoryUsageMB = {
    rss: Math.round(usage.rss / 1024 / 1024),
    heapTotal: Math.round(usage.heapTotal / 1024 / 1024),
    heapUsed: Math.round(usage.heapUsed / 1024 / 1024),
    external: Math.round(usage.external / 1024 / 1024)
  };
  
  logger.info('Memory usage', memoryUsageMB);
  
  // Alert on high memory usage
  if (memoryUsageMB.heapUsed > 512) { // 512MB threshold
    logger.warn('High memory usage detected', memoryUsageMB);
    
    // Force garbage collection if available
    if (global.gc) {
      global.gc();
      logger.info('Forced garbage collection');
    }
  }
  
  return memoryUsageMB;
}

// Schedule memory monitoring
setInterval(monitorMemoryUsage, 30000); // Every 30 seconds

Next Steps

Implement error handling and logging to ensure smooth operation and easy troubleshooting
Set up performance monitoring to identify bottlenecks and optimize your order management system
Test your integration thoroughly to ensure it meets your business needs
Stay updated with the latest features and improvements from StateSet

Troubleshooting and Maintenance

Common Issues and Solutions

Authentication Errors (401 Unauthorized)

Symptoms: API calls failing with 401 status codePossible Causes:

Invalid or expired API key
API key not properly set in environment variables
Using sandbox key in production environment

Solutions:

// Verify API key is loaded correctly
if (!process.env.STATESET_API_KEY) {
  throw new Error('STATESET_API_KEY environment variable not set');
}

// Check API key format
const apiKey = process.env.STATESET_API_KEY;
if (!apiKey.startsWith('sk_')) {
  logger.error('Invalid API key format. Keys should start with sk_');
}

// Test connection
try {
  const health = await client.health.check();
  logger.info('API connection verified', { status: health.status });
} catch (error) {
  logger.error('API connection failed', { error: error.message });
}

Order Validation Failures

Symptoms: Orders failing validation during creationCommon Validation Issues:

Missing required fields (customer_email, items, shipping_address)
Invalid product SKUs or quantities
Incorrect address format
Invalid payment information

Solutions:

// Comprehensive order validation
function validateOrderData(orderData) {
  const errors = [];
  
  // Required fields validation
  const required = ['customer_email', 'items', 'shipping_address'];
  required.forEach(field => {
    if (!orderData[field]) {
      errors.push(`Missing required field: ${field}`);
    }
  });
  
  // Email validation
  if (orderData.customer_email && !isValidEmail(orderData.customer_email)) {
    errors.push('Invalid email format');
  }
  
  // Items validation
  if (orderData.items && Array.isArray(orderData.items)) {
    orderData.items.forEach((item, index) => {
      if (!item.sku) errors.push(`Item ${index}: Missing SKU`);
      if (!item.quantity || item.quantity < 1) {
        errors.push(`Item ${index}: Invalid quantity`);
      }
      if (!item.price || item.price < 0) {
        errors.push(`Item ${index}: Invalid price`);
      }
    });
  }
  
  // Address validation
  if (orderData.shipping_address) {
    const addr = orderData.shipping_address;
    const addrRequired = ['line1', 'city', 'state', 'postal_code', 'country'];
    addrRequired.forEach(field => {
      if (!addr[field]) {
        errors.push(`Shipping address missing: ${field}`);
      }
    });
  }
  
  return errors;
}

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

Inventory Synchronization Issues

Symptoms: Orders failing due to insufficient inventoryDebugging Steps:

// Check inventory levels before order creation
async function validateInventoryAvailability(items) {
  const inventoryChecks = await Promise.all(
    items.map(async (item) => {
      try {
        const inventory = await client.inventory.get(item.sku);
        return {
          sku: item.sku,
          requested: item.quantity,
          available: inventory.available_quantity,
          sufficient: inventory.available_quantity >= item.quantity
        };
      } catch (error) {
        return {
          sku: item.sku,
          error: error.message,
          sufficient: false
        };
      }
    })
  );
  
  const insufficient = inventoryChecks.filter(check => !check.sufficient);
  
  if (insufficient.length > 0) {
    logger.warn('Insufficient inventory detected', { insufficient });
    throw new Error(`Insufficient inventory for SKUs: ${insufficient.map(i => i.sku).join(', ')}`);
  }
  
  return inventoryChecks;
}

Payment Processing Failures

Symptoms: Orders created but payment failingCommon Payment Issues:

Invalid payment method details
Insufficient funds
Payment processor connectivity issues
Currency mismatch

Debugging and Recovery:

async function handlePaymentFailure(order, paymentError) {
  logger.error('Payment processing failed', {
    orderId: order.id,
    error: paymentError.message,
    paymentMethod: order.payment_method?.type
  });
  
  // Hold the order for manual review
  await client.orders.update(order.id, {
    status: 'payment_failed',
    notes: `Payment failed: ${paymentError.message}`,
    hold_reason: 'payment_processing_error'
  });
  
  // Send notification to customer service team
  await client.notifications.send({
    type: 'internal',
    channel: 'slack',
    message: `Order ${order.number} payment failed. Requires manual review.`,
    metadata: {
      orderId: order.id,
      customerEmail: order.customer_email,
      errorCode: paymentError.code
    }
  });
  
  // Attempt to retry payment with exponential backoff
  if (paymentError.retryable) {
    await schedulePaymentRetry(order.id, paymentError.retryAfter || 300);
  }
}

Webhook Delivery Issues

Symptoms: Missing or delayed webhook notificationsDebugging Steps:

// Webhook health check
async function verifyWebhookHealth() {
  try {
    // Check webhook endpoint status
    const webhooks = await client.webhooks.list();
    
    for (const webhook of webhooks.data) {
      logger.info('Webhook status', {
        id: webhook.id,
        url: webhook.url,
        status: webhook.status,
        lastDelivery: webhook.last_successful_delivery,
        failureCount: webhook.consecutive_failures
      });
      
      // Test webhook delivery
      const testResult = await client.webhooks.test(webhook.id);
      if (!testResult.success) {
        logger.warn('Webhook test failed', {
          webhookId: webhook.id,
          error: testResult.error
        });
      }
    }
  } catch (error) {
    logger.error('Webhook health check failed', { error: error.message });
  }
}

// Webhook signature verification
function verifyWebhookSignature(payload, signature, secret) {
  const crypto = require('crypto');
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Rate Limiting and Throttling

Symptoms: Requests failing with 429 status codeSolutions:

// Implement intelligent retry with exponential backoff
async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers['retry-after']) || Math.pow(2, attempt);
        
        logger.warn('Rate limit hit, retrying', {
          attempt,
          retryAfter,
          rateLimitRemaining: error.headers['x-ratelimit-remaining']
        });
        
        if (attempt === maxRetries) {
          throw new Error(`Rate limit exceeded after ${maxRetries} attempts`);
        }
        
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}

// Monitor rate limit usage
function monitorRateLimit(response) {
  const remaining = parseInt(response.headers['x-ratelimit-remaining']);
  const limit = parseInt(response.headers['x-ratelimit-limit']);
  const resetTime = parseInt(response.headers['x-ratelimit-reset']);
  
  const usage = ((limit - remaining) / limit) * 100;
  
  if (usage > 80) {
    logger.warn('High rate limit usage', {
      usage: `${usage.toFixed(1)}%`,
      remaining,
      limit,
      resetTime: new Date(resetTime * 1000)
    });
  }
}

Data Consistency Issues

Symptoms: Order data appearing inconsistent across different API callsCommon Causes:

Race conditions in concurrent updates
Caching issues
Event ordering problems

Solutions:

// Implement optimistic locking
async function updateOrderWithLocking(orderId, updateData) {
  const maxRetries = 5;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // Get current order with version
      const currentOrder = await client.orders.get(orderId);
      
      // Include version in update
      const updatedOrder = await client.orders.update(orderId, {
        ...updateData,
        version: currentOrder.version
      });
      
      return updatedOrder;
    } catch (error) {
      if (error.code === 'VERSION_CONFLICT' && attempt < maxRetries) {
        // Version conflict - retry with exponential backoff
        const delay = Math.pow(2, attempt) * 100;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  
  throw new Error(`Failed to update order after ${maxRetries} attempts due to version conflicts`);
}

// Implement idempotency for critical operations
async function createOrderIdempotent(orderData) {
  const idempotencyKey = `order-${orderData.customer_email}-${Date.now()}`;
  
  try {
    return await client.orders.create(orderData, {
      headers: {
        'Idempotency-Key': idempotencyKey
      }
    });
  } catch (error) {
    if (error.code === 'DUPLICATE_REQUEST') {
      // Return the existing order
      return await client.orders.get(error.existingResourceId);
    }
    throw error;
  }
}

Performance Debugging

Slow Order Processing

Diagnostic Tools:

// Performance monitoring
class OrderPerformanceMonitor {
  constructor() {
    this.metrics = new Map();
  }
  
  startTimer(operation, orderId) {
    const key = `${operation}:${orderId}`;
    this.metrics.set(key, {
      start: process.hrtime.bigint(),
      operation,
      orderId
    });
    return key;
  }
  
  endTimer(key) {
    const metric = this.metrics.get(key);
    if (!metric) return;
    
    const duration = Number(process.hrtime.bigint() - metric.start) / 1000000;
    
    logger.info('Operation completed', {
      operation: metric.operation,
      orderId: metric.orderId,
      duration: `${duration.toFixed(2)}ms`
    });
    
    // Alert on slow operations
    if (duration > 5000) {
      logger.warn('Slow operation detected', {
        operation: metric.operation,
        duration: `${duration.toFixed(2)}ms`,
        threshold: '5000ms'
      });
    }
    
    this.metrics.delete(key);
    return duration;
  }
}

Memory Usage Issues

Monitoring and Optimization:

// Memory monitoring
function monitorMemoryUsage() {
  const usage = process.memoryUsage();
  const memoryUsageMB = {
    rss: Math.round(usage.rss / 1024 / 1024),
    heapTotal: Math.round(usage.heapTotal / 1024 / 1024),
    heapUsed: Math.round(usage.heapUsed / 1024 / 1024),
    external: Math.round(usage.external / 1024 / 1024)
  };
  
  logger.info('Memory usage', memoryUsageMB);
  
  // Alert on high memory usage
  if (memoryUsageMB.heapUsed > 512) { // 512MB threshold
    logger.warn('High memory usage detected', memoryUsageMB);
    
    // Force garbage collection if available
    if (global.gc) {
      global.gc();
      logger.info('Forced garbage collection');
    }
  }
  
  return memoryUsageMB;
}

// Schedule memory monitoring
setInterval(monitorMemoryUsage, 30000); // Every 30 seconds

Debug Mode and Logging

Enable comprehensive logging for troubleshooting:

// Enhanced debug configuration
const debugConfig = {
  logLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
  enableRequestLogging: true,
  enableResponseLogging: true,
  enablePerformanceLogging: true,
  sensitiveFields: ['password', 'credit_card', 'ssn'] // Fields to redact
};

// Create debug-enabled client
const debugClient = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  debug: debugConfig.enableRequestLogging,
  logger: (message, data) => {
    // Redact sensitive information
    const sanitized = redactSensitiveData(data, debugConfig.sensitiveFields);
    logger.debug(message, sanitized);
  }
});

function redactSensitiveData(data, sensitiveFields) {
  if (!data || typeof data !== 'object') return data;
  
  const sanitized = { ...data };
  
  sensitiveFields.forEach(field => {
    if (sanitized[field]) {
      sanitized[field] = '[REDACTED]';
    }
  });
  
  return sanitized;
}

Getting Help

If you continue to experience issues:

Check Service Status: Visit status.StateSet.com for service health
Review Logs: Enable debug logging and review application logs
Test in Sandbox: Reproduce issues in sandbox environment first
Contact Support: Email support@StateSet.com with:
- Error messages and stack traces
- Request/response examples
- Order IDs and timestamps
- Steps to reproduce the issue

Next Steps

Inventory Management

Learn advanced inventory management techniques

Returns Processing

Handle returns and refunds efficiently

Performance Optimization

Optimize your order processing performance

Error Handling

Implement robust error handling patterns

Conclusion

Congratulations! You now have a comprehensive understanding of order management with StateSet. You’ve learned how to:

✅ Handle the complete order lifecycle
✅ Implement robust error handling and recovery
✅ Set up real-time webhook notifications
✅ Monitor and optimize performance
✅ Handle complex scenarios like split fulfillment

Continue exploring our API documentation and join our community for support and best practices.

​Orders Management Quickstart Guide

​Table of Contents

​Introduction

​Prerequisites

​Getting Started

​Core Concepts of DOM

​API Walkthrough: End-to-End DOM Workflow

​Workflow 1: Order Capture and Routing

​Example 1: Capture an Order

​Example 2: Route an Order

​Workflow 2: Inventory Management and Allocation

​Example 1: Get a Global Inventory View

​Example 2: Allocate Inventory for an Order

​Example 3: Rebalance Inventory

​Webhook Integration

​Error Recovery Patterns

​Performance Monitoring

​Best Practices

​Troubleshooting and Maintenance

​Common Issues and Solutions

​Performance Debugging

​Next Steps

​Troubleshooting and Maintenance

​Common Issues and Solutions

​Performance Debugging

​Debug Mode and Logging

​Getting Help

​Next Steps

Inventory Management

Returns Processing

Performance Optimization

Error Handling

​Conclusion

Orders Management Quickstart Guide

Table of Contents

Introduction

Prerequisites

Getting Started

Core Concepts of DOM

API Walkthrough: End-to-End DOM Workflow

Workflow 1: Order Capture and Routing

Example 1: Capture an Order

Example 2: Route an Order

Workflow 2: Inventory Management and Allocation

Example 1: Get a Global Inventory View

Example 2: Allocate Inventory for an Order

Example 3: Rebalance Inventory

Webhook Integration

Error Recovery Patterns

Performance Monitoring

Best Practices

Troubleshooting and Maintenance

Common Issues and Solutions

Performance Debugging

Next Steps

Troubleshooting and Maintenance

Common Issues and Solutions

Performance Debugging

Debug Mode and Logging

Getting Help

Next Steps

Conclusion