# 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.

<pre><code>&#x3C;script>
  window.vuInventoryLevels = {
    "Red Finish": 12,
<strong>    "Blue Finish": 0,
</strong><strong>    "Premium Handle": 3,
</strong>    "Extended Warranty Tab": 0
   }
 &#x3C;/script>   
</code></pre>

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`.

<pre><code>[ 
 {
  "id": "42298194591939",
   "title": "Sea Spray",
   "available": "true"
   }, 
<strong> {
</strong>   "id": "51721197060468",
   "title": "Corsair",
   "available": "true"
   },
 {
   "id": "43735750705347",
   "title": "Tofu",
   "available": "false"
   },
 {
   "id": "51721197158772",
   "title": "Shadow Lime",
   "available": "true"
   }
]
</code></pre>

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()`&#x20;

To hide/show certain items, set an array `element.hideItems([...codes])` / `element.showItems([...codes])`&#x20;

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.&#x20;

**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.&#x20;

**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&#x20;

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&#x20;
  * Customizer tab/element/item `codes`

### Considerations&#x20;

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vu-custom.gitbook.io/vu-custom/vu-os-best-practices-platform-guides/out-of-stock-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.