How the Shopify Catalog API Ranks Products: What's Documented and What Isn't

When an AI assistant or a shopping app queries Shopify's Catalog API with "trail running shoes under $100," it gets back a ranked list. Some products surface, most don't, and if yours are in the second group you will never see an error message about it.

So what actually determines the list? The honest answer has two halves. Shopify documents the plumbing: what the API accepts, what it filters on, and what it returns. Shopify does not document the ordering: there is no published ranking algorithm. This post walks the documented half, because that's the half you can act on, and flags clearly where the documentation stops.

First, what's being queried

The Catalog API is the interface to Shopify's Global Catalog, the cross-merchant product index we broke down in the Global Catalog guide. Apps and assistants call search_catalog with keywords, get back product groupings, and can fetch details and checkout links per product. Your storefront is not consulted at query time. The catalog's copy of your product is the only version of you in the room.

That copy is built from your product data and then filled in by Shopify's inference. The docs are candid that some fields "might be inferred by Shopify's AI" with varying accuracy. Keep that phrase in mind; it explains more visibility problems than any ranking theory does.

The gates: filters that run before relevance

The documented search parameters are worth reading like a merchant, not a developer, because each one is a gate your product either passes or doesn't:

• Category. Queries can be filtered by taxonomy category ID. If Shopify's catalog has you filed under the wrong category, a category-filtered query excludes you outright. Relevance never gets a vote. This is why the product taxonomy is now a ranking factor.
• Price bounds. Min and max price filters run against the catalog's recorded price. If that price is stale, you can be excluded from a range you actually sit inside, or included in one you don't.
• Availability. The search defaults to returning only products available for sale. Stale stock data doesn't just embarrass you; it can remove you.
• Shipping. Queries can filter by ship-to and ship-from country. Incomplete shipping data narrows the geography you're even considered for.
• Condition. Secondhand items can be included or excluded per query.

None of this is speculation; it's the parameter list. And notice what it implies: before any ranking happens, your visibility is a data-accuracy problem. The gates read the catalog's copy of your category, price, stock, and shipping, not your admin's.

The matching: what relevance runs on

Past the gates, the query text has to match your product. Shopify doesn't publish the matching internals, but the inputs are your fields: title, description, product type, category attributes, and the details Shopify inferred where you left blanks.

The practical consequences are the ones we've documented field by field in the product fields that decide your AI shopping rank. A title that names what the thing is beats a clever one. A description with real specifics (materials, dimensions, use cases, compatibility) matches the qualified queries real shoppers ask. Blank fields don't stay blank; they get inferred, and an inferred attribute is a guess wearing your product's name.

The clustering: one product, many sellers, one winner

The Catalog API returns universal products: groupings where the same item sold by multiple stores collapses into a single listing with competing offers underneath. When an assistant presents that listing, one offer leads. That selection is the agentic buy box, and it has its own dynamics, covered in how the Global Catalog picks between sellers and, in head-to-head detail, in two stores, same product, different outcome.

One documented detail deserves more attention than it gets: a product's displayed title, image, and price come from its "top-ranked variant." Ranked how? Not documented. What's clear is that the API elevates one variant to be the face of your product. If your variants are clean and coherent, that face is right. If they're a mess of legacy options and placeholder SKUs, the face a shopper sees is whichever one the machine promoted.

The decay: freshness

Everything above operates on a snapshot. The catalog re-indexes on Shopify's schedule, not yours, so there is always some lag between your admin and the copy being queried. Usually it's small. When it isn't, the catalog quotes an old price, an old stock level, or a pre-rewrite description, and every app built on it repeats the error in unison. We covered the mechanics and the mitigation in why data freshness decides what AI shopping tells buyers.

What this adds up to

Where Shopify hasn't documented ranking, we won't invent it, and you should be suspicious of anyone who does. But the documented layer alone gives you a clear playbook, in order of leverage:

1. Correct category, so the filters include you.
2. Accurate price, stock, and shipping data, so the gates read you right.
3. Specific titles and descriptions, so matching has something real to work with and inference has less to guess.
4. Clean variants, so the top-ranked variant shows the right face.
5. Freshness, so the snapshot the world reads is the store you actually run.

Eligibility plus data quality won't guarantee you the top position, and we won't pretend otherwise. It guarantees something more fundamental: that when the query you deserve to win comes through, you're in the room, described accurately, at the right price.

The fastest way to see which of the five you're failing is the free Catalog Readiness checker. It reads your store the way the catalog does and grades each layer in about a minute, no signup. If you'd rather see the exact per-product mismatches between your admin and the catalog's copy, that diff is precisely what AgentReady was built to run.