# Product Variants

In <code class="expression">space.vars.productName</code>, a "variant" is a NetSuite **matrix item** — an item with several orderable versions distinguished by dimensions like Color and Size. Variants are created and maintained entirely in NetSuite. The Client Admin controls two things: whether variants are included in a given catalog, and how they're labeled and displayed in the portal.

## When you'd use this

* Setting up a catalog that includes apparel, paint, or any product with size/colour/material variants.
* Adjusting how variant selectors render (horizontal swatches vs dropdown).
* Troubleshooting why variants aren't showing up correctly in a portal.

## Before you start

* The matrix item records exist in NetSuite, with the variant custom fields (e.g. `custitem59` for Color, `custitem60` for Size) populated.
* You know which NetSuite custom field holds each variant dimension's value.

## The two settings that drive variants

Both live on the Edit Catalog page (Catalogs → click a catalog row).

### 1. Enable Matrix Items toggle

In the **Settings** section, check **Enable Matrix Items**. When enabled:

* Matrix items and their variants are included in the catalog output.
* A standard set of matrix-related NetSuite fields (parent item, variant template, matrix type) is auto-added to the **NetSuite Fields** section. These fields show a **Matrix Field** badge and can't be removed manually while *Enable Matrix Items* is on.

When disabled, matrix items are skipped entirely.

### 2. Attributes section

Each row in **Attributes** maps one variant dimension. Without Attributes, variants are included in the data but the portal has nothing to render selectors with.

| Column             | What you set                                                              |
| ------------------ | ------------------------------------------------------------------------- |
| **Label**          | Display name shown to portal users — *Color*, *Size*, *Material*.         |
| **NetSuite Field** | The `custitem` field that holds the dimension's value on the item record. |
| **Direction**      | How the selector renders (table below).                                   |

| Direction      | What it looks like                                                        |
| -------------- | ------------------------------------------------------------------------- |
| **Horizontal** | Row of buttons or swatches. Common for Color.                             |
| **Vertical**   | Stacked list.                                                             |
| **Dropdown**   | Single-select dropdown. Common for Size.                                  |
| **None**       | The dimension data is included in the output but no selector is rendered. |

The trash icon on a row removes that attribute.

## The full setup

{% stepper %}
{% step %}

### Confirm matrix items exist in NetSuite

The matrix item records and their variant custom fields should already be set up by your NetSuite Admin. Without that, there's nothing for the catalog to surface.
{% endstep %}

{% step %}

### Open the catalog

Go to **Catalogs** in the sidebar and click the catalog you want to edit. The Edit Catalog page opens.
{% endstep %}

{% step %}

### Turn on Enable Matrix Items

In the **Settings** card, check **Enable Matrix Items**.
{% endstep %}

{% step %}

### Add an Attribute row per dimension

Scroll to **Attributes**. Click **Add Attribute** for each dimension your matrix items use. Set the Label, pick the NetSuite Field, and choose the Direction.
{% endstep %}

{% step %}

### Save & Update

Click **Save & Update** in the top-right. The rebuild runs in the background; once the catalog status flips back to *Completed* in the list, the change is live in the portal.
{% endstep %}
{% endstepper %}

## What success looks like

* The catalog rebuilds without errors.
* A matrix item in a portal page shows the configured selectors (e.g. a Color swatch row and a Size dropdown).
* Switching options on the selectors updates the displayed item.

## Where variants appear in Page Builder

Once the catalog has Enable Matrix Items and Attributes configured, the following blocks in the Page Builder can render variant data:

| Page Builder block                                 | How it uses variants                                                                                                        |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Product Variations** *(in the Product category)* | Renders the variant selectors (swatches, dropdowns, stacked list) directly on a product detail card or page                 |
| **Catalog Display** — *matrix* view mode           | Shows a compact inline variant matrix for scanning across many items at once — used by experienced cashiers for quick entry |
| **Order Lines** — add-to-cart                      | When a user selects a variant on a product card, the chosen variant's SKU is what gets added to the order                   |

If Product Variations shows no selectors at runtime, the most common cause is that the Attribute rows aren't configured in the catalog (the data exists but there's nothing to render selectors with).

## Common issues

* **Variants render in the data but no selectors appear** — confirm there's an **Attribute** row for each dimension. Just enabling *Enable Matrix Items* isn't enough.
* **A selector shows the wrong values** — check the NetSuite Field column on that Attribute row. It must point at the same `custitem` field where the dimension's values live on the item record.
* **A dimension isn't surfacing at all** — confirm the field has values populated on the matrix item records in NetSuite. Empty values = nothing to show.
* **A new attribute doesn't appear after saving** — the catalog needs to rebuild. Click **Save & Update** (not just **Save**), or trigger **Reprocess** from the catalog list.
* **Matrix item rows disappear after toggling Enable Matrix Items off and back on** — the auto-managed Matrix fields in NetSuite Fields are restored on the next save. Save and reload the page if they don't reappear immediately.

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Creating a Catalog</strong></td><td>The full Edit Catalog reference, including the Settings and Attributes sections.</td><td><a href="/pages/sqKV6Gm0WqBRQeT9aFbs">/pages/sqKV6Gm0WqBRQeT9aFbs</a></td></tr><tr><td><strong>Categories &#x26; Attributes</strong></td><td>The relationship between categories, attributes, and variants.</td><td><a href="/pages/Lhd78fJQEK4v1phG1c1F">/pages/Lhd78fJQEK4v1phG1c1F</a></td></tr><tr><td><strong>Best Practices</strong></td><td>Tips for keeping attributes accurate as your catalog grows.</td><td><a href="/pages/NA4teeZGxH7G061cy5fd">/pages/NA4teeZGxH7G061cy5fd</a></td></tr></tbody></table>


---

# 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://docs.in8sync.com/client-admin-guide/creating-catalogs/product-variants.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.