# Set up Hooray's metafields

Chapter 7 of the Hooray user guide.

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

* **Product metafields** in the `custom` namespace (the one Shopify admin uses when you create a definition): occasions, the number on a number balloon, pack sizes, lead times and the card note.
* **Theme settings** in **Theme settings › Event date and delivery**, and the sections' and blocks' own settings: your occasion tiles, ages, garland colours, party themes and zones.
* **Product option names and values**, for garland lengths (chapter 9), and **collections**, for occasions, number balloons and party themes.

Hooray 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 Hooray reads

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

| Namespace and key | Type in admin | Example | What reads it |
| --- | --- | --- | --- |
| `custom.occasions` | **Single line text**, **List of values** (`list.single_line_text_field`) | Birthday, Baby shower | The occasion chips on cards and the product page, and the **Occasion** filter that the occasion tiles and chips link to (chapter 8) |
| `custom.number` | **Integer**, **One value** (`number_integer`) | 30 | The **Number** filter that the Turning picker links to (chapter 8) |
| `custom.pack_size` | **Integer**, **One value** (`number_integer`), 1 or more | 12 | Party in a box: how many come in one pack (chapter 11) |
| `custom.lead_days` | **Integer**, **One value** (`number_integer`), 0 to 30 | 3 | The cart's first event date: the days you need to get this product ready (chapter 10) |
| `custom.card_note` | **Single line text**, **One value** (`single_line_text_field`) | Air-filled, lasts weeks | The note line under the name on product cards, in place of the vendor (chapter 2) |

Two more metafields are filled in by review apps, not by you: `reviews.rating` and `reviews.rating_count` give the star rating under the product title. A **Kit contents row** block can show any other product metafield you create (chapter 6).

## How to fill them in

* **Occasions** are the words shoppers filter by, so spell each one exactly the same way on every product, and the same way as the **Name** of its occasion tile: the tile "Baby shower" finds products whose `custom.occasions` includes "Baby shower", not "Baby Shower" or "Babyshower". Put the most important occasion first: cards show only the first two.
* **Number** is the age or number a product is for: 30 for a "30" balloon pair, 18 for 18th birthday candles, 1 for a first-birthday banner. It holds one number per product, so a single product sold with ten digit variants (0 to 9) can only be found by one age. The Turning picker finds best when each age you sell has its own products: a pair of foil numbers sold as "Number 30 balloons", candles, banners and toppers, each with its number (chapter 8).
* **Pack size** is a whole number of 1 or more. Plates in packs of 12 get 12. A product sold singly, such as a cake topper you want one of per box, gets the number of guests one covers, or leave it out of the party theme.
* **Lead days** is in calendar days. 0 means it can go the same day (before the cutoff). The cart takes the slowest product in it, so one garland kit with 3 pushes the whole order's first date out by three days. A product without the metafield takes the theme's **Lead time** (2 days by default).
* **Card note** is one short line. If you write more than one line, cards show the first.

## 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**: Occasions, Number, Pack size, Lead time (days) or Card note.
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 "Pack size" gives `custom.pack_size`, but "Lead time (days)" would give something like `custom.lead_time_days`, which the theme won't find. Change it to `custom.lead_days`.
3. Click **Select type** and choose the type in the table. For **Occasions**, change **One value** to **List of values**.
4. For the integers, add a minimum and maximum under the validations, if your admin offers them, so a wrong number can't be saved: Number 0 to 120, Pack size 1 or more, Lead days 0 to 30.
5. **Save**.

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

`custom.occasions` should really be a list. A single line of text separated by commas still shows as chips, but the Occasion filter then treats the whole line as one value, so the tiles and chips can't find the product. `custom.number` and `custom.pack_size` must be **Integer**, not Decimal.

## Step 2: fill them in

Open a product in admin and scroll to **Metafields**. 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.

## Step 3: set up the filters

Install Shopify's free **Search & Discovery** app and add **Occasion** (from `custom.occasions`) and **Number** (from `custom.number`) as filters. The occasion tiles, the occasion chips and the Turning picker's ages all link to those filters. Chapter 14 has the steps.

## Step 4: check

* Open a collection: cards should show up to two occasion chips and the card note.
* Click an occasion chip on a product page: you should land on a collection with that occasion's filter ticked, showing only products with that occasion. If you see everything, the filter isn't set up yet, or the spelling differs.
* Click a number balloon in the Turning picker: you should see only products with that number.
* Put a product with `custom.lead_days` in the cart: the event date panel should say "Your order needs 3 days, so the first date is…".
* On your party box section, the maths line should say "24 guests ÷ 12 a pack = 2 packs".

If a value doesn't show, check the namespace and key first, then the type.