About Function input and output
This guide introduces how data is input to and output from Shopify Functions.
How it works
Anchor link to section titled "How it works"Shopify Functions query input data from the schema of a Function API. The output is also defined by the same Function API schema. Function 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 as JSON 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, Shopify CLI generates a GraphQL file for your input query. You can edit the query to request the exact data you need. Each target implemented in your function extension can have a unique input query.
Input example
Anchor link to section titled "Input example"The following example shows an input that retrieves a customer's email:
The Function API references provide information on the available fields for the input query.
Each Function API extension target specifies the shape of the function's output using a GraphQL type. For example, there's a FunctionRunResult
definition for the purchase.order-discount.run
target of the Order Discount API.
If a function discounts an order by $50.00, then it could return the following output:
The Function API references provide information on available targets, and their associated output GraphQL type.
GraphQL schema
Anchor 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
graphql_client
for Rust
On creation, each function includes a copy of the GraphQL schema in the schema.graphql
file.
Generating the latest schema
Anchor 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 function schema
command. This command outputs the latest schema based on your function's API type and version to the schema.graphql
file:
You can output the generated GraphQL schema to STDOUT
by passing the --stdout
flag:
You can also save the output to a different file or pipe it into a code generation tool, if needed:
API versions
Anchor link to section titled "API versions"Function APIs are versioned. Updates are released quarterly and supported API versions are listed in the release notes. You can update to a new version of a Function API by completing the following steps:
Update the version of the API specified in your configuration file:
If you're using JavaScript, then run the following command to regenerate types based on your input query:
Limitations
Anchor 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 10,000 bytes in size will not be returned.
- Field arguments and input query variables of list type can't exceed 100 elements.
Function input queries can have a maximum calculated query cost of 30. The following table describes the input query field costs for functions:
Field Example Cost value __typename
0 Any field that returns a Metafield
objectmetafield
on aProduct
object3 Any field on a Metafield
objectvalue
0 hasAnyTag
3 hasTags
3 Any field on a HasTagResponse
objecthasTag
0 inAnyCollection
3 inCollections
3 Any field on a CollectionMembership
objectisMember
0 Other leaf nodes id
orsku
on aProductVariant
object1
- Learn how input queries and metafields work in Shopify Functions.
- Learn how to use variables in input queries with Shopify Functions.