Inventory Management

Learn how to build a robust inventory synchronization system that keeps stock levels accurate across Quickbutik and your external systems in real-time.

Use cases covered:

Real-time stock level synchronization
Bulk inventory updates
Low stock alerts and management
Multi-location inventory tracking
Prevention of overselling

Quick Example

Here’s a complete example of syncing inventory when stock changes:

const QuickbutikAPI = require('./quickbutik-api');

class InventoryManager {
  constructor(apiKey) {
    this.api = new QuickbutikAPI(apiKey);
  }

  async updateProductStock(sku, newQuantity, location = 'main') {
    try {
      const result = await this.api.updateProducts({
        sku: sku,
        stock: newQuantity,
        qty_location: location
      });

      console.log(`Updated ${sku} stock to ${newQuantity} at ${location}`);
      return result;
    } catch (error) {
      console.error(`Failed to update stock for ${sku}:`, error);
      throw error;
    }
  }

  async bulkUpdateInventory(inventoryUpdates) {
    const results = [];
    const batchSize = 10;

    for (let i = 0; i < inventoryUpdates.length; i += batchSize) {
      const batch = inventoryUpdates.slice(i, i + batchSize);
      
      const batchPromises = batch.map(update => 
        this.updateProductStock(update.sku, update.quantity, update.location)
          .catch(error => ({ error: error.message, sku: update.sku }))
      );

      const batchResults = await Promise.all(batchPromises);
      results.push(...batchResults);

      // Small delay to avoid rate limiting
      if (i + batchSize < inventoryUpdates.length) {
        await new Promise(resolve => setTimeout(resolve, 100));
      }
    }

    return results;
  }
}

// Usage
const inventory = new InventoryManager(process.env.QUICKBUTIK_API_KEY);

// Update single product
await inventory.updateProductStock('SHIRT-123', 45);

// Bulk update
await inventory.bulkUpdateInventory([
  { sku: 'SHIRT-123', quantity: 45, location: 'warehouse-1' },
  { sku: 'PANTS-456', quantity: 12, location: 'warehouse-1' },
  { sku: 'HAT-789', quantity: 0, location: 'warehouse-2' }
]);

import asyncio
import time
from typing import List, Dict
from quickbutik_api import QuickbutikAPI

class InventoryManager:
    def __init__(self, api_key: str):
        self.api = QuickbutikAPI(api_key)
    
    async def update_product_stock(self, sku: str, new_quantity: int, location: str = 'main'):
        try:
            result = await self.api.update_products({
                'sku': sku,
                'stock': new_quantity,
                'qty_location': location
            })
            
            print(f'Updated {sku} stock to {new_quantity} at {location}')
            return result
        except Exception as error:
            print(f'Failed to update stock for {sku}: {error}')
            raise error
    
    async def bulk_update_inventory(self, inventory_updates: List[Dict]):
        results = []
        batch_size = 10
        
        for i in range(0, len(inventory_updates), batch_size):
            batch = inventory_updates[i:i + batch_size]
            
            batch_tasks = []
            for update in batch:
                task = self.update_product_stock(
                    update['sku'], 
                    update['quantity'], 
                    update.get('location', 'main')
                )
                batch_tasks.append(task)
            
            try:
                batch_results = await asyncio.gather(*batch_tasks, return_exceptions=True)
                results.extend(batch_results)
            except Exception as error:
                print(f'Batch update error: {error}')
            
            # Small delay to avoid rate limiting
            if i + batch_size < len(inventory_updates):
                await asyncio.sleep(0.1)
        
        return results

# Usage
async def main():
    inventory = InventoryManager(os.getenv('QUICKBUTIK_API_KEY'))
    
    # Update single product
    await inventory.update_product_stock('SHIRT-123', 45)
    
    # Bulk update
    await inventory.bulk_update_inventory([
        {'sku': 'SHIRT-123', 'quantity': 45, 'location': 'warehouse-1'},
        {'sku': 'PANTS-456', 'quantity': 12, 'location': 'warehouse-1'},
        {'sku': 'HAT-789', 'quantity': 0, 'location': 'warehouse-2'}
    ])

asyncio.run(main())

Webhook-Based Inventory Sync

Set up real-time inventory synchronization using webhooks:

