Coffee data — Roast docs

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.