Introducing `functionHandle` for Shopify Functions

Changelog
1

As of the 2025-10 API version, we’re introducing support for user-defined handles as the identifier for Shopify Functions in GraphQL mutations. Instead of passing a globally unique functionId in mutations that create or manage function owners, you can pass a stable, app-scoped handle that you define in your shopify.extension.toml. All GraphQL mutations that currently accept functionId will accept functionHandle.

This is a companion discussion topic for the original entry at https://shopify.dev/changelog/introducing-functionhandle
2 Likes
2

Is there a way to query functions by handle?

It seems we have to query by id to check if the function is created before creating it.

Example querying PaymentCustomizations, returns functionId, but not functionHandle:

To find out if you need to create or update the payment function instance is not possible if you only use the handle.

1 Like
4

Hey David, this is not currently possible, but it is a limitation we are aware of.

1 Like