# Coffee data

Chapter 7 of the Roast user guide.

Roast's coffee features read data you keep in Shopify: **product metafields** in the `custom` namespace, one **metaobject definition** (`producer`), one collection metafield and three product tags. None of it is required. Every card, line and stamp shows only the parts that have data, so a product with no coffee data still looks finished. In the theme editor, a section or block with no data shows sample values under a dashed note saying which metafields it needs; shoppers never see the samples.

## Step 1: create the product metafield definitions

In Shopify admin go to **Settings › Custom data › Products › Add definition**. For each row, type the namespace and key exactly as shown (for example `custom.tasting_notes` in the "Namespace and key" field), choose the type, add the validation where one is given, and save. Then fill the values on each product, in the **Metafields** card at the bottom of the product page in admin.

| Namespace and key | Type | Validation | Read by |
| --- | --- | --- | --- |
| `custom.origin` | Single line text | | Card origin line, product origin line, search suggestions, filters |
| `custom.region` | Single line text | | Product origin line, Origin card in Cupping notes |
| `custom.process` | Single line text | Preset choices: Washed, Natural, Honey, Anaerobic and so on | Card origin line, product origin line, Origin card, search suggestions, filters |
| `custom.variety` | Single line text | | Origin card |
| `custom.altitude` | Single line text | | Origin card ("2,100 m") |
| `custom.harvest` | Single line text | | Origin card ("December 2025") |
| `custom.tasting_notes` | Single line text, **list of values** | | Card notes, buy box notes line, search suggestions, filters (as chips) |
| `custom.flavour_profile` | Decimal, **list of values** | Minimum 0, maximum 5 | The flavour profile radar |
| `custom.roast_level` | Integer | Minimum 1, maximum 5 | Card roast dots, buy box roast line, roast meter, filters |
| `custom.brew_methods` | Single line text, **list of values** | Preset choices, see below | Buy box roast line, "Best for" chips, How to brew it |
| `custom.recommended_grind` | Integer | Minimum 1, maximum 7 | Roast and brew card, How to brew it |
| `custom.roast_date` | Date | | Freshness stamps and the Freshness block |
| `custom.lot` | Single line text | | Product image stamp, Flavour profile card, Freshness block |
| `custom.producer` | Metaobject reference (Producer) | | Origin card's Producer row, Producer chip, Image with text |
| `custom.label_color` | Color | | The product's own card label color |
| `custom.size` | Single line text | | The size beside the card price ("250 g") |
| `custom.restock_note` | Single line text | | Line on a sold-out card ("Next lot lands in December") |

What each value looks like:

* `custom.tasting_notes`: one note per value, in the order you want them read: Peach, Jasmine, Raw honey. Cards and the buy box join them as "Peach, jasmine and raw honey".
* `custom.flavour_profile`: exactly five numbers from 0 to 5, such as 4, 4.5, 2, 1, 3.5. They follow the order of **Theme settings › Tasting and roast › Flavour profile axes** (Sweetness, Acidity, Body, Bitterness, Finish by default). The profile is all or nothing: with fewer than five values the radar is not drawn. Extra values are ignored and values outside 0 to 5 are clamped.
* `custom.roast_level`: 1 is the lightest, 5 the darkest. The names come from **Roast level names** (Light, Medium-light, Medium, Medium-dark, Dark), followed by the **Roast scale word** ("Light roast").
* `custom.brew_methods`: the brewers it suits, such as Pour over, AeroPress, Cold brew. Roast draws a pictogram for Pour over (or Filter, V60, Chemex), AeroPress, Plunger (or French press), Espresso, Stovetop (or Moka pot), Cold brew, Teapot, Gaiwan and Hot chocolate. Other names show without one. The buy box names the first two; the Roast and brew card shows up to three chips.
* `custom.recommended_grind`: 1 is extra fine and 7 extra coarse, named by **Grind names** and **Grind comparisons** ("Medium-fine, like fine sea salt").
* `custom.roast_date`: the day this lot was roasted. See chapter 8 for how long a "Roasted 20 Oct" stamp stays up and what a date in the future does.
* `custom.label_color`: used only when the palette's text reads on it at 4.5:1 or better, or white text does (the label then switches to white). A color that fails both is ignored and the card keeps its palette label color, so a pale yellow or a mid grey can't make a card unreadable.

