> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockful.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Reference

> Complete reference for all Stockful storefront metafields

Stockful writes 11 metafields to Shopify - 7 at the variant level and 4 at the product level. All metafields have `public_read` storefront access and are available in Liquid, the Storefront API, and the `window.stockful` JavaScript API.

## Namespace

All metafields use the namespace `app--326028230657--stockful`.

## Variant metafields

These are written to each `ProductVariant` and reflect per-variant inventory data.

### stock\_status

Current stock status for this variant.

| Property             | Value                                          |
| -------------------- | ---------------------------------------------- |
| **Key**              | `stock_status`                                 |
| **Type**             | `single_line_text_field`                       |
| **Possible values**  | `in_stock`, `low_stock`, `out_of_stock`        |
| **Update frequency** | Real-time (within seconds of inventory change) |

<Tip>
  Internally, Stockful also tracks an "overstock" status for merchant analytics - but on the storefront this is normalized to `in_stock` since customers don't need to know a product is overstocked.
</Tip>

```liquid theme={null}
{% assign status = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.stock_status.value %}

{% if status == "low_stock" %}
  <span class="badge badge--warning">Low Stock</span>
{% elsif status == "out_of_stock" %}
  <span class="badge badge--danger">Out of Stock</span>
{% endif %}
```

### days\_of\_supply

Estimated number of days until this variant runs out of stock, based on current sell-through velocity.

| Property             | Value                                    |
| -------------------- | ---------------------------------------- |
| **Key**              | `days_of_supply`                         |
| **Type**             | `number_integer`                         |
| **Range**            | `0` to `999+` (null if velocity is zero) |
| **Update frequency** | Daily                                    |

```liquid theme={null}
{% assign days = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.days_of_supply.value %}

{% if days and days <= 7 %}
  <span>Only {{ days }} days left!</span>
{% endif %}
```

### velocity\_trend

Sales velocity classification based on ABC analysis and sell-through rate.

| Property             | Value                            |
| -------------------- | -------------------------------- |
| **Key**              | `velocity_trend`                 |
| **Type**             | `single_line_text_field`         |
| **Possible values**  | `selling_fast`, `steady`, `slow` |
| **Update frequency** | Daily                            |

* **selling\_fast** - ABC class A (top 80% of revenue) with positive velocity
* **steady** - ABC class B (next 15% of revenue) with positive velocity
* **slow** - ABC class C (bottom 5%) or no measurable velocity

```liquid theme={null}
{% assign trend = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.velocity_trend.value %}

{% if trend == "selling_fast" %}
  <span class="badge badge--purple">Selling Fast</span>
{% endif %}
```

### projected\_stockout

The estimated date when this variant will be out of stock, in ISO 8601 format.

| Property             | Value                                     |
| -------------------- | ----------------------------------------- |
| **Key**              | `projected_stockout`                      |
| **Type**             | `single_line_text_field`                  |
| **Format**           | ISO 8601 date (e.g. `2026-05-15`) or null |
| **Update frequency** | Daily                                     |

```liquid theme={null}
{% assign stockout = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.projected_stockout.value %}

{% if stockout %}
  <span>Expected to sell out by {{ stockout | date: "%B %d" }}</span>
{% endif %}
```

### abc\_class

Revenue-based classification of this variant using ABC analysis.

| Property             | Value                    |
| -------------------- | ------------------------ |
| **Key**              | `abc_class`              |
| **Type**             | `single_line_text_field` |
| **Possible values**  | `A`, `B`, `C`            |
| **Update frequency** | Daily                    |

* **A** - Top 80% of revenue (your best sellers)
* **B** - Next 15% of revenue
* **C** - Bottom 5% of revenue

```liquid theme={null}
{% assign abc = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.abc_class.value %}

{% if abc == "A" %}
  <span class="badge badge--gold">Best Seller</span>
{% endif %}
```

### restock\_status

Whether new stock is expected for this variant.

