Input queries and metafields

Shopify Functions belong to and can affect the behavior of objects in the Shopify data model. The object associated with a function is known as the function owner. For example, the owner of a Discount API function is a discount.

You use App Bridge to create merchant UIs for managing function owners and their metafields. Then, you use input queries to provide the metafields as input to your function.

Some Function APIs allow you to create a merchant interface for configuring your function using either embedded app pages or admin UI extensions. Refer to the available APIs documentation for specifics on what's supported by each Function API.

You need to configure specific properties in your function extension configuration based on the method that you use for creating a merchant interface.

You have the option to configure an admin UI extension to be used as the merchant interface to create and edit the function owner.

To configure a UI extension to be used for configuring your function, you must specify the extension.ui.handle property in your shopify.extension.toml file. Ensure that the value for extension.ui.handle matches the handle property of the corresponding UI extension in your app.

The following example shows the properties in the shopify.extension.toml file:

You have the option to configure the routes in your application that merchants will use to create and edit the function owner, such as a discount. The default path for both properties is the root directory of your app (/).

The following example shows the properties in the shopify.extension.toml file:

There are some cases where you might not want the merchant to create a function owner themselves. For example, the function could be an implementation detail of a bigger feature and it could make more sense for the bigger feature to manage the function owner lifecycle.

You can configure the function to opt-out of the default function owner creation workflow. This means that the app will solely be responsible for creating the function owner. While this means the merchant can't create a function owner in the Shopify Admin, they can still edit, activate, or deactivate one created by the app.

You can configure this with the following property in your function extension configuration.

If you specify the :id or :functionId in the ui.paths properties in shopify.extension.toml, then the URL is updated with the following values:

The ID values are needed as input to the create, update, and delete mutations for your customizations. By using dynamic IDs, you can avoid managing hardcoded values in your app.

Use App Bridge and Polaris to create a seamless merchant experience within the Shopify admin. You can use the GraphQL Admin API to create and update your function owner and its metafields. Metafields are supported on all function owner types, and can be used to store custom values for your function logic.

The following is an example of a mutation that would set metafields on a discount function owner, when implementing a Discount API function.

All Function APIs provide access to the function owner, and its metafields, as part of their GraphQL schema. This means that you can access the metafield values set by merchants using input queries, and use those values in your function's logic.

The following is an example of an input query that would retrieve a metafield on a discount function owner, when implementing a Discount API function.

This section provides some best practices for using metafields for function input.

You should use a reserved prefix in your metafield namespace, so that other apps can't use your metafields.

Metafields support many types of data, but functions will often require nested and/or repeating data structures. Using a single JSON metafield can simplify the management and querying of your configuration.

If you need to make breaking changes to your function configuration data, then you can implement the Parallel Change (Expand and Contract) pattern using additional metafields:

1. Update your function's logic to simultaneously read configuration from your existing and new metafields, preferring the newer data, if present.
2. Change your function UI to simultaneously update both your existing and new metafields.
3. Use the GraphQL Admin API to migrate existing data from your old metafields to your new metafields.
4. After you've finished the migration, remove any UI and function logic for your old metafields.
5. Use the GraphQL Admin API to remove your old metafields.

• Learn how to use variables in input queries with Shopify Functions.