---
title: >-
  Metafield references added to Customer Account API - Shopify developer
  changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/metafield-references-added-to-customer-account-api
  md: >-
    https://shopify.dev/changelog/metafield-references-added-to-customer-account-api.md
metadata:
  effectiveApiVersion: 2026-01
  affectedApi:
    - displayName: Customer Account API
      handle: customer-account-graphql
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2025-09-08T17:28:29-04:00'
  postedAt: '2026-01-01T00:00:00-05:00'
  updatedAt: '2025-12-19T14:27:47-05:00'
  effectiveAt: '2025-10-01T00:00:00-04:00'
---

January 1, 2026

Tags:

* Customer Account API
* Admin GraphQL API
* 2026-01

# Metafield references added to Customer Account API

We have added `metafield.reference` and `metafield.references` to the Customer Account API. This means that reference `Media` types, including [MediaImage](https://shopify.dev/docs/api/customer/unstable/objects/MediaImage), [GenericFile](https://shopify.dev/docs/api/customer/unstable/objects/GenericFile), [Model3d](https://shopify.dev/docs/api/customer/unstable/objects/Model3d), and [Video](https://shopify.dev/docs/api/customer/unstable/objects/Video), now exist on the common query objects that currently support metafields on the Customer Account API.

Metaobjects can now also be queried through `metafield.reference` on the Customer Account API. To enable access to metaobjects, toggle the Customer Account API access toggle when editing a metaobject definition in Admin. After toggling this value on, metaobjects are exposed and accessible to apps with [the customer\_read\_metaobjects scope](https://shopify.dev/docs/api/usage/access-scopes#customer-access-scopes).

This functionality can also be achieved with new changes to the GraphQL Admin API. We have exposed the ability to create, update, and query `CustomerAccess`, which can be set to either `READ` or `NONE`. You can specify the access on the [MetaobjectAccess](https://shopify.dev/docs/api/admin-graphql/unstable/objects/MetaobjectAccess) object when running the [metaobjectDefinitionCreate](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/metaobjectdefinitioncreate) or [metaobjectDefinitionUpdate](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/metaobjectdefinitionupdate) mutation.

Below are some example queries of Media types and metaobjects.

1. Querying a Media object metafield.reference (MediaImage) through customer:

```
query {
		customer {
			metafield(namespace: "custom", key: "example") {
				namespace
				key
				jsonValue
				reference {
					__typename
					... on MediaImage {
						image {
							url
						}
					}
				}
			}
		}
	}
```

2\. Querying a metaobject metafield.reference through an order (note, the metaobject contains a MediaImage reference):

```
order(id: "gid://shopify/Order/1") {
		metafield(namespace: "custom", key: "example") {
			__typename
			namespace
			key
			reference {
				__typename
				... on Metaobject {
					id
					fields {
						type
						value
						key
						value
						reference {
							__typename
							... on MediaImage {
								id
								image {
									altText
									url
								}
							}
						}
					}
				}
			}
		}
	}
```