# Metafields

Metafields are extra fields you can add to products in Shopify. Transom reads a small set of them to show specifications, badges, quantity breaks, and related products. None are required. A product without them still displays correctly; the matching feature simply does not appear.

Most metafields in Transom are **product** metafields; the blog post page also reads two [article metafields](#article-metafields). The theme does not read variant, collection, or customer metafields.

## Create the fields

You only do this once per store.

1. In your Shopify admin, go to **Settings > Custom data > Products**.
2. Select **Add definition**.
3. Enter a **Name** (for example, "Material").
4. Open the **Namespace and key** field and set it to the value from the table below (for example `transom.material`). The part before the dot is the namespace. The part after is the key.
5. Choose the **Type** from the table.
6. Select **Save**.

Once defined, the fields appear at the bottom of every product page in the admin, under **Metafields**. Fill them in per product.

Tip: Match the namespace and key exactly, including lowercase letters. `Transom.Material` or `transom.materials` will not work.

## Summary

| Namespace and key | Type | Shows up as |
|---|---|---|
| `transom.material` | Single line text | Specifications |
| `transom.dimensions` | Single line text | Specifications |
| `transom.care` | Multi-line text | Specifications |
| `transom.origin` | Single line text | Specifications ("Made in") |
| `transom.badge` | Single line text | Badge on product cards |
| `transom.fbt` | List of products | Frequently bought together |
| `transom.tiers` | JSON | Quantity breaks |
| `reviews.rating` | Rating | Star rating on the product page |
| `reviews.rating_count` | Integer | Review count next to the stars |

## Specification fields

These four fields feed the **Specifications** block on the product page. See [Specifications](https://lintelagency.com/support/transom/product-pages.md#specifications). Empty fields are skipped. If all four are empty, the block does not show.

### transom.material

- **Type:** Single line text
- **Label shown:** Material
- **Example:** `Solid European oak, natural oil`

### transom.dimensions

- **Type:** Single line text
- **Label shown:** Dimensions
- **Example:** `H 42 cm · Ø 32 cm`

### transom.care

- **Type:** Multi-line text
- **Label shown:** Care
- **Example:** `Wipe clean; re-oil once a year`

Line breaks you type are kept on the page.

### transom.origin

- **Type:** Single line text
- **Label shown:** Made in
- **Example:** `Turkey`

## transom.badge

- **Type:** Single line text
- **Where it shows:** A small label on the product's card in collections, search results, and product lists
- **Example:** `Bestseller`

Keep it to one or two words, such as "New", "Limited", or "Back in stock". Automatic "Sold out" and "Sale" badges (based on availability and compare-at price) still show; your custom badge appears beside them.

## transom.fbt

- **Type:** List of products (`list.product_reference`)
- **Where it shows:** The [Bought together](https://lintelagency.com/support/transom/product-pages.md#bought-together) block
- **Example:** Pick two or three products that go well with this one

The viewed product always appears first. The theme adds up to the **Maximum products to show** setting (1 to 3) from your list, in the order you set. If the list is empty, the block uses complementary product suggestions from the Search and Discovery app instead.

## transom.tiers

- **Type:** JSON
- **Where it shows:** The [Quantity breaks](https://lintelagency.com/support/transom/product-pages.md#quantity-breaks) block
- **Effect:** Overrides the tiers set in the block for this one product

Use this when different products need different tiers. The value is a list of tiers:

```json
[
  { "quantity": 1, "label": "Single mug" },
  { "quantity": 2, "label": "Save 10%", "percent": 10 },
  { "quantity": 4, "label": "Save 15%", "percent": 15, "badge": "Best value" }
]
```

Each tier can have:

| Key | Required | What it does |
|---|---|---|
| `quantity` | Yes | How many units this tier sets in the quantity field. |
| `label` | Yes | The text shoppers see, such as "Save 10%". |
| `percent` | No | The discount percent used to calculate the displayed total. Leave it out for a tier with no discount. |
| `badge` | No | A small tag on the tier, such as "Best value". |

Important rules:

- **The theme only displays the discount. It does not apply it.** Each `percent` must match a real automatic discount that you create in Shopify. See [Quantity breaks](https://lintelagency.com/support/transom/sell-more.md#quantity-breaks) for step-by-step instructions.
- A tier without `percent` shows the plain total (price times quantity), with no strikethrough.
- The `label` is free text. If you write "Save 10%" but set `percent` to 15, shoppers will see a mismatch. Keep them consistent.
- Valid JSON needs double quotes around keys and text, and no comma after the last item. If the JSON is invalid, Shopify will not let you save the field.

## reviews.rating

- **Type:** Rating
- **Where it shows:** The [Rating block](https://lintelagency.com/support/transom/product-pages.md#rating) on the product page, and wherever the theme shows a rating
- **Example:** A rating of 4.8 on a scale of 1 to 5

This is Shopify's standard review field. Most review apps write it for you. You can also fill it in by hand if you have real reviews.

The stars are drawn exactly, so 4.8 shows almost five full stars. The rating block is hidden when the product has no rating.

Do not enter ratings you cannot back up with real customer reviews.

## reviews.rating_count

- **Type:** Integer
- **Where it shows:** After the stars, for example "126 reviews"
- **Example:** `126`

Used together with `reviews.rating`. If it is empty or zero, only the stars and score show.

## Article metafields

Create these under **Settings > Custom data > Blog posts**, then fill them in on each blog post. You can use other namespaces and keys by changing the matching settings in the **Blog post** section.

| Namespace and key | Type | Shows up as |
|---|---|---|
| `custom.related_products` | List of products | **Products in the story**, a grid under the article |
| `custom.faq` | JSON | **Questions** under the article, plus FAQ structured data |

The `custom.faq` value is a list of questions and answers. Answers can contain simple HTML such as links:

```json
[
  {"question": "How often should I oil oak furniture?", "answer": "<p>Once a year for pieces in daily use.</p>"},
  {"question": "Does oiled oak stain?", "answer": "<p>Spills wiped up within a few minutes leave no mark.</p>"}
]
```

## Other places that use custom text

Not everything needs a metafield. These are set in the theme editor instead:

- **Benefits, shipping tabs, and guarantees:** Use [Benefits](https://lintelagency.com/support/transom/product-pages.md#benefits) and [Collapsible tab](https://lintelagency.com/support/transom/product-pages.md#collapsible-tab) blocks.
- **A shipping and returns tab shared across products:** Create a Shopify page, then pick it in the Collapsible tab's **Tab content from page** setting.