unauthenticated_read_shop_pay_installments_pricing permissions scope missing from permissions

[john-parton]

What is the location of your example repository?

No response

Which package or tool is having this issue?

Hydrogen

What version of that package or tool are you using?

2025.7.0

What version of Remix are you using?

React Router 7.9.2

Steps to Reproduce

Attempting to augment the product variant with Shop Pay metadata:

const PRODUCT_VARIANT_FRAGMENT = `#graphql
  fragment ProductVariant on ProductVariant {
    availableForSale
    compareAtPrice {
      amount
      currencyCode
    }
    id
    image {
      __typename
      id
      url
      altText
      width
      height
    }
    price {
      amount
      currencyCode
    }
    product {
      title
      handle
    }
    selectedOptions {
      name
      value
    }
    sku
    title
    unitPrice {
      amount
      currencyCode
    }
  
    shopPayInstallmentsPricing {
      available
      eligible
      fullPrice {
        amount
        currencyCode
      }
      pricePerTerm {
        amount
        currencyCode
      }
      installmentsCount {
        count
        precision
      }
    }

  }
` as const;

Results in the following error

╭─ error ────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                    │
│  In Hydrogen's `storefront.query`:                                                                 │
│                                                                                                    │
│  Access denied for shopPayInstallmentsProductVariantPricing field. Required access:                │
│  `unauthenticated_read_shop_pay_installments_pricing` access scope.                                │
│  Request ID: be2707b0-d88e-4323-bff3-cd010be45632-1767134708                                       │
│                                                                                                    │
│  To debug the query `Product`, try it in                                                           │
│  GraphiQL.                                                                                         │
│                                                                                                    │
│  To investigate the issue, examine this stack trace:                                               │
│    at loadCriticalData (app/routes/catalog.$handle.tsx:167)                                        │
│    at loader (app/routes/catalog.$handle.tsx:81)                                                   │
│                                                                                                    │
╰────────────────────────────────────────────────────────────────────────────────────────────────────╯

There's no straightforward way to grant the permission in the Shopify admin:

Expected Behavior

The query should likely work out-of-the-box. Failing that, it should be easy to enable using the administrative interface.

Actual Behavior

The query fails, as described above. In attempting to get this to work, it looks like I might have to manage a second token with manually edited permissions, which is additional complexity and possibly increases the surface area for permissions issues.

[john-parton]

I opened up a support ticket with Shopify using our Shopify Plus account, and received a response suggesting that this is intentional, and was given explicit instructions to create a separate API token and apply a workaround involving swapping out the key.

I still believe this is less-than-ideal behavior.

My understanding is that Hydrogen is supposed to be relatively friction-less, and this seems like an unnecessary speed bump. It conflicts with the setup instructions of using h2 link for development and just generally makes things more complicated than it could be.

I've attached the support response with some things omitted/redacted here for reference:

Shopify Support Response

I’ve reviewed the error log you provided regarding the ProductVariant query. I want to reassure you that there is no mistake in your GraphQL fragment code. You have run into a specific permission requirement introduced in the Storefront API 2024-10 release.

The Issue:
The error Access denied for shopPayInstallmentsProductVariantPricing field occurs because the Storefront API token your Hydrogen app is using lacks the specific scope required to read these new fields. As noted in the release documentation:

"We’ve added ShopPayInstallmentsPricing fields to the Shop and ProductVariant types… These require the unauthenticated_read_shop_pay_installments_pricing access scope."

How to Resolve This:

To fix this, we need to ensure you are using a Custom App token that has this specific scope enabled. Please follow these steps:

Navigate to Custom Apps:
Go to your Shopify Admin > Settings > Apps and sales channels > Develop apps.
Select or Create the App:
Open the Custom App that your Hydrogen storefront is currently using (or create a new one specifically for Shop Pay).
Configure Scopes:

Go to Configuration > Storefront API integration.
Search for and select the unauthenticated_read_shop_pay_installments_pricing scope.
Note: Ensure standard scopes like unauthenticated_read_product_listings are also selected.

Update Your Environment:

Save the configuration and click Install app (or re-install).
Copy the new Storefront API Access Token.
Update the PUBLIC_STOREFRONT_API_TOKEN (or PRIVATE_STOREFRONT_API_TOKEN) in your Hydrogen project's .env file.

Code Verification:
Ensure your Hydrogen client is initializing with the updated token in your server.js (or client creation file):

import {createStorefrontClient} from '@shopify/hydrogen';
 
const storefront = createStorefrontClient({
storeDomain: process.env.SHOPIFY_STORE_DOMAIN,
publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN, // Token with the new scope
});
 

Next Steps & Support Action:
If you navigate to the Custom App configuration and do not see the unauthenticated_read_shop_pay_installments_pricing checkbox in the list of available scopes, this means it is currently gated for your specific shop.

If the scope is missing from your list:
Please reply to this email confirming that you have created the Custom App. Once confirmed, I can manually request our technical team to activate the unauthenticated_read_shop_pay_installments_pricing scope for that specific app on your backend.

Additional Resources:

[Storefront API 2024-10 Release Notes](https://shopify.dev/docs/api/release-notes/2024-10)
[ShopPayInstallmentsProductVariantPricing API Doc](https://www.google.com/search?q=https://shopify.dev/docs/api/storefront/latest/objects/ShopPayInstallmentsProductVariantPricing)

[kdaviduik]

Hey @john-parton! This definitely isn't ideal, and in this situation we will be updating the API permissions listed in the Hydrogen channel so that you can set unauthenticated_read_shop_pay_installments_pricing how you'd like. No need for a custom app here!

We will get this updated in the Hydrogen channel, but in the meantime I think this should work as a workaround:

(TLDR: copy the mutation network request as cURL, then manually add the scope to the payload and submit the cURL request)

1. Go to the Storefront API settings page in the Hydrogen channel
2. Update one of your SF API permission scope while you have the network tab open in your browser's developer tools. The specific update you do doesn't matter (ie: you can add a permission scope then immediately revoke it) - the goal here is just to send this specific GraphQL mutation with the network tab open
3. Find this GraphQL mutation network request, and copy as cURL
4. Paste this somewhere, and manually update the scopes to include unauthenticated_read_shop_pay_installments_pricing

eg:

  --data-raw '{"operationName":"UpdateApiPermissions","variables":{"scopes":["unauthenticated_read_product_listings","unauthenticated_read_shop_pay_installments_pricing","unauthenticated_read_product_tags","unauthenticated_read_product_pickup_locations","unauthenticated_read_customers","unauthenticated_write_customers","unauthenticated_read_customer_tags","unauthenticated_read_content","unauthenticated_read_checkouts","unauthenticated_write_checkouts","unauthenticated_read_selling_plans","unauthenticated_read_metaobjects"]},.................}}}'

5. With unauthenticated_read_shop_pay_installments_pricing added to the list of scopes, submit the cURL request from your terminal.