# Set up Dose's metafields

Chapter 7 of the Dose user guide.

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

* **Metafields** in the `custom` namespace (the one Shopify admin uses when you create a definition): ten on products, one optional on variants, and an optional tagline.
* **Theme settings** in **Theme settings › Goals** and **Subscriptions**, and the blocks' own settings: your goal names, plan lengths and container words, the facts panel's heading and disclaimer.
* **Delivery plans** from your subscription app (chapter 10), and two **product tags** for badges: `new` and `badge:` (chapter 2).

Dose 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 › Custom data** (called **Metafields and metaobjects** in newer versions of the admin).

## The metafields Dose reads

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

| Namespace and key | Owner | Type in admin | Example | What reads it |
| --- | --- | --- | --- | --- |
| `custom.supplement_facts` | Product | **Multi-line text** (`multi_line_text_field`) | `Serving size \| 2 gummies` first, then one nutrient per line: `Vitamin D3 \| 25 mcg \| 125%` | The facts panel (chapter 8). Its first line also gives the serving size to the supply calculator, the serving chip and the card's count. |
| `custom.servings` | Product | **Integer** (`number_integer`) | 30 | Servings per container: the facts panel, the supply calculator, the serving chip, compare |
| `custom.daily_servings` | Product | **Integer** | 1 | Servings a day, the calculator's starting choice (the shopper can change it). Without it, 1. |
| `custom.other_ingredients` | Product | **Single line text** (`single_line_text_field`) | Water, tapioca syrup, apple pectin, citric acid | The facts panel's "Other ingredients" line |
| `custom.allergens` | Product | **Single line text** | None. Made in a facility that also handles tree nuts. | The facts panel's "Allergens" line |
| `custom.goals` | Product | **Single line text**, **List of values** (`list.single_line_text_field`) | Sleep, Calm | The goal finder's ranking, goal tags, the card's colour, the goal chips and the **Goal** filter (chapters 9 and 14) |
| `custom.format` | Product | **Single line text** | Gummy | The goal finder's format question, the format tag and chip, compare, the **Format** filter |
| `custom.key_ingredients` | Product | **Multi-line text** | `Magnesium glycinate \| 200 mg \| The form we chose for evenings` (one per line) | Ingredient cards (chapter 11) and the card's meta line |
| `custom.certifications` | Product | **Single line text**, **List of values** | Third-party tested, Vegan, Gluten free, Non-GMO | Certification chips (chapter 11) and the **Certification** filter |
| `custom.lab_report` | Product | **File** (`file_reference`) **or** **URL** (`url`): one of the two | A PDF in Files, or `https://…/lab-report.pdf` | The "View lab results (PDF)" button (chapter 11) |
| `custom.servings` | **Variant** (optional) | **Integer** | 60 | Servings in this variant, for sizes such as 30, 60 and 90 counts. Wins over the product's for the supply calculator and the serving chip. |
| `custom.tagline` | Product (optional) | **Single line text** | Two before bed, as part of your evening routine. | The short description under the title, in place of the description's first paragraph (chapter 6) |

A **Specification row** block can show any other product metafield you create (chapter 6). Review apps write `reviews.rating` and `reviews.rating_count`, which give the title its stars.

## How to fill them in

**Supplement facts** (`custom.supplement_facts`): copy your label, one row per line, cells separated by `|`: first `Serving size | 2 gummies` (the number first, because the supply calculator counts with it), then `Name | amount | % daily value` for each nutrient. Chapter 8 has the full format, with sub-headings, indented rows, footnotes and an example.

**Servings** (`custom.servings`): the number of servings in the container, as on the label: `30` for a bottle of 60 gummies at 2 gummies a serving. Not the number of pieces.

**Daily servings** (`custom.daily_servings`): how many servings the label directs a day, usually `1`. The calculator starts there; shoppers can choose more.

**Other ingredients** and **Allergens**: one line each, as printed on your label.

**Goals** (`custom.goals`): the goals the product belongs to, one per value, spelt exactly as in **Goal names** (Theme settings › Goals): `Sleep`, `Calm`. Capitals don't matter to the theme, but the Goal filter lists different spellings separately, so pick one. The first goal that's in **Goal names** gives the product its colour. A goal that isn't a tile, such as "Calm" in the Dose preset, still counts in the quiz's routine question (chapter 9). Make it a list: a single line "Sleep, Calm" reads as one goal that matches nothing.

