Function input and output
This guide introduces how data is input to and output from Shopify Functions.
How it worksAnchor link to section titled "How it works"
Shopify Functions request an input against the schema of the specific Function API schema. 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 using
STDIN, and your function writes output to Shopify using
STDOUT. Refer to 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 exampleAnchor 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:
GraphQL schemaAnchor link to section titled "GraphQL schema"
Each Function API has a GraphQL schema representation, which you can use to improve your development workflow. For example, a GraphQL schema can be used with:
- The VSCode GraphQL plugin
- Language-specific code generation tools, such as
On creation, each function includes a copy of the GraphQL schema in the
Generating the latest schemaAnchor link to section titled "Generating the latest schema"
If you're using an unstable API version, then the GraphQL schema might have changed since you created the function or last generated the schema. If you change your target API version, then the Function API schema might have changed between versions.
To generate the latest GraphQL schema for your function, use the
generate schema command. This command outputs the latest schema based on your function's API type and version to stdout. Yuo can save the output to a file or pipe it into a code generation tool.
To overwrite your function's
schema.graphql file with a newly generated version, run the following command from your function directory:
LimitationsAnchor link to section titled "Limitations"
The following limitations apply to input queries:
- The maximum size for an input query, excluding comments, is 3000 bytes.
- Metafields with values exceeding 1 kB in size will not be returned.
Function input queries can have a maximum calculated query cost of 30. The following table describes the input query field costs for functions:
Field Cost value Any field that returns a
Metafieldobject (For example,
3 Any field on a
Metafieldobject (For example,
3 Other leaf nodes (For example,
- Learn how input queries and metafields work in Shopify Functions.
- Learn how to use variables in input queries with Shopify Functions.