App metafields split cleanly into definitions (schema) and values (data on a product, customer, order line, and other owner resources). Your app owns its definition schema. Merchants never edit app-owned definitions in Store Admin.
Definitions are not created through the Store API#
An app declares the metafield definitions it needs in the Developer Portal (Metafields on the app settings page). The declaration is frozen into an app release. When a merchant installs or updates to that release, Tringify materializes the definitions on their store under your app namespace: app:{your-slug}.{key}.
End-to-end flow#
Request the Store API permissions your metafields need on the app Permissions tab.
Declare metafields on the app Metafields tab — one row per
(owner_type, key).Submit and publish a release containing the declaration.
Install (or update) the app on a development store and confirm the merchant granted the required scopes.
After install, list definitions with
GET /metafield-definitions?owner_type=...if you need discovery.Read and write values on the owner resource endpoints using
namespaceandkey— for examplePUT /products/{id}/metafields.
What changes require a new release#
Adding a declaration or changing its supported settings requires a reviewed app release. Published keys, owner types and value types cannot be removed or changed; enabled translation cannot be turned off. Update the declaration in the Developer Portal, submit a release, and have merchants install the update. Existing stores keep their installed release until updated; new keys materialize on update the same way they do on first install.