Metafields · Transom theme guide

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. The theme does not read variant, collection, or customer metafields.

Create the fields

You only do this once per store.

In your Shopify admin, go to Settings > Custom data > Products.
Select Add definition.
Enter a Name (for example, "Material").
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.
Choose the Type from the table.
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. 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 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 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:

[
  { "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 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 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:

[
  {"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 and 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.