Operating metafield definitions

A metafield definition is a custom field your raw materials can carry: “Lead time”, “Supplier”, “Certified until”. The definition is the field itself; the values are what each material holds for it. A connected assistant can read the definitions on any plan, and with write access and the Enhanced plan add, correct and remove them.

What it takes

Reading the catalogue needs nothing beyond a connection.

Changing it needs two things: write access — either an API key created with read & write scope or a web-chat connection granted read & write when it was linked — and the Enhanced plan. Metafield definitions are an Enhanced feature in the app, and the same check applies to an assistant: on any other plan the request is refused before anything is read or written, and the answer names the plan you need. See API keys and Connect claude.ai or ChatGPT.

Reading stays open on every plan on purpose. If your subscription lapses you still own the fields and the values already recorded against them, and an assistant can still report them to you.

Reading the catalogue

The assistant can list every definition your store has, with its name, description and type, and whether it is bound to a Shopify metafield. It can also read a single one by id.

That list is the starting point for anything to do with values: every value the assistant writes names the definition it belongs to, so it reads the catalogue first rather than guessing at a field name.

Adding a field

A new definition needs a name and a type, and the type is fixed once it is created. There are four:

text — anything at all.
number — anything that reads as a number.
date — anything that reads as a date.
boolean — true or false.

The type is what makes the field worth having: it is checked every time a value is written, so a “Lead time” declared as a number cannot quietly collect “about two weeks” on one material and “14” on another.

Binding a field to Shopify

A definition can be bound to a metafield definition that already exists in Shopify, which is what lets values be pulled in from there instead of typed in twice.

The binding is all four parts together — the owner type (product or variant), the namespace, the key, and Shopify’s own definition id — or none of them. The assistant cannot set half of it.

To find the candidates, ask the assistant what metafield definitions Shopify has for products or for variants; it reads them live. If Shopify cannot be reached it says so rather than reporting an empty list, so “Shopify has none” always means Shopify has none.

Correcting a field

The assistant writes only the parts you asked it to change; everything else is left as it is. It can add a binding, replace one, or clear one back to a purely internal field.

Changing the type is the one edit to think about before asking for it. The type is checked when a value is written, not re-checked afterwards, so values recorded under the old type stay exactly as they are. Widening a field to text is always safe. Narrowing one — text to number, say — can leave values behind that the new type would never have accepted. Ask the assistant to read the values first.

What a delete really removes

Deleting a definition deletes every value stored under it, on every raw material. There is no hidden-instead-of-deleted state here and no undo.

Because of that, the answer says how many values went with it. If that number matters to you, ask the assistant to read the values before it deletes, not after.

Deleting a field your store does not have is reported as not found rather than as a quiet success, so a typo in an id cannot look like a successful cleanup.

Definitions and values

The two are separate on purpose, and they are gated differently.

Definitions — the fields themselves, shop-wide, Enhanced, covered by this page.
Values — what each raw material holds, covered in Operating raw materials and stock. The assistant can add, change, clear and re-sync a value, and read a value’s history.

A value always names its definition, so the ids on this page are the ids the value calls take.