Out Of Stock Handling

As customers navigate through the customization journey, it is important to keep them up to date with the selections available for them to select from.

Inventory is handled external to the Customizer, however the Customizer can be informed of inventory levels and correspondingly show or hide options. This can be achieved in a few different ways. The below outlines how to piece together inventory driven logic alongside the VU Customizer.

OOS handling is achieved by pairing:

1. Shopify inventory data (source of truth)

2. A public inventory variable on the product page

3. Customizer visibility functions

When an item’s stock reaches a defined low or zero threshold, the customizer can react immediately by hiding or disabling the corresponding content.

Exposing Shopify Stock Levels

Why a Public Variable Is Required:

The VU Customizer runs in the browser and does not call Shopify APIs directly. To make inventory data available, stock levels must be embedded into the product page as a public JavaScript variable.

This variable serves as a lookup table, mapping Shopify inventory quantities or availability states to the codes (unique naming) used inside the customizer (elements, tabs, or list items). The Variable can be structure in a few different ways, below are a couple examples:

Example A: Name → Stock Level Mapping

This is the most common approach when working directly with numeric inventory thresholds.

<script>
  window.vuInventoryLevels = {
    "Red Finish": 12,
    "Blue Finish": 0,
    "Premium Handle": 3,
    "Extended Warranty Tab": 0
   }
 </script>   

In this example:

• Red Finish is in stock

• Blue Finish is out of stock

• Premium Handle is low stock

• Extended Warranty Tab is fully out of stock

Example B: Variant Availability Array

In some storefronts, inventory is represented as a list of variants with availability flags (often sourced directly from Shopify Liquid). This structure can still be used for OOS handling, as long as it is transformed or mapped to customizer codes.

[ 
 {
  "id": "42298194591939",
   "title": "Sea Spray",
   "available": "true"
   }, 
 {
   "id": "51721197060468",
   "title": "Corsair",
   "available": "true"
   },
 {
   "id": "43735750705347",
   "title": "Tofu",
   "available": "false"
   },
 {
   "id": "51721197158772",
   "title": "Shadow Lime",
   "available": "true"
   }
]

A common pattern is to convert this array into a lookup object that the customizer can easily consume:

const availabilityMap = {};

variants.forEach(variant => {
  availabilityMap[variant.title] = variant.available ===
 "true"; 
  });

Once mapped, these values can be treated the same way as numeric stock levels (e.g., hide when false).

Defining Stock Thresholds

You are free to define what qualifies as:

• In stock

• Low stock

• Out of stock

A common approach:

const LOW_STOCK_THRESHOLD = 5;

This allows you to treat items differently depending on business requirements (e.g., hide only at 0, or hide when ≤ 5).

Connecting Inventory to the Customizer

Reading Inventory Values

Inside your customizer logic, read inventory values from the public variable:

function getInventory(name) {
return window.vuInventoryLevels?.[name] ?? null;
}

Applying Visibility Rules

Use the built‐in VU Customizer visibility functions to react to inventory changes:

To hide/show all element.hideAllItems() / element.showAllItems()

To hide/show certain items, set an array element.hideItems([...codes]) / element.showItems([...codes])

VU's customizer has core CSS classes available, such as customizer-hidden. Using one of the above hide/show methods will invoke the CSS class within the display.

Example: Hide an Element When OOS

const stock = getInventory("Blue Finish");

if (stock === 0) { 
        element.hideItems("Finish");
}

In this example, if an option is out of the stock, the entire element will be hidden.

Example: Hide a Tab at Low Stock

const stock = getInventory("Extended Warranty Tab");

if (stock <= LOW_STOCK_THRESHOLD) {
  tab.hide("Extended Warranty Tab");
}

In this example if an option is below the stock threshold, the entire tab will be hidden. Please note that tabs can contain multiple elements, and options are configured at an element level.

Example: Hide List Items Dynamically

["Red Finish", "Blue Finish", "Green Finish"].forEach(item => {
  const stock = getInventory(item);

if (stock === 0) {
  element.hideItems([codes)];
 }
});

Naming Conventions

To ensure reliable OOS behavior:

• Inventory keys or titles must exactly match the codes used in the customizer

• Avoid dynamically generated or translated labels for inventory‐controlled content

• Use a single naming system across:

  • Shopify products/variants

  • Inventory data objects

  • Customizer tab/element/item codes

Considerations

1. Inventory variable not loaded before the customizer initializes

2. Mismatched naming between Shopify and the customizer

3. Treating null / undefined inventory values as 0

4. Always validate that inventory data exists before applying OOS logic.