# Set up Sprinkle's metafields

Chapter 7 of the Sprinkle user guide.

Sprinkle'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): a product's lead time, dietary claims, allergens, ingredients and storage, and each size's servings.
* **Theme settings** in **Theme settings › Order ahead**, **Cake builder** and **Allergens and dietary** (chapter 2).
* **Product tags** for the cake builder, pre-orders and two seals.

Sprinkle 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. The one exception to think about is `custom.allergens`: a product without it shows your fallback line, not a blank (chapter 11).

In Shopify admin, metafield definitions live under **Settings › Custom data** (called **Metafields and metaobjects** in newer versions of the admin).

## The metafields Sprinkle reads

| Name (yours to choose) | Namespace and key | Owner | Type | Example | What it does |
| --- | --- | --- | --- | --- | --- |
| Lead days | `custom.lead_days` | Product | **Integer**, **One value** | 3 | The days of notice this product needs: the card's lead line, the Lead time note, and the first date in the bag (chapter 8). 0 means it needs no notice. |
| Servings | `custom.servings` | **Variant** | **Single line text**, **One value** | Serves 10–12 | Beside the price, on the variant's option card, in the cake builder's Size step and in Compare |
| Dietary | `custom.dietary` | Product | **Single line text**, **List of values** | Gluten free, Vegan | The chips on cards and on the product page, the dietary filter (chapter 13) and Compare |
| Allergens | `custom.allergens` | Product | **Single line text**, **List of values** | wheat, egg, milk | The statement "Contains: wheat, egg, milk." in the Allergens and dietary panel, and Compare |
| Ingredients | `custom.ingredients` | Product | **Multi-line text** | Flour, butter, brown sugar… | The **Ingredients** row in the panel. Rich text works too. |
| Storage | `custom.storage` | Product | **Multi-line text** | Keeps for 5 days in a sealed tin. | The **Storage and shelf life** row in the panel. Rich text works too. |
| Back note | `custom.back_note` | Product | **Single line text**, **One value** | Back Saturday | On a sold-out or pre-order card, in place of the lead line. "Back Saturday" or "Baking from 14 Nov". |

Two more metafields are filled in by review apps, not by you: `reviews.rating` and `reviews.rating_count` give the rating under the product title. And a **Spec row** block (chapter 6) can show any other product metafield you create in the Spec table, such as `custom.box_contents`.

## The product tags Sprinkle reads

Capitals don't matter in any of these.

| Tag | What it does |
| --- | --- |
| `custom-cake` | Turns the product into a cake builder product: the Cake builder block shows, the card reads **Start your cake**, quick view links to the product page, and Buy it now is hidden (chapter 9). This is the default: change the tag itself in **Theme settings › Cake builder › Cake builder tag**. |
| `mix-box` | Sells the product only through the Mix-and-match box: no variant picker or buy buttons on its page, **Choose flavours** on its card, and quick view links to its page (chapter 10). This is the default: change the tag itself in **Theme settings › Mix-and-match box › Mix box tag**. |
| `pre-order` | Cards and seals only: a **Pre-order** seal on the card and pill on the product page, **Pre-order** on the card's button, and `custom.back_note` in place of the lead line. It changes nothing on the product page's button, the bag or the order (chapter 6). `preorder` works too. |
| `new` | A **New** seal |
| `best-seller` | A **Best seller** seal |

A card shows one seal, so Sold out, Pre-order, Save and Only 3 left come before New and Best seller (chapter 2).

## Step 1: create the product metafield definitions

In admin, go to **Settings › Custom data › Products** and click **Add definition** for each metafield 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 above. Shopify suggests `custom.` plus the name, so "Dietary" gives `custom.dietary`, but "Lead time" would give `custom.lead_time` and "Allergen list" would give `custom.allergen_list`, which the theme won't find. Keys are case-sensitive.
3. Click **Select type** and choose the type in the table:
   * **Lead days**: **Integer**, **One value**. Under Validations you can set a minimum of 0.
   * **Dietary** and **Allergens**: **Single line text**, then **List of values** (not One value), so a product can hold several and the dietary filter can offer each one on its own. For **Dietary**, turn on **Limit to preset choices** and add your labels (Gluten free, Vegan, Nut free, Egg free, Dairy free, Halal). Choices keep every product spelled the same, which the filter relies on.
   * **Ingredients** and **Storage**: **Multi-line text**.
   * **Back note**: **Single line text**, **One value**.
4. **Save**.

## Step 2: create the variant metafield definition

Each size of a cake serves a different number, so servings live on the variant. Go to **Settings › Custom data › Variants** and click **Add definition**:

1. **Name**: Servings. Key: `custom.servings`. Type: **Single line text**, **One value**.
2. **Save**.

This is a variant metafield: a definition under **Products** with the same key won't be read.

## Step 3: fill in your products

Open a product in admin and scroll to **Metafields**: every product definition you created is listed there. For servings, click the variant and scroll to its **Metafields**.

* **Lead days**: a whole number of calendar days. Leave it empty to use **Default lead time**. Set 0 for something on the shelf every day: the card then reads "No need to order ahead".
* **Servings**: as shoppers should read it. Sprinkle prints it exactly as you type it, so write "Serves 10–12", not "10–12".
* **Dietary**: one value per claim. Spell them as they are in **Theme settings › Allergens and dietary › Dietary labels** so they sort in your order. Only claim what's true of the whole product.
* **Allergens**: one value per allergen, in the words you want shoppers to read: "wheat", "egg", "milk", "tree nuts". They print in the order you enter them, joined with commas, so "wheat, egg, milk". Don't add "Contains" or a full stop: Sprinkle does that.
* **Ingredients** and **Storage**: plain text. Line breaks are kept.
* **Back note**: a short line. It shows only on a card that's sold out or tagged `pre-order`, so you can leave it there between batches.

To fill many products at once, use **Bulk edit** from the products list and add the metafield columns. Add tags in the product's **Tags** field.

> **Note:** If you created **Dietary** or **Allergens** as **One value** by mistake, Sprinkle still splits a value like "Gluten free, Vegan" at its commas for the chips and the statement. Search & Discovery doesn't: it would offer "Gluten free, Vegan" as one filter value. Change the definition to **List of values** before you set up the filter.

## What shows without the data

| Missing | What happens |
| --- | --- |
| `custom.lead_days` | The product uses **Default lead time** on its card, in its note and in the bag |
| `custom.servings` | No servings beside the price. The option shows as pills, or in the cake builder as cards with the name and price only. |
| `custom.dietary` | No chips on the card or the product page |
| `custom.allergens` | The panel shows your **When no allergens are listed** line, never a blank. A flavour's row in the Mix-and-match box shows no Contains line. |
| `custom.ingredients` | No Ingredients row |
| `custom.storage` | No Storage and shelf life row |
| `custom.back_note` | A sold-out card has no line under the price. A pre-order card shows its normal lead line. |
| All of the above | The product still sells. Its allergens panel shows the fallback line and the kitchen statement. |

In the theme editor, features with no data show a sample so you can see the design: two dietary chips from your labels, sample Ingredients and Storage rows tagged **Sample**, the cake builder on an untagged product and the mix box before it has a product. Shoppers never see them. The allergen statement never shows a sample, so what you see in the editor is what shoppers will read.