Shopify Connector Failure: HTTP 403 / Missing 'read_locations' Scope – Amperity

This article outlines the steps necessary to resolve failures with Shopify Couriers or Workflows that occur after Shopify updates its API requirements.

Problem

The Amperity workflow fails when attempting to fetch data from Shopify, resulting in the following error message in the workflow log:

Error: HTTP request failed: 403 Internal Message: [API] This action requires merchant approval for read_locations scope.

This issue typically occurs because the Shopify API version used by Amperity has introduced a new mandatory permission (read_locations), which is required when querying location-related resources. The customer's existing Private App credentials lack this specific access scope.

Root Cause

The failure is due to outdated permissions granted to the Amperity Custom/Private App within the Shopify merchant settings. When Shopify updates its platform, new data fields (such as location data) are sometimes moved into new, mandatory permission scopes that the Amperity App must be granted manually by the customer's Shopify administrator.

Reference link of Shopify docs : https://shopify.dev/docs/api/release-notes/2024-10#location-resource

Solution

Solution: Granting Missing Permissions

This issue requires the Shopify administrator to update the permissions for the Custom App used by Amperity.

Required Action: Grant the read_locations scope to the Amperity Custom App.

Step-by-Step Instructions (Customer-Side)

Log in to Shopify: The user with appropriate administrator privileges must log into the Shopify Merchant account.
Navigate to Apps: Go to the Shopify Admin dashboard, then navigate to Settings > Apps and sales channels > Develop apps.
Locate Amperity App: Find and select the Custom/Private App that was created for the Amperity connection (often named something related to the tenant, e.g., Amperity_App).
Update Scopes/Permissions: Navigate to the Configuration section and find the Admin API integration settings.
Grant New Scope: Locate the permissions list (Scopes) and check the box to grant the read_locations scope.
Save Changes: Save the changes to the Custom App. Shopify may require re-installation or re-activation after updating scopes.
Retry Workflow: Once the changes are saved in Shopify, the customer can re-run the failed courier or workflow in Amperity. The workflow should now succeed.

Note: Shopify Amperity doc should be updated regarding this particular persmission - grant the read_locations scope in their Shopify merchant settings. - https://docs.amperity.com/operator/source_shopify.html#get-details

Important Information need to update in Amperity Docs - If your app retrieves a Location resource using the REST Admin API, then you need to request the read_locations access scope.
If your app reads a Location resource without the read_locations access scope, then a 403 Forbidden error is returned.