Skip to main content

Migrate to read_locations scope

This guide describes how to migrate your app with read_inventory scope to access Location GraphQL fields, which became a requirement in API version 2024-07.

Anchor to RequirementsRequirements

  • You've built an inventory management app that accesses location data.
  • Your app currently has the read_inventory or write_inventory scope.
  • Your app queries Location GraphQL fields.
Note

As of GraphQL API version 2024-07, the Location fields require the read_locations scope. Apps without this scope will receive access denied errors when querying location data.

Anchor to Step 1: Determine if your app needs migrationStep 1: Determine if your app needs migration

Your app needs migration if:

  • Your app queries Location GraphQL fields
  • Your app has read_inventory or write_inventory scope but lacks read_locations
  • You're receiving access denied errors when querying location data

Anchor to Step 2: Update your app's permissionsStep 2: Update your app's permissions

Note

Tip: If you configure your app using Shopify CLI, then your app will automatically use Shopify managed installation. You can skip this step.

When you've determined that your app needs read_locations scope, you can update your app for new installations and existing installations.

Anchor to New installationsNew installations

For new installations, include the read_locations scope in the permissions that your app requests as part of authorization code grant.

Anchor to Existing installationsExisting installations

For existing installations of your app, you can use the request_granular_access_scopes REST endpoint to request the read_locations scope based on the inventory access scopes your app is already granted. You should make a request to the request_granular_access_scopes REST endpoint for each shop where your app is installed.

  • If your app has the read_inventory or write_inventory access scope, then it can request the read_locations access scope.

The following example request adds the read_locations scope to an existing installation of an inventory management app that has read_inventory scope.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

REST body

{
"requested_scopes": [
"read_locations"
]
}

JSON response

HTTP/1.1 200 OK
{
"access_scopes": [
{
"handle": "read_inventory"
},
{
"handle": "read_locations"
}
]
}

The following example request demonstrates an error returned if an app does not have the read_inventory or write_inventory access scope but requests the read_locations access scope.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

REST body

{
"requested_scopes": [
"read_locations"
]
}

JSON response

HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"requested_scopes": "Missing required scopes: \"read_locations\" requires \"read_inventory\" or \"write_inventory\"."
}
}

Anchor to Step 3: Verify your migrationStep 3: Verify your migration

After implementing scope expansion, you can verify that your app can now access location data by making a GraphQL query to fetch locations:

query getLocations {
locations(first: 10) {
edges {
node {
id
name
}
}
}
}

If your scope expansion was successful, this query will return location data. If you encounter any errors, ensure that:

  1. The scope expansion request was successful
  2. The access token you're using for the GraphQL request is the updated token
  3. Your app has properly handled any authorization errors
Was this page helpful?