App-owned TOML metafield definitions: what happens after uninstall/reinstall?

Hi,

I have a question about app-owned metafield definitions declared via shopify.app.toml (no API-created definitions, no app-data metafields). The app is installed on a specific store via app distribution link (not published on the App Store).

If I uninstall and reinstall the same app (same client_id) on the store:

  • Are metafield values lost? Or do they persist and get re-associated with the new installation?
  • Do definitions get a new App ID namespace? (e.g. app--OLD_ID → app--NEW_ID) And if so, does the data follow?

Additionally: if I have metafields that need to be referenced by external integrations (theme Liquid, third-party tools), is it better to declare them as app-owned (via TOML with $app namespace) or as merchant-owned (e.g. custom namespace) to avoid dependency on the app lifecycle?

Thanks for any clarification!

Hey @Max86 :waving_hand: thanks for reaching out.

I tested this today using a TOML-defined app-owned product metafield and Admin GraphQL API version 2026-07.

After uninstalling and reinstalling the same app, this is what I observed:

  • The App GID and app–{app_id} namespace were unchanged.
  • The AppInstallation GID changed.
  • The metafield definition GID changed.
  • The metafield GID and stored value were unchanged.
  • The definition returned with a new GID after reinstall. The retained metafield’s nested definition.id changed to that same new GID.

The public metafield-definition documentation doesn’t currently specify uninstall/reinstall behaviour, so I’m going to dig into this deeper as well:

If these metafields or metaobjects need to be accessible by another app, Shopify’s documentation says they must use a custom namespace rather than the owning app’s reserved namespace: Public access for app owned metafields and metaobjects is now disabled - Shopify developer changelog

I’ll follow up here once I more information to share and I hope this helps point you in the right direction for now!

Hey @Max86 - I have an update on this.

The persistence I observed in my testing can happen when the app is reinstalled shortly after uninstallation, but it isn’t behaviour an app should rely on.

Uninstalling deletes app-owned metafield definitions. Shopify temporarily retains metafields and their values without a definition, then recreates and reassociates them if the same app is reinstalled while that data is still retained. Shopify doesn’t guarantee how long that data is retained, so don’t depend on a reinstall within a particular period to preserve it. TOML-defined definitions receive new GIDs after reinstall, so look them up by owner type, namespace, and key rather than by a previous definition ID.

We’ve added an App uninstall and reinstall section to the metafield documentation, with equivalent guidance for metaobjects as well to make this more clear.

For values that other apps or integrations must access, use a merchant-owned definition in a custom namespace rather than the app-reserved namespace as I mentioned in my last message.

Hope this helps!