Shopify Alt Text Audit Woes: Why Your /products.json Might Be Lying (and How to Fix It!)

Hey store owners!

Let's talk about something that might seem small but can have a huge impact on your store's SEO and accessibility: alt text. We all know it's crucial for describing images to search engines and visually impaired users. You diligently fill it in your Shopify admin, right? But what if I told you that a common way to audit your alt text coverage might be giving you completely false negatives?

This exact issue recently sparked a really insightful discussion in the Shopify community, and it's something I've seen trip up many merchants. Our fellow store owner, haimo, kicked off a thread because they noticed a puzzling discrepancy: their store's /products.json endpoint was returning alt: null for images that absolutely had alt text saved in the admin. Meanwhile, the actual product page (/products/{handle}) rendered the alt text perfectly!

"Same image. The rendered page has the description. The JSON says null," haimo pointed out. Imagine building an audit tool on that! You'd report a ton of 'missing' alt text, and your merchant would look at their live page and think your tool was broken. Not ideal, right?

The Root of the Discrepancy: Why /products.json Can Be Misleading

So, what's going on here? Is Shopify broken? Not exactly, but it's a nuance that's easy to miss. The community quickly chimed in to confirm that this isn't an isolated incident.

As haimo correctly theorized, and others like Daniel_Jude and Arslan_Shopify_Dev confirmed, the issue often stems from how themes handle alt text. Many Shopify themes use what we call "Liquid fallbacks." This means if an image's directly associated alt text is empty, the theme might automatically pull in the product's title, a metafield, or even compose a generic string to display something as alt text on the live page. So, the page shows alt text, but the underlying media object in the database might genuinely have a null value for its alt attribute.

Daniel_Jude even checked four live stores and found that /products.json consistently returned null for alt text, while /products/{handle}.js (another endpoint for individual product data) correctly returned the saved alt text. This strongly suggests it's a general Shopify behavior, not just a quirky theme.

Auditing Alt Text: The Community-Approved Best Practices

If /products.json isn't reliable for alt text values, what's the best way to get an accurate picture of your store's alt text coverage? The community discussion converged on a few powerful solutions, with a clear winner for bulk operations.

1. The Storefront API: Your Best Bet for Bulk Audits

This was the strongest recommendation from Arslan_Shopify_Dev (a Shopify Dev!) and JaumeG. The Shopify Storefront API is designed for exactly this kind of data retrieval, especially for headless setups or large catalogs. It directly returns the saved alt text value and is far more robust for bulk queries than hitting thousands of individual .js endpoints, which can lead to dreaded 429s (too many requests) or bot challenges.

You can query it for products and their images like this (using GraphQL syntax):


images { altText }

or for media objects:


media { ... on MediaImage { alt } }

The Storefront API gives you stable image IDs, URLs, and the actual saved alt value, making it ideal for a comprehensive and reproducible audit. It can fetch up to 250 products per page with a public token, making it highly efficient.

2. The /products/{handle}.js Endpoint (with caution)

If the Storefront API feels a bit too technical or you're dealing with a smaller catalog, the /products/{handle}.js endpoint for individual products can work. As Daniel_Jude and boliu_builds found, this endpoint *does* return the saved media alt. However, for a bulk audit, making thousands of individual calls can quickly hit rate limits. Boliu_builds even mentioned cross-checking /products.json against the .js endpoint before flagging "missing alt."

3. The Admin API (Authoritative Source)

Haimo also suggested the Admin API as an authoritative source for what's *stored*. This is absolutely true – if you're building an internal tool or have development resources, the Admin API provides the most direct access to your store's data, including accurate alt text values.

Understanding Your Alt Text Coverage: Beyond Just 'Missing'

JaumeG brought up an excellent point about classifying alt text, suggesting we move beyond a simple "present/missing" percentage. They proposed three states, which I think is brilliant:

  1. "Stored Alt": The media value for alt text is actually present in the database. This is what you want!
  2. "Fallback Only": The stored value is empty, but the rendered page displays meaningful alt text (likely from a theme fallback like the product title). This improves accessibility but isn't an intentionally written description.
  3. "Missing": Both the stored value and the rendered page have empty or generic alt text. This is where you need to focus your efforts.

Troubleshooting Individual Alt Text Discrepancies

Before diving into a massive audit, Lauren_Scott offered some great steps to confirm what's happening with individual images:

  1. Confirm the Image ID: In your Shopify admin, open the product's media section and find the image that matches the ID you're seeing in your JSON. Ensure the alt text is saved on that exact file. Sometimes, themes might swap variant images or use a different upload.
  2. View Page Source (Not Inspect Element): Open the product page in your browser, then view the page source (usually Ctrl+U or Cmd+Option+U). Search for the alt text. If it only appears within a theme section, a metafield, or as a hardcoded string, then the media alt is likely empty, and the API is reporting correctly.
  3. Check for Theme Swaps: If the alt text is correctly saved on the media, but the live page shows a *different* image or no alt text at all, your theme might be picking the wrong file or overriding the alt attribute.

The takeaway here is clear: while /products.json is handy for basic product counts, don't rely on it for accurate alt text values. For a proper audit, especially for larger stores, the Storefront API is your most reliable and scalable tool. It gives you the true picture of what's saved, allowing you to focus your efforts on improving accessibility and SEO where it genuinely matters. Happy auditing!

Share:

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools