Skip to main content

Function APIs

Shopify Functions enable you to customize Shopify's backend logic by running custom code during the checkout process. You can create Functions to implement specialized features that aren't available natively.

For example, you can generate custom delivery options, create new types of discounts, and provide your own validation of a cart and checkout.

When you build a Function, prioritize performance. Functions run in the context of key purchase flows, like discounts and checkout. Delays can negatively impact the Shopify backend and prevent customers from making purchases.

Anchor to Shopify CLI scaffoldShopify CLI scaffold

Function APIs require a set of essential files, such as TOML configuration, GraphQL schema, GraphQL input query, and Function code.

Use Shopify CLI to scaffold the essential elements that you need to get started.

Anchor to Function execution order in checkoutFunction execution order in checkout

When building Shopify Functions, you need to understand where they fit into the checkout process. Functions execute in a specific sequence during checkout, and each Function depends on data from earlier steps. This sequencing is important because:

  • Your Function's input data comes from previous checkout operations.
  • The logic of your Function might change, depending on where it's executed during the checkout process.
  • Understanding this flow helps you build more reliable and efficient Functions.

For example, when a customer adds items to their cart and proceeds to checkout, several Functions might run in sequence:

First, Functions that change the pricing and presentation of items in a cart run. Then, Functions that calculate discounts execute. Finally, Functions that validate the cart contents run.

Each step builds on the data from previous steps, so that a cart validation Function can't run until after discount calculations are complete.

Use this diagram to help you understand when each Function runs during checkout, and plan your Function's implementation accordingly.

Anchor to Function extension target typesFunction extension target types

Identifiers that specify where you're injecting code into Shopify. Targets define where Functions run during the commerce loop.

Fetch target limited access
Limited access

The fetch target is limited to custom apps installed on Enterprise stores. You'll also need to request network access for Functions, as it's not currently available on development stores or in a developer preview. However, there are exceptions for some Function APIs. For information on fetch target access for a specific API, refer to that Function's API reference page.

A mechanism for retrieving the data from a third party provider and passing the data to the run target.

Shopify calls the fetch target before the run target. Shopify makes the HTTP call on your behalf, which makes the fetch results available to the run target. This ensures that the run target has access to data from an external source.

Returning a network request is optional if it's not necessary for a specific Function execution.

Run target

An extension point that enables you to customize Shopify's backend with custom business logic.

For example, you can prioritize locations for order routing, or create a new type of discount that's applied to a product or product variant in the cart.

The run target uses either Shopify data, hardcoded values, or fetch results from external providers.

Anchor to Function anatomyFunction anatomy

When you create a Function, you write a GraphQL input query that defines the shape of your data. Then you write logic that transforms the input data and returns the output to Shopify.

Functions query input data from the schema of a specific Shopify Function API.

The output is also defined by that Function API's schema. Function output is a declarative object of operations for Shopify to execute.

Anchor to InputInput

The Input object is the complete GraphQL schema that your Function can receive as input. You can specify what input your Function needs using an input query. Before calling your target, Shopify runs its associated GraphQL query and passes the resulting JSON data to your target.

You can customize input queries using metafields or input variables.

Anchor to FunctionFunction

The logic that processes your input data to generate a standardized response. It transforms your data into an ordered list of operations.

Each operation specifies the action to take based on your Function's purpose. Shopify processes your response to present the results, such as available cart line discounts, during the commerce flow.

Shopify strongly recommends Rust as the most performant language choice to avoid your Function failing with large carts.

Anchor to OutputOutput

When your Function runs, it returns an object that Shopify uses to perform an operation.

Each Function API extension target specifies the shape of the Function's output using a GraphQL type.

Anchor to ConfigurationConfiguration

Functions rely on a shopify.extension.toml file that contains the extension's configuration. This includes the extension name, type, API version, UI paths, build configuration, and metafields for query variables.

The name value is what displays in the Shopify admin to merchants, so consider this value carefully. We recommend that the api_version reflects the latest supported API version.

Anchor to PropertiesProperties

Functions use common configuration properties for app extensions. Additionally, the following properties in shopify.extension.toml are specific to Shopify Functions extensions:

[[extensions.targeting]] required

The name of the array that contains a target and its associated WebAssembly module export. Contains the following properties:

  • target: required

    An identifier that specifies where you're injecting code into the Shopify backend.

  • input_query: optional

    The path to the input query file for the target. If omitted, then the Function receives no input.

  • export: optional

    The name of the WebAssembly export in your module that executes the target.

    Functions don't use the extensions.targeting.module setting. Use export instead. Defaults to _start.

[extensions.build] optional

The settings related to the build and deployment of the function extension's WebAssembly module. Contains the following properties:

  • command: required

    The command to build the Function, which is invoked by the Shopify CLI build command. This setting can be omitted for JavaScript.

  • path: optional

    The relative path to the Function's WebAssembly module. For example, build/my-module.wasm. Defaults to dist/index.wasm.

  • watch: optional

    The relative paths that Shopify CLI should watch when the dev command is invoked. Changes to matched files will trigger a build of the function and update it in your application drafts. This setting accepts a single file path or glob pattern, or an array of file paths and glob patterns.

    For JavaScript and TypeScript functions, this setting defaults to ['src/**/*.js', 'src/**/*.ts'].

    Only paths inside the Function directory are allowed. Don't use ../ (no parent directory references).

    Input queries are automatically included in watch paths and don't need to be configured in build.watch.

  • wasm_opt: optional

    Whether to optimize your module before upload. Defaults to true.

[extensions.ui] optional

The settings related to the merchant interface for your Function. Contains the following properties:

[extensions.ui.paths] optional

The settings related to the App Bridge paths of the merchant interface for your Function. Contains the following properties:

  • create: optional

    The path within your app that's launched when a merchant clicks on creating a new customization with this function. Learn how to create your Function's merchant interface.

  • details: optional

    The edit path that launches when a merchant clicks customization. Learn how to create your Function's merchant interface.

[extensions.input.variables] optional

The variables to use in your input query. A means of inserting the dynamic values in the input query if you use hasTags and hasCollections. Contains the following properties:

  • namespace: optional

    A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name.

  • key: optional

    The name for the metafield.

Anchor to GraphQL schema and versioningGraphQL schema and versioning

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 tools like the VS Code GraphQL plugin.

On creation, each Function includes a copy of the GraphQL schema in the schema.graphql file. We recommend that your Function always uses the latest supported schema version. Learn how to generate the latest schema for your Function.

Anchor to API availabilityAPI availability

All plans: Except as noted in individual API pages, stores on any plan can use public apps that are distributed through the Shopify App Store and contain Functions.

Shopify Plus: Only stores on a Shopify Plus plan can use custom apps that contain Shopify Function APIs.

Anchor to Resource limits and performanceResource limits and performance

Your Function must adhere to our resource limits. Performance is critical because Functions run in the context of key purchase flows like discounts and checkout. Slow or resource-intensive Functions can negatively impact the customer experience and potentially prevent customers from completing their purchases.

We strongly recommend that you use Rust as the most performant language choice. Rust's memory safety and zero-cost abstractions help ensure your Function runs efficiently and stays within resource limits, even when processing large carts or complex business logic.

Learn about additional limitations and considerations for apps that use Shopify Functions.

Was this page helpful?