Inventory Management

Track stock levels, handle overselling, and manage inventory across your products. Inventory is managed through the Products API.

Key Concepts

Stock Tracking — Optional per-product inventory tracking
Low Stock Alerts — Configurable thresholds via webhooks
Auto-Deduction — Stock decrements on order creation

Inventory Fields

Products have the following inventory-related fields:

Field	Type	Default	Description
stock	integer	0	Current stock quantity
trackStock	boolean	false	Enable inventory tracking
lowStockThreshold	integer	null	Trigger alerts when stock falls below
sku	string	null	Stock Keeping Unit identifier
barcode	string	null	UPC/EAN barcode

Enable Stock Tracking

Set trackStock: true to enable inventory management:

curl -X POST "https://api.barecommercecore.com/stores/{storeId}/products" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Limited Edition Sneakers",
    "slug": "limited-edition-sneakers",
    "price": "199.99",
    "status": "published",
    "sku": "SNK-LE-001",
    "stock": 50,
    "trackStock": true,
    "lowStockThreshold": 10
  }'

ℹ️ Digital Products: Leave trackStock: false for digital products that don't need inventory limits.

Update Stock Levels

Update stock by setting an absolute value:

curl -X PUT "https://api.barecommercecore.com/stores/{storeId}/products/prod_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stock": 75 }'

Increment/Decrement Pattern

async function adjustStock(productId, adjustment) {
  // 1. Get current stock
  const { item: product } = await fetch(
    `/stores/${storeId}/products/${productId}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  ).then(r => r.json());
 
  // 2. Calculate new stock (never go below 0)
  const newStock = Math.max(0, product.stock + adjustment);
 
  // 3. Update
  await fetch(`/stores/${storeId}/products/${productId}`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ stock: newStock }),
  });
 
  return newStock;
}
 
// Add 20 units (restock)
await adjustStock('prod_abc123', 20);
 
// Remove 5 units (manual adjustment)
await adjustStock('prod_abc123', -5);

Automatic Stock Deduction

When an order is created, stock is automatically decremented for products with trackStock: true.

Order Flow

Order created via API
For each line item, stock is checked
If sufficient stock exists, it's decremented
product.updated webhook fires with new stock level

⚠️ Overselling: The API does not currently prevent overselling. Check stock availability in your checkout flow before creating orders.

Check Stock Before Checkout

Always verify stock availability before processing an order:

async function validateCartStock(cartItems) {
  const errors = [];
 
  for (const item of cartItems) {
    const { item: product } = await fetch(
      `/stores/${storeId}/products/${item.productId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    ).then(r => r.json());
 
    if (product.trackStock && product.stock < item.quantity) {
      errors.push({
        productId: item.productId,
        title: product.title,
        requested: item.quantity,
        available: product.stock,
      });
    }
  }
 
  return { valid: errors.length === 0, errors };
}

Low Stock Alerts

Use webhooks to receive notifications when stock falls below the threshold:

// Handle webhook in your app
app.post('/webhooks/inventory', (req, res) => {
  const { event, data: product } = req.body;
 
  if (event === 'product.updated' && product.trackStock) {
    if (product.lowStockThreshold && product.stock <= product.lowStockThreshold) {
      sendLowStockAlert({
        productId: product.id,
        title: product.title,
        sku: product.sku,
        currentStock: product.stock,
        threshold: product.lowStockThreshold,
      });
    }
 
    if (product.stock === 0) {
      sendOutOfStockAlert(product);
    }
  }
 
  res.status(200).send('OK');
});

Bulk Stock Updates

Update stock for multiple products (e.g., from warehouse sync):

async function bulkUpdateStock(stockUpdates) {
  const results = { success: [], failed: [] };
 
  for (const update of stockUpdates) {
    // Find by SKU
    const { items } = await fetch(
      `/stores/${storeId}/products?sku=${encodeURIComponent(update.sku)}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    ).then(r => r.json());
 
    if (items.length === 0) {
      results.failed.push({ sku: update.sku, error: 'Product not found' });
      continue;
    }
 
    // Update stock
    await fetch(`/stores/${storeId}/products/${items[0].id}`, {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ stock: update.stock }),
    });
 
    results.success.push({ sku: update.sku, productId: items[0].id });
  }
 
  return results;
}

Best Practices

Set meaningful SKUs — Use consistent formats for warehouse integration
Use webhooks for real-time alerts — Don't poll, subscribe to events
Check stock before checkout — Validate availability to prevent overselling
Set appropriate thresholds — Consider lead times for lowStockThreshold values

Related Guides

Products — Full products documentation
Webhooks — Subscribe to inventory events

Categories Media