---
title: Migrate your app to use non-encoded object IDs
description: Learn how to migrate your app from using Base64-encoded object IDs to non-encoded object IDs.
source_url:
  html: https://shopify.dev/docs/storefronts/headless/object-ids
  md: https://shopify.dev/docs/storefronts/headless/object-ids.md
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/storefronts/headless/object-ids#requirements)
* [Step 1: Migrate your app](https://shopify.dev/docs/storefronts/headless/object-ids#step-1-migrate-your-app)
* [Step 2: Handle persisted IDs](https://shopify.dev/docs/storefronts/headless/object-ids#step-2-handle-persisted-ids)
* [Next steps](https://shopify.dev/docs/storefronts/headless/object-ids#next-steps)

# Migrate your app to use non-encoded object IDs

In API version 2022-04, using Base64-encoded object IDs as arguments to fields and mutations was deprecated. Support for this behavior will be removed in API version 2023-07.

This guide shows you to migrate your app from using Base64-encoded object IDs to non-encoded object IDs.

***

## Requirements

You need to migrate your app if you're caching or parsing IDs, or persisting IDs to a database.

If your app queries the Storefront API and uses the object IDs as they're given without any long-term persistence or transformations, then you don't have to migrate your app.

***

## Step 1: Migrate your app

Most object types in Shopify's GraphQL APIs have an `id` field. The `id` field represents the globally-unique identifier for an individual record. The following are examples of a product ID in the GraphQL Admin and Storefront APIs before the change:

## GraphQL Admin API

```json
"gid://shopify/Product/1"
```

## GraphQL Storefront API

```json
"Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE="
```

To help you migrate your app, Shopify has changed the GraphQL Storefront API to allow for non-encoded object IDs to be used interchangeably as arguments to fields and mutations. For example, the following two queries are now valid and return identical responses:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

```graphql
{
  product(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE=") {
    id
  }
}
```

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

```graphql
{
  product(id: "gid://shopify/Product/1") {
    id
  }
}
```

***

## Step 2: Handle persisted IDs

If you have a database of persisted object IDs, then there are a few possible migration strategies.

Base64 encoding and decoding is commonly a part of most programming standard libraries, and if not, readily available as a 3rd-party package. You can write a script that iterates through each record, removes the Base64 encoding, and updates the database. The following example shows what a script written in Ruby could look like:

## File

```ruby
require 'base64'


Product.in_batches.each_record do |product|
  encoded_id = product.shopify_id # Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE=
  decoded_id = Base64.strict_decode64(encoded_id)
  product.shopify_id = decoded_id # gid://shopify/Product/1
  product.save!
end
```

***

## Next steps

* If you have questions or need help migrating your app, refer to Shopify's [Storefront API Feedback GitHub discussion board](https://github.com/Shopify/storefront-api-feedback).

***

* [Requirements](https://shopify.dev/docs/storefronts/headless/object-ids#requirements)
* [Step 1: Migrate your app](https://shopify.dev/docs/storefronts/headless/object-ids#step-1-migrate-your-app)
* [Step 2: Handle persisted IDs](https://shopify.dev/docs/storefronts/headless/object-ids#step-2-handle-persisted-ids)
* [Next steps](https://shopify.dev/docs/storefronts/headless/object-ids#next-steps)