Skip to main content
Metafields let you attach your own data to a storefront resource — a product’s material, a post’s reading time, a page’s accent colour. Each metafield is a typed value filed under a namespace and a key.
Metafields are public. The public storefront endpoints return every metafield on a resource, to anyone. Never store private, internal, or personal data in them.

​
Read metafields

Every storefront response includes a metafields array. It’s empty when the resource has none:
The public and company endpoints return the same array. value comes back exactly as it was written: a number written as "42" reads back as the string "42".

​
Write metafields

Send metafields_attributes on a company create or update. Each entry needs namespace, key, value, and value_type. description is optional.
How a write is applied:
  • Matched by namespace and key. An entry that matches an existing metafield replaces it. A new pair adds a metafield.
  • Everything else is kept. Metafields you don’t send are left as they are. Omitting metafields_attributes, or sending [], changes nothing.
  • description is kept if you leave it out. Send a new one to change it.
  • All or nothing. If any entry is invalid, the request returns 422 and none of the metafields change.

​
Delete a metafield

Send the entry with _destroy: true. value and value_type are still required, so include them:
There is no way to clear every metafield in one request. Delete them one entry at a time.

​
Naming rules

  • namespace: up to 20 characters. key: up to 30 characters.
  • Both may contain only letters, digits, and underscores.
  • A namespace and key pair is unique on each resource.
Group your own fields under one namespace, such as custom or your app’s name, so they don’t collide with anyone else’s.

​
Value types

value_type says what kind of value a metafield holds. Fluid checks value against it: "abc" as a number_integer returns 422. A few rules catch people out:
  • boolean takes JSON true or false. The string "true" is rejected.
  • color is #RGB or #RRGGBB.
  • url must start with http:// or https://.
  • Measurements are objects with exact keys. For example, money is {"amount": ..., "currency_code": ...}.

​
Metafield definitions

A store can define its metafields in Fluid Admin: the type each namespace and key must have, and rules such as a minimum, a maximum, a list of allowed choices, or a pattern. When a definition matches a metafield you write, Fluid enforces it. A value of the wrong type, or one that breaks a rule, returns 422. A definition never hides a metafield or makes it required. locked in a response shows whether the matching definition is locked in Fluid Admin, or null when there is no definition.

​
Search, translation, and themes

  • Search. A list’s q search matches metafield values. You can’t filter a list by a metafield.
  • Translation. Metafields aren’t translated. A translation PATCH (a write with a non-default lang) ignores metafields_attributes, except on products. See Translations.
  • Themes. Liquid templates read product, variant, and enrollment pack metafields as resource.metafields.<namespace>.<key>, for example product.metafields.custom.material.

​
Current limitations

Two resources don’t follow the rules above yet:
  • Collections don’t accept metafields_attributes through v2026-04.
  • Products can add a new metafield through v2026-04, but can’t change or delete an existing one. Sending an existing namespace and key again returns 422.

​
Next steps