# Set up Wick's product data

Chapter 7 of the Wick user guide.

Wick's scent notes, family glows, burn label and safety text read product and variant **metafields** in the `custom` namespace, the one Shopify admin uses when you create a definition. You don't need an app or any metaobjects. You only need the metafields for the features you use: a soap shop can skip the burn fields, a diffuser brand the strength meter. Every feature hides when its data is empty, and most blocks also have **fallback fields** you can fill instead (chapters 8 and 11), so nothing breaks while you fill them in.

## Step 1: create the product metafield definitions

In admin, go to **Settings › Custom data › Products** and click **Add definition** for each row you need:

1. Type the **Name** (yours to choose; it's what you see when you edit a product).
2. Check the **Namespace and key** under it and change it to exactly the key in the table. Shopify suggests `custom.` plus the name, so a name like "Scent family" gives `custom.scent_family`, but "Top" would give `custom.top`, which the theme won't find. Keys are case-sensitive.
3. Click **Select type** and choose the type in the table. For the three note fields, choose **Single line text** and then **List of values**; for everything else marked single line text, choose **One value**.
4. Add the validation in the table where there is one (for Scent family, turn on **Limit to preset choices** and add the eight families), then **Save**.

| Name | Namespace and key | Type | Validation | Example | Used by |
| --- | --- | --- | --- | --- | --- |
| Top notes | `custom.top_notes` | Single line text, **List of values** | | Fig leaf, Bergamot, Pink pepper | The Scent notes label, the notes line on cards, the gift box items (chapter 8) |
| Heart notes | `custom.heart_notes` | Single line text, List of values | | Green fig, Cedar, Jasmine | As above |
| Base notes | `custom.base_notes` | Single line text, List of values | | Amber, Vetiver, Musk | As above |
| Scent family | `custom.scent_family` | Single line text, one value | **Limit to preset choices**: Fresh, Floral, Fruity, Woody, Gourmand, Herbal, Citrus, Smoky | Woody | The family tag and dot, the glow in cards and the gallery, the scent chips and shop by scent links (chapter 9), compare |
| Scent strength | `custom.scent_strength` | Integer | Minimum 1, maximum 5 | 4 | The strength meter ("Strong, 4 of 5"), compare |
| Smells like | `custom.smells_like` | Single line text, one value | | a fig tree after a summer storm | "Smells like a fig tree after a summer storm." on the product page and the spotlight, and on cards with **Line under the title** set to Smells like |
| Burn time | `custom.burn_time` | Integer (hours) | Minimum 1 | 50 | The burn label's big row, "50 hours of burn time" (chapter 11), compare |
| Wax | `custom.wax` | Single line text, one value | | Soy and coconut blend | Burn label |
| Wick | `custom.wick` | Single line text, one value | | Cotton, lead-free | Burn label |
| Vessel | `custom.vessel` | Single line text, one value | | Amber glass, reusable | Burn label |
| Net weight | `custom.net_weight` | Weight | | 220 g | Burn label (it prints with its unit) |
| Dimensions | `custom.dimensions` | Single line text, one value | | 8 × 9 cm | Burn label |
| Safety and allergens | `custom.safety_info` | Rich text | | Your CLP or IFRA statement and allergen list | Care and safety: "Safety and allergens" (chapter 11) |

These are optional, for the features named:

| Name | Namespace and key | Type | Example | Used by |
| --- | --- | --- | --- | --- |
| Care instructions | `custom.care_instructions` | Rich text | Soap care for one product | Care and safety: replaces the block's care text for that product (chapter 11) |
| Subtitle | `custom.subtitle` | Single line text | Hand-poured soy candle in amber glass | The **Product metadata** block set to Subtitle (falls back to the product type) |
| Card detail line | `custom.card_meta` | Single line text | Soy candle · 220 g | The card's detail line, with Theme settings › Product cards › **Detail line** set to Metafield |

The **Lather** preset's burn label ("In the bar") reads three more. Create them if you use that preset's rows:

| Name | Namespace and key | Type | Example | Row |
| --- | --- | --- | --- | --- |
| Cure time | `custom.cure_time` | Integer (weeks) | 6 | Cure time, the big row: "6 weeks" |
| Oils | `custom.oils` | Single line text (one value, or a list) | Olive, coconut and shea | Oils |
| Essential oils | `custom.essential_oils` | Single line text (one value, or a list) | Lavender and rosemary | Scented with |

A burn label row can read any metafield you create, so you can add your own rows the same way, such as `custom.melt_pool` or `custom.diffuser_life` (chapter 11).

How the theme reads what you type:

* **Notes**: a list field holds one note per entry. A single line text with the notes separated by commas also works. The product page prints them with dots between them, the first note as you wrote it and the rest in lower case ("Fig leaf · bergamot · pink pepper"), so write the first note with a capital and don't rely on capitals in the others.
* **Scent family** is read without regard to capitals ("Woody", "woody"), but the scent filter and the shop by scent links match the value exactly as stored, so keep to the eight preset choices. A family outside the eight still prints, as written, but glows in candlelight and gets no family color.
* **Scent strength** shows only for a whole number from 1 to 5. Its words ("Whisper, Soft, Medium, Strong, Room-filling") come from the Scent notes block.
* **Smells like** is written to follow the words "Smells like", in lower case ("a fig tree after a summer storm"). The theme adds a full stop unless you end with `.`, `!` or `?`.
* **Burn time** and **Cure time** are plain numbers; the unit comes from the burn label row ("hours", "weeks").

## Step 2: variant metafields (optional)

Some facts belong to one variant: a candle sold in three sizes has three weights and burn times, and a soap sold in two scents has two sets of notes. Go to **Settings › Custom data › Variants** and add any of these, with the same namespace, key and type as the product's:

| Namespace and key | What the variant's value does |
| --- | --- |
| `custom.top_notes`, `custom.heart_notes`, `custom.base_notes`, `custom.scent_family`, `custom.scent_strength`, `custom.smells_like` | Wins over the product's on the product page (Scent notes updates as the shopper picks), on cards and in the gallery glow. A candle whose sizes all smell the same needs only the product's. |
| `custom.net_weight` (Weight), `custom.burn_time` (Integer) | The detail line on the variant picker's option tiles: "220 g · 50 hours". Compare and the burn label also prefer the variant's value. |

Any burn label row reads the selected variant's metafield of the same key first and the product's when the variant has none, and the label follows the shopper's pick. Fill the product's value too, for the variants that have none of their own.

Fill a variant's metafields in admin by opening the product, clicking the variant, and scrolling to **Metafields**.

## Step 3: fill them in

Open a product in admin and scroll to **Metafields**: every definition you created is listed there. To fill many products at once, use **Bulk edit** from the products list and add the metafield columns.

## What shows without the data

| Missing | What happens |
| --- | --- |
| Notes, family, strength and smells like | No Scent notes label for shoppers, unless the block's fallback fields are filled (chapter 8); no notes line on cards; the theme editor shows a sample tagged "Sample" |
| Scent family | No family tag; cards and the gallery glow in candlelight (with **Glow behind products** set to Scent family color); the product can't be found by the scent filter |
| Scent strength | No strength meter |
| Burn label fields | Each row without a value is hidden, unless the row has a fallback **Value** (chapter 11); with no rows at all, the burn label hides |
| Safety and allergens | The block's **Safety text** shows instead; with neither (and no warning line), the safety row is left out |
| Care instructions | The block's **Care text** shows, under the block's **Care heading** |
| Subtitle | The product type shows |