| Property             | Value                       |
| -------------------- | --------------------------- |
| **Key**              | `restock_status`            |
| **Type**             | `single_line_text_field`    |
| **Possible values**  | `pending`, `needed`, `none` |
| **Update frequency** | Daily                       |

* **pending** - Incoming stock has been recorded (purchase order or transfer in transit)
* **needed** - Stock is at or below reorder point and no incoming stock is recorded
* **none** - No restock action required

```liquid theme={null}
{% assign restock = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.restock_status.value %}

{% if restock == "pending" %}
  <span>Restock on the way</span>
{% elsif restock == "needed" and stock_status == "out_of_stock" %}
  <span>Back in stock soon</span>
{% endif %}
```

### sold\_last\_30d

Total units sold for this variant across all locations in the past 30 days.

| Property             | Value            |
| -------------------- | ---------------- |
| **Key**              | `sold_last_30d`  |
| **Type**             | `number_integer` |
| **Range**            | `0+`             |
| **Update frequency** | Daily            |

```liquid theme={null}
{% assign sold = product.selected_or_first_available_variant.metafields.app--326028230657--stockful.sold_last_30d.value %}

{% if sold and sold > 50 %}
  <span>{{ sold }} sold in the last 30 days</span>
{% endif %}
```

## Product metafields

These are written to the `Product` and aggregate data across all variants.

### stock\_status (product)

The worst stock status across all variants of this product.

| Property             | Value                                   |
| -------------------- | --------------------------------------- |
| **Key**              | `stock_status`                          |
| **Type**             | `single_line_text_field`                |
| **Possible values**  | `in_stock`, `low_stock`, `out_of_stock` |
| **Update frequency** | Real-time                               |

The "worst" status means: if any variant is `out_of_stock`, the product is `out_of_stock`. If any variant is `low_stock` (and none are out), the product is `low_stock`.

```liquid theme={null}
{% assign status = product.metafields.app--326028230657--stockful.stock_status.value %}

{% if status == "out_of_stock" %}
  <div class="product-card__badge">Out of Stock</div>
{% elsif status == "low_stock" %}
  <div class="product-card__badge">Low Stock</div>
{% endif %}
```

### low\_stock\_variant\_count

Number of variants that are `low_stock` or `out_of_stock`.

| Property             | Value                     |
| -------------------- | ------------------------- |
| **Key**              | `low_stock_variant_count` |
| **Type**             | `number_integer`          |
| **Range**            | `0+`                      |
| **Update frequency** | Real-time                 |

```liquid theme={null}
{% assign low = product.metafields.app--326028230657--stockful.low_stock_variant_count.value %}

{% if low and low > 0 %}
  <span>{{ low }} {{ low | pluralize: 'variant', 'variants' }} running low</span>
{% endif %}
```

### velocity\_trend (product)

The dominant velocity trend across all variants, weighted by ABC classification (A-class variants carry more weight).

| Property             | Value                            |
| -------------------- | -------------------------------- |
| **Key**              | `velocity_trend`                 |
| **Type**             | `single_line_text_field`         |
| **Possible values**  | `selling_fast`, `steady`, `slow` |
| **Update frequency** | Daily                            |

```liquid theme={null}
{% assign trend = product.metafields.app--326028230657--stockful.velocity_trend.value %}

{% if trend == "selling_fast" %}
  <div class="product-card__badge product-card__badge--trending">Trending</div>
{% endif %}
```

### total\_sold\_30d

Sum of units sold across all variants in the past 30 days.

| Property             | Value            |
| -------------------- | ---------------- |
| **Key**              | `total_sold_30d` |
| **Type**             | `number_integer` |
| **Range**            | `0+`             |
| **Update frequency** | Daily            |

```liquid theme={null}
{% assign total = product.metafields.app--326028230657--stockful.total_sold_30d.value %}

{% if total and total > 100 %}
  <span>{{ total }}+ sold recently</span>
{% endif %}
```