Input queries and metafields
To make your code reusable, you can replace hard-coded variables in your function with metafield values. Using metafields enables merchants and staff to customize your function by entering values and options in interfaces provided by your app.
This guide introduces how input queries and metafields work in Shopify Functions. For an overview of how data is input to and output from Shopify Functions, refer to Function input and output.
How it worksAnchor link to section titled "How it works"
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.
Creating your merchant interfaceAnchor link to section titled "Creating your merchant interface"
When implementing a function, you must configure it with routes in your application which merchants will use to create and edit the function owner, such as a discount.
You must configure the following properties in your function settings. The default path for both properties is the root directory of your app (
||The route to create a new function owner.||
||The route to edit the function owner.||
The following example shows the properties in the
Configuring creation workflows for function ownersAnchor link to section titled "Configuring creation workflows for function owners"
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 settings.
||Whether the merchant can create a function owner in the Shopify admin. Default value is
Dynamic ID valuesAnchor link to section titled "Dynamic ID values"
If you specify the
: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.
Merchant experienceAnchor link to section titled "Merchant experience"
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.
Reading metafields with input queriesAnchor link to section titled "Reading metafields with input queries"
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.
Best practicesAnchor link to section titled "Best practices"
This section provides some best practices for using metafields for function input.
Use a reserved prefix in your metafield namespaceAnchor link to section titled "Use a reserved prefix in your metafield namespace"
You should use a reserved prefix in your metafield namespace, so that other apps can't use your metafields.
Use JSON metafields for complex configurationsAnchor link to section titled "Use JSON metafields for complex configurations"
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.
Manage configuration changes with new metafieldsAnchor link to section titled "Manage configuration changes with new metafields"
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:
- Update your function's logic to simultaneously read configuration from your existing and new metafields, preferring the newer data, if present.
- Change your function UI to simultaneously update both your existing and new metafields.
- Use the GraphQL Admin API to migrate existing data from your old metafields to your new metafields.
- After you've finished the migration, remove any UI and function logic for your old metafields.
- Use the GraphQL Admin API to remove your old metafields.
- Learn how to use variables in input queries with Shopify Functions.