Skip to content

Metafields — extra fields on records you already have

CIQRA knows what a product is. It does not know that your products have a care symbol, a harvest year, or a shelf-life in months. A metafield is how you tell it.

A metafield hangs off a record that already exists. It is an extra column on something CIQRA already sells with — not a thing in its own right.

Metafields and metaobjects look similar and are not.

If deleting the product should delete it, it is a field. If it should outlive the product, it is a type of its own. A product’s care instructions die with the product; the size guide three hundred products link to does not.

The screen says this itself, and it is worth stating plainly before you start:

🔴 A definition’s key and type cannot be changed after it is created. Not renamed, not widened from an integer to a decimal, not switched from text to rich text. Getting them right is a five-minute conversation now or a migration later.

  • The key is how your theme addresses the field. It is lowercase letters, numbers, hyphens and underscores, inside a namespace you choose. The $app namespace is reserved for apps and will be refused.
  • The type decides what may be stored and how staff edit it. CIQRA offers a wide set — single- and multi-line text, rich text, integers and decimals, true/false, dates, colors, URLs, money, ratings, JSON, dimensions, weights, volumes, and references to other records — and each may be a single value or a list.

The name and description are the parts staff read, and those you can revise freely.

Private by default, and that default is the safe one

Section titled “Private by default, and that default is the safe one”

A new field is private: admin only, and invisible to your theme. It becomes readable on a live page only when you set its storefront access to readable by the storefront.

This is the right way round. A field created for an internal note — a supplier’s reference, a margin band, a returns flag — is created private and stays private unless somebody deliberately publishes it. The alternative default would publish your internal notes on the day you defined them.

Ask one question before turning it on: would I be comfortable if a customer read this? Once a field is storefront-readable, anything in it on any record of that type is fetchable by the theme.

Defining a field applies it to every record of that type

Section titled “Defining a field applies it to every record of that type”

There is no per-product opt-in. Define a field on products, and every product now carries it — empty until someone fills it in. That is what makes the field usable from a theme without a per-record check, and it is also why a definition is worth thinking about: an unused field is a blank box on every editing screen your staff open.

  • It does not list which owner types you can define fields on. The hub screen shows the set that is actually available to your store, and a list written here would go false the first time it changed.
  • It does not cover filling values in. Defining a field and entering values are different screens; values are edited on the record itself.
  • It does not cover deleting a definition. Treat a definition as a commitment: the safe assumption is that what you define, you keep.