**Format** (`custom.format`): one word for the form: `Gummy`, `Capsule`, `Softgel`, `Powder`, `Liquid` or `Tablet`. The goal finder's format question matches it, ignoring a plural ("Gummies" = "Gummy"). The icon also knows `Stick`, `Scoop`, `Drop`, `Tincture` and `Chew`; other words show a dot.

**Key ingredients** (`custom.key_ingredients`): one ingredient per line, `Name | amount | note`. The note says where it comes from or why you chose it, not what it does for the body (chapter 12). A line with only a name shows the name. The first two names also form the card's meta line.

```
Magnesium glycinate | 200 mg | The form we chose for evenings
L-theanine | 100 mg | Found naturally in green tea leaves
Chamomile flower extract | 50 mg | Grown and dried in Egypt
```

**Certifications** (`custom.certifications`): short phrases, one per value, such as `Third-party tested`, `Vegan`, `Gluten free`, `Non-GMO`. Each becomes a chip with a simple icon. Add only what you can show proof for.

**Lab report** (`custom.lab_report`): a link to your current certificate of analysis or lab report. A metafield definition holds one type, so choose the one that suits you:

* **File**: upload the PDF in **Content › Files** (or straight from the product page) and pick it on each product. The theme links to the file.
* **URL**: paste a link, such as a PDF on your own site or your lab's portal. The theme links to the address.

The theme reads either. A link ending in `.pdf` gets the button "View lab results (PDF)"; any other link drops "(PDF)".

**Variant servings** (`custom.servings` on variants): only for products sold in several counts. On each variant, the servings in that size: `30`, `60`, `90`.

## Step 1: create the definitions

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

1. Type the **Name**: Supplement facts, Servings, Daily servings, Other ingredients, Allergens, Goals, Format, Key ingredients, Certifications or Lab report.
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 "Supplement facts" gives `custom.supplement_facts`, but a name like "Servings per container" would give `custom.servings_per_container`, which the theme won't find. Change it to `custom.servings`.
3. Click **Select type** and choose the type in the table: **Multi-line text** for supplement facts and key ingredients; **Integer** for servings and daily servings; **Single line text** for other ingredients, allergens, goals, format and certifications; **File** or **URL** for the lab report. For **Goals** and **Certifications**, change **One value** to **List of values**.
4. For **Servings** and **Daily servings**, add a minimum of 1 under the validations, if your admin offers it, so a wrong number can't be saved.
5. **Save**.

For sizes in several counts, go to **Settings › Custom data › Variants** and add **Servings** there too: key `custom.servings`, type **Integer**, **One value**.

If Search & Discovery later doesn't offer **Goals**, **Format** or **Certifications** as a filter source, open the definition again and check its access and filter options: the wording depends on your admin version.

## Step 2: fill them in

Open a product in admin and scroll to **Metafields**. For variant servings, click each variant in the product's **Variants** list and fill it in on the variant's page. To fill in many at once, select your products, use **Bulk edit** and add the metafield columns there. Metafields can also go through a product CSV, once they're defined.

The multi-line fields keep line breaks: press Enter between lines.

## Step 3: set up the filters

Install Shopify's free **Search & Discovery** app and add **Goal** (from `custom.goals`), **Format** (from `custom.format`) and **Certification** (from `custom.certifications`) as filters. The goal tiles and goal chips link to the Goal filter. Chapter 14 has the steps, and what they link to without it.

## Step 4: check

* Open a product with all the metafields: the facts panel should show "Serving size 2 gummies", "Servings per container 30" and your rows; the card in a collection should sit on its goal colour with "2 a day · 30 days".
* With a delivery plan of 30 days on the product, open **Subscribe and save**: it should say "This bottle lasts 30 days. Delivery set to match." with "Deliver every 30 days" chosen.
* Beside the facts, the ingredient cards, chips, the format chip and the lab report button should show; the button should open your report in a new tab.
* On the home page, take the quiz with a goal your products have: the stack should list them with "Matches sleep · night · gummy".

If a value doesn't show, check the namespace and key first, then the owner (product or variant), then the type, and whether it's a list.