---
title: Introducing functionHandle for Shopify Functions - Shopify developer changelog
description: Shopify’s developer changelog documents all changes to Shopify’s platform. Find the latest news and learn about new platform opportunities.
source_url:
  html: https://shopify.dev/changelog/introducing-functionhandle
  md: https://shopify.dev/changelog/introducing-functionhandle.md
---

[Back to Developer changelog](https://shopify.dev/changelog)

October 1, 2025

Tags:

* Functions
* 2025-10

# 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`:

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

2. Create the payment customization using `functionHandle`

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