Skip to main content

​
Metafield Definitions

A definition is the schema for a metafield: it sets the type, validation rules, human label, and whether the field is pinned to the resource detail page in admin. Values that conflict with the definition’s type or validations are rejected at write time.
Definition CRUD lives on the Admin API (merchant JWT) only. It is not exposed to OAuth-scoped apps. Apps can write metafield values without ever creating a definition — the type+validation contract is optional. Definitions exist primarily to power the merchant Settings → Custom data admin UI.

​
Why definitions exist

​
Schema

Definitions are keyed by (owner type, namespace, key) — one definition per combination per store.

​
Validation rules per type

The validations object’s allowed keys depend on type:

​
Endpoints

​
Auth

Merchant JWT (owner, or staff with admin/manager access). The storeId is resolved from the token.

​
Notes for app developers

  • You can still write metafield values under your own namespace without creating a definition first. The platform won’t enforce types unless you’ve defined them.
  • If you want merchants to see and edit your fields in the admin, ask the merchant (or your install flow) to create matching definitions. The definition + value combination is what populates the admin UI.
  • Deleting a definition does not delete the values. Values persist; they just lose the schema. Cleaning up values requires explicit DELETE /metafields/:id calls.