Private metafields

Private metafields function similarly to other metafields, but with the following differences:

  • Private metafields are accessible only by the app that created them.
  • Private metafields are deleted when the app that created them is uninstalled.
  • Private metafields are accessible only from the GraphQL Admin API. They're not accessible through Liquid or the Storefront API.
  • An app can create a maximum of 10 private metafields per shop resource.

For example, suppose that App A creates 2 metafields and 10 private metafields for a product, and App B creates 10 private metafields for the same product. Both apps can access the two metafields created by App A, but each app can access only the 10 private metafields that it created.

You can create, retrieve, update, and delete metafields using the Shopify GraphQL Admin API.

Creating private metafields

Each app can create a maximum of 10 private metafields per shop resource. There are two ways to create a private metafield:

Create a private metafield using privateMetafieldUpsert

Use the privateMetafieldUpsert mutation to create a private metafield for an existing resource. Specify the owning resource by providing its ID as part of the input.

POST /admin/api/2021-10/graphql.json

Variables

JSON response

Create or update the owning resource

You can create a private metafield by including it as part of the input when you create or update the private metafield's owning resource.

The following mutations accept an array of private metafields as part of their input object:

  • collectionCreate
  • collectionUpdate
  • customerCreate
  • customerUpdate
  • draftOrderCreate
  • draftOrderUpdate
  • orderCreate
  • orderUpdate
  • productCreate
  • productUpdate
  • productVariantCreate
  • productVariantUpdate

The example below uses the productUpdate mutation to create a private metafield for an existing product.

POST /admin/api/2021-10/graphql.json

Variables

JSON response

Retrieve a private metafield

When you query a resource, you can retrieve its private metafields individually or in a list.

Retrieve a single private metafield

Use the privateMetafield field to return a single private metafield. Specify the private metafield that you want to retrieve by using the namespace and key arguments.

POST /admin/api/2021-10/graphql.json

JSON response

Retrieve a list of private metafields

Use the privateMetafields connection to retrieve a list of metafields. This connection can be queried in a resource or in the query root. You can include the namespace argument to filter the returned results.

POST /admin/api/2021-10/graphql.json

JSON response

Update a private metafield

There are two ways to update a private metafield:

Update a private metafield using privateMetafieldUpsert

You can update a private metafield by using the privateMetafieldUpsert mutation. As part of the input, specify the owning resource by its ID, and specify the private metafield by its namespace and key.

POST /admin/api/2021-10/graphql.json

Variables

JSON response

Update the owning resource

You can update a private metafield by using a GraphQL mutation to update the owning resource and including the private metafield as part of the mutation input. Specify the owning resource by its ID, and specify the private metafield by its namespace and key. The following GraphQL mutations accept private metafields as part of their input:

  • collectionUpdate
  • customerUpdate
  • draftOrderUpdate
  • orderUpdate
  • productUpdate
  • productVariantUpdate

The following mutation uses the productUpdate mutation to update a private metafield that belongs to a product.

POST /admin/api/2021-10/graphql.json

Variables

JSON response

Delete a private metafield

Use the privateMetafieldDelete mutation to delete a private metafield. Specify the private metafield that you want to delete by providing the following data in the input:

  • its namespace
  • its key
  • the ID of its owning resource

POST /admin/api/2021-10/graphql.json

Variables

JSON response