app.post('/webhooks/quickbutik', async (req, res) => {
  const { event_type, product_id } = req.query;
  
  // Acknowledge webhook immediately
  res.status(200).send('OK');
  
  if (event_type === 'product.update') {
    await handleProductUpdate(product_id);
  }
});

async function handleProductUpdate(productId) {
  try {
    // Fetch updated product details
    const products = await api.getProducts({ 
      product_id: productId,
      include_details: true 
    });
    
    if (!products || products.length === 0) {
      throw new Error(`Product ${productId} not found`);
    }
    
    const product = products[0];
    
    // Check if stock changed
    if (await hasStockChanged(product)) {
      await syncInventoryToExternalSystem(product);
    }
    
  } catch (error) {
    console.error(`Failed to handle product update for ${productId}:`, error);
  }
}

async function hasStockChanged(product) {
  // Compare with your local inventory database
  const localInventory = await getLocalInventory(product.sku);
  return localInventory.quantity !== parseInt(product.qty || 0);
}

async function syncInventoryToExternalSystem(product) {
  try {
    const inventoryUpdate = {
      sku: product.sku,
      quantity: parseInt(product.qty || 0),
      location: product.qty_location || 'default',
      updated_at: new Date().toISOString()
    };
    
    const response = await fetch('https://your-system.com/api/inventory', {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.EXTERNAL_API_TOKEN}`
      },
      body: JSON.stringify(inventoryUpdate)
    });
    
    if (!response.ok) {
      throw new Error(`External API error: ${response.status}`);
    }
    
    console.log(`Synced inventory for ${product.sku}: ${product.qty} units`);
    
  } catch (error) {
    console.error(`Failed to sync inventory for ${product.sku}:`, error);
    
    // Add to retry queue
    await addToRetryQueue({
      type: 'inventory_sync',
      product,
      timestamp: new Date()
    });
  }
}

@app.route('/webhooks/quickbutik', methods=['POST'])
def quickbutik_webhook():
    event_type = request.args.get('event_type')
    product_id = request.args.get('product_id')
    
    # Acknowledge webhook immediately
    response = jsonify({'status': 'received'})
    
    if event_type == 'product.update':
        asyncio.create_task(handle_product_update(product_id))
    
    return response, 200

async def handle_product_update(product_id):
    try:
        # Fetch updated product details
        products = await api.get_products(
            product_id=product_id,
            include_details=True
        )
        
        if not products:
            raise Exception(f'Product {product_id} not found')
        
        product = products[0]
        
        # Check if stock changed
        if await has_stock_changed(product):
            await sync_inventory_to_external_system(product)
    
    except Exception as error:
        app.logger.error(f'Failed to handle product update for {product_id}: {error}')

async def has_stock_changed(product):
    # Compare with your local inventory database
    local_inventory = await get_local_inventory(product['sku'])
    return local_inventory['quantity'] != int(product.get('qty', 0))

async def sync_inventory_to_external_system(product):
    try:
        inventory_update = {
            'sku': product['sku'],
            'quantity': int(product.get('qty', 0)),
            'location': product.get('qty_location', 'default'),
            'updated_at': datetime.now().isoformat()
        }
        
        async with aiohttp.ClientSession() as session:
            async with session.put(
                'https://your-system.com/api/inventory',
                headers={
                    'Content-Type': 'application/json',
                    'Authorization': f'Bearer {os.getenv("EXTERNAL_API_TOKEN")}'
                },
                json=inventory_update
            ) as response:
                if not response.ok:
                    raise Exception(f'External API error: {response.status}')
        
        app.logger.info(f'Synced inventory for {product["sku"]}: {product.get("qty", 0)} units')
        
    except Exception as error:
        app.logger.error(f'Failed to sync inventory for {product["sku"]}: {error}')
        
        # Add to retry queue
        await add_to_retry_queue({
            'type': 'inventory_sync',
            'product': product,
            'timestamp': datetime.now()
        })

Low Stock Monitoring

Implement automated low stock alerts and reordering:

class LowStockMonitor {
  constructor(apiKey, thresholds = {}) {
    this.api = new QuickbutikAPI(apiKey);
    this.defaultThreshold = thresholds.default || 10;
    this.customThresholds = thresholds.custom || {};
  }

  async checkLowStock() {
    try {
      const products = await this.api.getProducts({ 
        include_details: true,
        limit: 500
      });

      const lowStockProducts = [];

      for (const product of products) {
        if (product.variants && product.variants.length > 0) {
          // Check variants
          for (const variant of product.variants) {
            if (this.isLowStock(variant)) {
              lowStockProducts.push({
                ...variant,
                parent_sku: product.sku,
                parent_title: product.title
              });
            }
          }
        } else {
          // Check main product
          if (this.isLowStock(product)) {
            lowStockProducts.push(product);
          }
        }
      }

      if (lowStockProducts.length > 0) {
        await this.handleLowStockAlert(lowStockProducts);
      }

      return lowStockProducts;

    } catch (error) {
      console.error('Failed to check low stock:', error);
      throw error;
    }
  }

  isLowStock(product) {
    const currentStock = parseInt(product.qty || 0);
    const threshold = this.customThresholds[product.sku] || this.defaultThreshold;
    
    return currentStock > 0 && currentStock <= threshold;
  }

  async handleLowStockAlert(lowStockProducts) {
    // Send alert notification
    await this.sendLowStockNotification(lowStockProducts);
    
    // Auto-reorder if configured
    const autoReorderProducts = lowStockProducts.filter(p => 
      this.shouldAutoReorder(p)
    );
    
    if (autoReorderProducts.length > 0) {
      await this.createReorderRequests(autoReorderProducts);
    }
  }

  async sendLowStockNotification(products) {
    const message = `🚨 Low Stock Alert!\n\n${products.map(p => 
      `${p.title || p.parent_title} (${p.sku}): ${p.qty} units remaining`
    ).join('\n')}`;

    // Send to Slack
    if (process.env.SLACK_WEBHOOK_URL) {
      await fetch(process.env.SLACK_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: message })
      });
    }

    // Send email
    if (process.env.EMAIL_WEBHOOK_URL) {
      await fetch(process.env.EMAIL_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          to: process.env.INVENTORY_EMAIL,
          subject: 'Low Stock Alert',
          body: message
        })
      });
    }
  }

  shouldAutoReorder(product) {
    // Add your auto-reorder logic here
    return product.supplier_sku && product.auto_reorder_enabled;
  }

  async createReorderRequests(products) {
    for (const product of products) {
      try {
        const reorderQuantity = this.calculateReorderQuantity(product);
        
        await this.createPurchaseOrder({
          sku: product.sku,
          supplier_sku: product.supplier_sku,
          quantity: reorderQuantity,
          supplier: product.supplier_name
        });

        console.log(`Created reorder for ${product.sku}: ${reorderQuantity} units`);
      } catch (error) {
        console.error(`Failed to create reorder for ${product.sku}:`, error);
      }
    }
  }

  calculateReorderQuantity(product) {
    // Simple reorder logic - you can make this more sophisticated
    const currentStock = parseInt(product.qty || 0);
    const threshold = this.customThresholds[product.sku] || this.defaultThreshold;
    const targetStock = threshold * 3; // Reorder to 3x threshold
    
    return Math.max(targetStock - currentStock, threshold);
  }
}

// Usage
const monitor = new LowStockMonitor(process.env.QUICKBUTIK_API_KEY, {
  default: 10,
  custom: {
    'POPULAR-ITEM-123': 50,
    'SEASONAL-456': 5
  }
});

// Run every hour
setInterval(async () => {
  try {
    const lowStockProducts = await monitor.checkLowStock();
    console.log(`Found ${lowStockProducts.length} low stock products`);
  } catch (error) {
    console.error('Low stock check failed:', error);
  }
}, 60 * 60 * 1000);

Multi-Location Inventory

Handle inventory across multiple locations:

class MultiLocationInventory {
  constructor(apiKey) {
    this.api = new QuickbutikAPI(apiKey);
    this.locations = {
      'warehouse-1': { name: 'Main Warehouse', priority: 1 },
      'warehouse-2': { name: 'Secondary Warehouse', priority: 2 },
      'store-front': { name: 'Physical Store', priority: 3 }
    };
  }

  async getInventoryByLocation(sku) {
    try {
      const products = await this.api.getProducts({ 
        product_id: sku,
        include_details: true 
      });

      if (!products || products.length === 0) {
        return null;
      }

      const product = products[0];
      const inventory = {};

      // If product has variants, aggregate by location
      if (product.variants && product.variants.length > 0) {
        for (const variant of product.variants) {
          const location = variant.qty_location || 'default';
          const quantity = parseInt(variant.qty || 0);
          
          inventory[location] = (inventory[location] || 0) + quantity;
        }
      } else {
        const location = product.qty_location || 'default';
        inventory[location] = parseInt(product.qty || 0);
      }

      return {
        sku: product.sku,
        title: product.title,
        total_quantity: Object.values(inventory).reduce((sum, qty) => sum + qty, 0),
        locations: inventory
      };

    } catch (error) {
      console.error(`Failed to get inventory for ${sku}:`, error);
      throw error;
    }
  }

  async transferStock(sku, fromLocation, toLocation, quantity) {
    try {
      // Get current inventory
      const inventory = await this.getInventoryByLocation(sku);
      
      if (!inventory || !inventory.locations[fromLocation]) {
        throw new Error(`No inventory found for ${sku} at ${fromLocation}`);
      }

      if (inventory.locations[fromLocation] < quantity) {
        throw new Error(`Insufficient stock at ${fromLocation}. Available: ${inventory.locations[fromLocation]}, Requested: ${quantity}`);
      }

      // Update source location (decrease)
      await this.updateLocationStock(sku, fromLocation, inventory.locations[fromLocation] - quantity);

      // Update destination location (increase)
      const currentDestStock = inventory.locations[toLocation] || 0;
      await this.updateLocationStock(sku, toLocation, currentDestStock + quantity);

      console.log(`Transferred ${quantity} units of ${sku} from ${fromLocation} to ${toLocation}`);

      return {
        sku,
        quantity,
        from: fromLocation,
        to: toLocation,
        timestamp: new Date().toISOString()
      };

    } catch (error) {
      console.error(`Failed to transfer stock for ${sku}:`, error);
      throw error;
    }
  }

  async updateLocationStock(sku, location, newQuantity) {
    return this.api.updateProducts({
      sku,
      stock: newQuantity,
      qty_location: location
    });
  }

  async getOptimalFulfillmentLocation(sku, requestedQuantity) {
    const inventory = await this.getInventoryByLocation(sku);
    
    if (!inventory) {
      return null;
    }

    // Sort locations by priority and availability
    const availableLocations = Object.entries(inventory.locations)
      .filter(([location, quantity]) => quantity >= requestedQuantity)
      .map(([location, quantity]) => ({
        location,
        quantity,
        priority: this.locations[location]?.priority || 999
      }))
      .sort((a, b) => a.priority - b.priority);

    return availableLocations.length > 0 ? availableLocations[0] : null;
  }
}

// Usage
const multiLocation = new MultiLocationInventory(process.env.QUICKBUTIK_API_KEY);

// Get inventory across all locations
const inventory = await multiLocation.getInventoryByLocation('SHIRT-123');
console.log('Inventory:', inventory);

// Transfer stock between locations
await multiLocation.transferStock('SHIRT-123', 'warehouse-1', 'store-front', 5);

// Find optimal fulfillment location
const optimal = await multiLocation.getOptimalFulfillmentLocation('SHIRT-123', 10);
console.log('Optimal location:', optimal);

Preventing Overselling

Implement safeguards to prevent overselling:

class OversellProtection {
  constructor(apiKey) {
    this.api = new QuickbutikAPI(apiKey);
    this.safetyBuffer = 1; // Keep 1 unit as safety buffer
    this.checkInterval = 5 * 60 * 1000; // Check every 5 minutes
  }

  async enableOversellProtection() {
    // Start monitoring
    setInterval(() => {
      this.checkAndProtectInventory();
    }, this.checkInterval);

    console.log('Oversell protection enabled');
  }

  async checkAndProtectInventory() {
    try {
      const products = await this.api.getProducts({ 
        include_details: true,
        limit: 500
      });

      const protectionActions = [];

      for (const product of products) {
        // Skip if minus quantity is already disabled
        if (product.disable_minusqty === '1') {
          continue;
        }

        const currentStock = parseInt(product.qty || 0);
        
        if (currentStock <= this.safetyBuffer) {
          protectionActions.push({
            sku: product.sku,
            title: product.title,
            currentStock,
            action: 'disable_minus_qty'
          });

          await this.protectProduct(product.sku);
        }
      }

      if (protectionActions.length > 0) {
        await this.notifyProtectionActions(protectionActions);
      }

    } catch (error) {
      console.error('Failed to check oversell protection:', error);
    }
  }

  async protectProduct(sku) {
    try {
      await this.api.updateProducts({
        sku,
        disable_minusqty: '1'
      });

      console.log(`Enabled oversell protection for ${sku}`);
    } catch (error) {
      console.error(`Failed to protect product ${sku}:`, error);
    }
  }

  async unprotectProduct(sku) {
    try {
      await this.api.updateProducts({
        sku,
        disable_minusqty: '0'
      });

      console.log(`Disabled oversell protection for ${sku}`);
    } catch (error) {
      console.error(`Failed to unprotect product ${sku}:`, error);
    }
  }

  async notifyProtectionActions(actions) {
    const message = `🛡️ Oversell Protection Activated!\n\n${actions.map(action => 
      `${action.title} (${action.sku}): ${action.currentStock} units remaining - Protection enabled`
    ).join('\n')}`;

    // Send notification
    if (process.env.SLACK_WEBHOOK_URL) {
      await fetch(process.env.SLACK_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: message })
      });
    }
  }

  async manualStockCheck(sku) {
    try {
      const products = await this.api.getProducts({ 
        product_id: sku,
        include_details: true 
      });

      if (!products || products.length === 0) {
        throw new Error(`Product ${sku} not found`);
      }

      const product = products[0];
      const currentStock = parseInt(product.qty || 0);
      const isProtected = product.disable_minusqty === '1';

      return {
        sku: product.sku,
        title: product.title,
        currentStock,
        isProtected,
        recommendedAction: this.getRecommendedAction(currentStock, isProtected)
      };

    } catch (error) {
      console.error(`Failed manual stock check for ${sku}:`, error);
      throw error;
    }
  }

  getRecommendedAction(currentStock, isProtected) {
    if (currentStock <= this.safetyBuffer && !isProtected) {
      return 'ENABLE_PROTECTION';
    } else if (currentStock > this.safetyBuffer && isProtected) {
      return 'DISABLE_PROTECTION';
    } else {
      return 'NO_ACTION_NEEDED';
    }
  }
}

// Usage
const protection = new OversellProtection(process.env.QUICKBUTIK_API_KEY);

// Enable automatic protection
await protection.enableOversellProtection();

// Manual check for specific product
const status = await protection.manualStockCheck('SHIRT-123');
console.log('Stock status:', status);

if (status.recommendedAction === 'ENABLE_PROTECTION') {
  await protection.protectProduct(status.sku);
} else if (status.recommendedAction === 'DISABLE_PROTECTION') {
  await protection.unprotectProduct(status.sku);
}

🎯 Best Practices

Batch Processing

Process inventory updates in batches to avoid rate limiting and improve performance.

Error Recovery

Implement retry logic for failed inventory updates with exponential backoff.

Data Validation

Validate inventory data before updates to prevent incorrect stock levels.

Monitoring

Monitor inventory sync health with metrics and alerts for critical failures.

Next Steps

Product Catalog Sync

Learn how to sync complete product catalogs between systems

Getting Started

Guides

Settings

Webhooks

Settings

Scripts

Orders

Products

Categories

Payment Methods

Shipping Methods

Metadata

Quick Example

Webhook-Based Inventory Sync

Low Stock Monitoring

Multi-Location Inventory

Preventing Overselling

🎯 Best Practices

Batch Processing

Error Recovery

Data Validation

Monitoring

Next Steps

Product Catalog Sync

​Quick Example

​Webhook-Based Inventory Sync

​Low Stock Monitoring

​Multi-Location Inventory

​Preventing Overselling

​🎯 Best Practices

Batch Processing

Error Recovery

Data Validation

Monitoring

​Next Steps

Product Catalog Sync

Quick Example

Webhook-Based Inventory Sync

Low Stock Monitoring

Multi-Location Inventory

Preventing Overselling

🎯 Best Practices

Next Steps