# Set up Altar's metafields

Chapter 7 of the Altar user guide.

Altar'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 intentions, chakras, signs, element, how to use, care note and origin, and each piece's weight and size.
* **Theme settings** in **Theme settings › Crystals and rituals** (chapter 2): the finder collection and filter keys, the disclaimer, the piece option names and the moon view.
* **Section settings** for the intention cards, the zodiac wheel and the moon's phase groups, and **product tags** for three badges.

Altar doesn't use metaobjects, so there is nothing to set up under Content › Metaobjects. You only need the data for the features you use: every row of the properties panel hides when its metafield is empty, and a product with none shows no panel at all, so nothing breaks while you fill it in.

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

## The metafields Altar reads

| Name (yours to choose) | Namespace and key | Owner | Type | Choices | Example | What it does |
| --- | --- | --- | --- | --- | --- | --- |
| Intentions | `custom.intentions` | Product | **Single line text**, **List of values** | Free text. Good ones to start with: Calm, Protection, Love, Abundance, Clarity, Grounding, Intuition, Cleansing, Confidence, Joy, Sleep, Focus | Calm, Intuition, Sleep | The **Intentions** row of the properties panel, the chips under the price and on cards, and the **Intentions** filter behind the intention cards (chapter 9) |
| Chakras | `custom.chakras` | Product | **Single line text**, **List of values**, limited to choices | Root, Sacral, Solar plexus, Heart, Throat, Third eye, Crown | Heart, Throat | The **Chakras** row: each chakra's colored dot and its name, always in body order from Root to Crown, whatever order you enter them in |
| Zodiac signs | `custom.zodiac` | Product | **Single line text**, **List of values**, limited to choices | Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, Pisces | Pisces, Virgo | The **Zodiac** row (each sign's glyph and name, Aries to Pisces), and the **Zodiac** filter behind the zodiac wheel (chapter 9) |
| Element | `custom.element` | Product | **Single line text**, **One value**, limited to choices | Earth, Air, Fire, Water, Spirit | Water | The **Element** row: the element's glyph and name |
| How to use | `custom.how_to_use` | Product | **Rich text** | | A numbered list of three steps (below) | The **How to use** row, open, under the properties panel |
| Care note | `custom.care_note` | Product | **Single line text**, **One value** | | Not water safe. Cleanse with smoke, sound or moonlight instead. | The highlighted **care warning** at the foot of the panel (chapter 8) |
| Origin | `custom.origin` | Product | **Single line text**, **One value** | | Minas Gerais, Brazil | After the product type in the line above the title ("Crystals · Minas Gerais, Brazil"). Optional. |
| Piece weight | `custom.specimen_weight` | **Variant** | **Weight**, **One value** | | 142 g | The weight on the piece's photo card and on its bag line (chapter 11) |
| Piece size | `custom.specimen_size` | **Variant** | **Single line text**, **One value** | | 6.2 × 4.8 cm | The size on the piece's photo card (chapter 11) |

Two more metafields are filled in by review apps, not by you: `reviews.rating` and `reviews.rating_count` give the stars on cards and "4.9 · 86 reviews" 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.card_count` ("78 cards") for a tarot deck or `custom.burn_time` for a candle.

These product tags add badges (capitals don't matter):

| Tag | What it does |
| --- | --- |
| `new` | A **New** badge, whatever the product's age. Without the tag, products get it for **Theme settings › Product cards › Show New for products published in the last** days (30) after they're published. |
| `best-seller` | A **Best seller** badge on the product's card |
| `limited` | A **Limited** badge |

A card shows one badge, so Sold out, Save and One of a kind come before these (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 "Intentions" gives `custom.intentions`, but "Zodiac signs" would give `custom.zodiac_signs`, "Care note" is fine, and "How to use it" would give `custom.how_to_use_it`, which the theme won't find. Keys are case-sensitive.
3. Click **Select type** and choose the type in the table:
   * **Intentions**: **Single line text**, then **List of values** (not One value), so a stone can hold several intentions and the Intentions filter can offer each one on its own.
   * **Chakras** and **Zodiac signs**: **Single line text**, **List of values**. Turn on **Limit to preset choices** and add each choice from the table, spelled as it is there (the signs in English, with a capital letter: "Scorpio", not "scorpio" or "♏"). Choices keep every product spelled the same, which the zodiac wheel's links rely on.
   * **Element**: **Single line text**, **One value**, with **Limit to preset choices** and the five elements as choices.
   * **Care note** and **Origin**: **Single line text**, **One value**.
   * **How to use**: **Rich text**.
4. **Save**.

## Step 2: create the variant metafield definitions

One-of-a-kind stones are sold as one variant per stone (chapter 11), and each stone has its own weight and size. Go to **Settings › Custom data › Variants** and click **Add definition** twice:

1. **Piece weight**: key `custom.specimen_weight`, type **Weight** (under Measurement), **One value**. Altar prints it in the unit you entered, rounded to one decimal, with ".0" dropped and the unit shortened: 142 g, 1.2 kg, 4.5 oz, 1.1 lb.
2. **Piece size**: key `custom.specimen_size`, type **Single line text**, **One value**. Altar prints it exactly as you type it.

These are variant metafields: a definition under **Products** with the same key won't be read for the piece cards.

## Step 3: fill in your products

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

* **Intentions**: add one value per intention, in the order you want the chips: the first ones are the ones cards show. Write each the way shoppers should read it ("Calm", "Protection"), and use the same spelling on every product: "Calm" and "Calming" are two different filter values.
* **Chakras**, **Zodiac signs** and **Element**: pick from the choices. A stone can hold up to all seven chakras and all twelve signs, but two or three of each reads best.
* **Care note**: one or two short sentences. The first sentence is the warning and shows in bold; the rest is what to do instead: "Not water safe. Cleanse with smoke, sound or moonlight instead." or "Fades in strong sun. Keep it out of the window." Altar picks the icon from your words (chapter 8).
* **How to use**: use the rich text editor's **numbered list**, one step per item. For example:
  1. Hold the stone and set one intention, out loud or on paper.
  2. Keep it by your bed or where you rest.
  3. Recharge it on a windowsill at the full moon.
* **Origin**: where the stone comes from, as shoppers should read it: "Minas Gerais, Brazil".
* **Piece weight**: the number and the unit, such as 142 and g.
* **Piece size**: the stone's size as you want shoppers to read it. Write it with a multiplication sign and spaces, "6.2 × 4.8 cm", or with a spaced x, "6.2 x 4.8 cm"; screen readers then read "6.2 by 4.8 cm".

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

> **Note:** If you created **Intentions**, **Chakras** or **Zodiac signs** as **One value** by mistake, Altar still splits a value like "Calm, Love" at its commas for the panel and the chips. Search & Discovery doesn't: it would offer "Calm, Love" as one filter value. Change the definition to **List of values** before you set up the filters.

## What shows without the data

| Missing | What happens |
| --- | --- |
| All the crystal metafields | No properties panel and no How to use. The product page shows its gallery and the two collapsible rows. |
| One of them | That row is left out of the panel |
| `custom.intentions` | No chips under the price or on the product's card |
| `custom.care_note` | No care warning |
| `custom.how_to_use` | No How to use row |
| `custom.origin` | The line above the title shows the product type alone (or nothing, without a type) |
| `custom.specimen_weight` or `custom.specimen_size` | The piece card shows its letter and price without the weight or size |
| A chakra or sign that isn't one of the choices | It still prints, after the others, with a plain dot and no glyph |
| An element that isn't one of the five | Its name prints without a glyph |

In the theme editor, features with no data show a sample tagged **Sample** so you can see the design: an amethyst's properties panel (Calm, Intuition and Sleep; Third eye and Crown; Pisces, Virgo, Aquarius and Capricorn; Air; "Fades in strong sun…") with a sample How to use, three sample chips under the price, and the sample piece grid in the variant picker (chapter 6). Shoppers never see them, and card chips never show samples.