App-owned metafields and metaobjects not accessible to other apps via Storefront API

Technical Q&A
,
1

I’m building an app feature that requires app-owned metaobjects linked to products via a list.metaobject_reference metafield. Both are declared in shopify.app.toml with access.storefront = "public_read".

Setup:

[metaobjects.app.my_custom_type]
name = "My Custom Type"
access.storefront = "public_read"

[product.metafields.app.my_reference]
name = "My Reference"
type = "list.metaobject_reference<$app:my_custom_type>"
access.storefront = "public_read"

Our app can read the data fine via Storefront API using our own storefront access token — the metafield value and referenced metaobject entries resolve correctly.

The problem: When a third-party app or partner queries the same product via the Storefront API using their own storefront access token, the metafield references come back as null:

{
  "data": {
    "product": {
      "metafield": {
        "references": null
      }
    }
  }
}

The metafield value itself (the raw GID list) may be visible, but the resolved references are null.

What worked: Partners were able to access the app-owned metafields when using the resolved app namespace in the query app-<<APP_ID>>. This also worked app-owned metaobjects linked to app-owned metafields

query {
    product(id: "gid://shopify/Product/<<PRODUCT_ID>>") {
      customBadge: metafield(namespace: "app-<<APP_ID>>", key: "custom_badge") {
        namespace
        key
        type
        value
      }
    }
  }

This returns data correctly. However there is no official shopify documentation to prove this.

Could someone help me with this.

2

Hey @ErenYeager ,
Step 1: Understand the actual limitation

App owned metaobjects are not globally resolvable in the Storefront API.

Even if you set:

access.storefront = public_read

this only controls whether the data can be read not whether references can be resolved across different apps.

Step 2: Recognize the behavior difference

With a third party or partner Storefront token:

Metafield value (GIDs) may be visible
references resolves to null

This is expected because Shopify blocks cross-app resolution of app-owned metaobjects.

Step 3: Understand why your own app works

When using your own app’s Storefront access token:

Shopify recognizes the owning app context
It allows full resolution of:
metaobjects
reference fields
nested relationships

So everything resolves correctly.

Step 4: Understand why app-<<APP_ID>> works

When you query using:

metafield(namespace: “app-<<APP_ID>>”, key: “…”)

Shopify explicitly enters the app-owned namespace resolution path.

That is why:

metafield data is returned correctly
references resolve properly

This is still within the owner context not cross-app access.

Step 5: Decide your correct architecture

You have only two valid approaches depending on your requirement.

Thank You !

3

Adding to @Wsp’s mapping: the app-<APP_ID> namespace path is the only working cross-app resolution today, but it’s undocumented behaviour. Two practical issues if you build on it:

  1. App review tends to push back on integration docs or partner guides that reference undocumented namespaces. Shopify treats app-<APP_ID> as an internal resolution path and doesn’t want partners building publicly on it.

  2. It can break silently if Shopify changes how app-owned references resolve in a Storefront API minor version. No deprecation notice will cover it because it’s not in the public surface area.

If true cross-app interop is a hard requirement, the safer architecture is to drop app-owned and use a custom namespace + key for both the metaobject definition and the reference metafield. Declare them via Admin API mutations (metaobjectDefinitionCreate, metafieldDefinitionCreate with type=list.metaobject_reference) instead of shopify.app.toml. Custom-namespace data resolves cleanly across all Storefront tokens with default permissions, no app-<APP_ID> gymnastics.

Tradeoff: app-uninstall doesn’t clean up the data automatically anymore, so you need to handle that in your uninstall webhook.

What does the 3rd-party integration need to do with the references - read-only display, or write back too? That changes which path is least painful.

4

Hey lumine,

Thank you for this.

We only need read-only permission for partners to view the app-owned metafield/metaobjects.

As you mentioned, app-owned metafields does help in clean up time and that is why we are shifting towards this. But we don’t want the partners getting effected with the permissions. Using the metaobjects and metafields for structured data is shopify suggested way to manage structured data.