Function input and output
Shopify Functions request an input against the schema of the specific Function API schema. Function API schemas are based on the Cart API. The output is also defined by the same Function API schema. The output is a declarative object which represents operations for Shopify to execute.
Shopify passes input as JSON to your function via STDIN, and your function writes output to Shopify via STDOUT. See the WebAssembly API for details.
You can specify what input your function needs using an input query. For example, the structure of the JSON in the input example matches the shape of the following query:
When you create a function, an input.graphql file is generated at the root of your project directory. You can edit the query to request the exact data you need, which results in a more performant function. The query is executed against the specific Function input API, in the context of the current execution.
Input example
Anchor link to section titled "Input example"The following example shows an input that retrieves a customer's email along with the payment methods:
Each Function API specifies the shape of the function's output using an object with the name FunctionResult. For example, there's a FunctionResult definition for the Order Discount API.
If a function discounts an order by $50.00, then it could return the following output:
Using metafields with input queries
Anchor link to section titled "Using metafields with input queries"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.
How it works
Anchor 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.
Create your merchant interface
Anchor link to section titled "Create 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 (/).
| Property | Description | Example |
|---|---|---|
ui.paths.create |
The route to create a new function owner. | /my-discount-type |
ui.paths.details |
The route to edit the function owner. | /my-discount-type/:id, where :id is dynamically replaced by the ID of the function owner |
The following example shows the properties in the shopify.function.extension.toml file:
Merchant experience
Anchor 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.
Read metafields with input queries
Anchor link to section titled "Read 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.
Input query limitations
Anchor link to section titled "Input query limitations"The following limitations apply to input queries:
- Input queries may include a maximum of 30 scalar fields.
- The maximum byte size is 3000.
- Metafields with values exceeding 1kb in size will not be loaded.
Best practices
Anchor link to section titled "Best practices"This section provides some best practices for using metafields for function input.
Use your app name as your metafield namespace
Anchor link to section titled "Use your app name as your metafield namespace"To avoid conflicts with other apps, use a derivative of your app's name for your metafield namespace.
For example, if your app name is Discounts Plus, then use a metafield namespace such as discounts-plus.
Use JSON metafields for complex configurations
Anchor 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 metafields
Anchor 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.