---
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/posts/introducing-functionhandle'
  md: 'https://shopify.dev/changelog/posts/introducing-functionhandle.md'
metadata:
  effectiveApiVersion: 2025-10
  affectedApi:
    - displayName: Functions
      handle: functions-api
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Deprecation announcement
    handle: deprecation-announcement
  indicatesActionRequired: false
  createdAt: '2025-09-15T15:31:23-04:00'
  postedAt: '2025-10-01T12:00:00-04:00'
  updatedAt: '2026-07-09T18:29:32-04:00'
  effectiveAt: '2025-09-01T12:00:00-04:00'
---

October 1, 2025

# Introducing `functionHandle` for Shopify Functions

DateOctober 1, 2025

Version[2025-10](https://shopify.dev/changelog?api_version=2025-10)

Flags[Deprecation announcement](https://shopify.dev/changelog?filter=deprecation-announcement)

SurfacesAPI

Affected APIs[Functions](https://shopify.dev/changelog?api_type=functions-api)

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"
```

1. Create the payment customization using `functionHandle`

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