# Set up Decant's metafields

Chapter 7 of the Decant user guide.

Decant's features read three kinds of data, none of which needs an app:

* **Product and variant metafields** in the `custom` namespace (the one Shopify admin uses when you create a definition): notes, accords, longevity and the rest.
* **Theme settings** in **Theme settings › Size and concentration** and **Discovery set**, and the sections' own settings.
* **Product option names and values**, for sizes and concentrations (chapter 8), and **product tags** for sets and badges.

Decant doesn't use metaobjects, so there is nothing to set up under Content › Metaobjects. You only need the data for the features you use, and nothing breaks while you fill it in: each part of a feature shows only when it has data.

In Shopify admin, metafield definitions live under **Settings › Metafields and metaobjects** (called **Custom data** in older versions of the admin, and in a few of the theme editor's hints).

## The metafields Decant reads

Keys are exact and case-sensitive. The name is yours to choose: it's what you see when you edit a product.

**Product metafields:**

| Namespace and key | Type in admin | Example | What reads it |
| --- | --- | --- | --- |
| `custom.top_notes` | **Single line text**, **List of values** (`list.single_line_text_field`) | Bergamot, Fig leaf | Scent profile. The first entry goes on cards, in the set builder and in the finder's results. |
| `custom.heart_notes` | The same | Green fig, Orris | The same |
| `custom.base_notes` | The same | Smoked vetiver, Cedar | The same |
| `custom.accords` | The same | `Woody:80`, `Green:60` | Scent profile bars, and the finder |
| `custom.longevity_hours` | **Decimal**, **One value** (`number_decimal`) | 8 | Scent profile, compare table |
| `custom.sillage` | **Integer**, **One value** (`number_integer`), from 1 to 4 | 2 | Scent profile, the finder, compare table |
| `custom.seasons` | **Single line text**, **List of values** | Spring, Summer | Scent profile, the finder |
| `custom.time_of_day` | **Single line text**, **List of values** | Day, Night | Scent profile |
| `custom.layer_with` | **Product**, **List of values** (`list.product_reference`) | Two of your scents | Scent profile's Layer it with |
| `custom.family` | **Single line text**, **One value** (`single_line_text_field`) | Woody | The finder, the family strip on cards, the dip colour on strips and bottles, compare table, the Family filter |
| `custom.concentration_label` | **Single line text**, **One value** | Eau de parfum | Optional. The line above the title and on cards, in place of the product type, and the compare table. |
| `custom.notes_short` | **Single line text**, **One value** | Fig, iris and smoked vetiver | Optional. The product page's Notes line, in place of the first sentence of the description. |

**Variant metafield:**

| Namespace and key | Type in admin | Example | What reads it |
| --- | --- | --- | --- |
| `custom.volume_ml` | **Decimal**, **One value** (`number_decimal`) | 10 | The price per ml when a variant has no Shopify unit price, and the bottle when a size value isn't in ml (chapter 8) |

Two more metafields are filled in by review apps, not by you: `reviews.rating` and `reviews.rating_count` give the rating in **Product metadata**. A **Spec row** block can show any other product metafield you create.

## How to fill them in

* **Sillage** is a number from 1 to 4: 1 Intimate, 2 Moderate, 3 Strong, 4 Enormous. Anything else doesn't show. Use the **Integer** type, not Decimal.
* **Longevity** is in hours. Above 12 the ruler is simply full. 0 or less doesn't show.
* **Accords** are written `Name:number`, with the number from 0 to 100, such as `Woody:80`. A `%` on the end is fine. An entry that doesn't fit that shape is skipped, so `Woody` alone, `:40` and `Woody:strong` never reach shoppers. They show in the order you enter them, so put the strongest first.
* **Seasons** that the finder understands are Spring, Summer, Autumn and Winter. Capitals don't matter, and Fall counts as Autumn. Other words still show on the Scent profile, but the finder can't match them.
* **Family** should be one word that matches a line in the finder's **Families** (chapter 11), and one of the five families or a word in **Family names** (chapter 2), so it gets a tint. Use the same spelling on every product.
* **Time of day** is free text: Day, Night, Evening, whatever suits you.
* **Top, heart and base notes** read best as short names. Put the most recognisable note first in each list, because cards show only the first of each.

## The product tags Decant reads

Capitals don't matter in any of these.

| Tag | What it does |
| --- | --- |
| `discovery-set` | Sells the product only through the Discovery set section: no variant picker or buy buttons on its page, a card link instead of quick add, and quick view links out too (chapter 9). This is the default: change the tag itself in **Theme settings › Discovery set › Discovery set tag**. |
| `new` | A **New** badge |
| `best-seller` | A **Best seller** badge. This is the default: change it in **Theme settings › Product cards › Best seller tag**. |

## Step 1: create the product metafield definitions

In admin, go to **Settings › Metafields and metaobjects › Products** and click **Add definition** for each metafield you need:

1. Type the **Name**.
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 "Top notes" gives `custom.top_notes`, but "Opening notes" would give `custom.opening_notes`, which the theme won't find.
3. Click **Select type** and choose the type in the table. For a list, change **One value** to **List of values**.
4. For `custom.sillage`, add a minimum of 1 and a maximum of 4 under the validations, if your admin offers them, so a wrong number can't be saved.
5. **Save**.

`custom.family` must be **Single line text** with **One value**: as a list, it won't work on cards or in the finder. And every list above must really be a list. A notes metafield made as one value shows on the Scent profile but not on cards.

## Step 2: create the variant metafield definition

Only if you'll use `custom.volume_ml`. Go to **Settings › Metafields and metaobjects › Variants**, click **Add definition**, name it Volume in ml, set the key to `custom.volume_ml`, choose **Decimal** with **One value**, and **Save**.

## Step 3: fill them in

Open a product in admin and scroll to **Metafields**. For a variant metafield, open the variant. To fill in many at once, select your products, use **Bulk edit** and add the metafield columns there. Product metafields can also go through a product CSV, once they're defined. **Variant metafields can't**, so fill in `custom.volume_ml` in the bulk editor.

## Step 4: check

Open a scent on your online store. You should see the notes on the Scent profile and, on its collection page, the notes line on the card. If a value doesn't show, check the namespace and key first, then the type. If the block shows nothing at all, none of its parts has data, or the product has no value for any part you've left on.

## Don't name other brands

Decant has **no field, block or setting for "inspired by", "dupe of", "smells like" or "similar to"**, and that's on purpose. Don't add those comparisons in your titles, descriptions, tags, metafields or anything else, and don't name other perfume houses. Using another brand's name to sell your own scent is a trademark risk, and it can get listings and shops taken down.

Describe your scents by their own notes, family and mood instead. That's what the Scent profile and the finder are for. If you decant other houses' perfumes, or you're unsure what you may say, take legal advice from someone qualified in your country before you publish.