Manage private metafields

• Your app can make authenticated requests to the GraphQL Admin API.
• You have access to the type of resource that you want to add the metafield on. For example, setting a metafield on a PRODUCT requires the same access as mutating a product.

Private metafields are similar to other metafields, but they have the following limitations:

• Private metafields are accessible only by the app that created them.
• 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 resource.
• Private metafields don't support metafield definitions.

Note: Private metafields are deleted when the app that created them is uninstalled.

You can create private metafields using the GraphQL Admin API mutations:

• Use the privateMetafieldUpsert mutation
• Use a GraphQL mutation to create or update the owning resource

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.

The following example creates a private metafield for an existing product:

You can include private metafields as part of the input when you create or update the 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 following example uses the productUpdate mutation to create a private metafield for an existing product:

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

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.

The following example retrieves a private metafield that belongs to a product:

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

The following example retrieves all the private metafields that belong to a product:

There are two ways to update a private metafield:

• Use the privateMetafieldUpsert mutation
• Update the owning resource

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.

The following example updates the value of a private metafield that belongs to a product:

You can update a private metafield by updating 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
• productUpdate
• productVariantUpdate

The following example uses the productUpdate mutation to update the value of a private metafield that belongs to a product:

Use the privateMetafieldDelete mutation to delete a private metafield. Specify the private metafield you want to delete by its namespace and key, and specify the owning resource by ID.

The following example deletes the wholesale.price metafield from a product resource:

• Learn about access controls for metafields.