What the Catalog API now returns
Shopify's developer changelog states that the Catalog API now returns a merchant's compare-at price as a field named list_price on each product variant. Products also return list_price_range, which holds the lowest and highest list_price across the product's variants. According to the changelog, an app or agent can use list_price to tell when a product is marked down and by how much. The existing price field does not change, and the changelog states that no action is required.
Here is what that means in practice. A shopping agent that reads a Shopify catalog through this API no longer has to guess whether a price is a sale price. When list_price is present, the gap between it and price is the markdown. The field only appears when three conditions hold, though, and Shopify turns sharing off by default for some stores. The changelog also leaves presentation entirely to whoever builds the agent. This change gives markdown data a path to agents. It does not guarantee that discounts appear in AI answers.
The changelog states that list_price is an optional field defined in the UCP catalog specification, version 2026-08-25. It uses the same Price object as price: an amount in minor units plus a currency. The entry gives no effective date and no release label such as GA or beta. The present-tense wording (“now returns”) suggests the behaviour is live, but that is our reading, not a stated fact.
Three conditions decide whether an agent sees the markdown
Per the changelog, a variant includes list_price only when all three of the following are true. If any one fails, the field is absent.
| Condition | What the changelog states | Who it filters out (our read) |
|---|---|---|
| Merchant shares compare-at prices through Catalog Mapping | On by default for most stores. Off by default for stores that use compare-at for MSRP or another reference price | Stores Shopify classifies as reference-price users, plus any store that has turned sharing off |
| Compare-at is higher than price for the buyer's context | Compare-at must exceed price in that context | Variants where compare-at is blank, equal to price or below it for that buyer |
| Merchant shows compare-at prices in the buyer's region | Stores that hide compare-at from EEA buyers do not return list_price to those buyers | EEA buyers of stores that hide “was” prices there |
The changelog states that a missing list_price means the variant has no compare-at price to show for that buyer and configuration. Anyone consuming the API should therefore read an absent field as a real answer, not as an error. Per the changelog, how a UI or agent response handles the missing field is up to the developer.
Conditions two and three depend on who is asking. As a result, the same variant can look discounted to an agent shopping for one buyer and full-price to an agent shopping for another. The changelog does not define “the buyer's context.” Markets, currency, B2B catalogs and price lists are all plausible inputs, but the changelog names none of them.
Why the MSRP and EEA carve-outs exist
The most consequential detail in the entry is the default-off setting for stores that use compare-at for MSRP or another reference price. Many merchants put a manufacturer's suggested price in compare-at to frame value, even if the product never sold at that price. If an agent received that number as list_price, it would read as a genuine markdown. Our read is that the default-off guards against agents repeating discounts that never existed. The changelog does not say how Shopify identifies these stores. It could be a merchant declaration, a heuristic or something else.
The EEA rule looks consistent with EU price-indication rules on announced price reductions, which limit how a “was” price can be displayed. That is our inference. The changelog states the behaviour but gives no reason for it, and it does not say whether other regions are treated the same way.
Shopify has made markdowns machine-readable, then deliberately limited which markdowns count.
What it means for Shopify brands selling through agents
Some merchants gain clearly from this change: those who use compare-at for genuine markdowns, sell into regions where compare-at is shown, and have Catalog Mapping sharing turned on. Before, their discount existed only in the rendered PDP. Now it is a structured field that an agent can read from the catalog. An agent with only price could not tell a sale price from a regular one. With list_price, it can work out the discount without scraping the page.
An illustrative example: a variant has a price of 7900 and a list_price of 9900, both in USD minor units. An agent can read that as $20 off a $99 reference price, roughly 20 percent. That calculation is the whole value of the field, and it is only meaningful if the compare-at number is honest.
The field does not guarantee placement in answers. The source does not say which AI agents or surfaces consume the Catalog API or read list_price. It also says nothing about whether the field affects ranking or recommendation. Whether ChatGPT, Perplexity, Google AI Mode or any other agent mentions a markdown depends on how each one is built. Price is one input among many. Our breakdown of how AI engines pick which products to cite covers the others.
For brands that use compare-at as an MSRP anchor, the default-off means nothing changes unless sharing is turned on. For most of them, that is probably the right outcome.
What Shopify has not said
- When the Catalog API began returning
list_price, and whether it is generally available or still rolling out. - How Shopify decides which stores use compare-at for MSRP or a reference price, when that default was applied, and whether merchants were told.
- Where the Catalog Mapping compare-at setting is in the admin and what it is called. The changelog names Catalog Mapping but gives no navigation path.
- What “buyer's context” includes, how a store hides compare-at from EEA buyers, and whether any other region has a similar rule.
- How
list_priceappears in Global Catalog responses. The changelog links to that material, but it is not covered here. - Which agents read the field, and whether it is used only for display or also feeds recommendations.
- What else changed in version 2026-08-25 of the UCP catalog specification.
Until Shopify answers these questions, be wary of any claim that agents now show your sale prices.
What to do this week
- Check the Catalog Mapping setting. Confirm whether your store shares compare-at prices. Per the changelog, sharing is on by default for most stores and off for stores that use compare-at for MSRP or another reference price. Do not assume you know which group your store is in.
- Audit what compare-at actually holds. Export your variants and separate genuine former selling prices from MSRP or reference prices. If much of it is reference pricing, decide whether you want that number reaching agents as
list_price. For a catalog-wide pass, see how to audit a Shopify catalog for AI readiness. - Fix variants where a real markdown goes unseen.
list_priceis only returned when compare-at is higher than price for the buyer's context. A discounted variant with a blank compare-at, or one equal to price, sends nolist_price. - Review your EEA display settings. Per the changelog, if you hide compare-at from EEA buyers, agents serving those buyers will not receive
list_price. Confirm that this matches both your intent and your compliance position. - Audit by region. Any check of how a markdown reaches agents has to account for buyer region and context, so one pass is not enough. Pair it with a broader check of whether AI agents can read your PDPs, because the PDP and the catalog data should agree.
You don't need to do any of this to keep current behaviour. The changelog is explicit that price does not change and no action is required.
The strategic read
The field is small, but it says a lot about direction. Shopify is filling in a field defined in the UCP catalog specification, and its changelog names the spec version. Shopify's developer docs also list an Agents area with a link titled “Build agents with UCP.” Taken together, our read is that Shopify is closely following UCP field definitions in its catalog output. Teams monitoring how readable Shopify catalogs are to agents should expect more fields to arrive the same way: quietly, with “no action is required” attached. Our earlier coverage of the Global Catalog REST API shutdown and the move to UCP MCP and of multiple barcodes on Shopify variants points the same way.
The second point is about trust. Shopify could have exposed every compare-at value and left agents to sort it out. Instead, it set defaults that hold back reference prices and respect regional display choices. We expect agent platforms to rely more on structured discount data as it becomes trustworthy. If that happens, an accurate compare-at field becomes a matter of catalog quality, not just merchandising. Brands that have used compare-at loosely now have a concrete reason to clean it up.
Frequently asked questions
What is list_price in Shopify's Catalog API?
Shopify's changelog states that list_price is the merchant's compare-at price, returned on each product variant. It is an optional field defined in version 2026-08-25 of the UCP catalog specification. It uses the same Price object as price: an amount in minor units and a currency. Products also return list_price_range, which gives the lowest and highest list_price across their variants.
Why is list_price missing for some of my variants?
Per the changelog, list_price only appears when three things are true: the merchant shares compare-at prices through Catalog Mapping, compare-at is higher than price for the buyer's context, and the merchant shows compare-at prices in the buyer's region. When list_price is missing, the variant has no compare-at price to show for that buyer and configuration.
Does list_price mean AI agents will show my discounts?
Not necessarily. The changelog says an app or agent can use list_price to detect a markdown, but presentation is up to the developer. The source does not say which agents read the field or whether it affects recommendations.
Why does Shopify turn compare-at sharing off for some stores?
The changelog states that sharing is off by default for stores that use compare-at for MSRP or another reference price. It does not give a reason. Our interpretation is that the default keeps agents from presenting reference prices as genuine markdowns.
Do I need to change anything in my Shopify store?
No. The changelog states that no action is required and that the price field does not change. Still, merchants should check their Catalog Mapping setting and what their compare-at values actually represent.
Ask AI about this
Ask an AI engine how Shopify's new list_price field affects the way shopping agents read your markdowns.