> **Tip:** For values you filter on (process, origin, tasting notes, brew methods), use the **Limit to preset choices** validation, so every product spells them the same way. Filters group values by their exact spelling.

## Step 2: create the Producer metaobject

Go to **Settings › Custom data › Metaobjects › Add definition**. Name it **Producer**; its type must be exactly `producer`. Add these fields (the key is what the theme reads, so match it exactly):

| Field key | Type | Shown as |
| --- | --- | --- |
| `name` | Single line text | The producer's name. Set it as the definition's display name. |
| `farm` | Single line text | Joined to the name in Image with text: "Aregash Bekele, Hambela Estate" |
| `region` | Single line text | Image with text facts, with the country |
| `country` | Single line text | Image with text facts |
| `altitude` | Single line text | Image with text facts |
| `varieties` | Single line text | Image with text facts |
| `process` | Single line text | Image with text facts |
| `image` | File (images) | The round photo on the Producer chip and the Image with text photo |
| `quote` | Multi-line text | The pull quote in Image with text |
| `story` | Rich text | Optional. Your own long story; the theme links to `story_url` rather than printing it |
| `since` | Single line text | The stamp in Image with text, such as 2019 ("Buying since 2019") |
| `story_url` | URL | Where "Read the full story" goes, such as a blog article about the farm |

Under **Access**, turn on **Storefronts**: without it the theme can't read the entries. If you turn on the **Active/draft status** feature, only Active entries show. Then add entries in **Content › Metaobjects › Producer**, and on each coffee pick its producer in the `custom.producer` metafield.

Where producers show:

* The **Producer** card in Cupping notes: photo, name and a link to `story_url`.
* The **Producer** row of the Origin spec table, which prints the producer's name. A spec row can print any other field too: set its **Product metafield** to `custom.producer.farm`, for example.
* **Image with text** with **Content** set to **A producer**: on a product page it uses the product's own producer, anywhere else the one you pick in **Producer**. The metaobject's fields fill the image, heading, quote, facts, stamp and link; the section's own settings fill any gaps.

## Step 3: optional collection color

Collection tiles cycle through the four palette label colors. To give a collection its own, add a **collection** metafield definition (**Settings › Custom data › Collections**) `custom.label_color` of type **Color**. The same readability rule as product labels applies.

## Step 4: product tags

| Tag | What it does |
| --- | --- |
| `roast-to-order` | The product is roasted after it's ordered. It gets the "Roasting 23 Oct" stamp with the next roast date, and the Freshness block's "Roasted to order. Next roast Thursday 23 October" sentence (chapter 8). |
| `new` | Shows the "New" badge on its card whatever its age. With a **Batch word** set, the badge reads "New roast" (or "New batch", "New bake"). |
| `limited` | Shows a "Limited" badge on its card. |

A card shows at most two badges, in this order: Pre-order, Sale, New, Limited. A sold-out card shows only "Sold out".

## What shows without the data

| Feature | Needs | Without it |
| --- | --- | --- |
| Card origin line | `custom.origin` or `custom.process` | Shows the vendor; nothing when that's empty too |
| Card tasting notes | `custom.tasting_notes` | Hidden |
| Card roast dots | `custom.roast_level` | Hidden |
| Origin line (product page) | `custom.region`, `custom.origin`, `custom.process` or a product type | Hidden |
| Tasting notes block | Notes, roast level or brew methods | Each line hides; with none of the three the block hides |
| Flavour profile card | Five `custom.flavour_profile` values | Hidden |
| Roast and brew card | Roast level, brew methods or recommended grind | Hidden (its Rest note alone doesn't show it) |
| Origin card | At least one row with a value | Rows without a value hide; with none, the card hides |
| Producer card | `custom.producer` | Hidden |
| Cupping notes section | Any of its cards | Hidden entirely |
| How to brew it | Brew methods, a grind, or a link | Hidden |
| Freshness block and stamps | A roast date, or the `roast-to-order` tag and the roast schedule | Hidden (chapter 8) |

## Not selling coffee?

Every word the coffee features print comes from **Theme settings › Tasting and roast** and **Roast schedule**. A tea shop can rename the flavour axes to Floral, Grassy, Sweet, Astringency, Finish; a chocolate maker can rename the roast levels; a bakery can set the **Batch word** to "bake" and the stamp words to "Baked" and "Baking". The Pantry and Café presets already do this (chapter 1). The metafield keys stay the same.