Function input and output

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.

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.

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.

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:

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:

1. Update the version of the API specified in your configuration file:

2. Generate the latest schema.

3. If you're using JavaScript, then run the following command to regenerate types based on your input query:

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.
• Input query variables of list type cannot 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
  Any field that returns a Metafield object	metafield on a Product object	3
  Any field on a Metafield object	value	0
  hasAnyTag		3
  hasTags		3
  Any field on a HasTagResponse object	hasTag	0
  inAnyCollection		3
  inCollections		3
  Any field on a CollectionMembership object	isMember	0
  Other leaf nodes	id or sku on a ProductVariant object	1

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