Introducing functionHandle for Shopify Functions

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.

Note: You must provide either 'functionId' or 'functionHandle' for each call, not both. Providing both will result in a user error.

What this does for you

Function IDs change with each deployment to a different environment. This forces developers to query for the latest ID before they can create or update a function owner. Handles are stable across environments and scoped to your app, removing the need to query shopifyFunction before creating the function owner.

No developer action required

These changes will not break your existing integrations. functionId will continue to work. However, we recommend you update your code to use functionHandle instead:

• Remove code that queries for functionId at runtime.
• Use the functionHandle you define in shopify.extension.toml directly in GraphQL mutations.

Formal deprecation and removal timelines for functionId will be announced separately.

Example Usage

1. Obtain functionHandle from the function's shopify.extension.toml:

   [[extensions]]
   name = "Payment Customization Function"
   handle = "YOUR_FUNCTION_HANDLE" 
     type = "function"
   

2. Create the payment customization using functionHandle

   mutation {
     paymentCustomizationCreate(paymentCustomization: {
       title: "Payment Customization Title",
       enabled: true,
       functionHandle: "YOUR_FUNCTION_HANDLE",
     }) {
       paymentCustomization {
         id
       }
       userErrors {
         message
       }
     }
   }