Inventory Rules and Bundle Availability

BundlesIQ derives bundle availability from component stock levels, ensuring bundles show as out of stock when any required component runs out. This guide explains how inventory works and how to configure it.

What You Will Accomplish

After reading this guide, you will understand how BundlesIQ calculates bundle availability, how inventory sync works, and what to expect in common scenarios.

When to Use This Guide

You are setting up a new bundle and want to understand inventory behavior
A bundle is showing as out of stock and you need to understand why
You want to decide whether to enable or disable inventory sync

How Bundle Availability Is Calculated

BundlesIQ uses the least available component formula:

bundle_availability = min(component_available / qty_per_bundle)

For each component, BundlesIQ divides the available inventory by the quantity needed per bundle, then takes the minimum across all components. This ensures you cannot sell more bundles than your lowest-stock component allows.

Example:

Bundle: "Starter Kit" (contains 3 items)
  Item A: 100 available, 2 per bundle → 100 / 2 = 50
  Item B:  30 available, 1 per bundle →  30 / 1 = 30
  Item C: 200 available, 5 per bundle → 200 / 5 = 40

Bundle availability = min(50, 30, 40) = 30 bundles

In this example, Item B is the bottleneck — you can only sell 30 bundles before Item B runs out.

Inventory Sync

When inventory sync (sync_bundle_inventory: true) is enabled, BundlesIQ automatically updates the ghost SKU's inventory level in Shopify to match the calculated bundle availability.

Inventory sync is only applicable if you are tracking inventory on the bundle product itself. If the ghost SKU has inventory tracking disabled, Shopify treats it as always in stock and inventory sync has no effect.

How It Works

Shopify fires an inventory_levels/update webhook when any product's inventory changes
BundlesIQ checks whether the updated variant is a component of any active bundles (using the component bundle index)
For each affected bundle, BundlesIQ recalculates availability using the least-available-component formula
BundlesIQ updates the ghost SKU's inventory level in Shopify to match the new availability

Enabling or Disabling Inventory Sync

Store-level default:

Navigate to BundlesIQ > Settings
Toggle Sync bundle inventory (sync_bundle_inventory) on or off
Click Save

Per-bundle override:

Open a bundle in BundlesIQ > Bundles
Toggle Sync inventory on or off
Click Save

When to Enable Inventory Sync

You want bundles to automatically show as out of stock when components run low
You rely on Shopify's "Continue selling when out of stock" setting to control availability
You want your storefront to reflect accurate bundle availability without manual updates

When to Disable Inventory Sync

You manage bundle availability manually in Shopify
Your ghost SKU has inventory tracking disabled (Shopify treats it as always in stock)
You have a separate system that manages ghost SKU inventory

Retail Sync

Retail sync (sync_bundle_retail: true) automatically updates bundle pricing when component prices change. Behavior varies based on pricing mode:

Pricing Mode	Retail Sync Enabled	Retail Sync Disabled
Component-Led	Bundle price recalculates automatically as the sum of (component retail × qty × discount)	Orders are flagged with a warning if component prices change. Manual review required
Bundle-Led	Bundles are flagged for review when component prices change (the bundle price itself does not auto-update, since it is fixed)	No action taken when component prices change

Enabling or Disabling Retail Sync

Store-level default:

Navigate to BundlesIQ > Settings
Toggle Sync bundle retail (sync_bundle_retail) on or off
Click Save

Per-bundle override:

Open a bundle in BundlesIQ > Bundles
Toggle Sync retail on or off
Click Save

Retail sync is recommended for most stores. In component-led mode, it keeps your bundle price accurate. In bundle-led mode, it alerts you when the discount math may have shifted.

Ghost SKU Inventory Tracking

For inventory sync to work correctly, the ghost SKU product variant should have one of these configurations:

Configuration	Behavior
Inventory tracked, managed by BundlesIQ (recommended)	BundlesIQ sets the available quantity based on components. Shopify enforces out-of-stock rules
Inventory not tracked	The bundle is always shown as in stock on the storefront. BundlesIQ still processes orders but does not control availability

We recommend enabling inventory tracking on the ghost SKU and letting BundlesIQ manage the quantity. This ensures customers cannot purchase bundles when components are out of stock.

What Happens When a Component Hits Zero

When any component's available inventory drops to zero:

BundlesIQ recalculates the bundle availability as 0
If inventory sync is enabled, BundlesIQ sets the ghost SKU's inventory to 0
If the ghost SKU has "Continue selling when out of stock" disabled (recommended), the bundle product shows as Out of stock on your storefront
If "Continue selling when out of stock" is enabled, customers can still purchase the bundle, but the order may not be fulfillable

Shopify's "Continue Selling When Out of Stock" Setting

This Shopify setting on the ghost SKU variant controls what happens when inventory reaches zero:

Setting	Effect
Disabled (recommended)	Bundle cannot be purchased when inventory is 0. Prevents overselling
Enabled	Bundle can still be purchased at 0 inventory. Useful for pre-orders or made-to-order scenarios, but risks overselling components

Set this on the ghost SKU variant in Shopify Admin under Products > [Bundle Product] > Inventory.

Inventory After an Order

Hybrid, Reporting, and Operational Modes

When a customer purchases a bundle:

Component inventory is decremented by Shopify as part of its normal order fulfillment flow (because BundlesIQ adds component line items to the order)
Bundle inventory is recalculated by BundlesIQ when the component inventory webhook fires, reflecting the reduced component stock

This means inventory stays consistent — selling a bundle reduces both the component stock and the derived bundle availability.

Parent-Only (BOM) Mode

In Parent-Only mode, BundlesIQ does not add component line items to the order, so Shopify's normal fulfillment flow does not decrement component stock. Instead, BundlesIQ manages component inventory through Shopify's inventory state API:

Event	Inventory Action
Order created or paid (depending on `reserve_timing`)	Component stock moves from `available` to `reserved`
Order fulfilled	`reserved` stock is consumed (decremented)
Order cancelled	`reserved` stock is released back to `available`
Return/restock	Stock is restocked to `available`

The inventory lifecycle:

Order placed → Component: 100 available, 2 reserved
Order fulfilled → Component: 100 available, 0 reserved (2 consumed)
-- OR --
Order cancelled → Component: 102 available, 0 reserved (2 released)

This approach ensures component stock is tracked accurately without modifying the order itself. The ghost SKU's inventory sync still works the same way — bundle availability is recalculated based on component available quantities.

In Parent-Only mode, reserved quantities reduce the effective available stock. A component with 100 available and 10 reserved has 90 units effectively available for new orders. BundlesIQ factors this into bundle availability calculations.

Shared Components Across Bundles

If the same component variant appears in multiple bundles, all bundles that share that component are affected when its inventory changes.