Executive summary
- What: The Catalog API now returns a merchant's compare-at price as listprice on each product variant, with a matching listprice_range at the product level. The existing price field is untouched.
- Why: Apps and AI shopping agents can now calculate markdown depth from the API itself rather than inferring it or scraping a storefront.
- Who: App and agent developers reading Shopify Catalog data. No merchant action is required, though the field only appears when catalog mapping permits it.
What changed
listprice is an optional field in the UCP catalog specification, version 2026-08-25. It uses the same Price object shape as price, with an amount in minor units and a currency code. Products also return listpricerange, covering the lowest and highest listprice across their variants.
Three conditions must all hold before a variant carries the field. The merchant has to be sharing compare-at prices through Catalog Mapping in the Shopify admin, which Shopify enables by default for most stores and disables for stores that use compare-at as an MSRP or other reference price. The compare-at price has to exceed price for that buyer's context. And the merchant has to show compare-at prices in the buyer's region, so stores that hide them from EEA buyers return nothing to those buyers.
When list_price is absent, the correct reading is that there is no compare-at price to show for that buyer and that configuration. It is not a signal that the product is full price everywhere.
Why it matters
For merchants, this is the point at which promotional pricing becomes legible to agentic channels. An AI assistant comparing two suppliers can now see that one is thirty percent off list rather than treating both as flat prices. Discount visibility has been a quiet disadvantage for brands that run structured promotions, and this closes part of that gap.
The conditional nature of the field is the part that needs attention. Any integration that assumes list_price is always present for a discounted item will produce inconsistent output across regions and across merchants. Build the absent case as a first class state, not an error.
There is also a data governance angle. If your organisation uses compare-at to carry MSRP rather than a genuine prior price, Shopify's default is to suppress the field, and that default is correct. Confirm it rather than assume it. Teams managing wide assortments across channels will recognise this as the same discipline described in our notes on handling large catalogs and high order volume.
Role-specific impact
- Marketers: Promotional pricing can now reach agentic surfaces as a visible markdown. Check that the compare-at values in your catalogue reflect a defensible prior price rather than an aspirational one.
- Developers: Read listprice and listprice_range as optional. Derive discount percentage at render time rather than storing it, and handle a missing field as a valid state instead of a failure.
- Store admins: Verify the Catalog Mapping compare-at setting matches how your business actually uses the field. Spot check regional behaviour if you suppress compare-at prices for EEA buyers.
Use-case example
Real-world scenario
A footwear brand runs a seasonal clearance with compare-at prices set on roughly four hundred variants. Before this change, an agent surfacing those products showed only the current price, so a pair reduced from 180 to 126 looked identical in kind to a full price pair at 126.
With list_price exposed, the same agent can present a 30 percent reduction. On an assortment where clearance drives a meaningful share of units, the practical effect is that promotional inventory competes on its actual discount rather than on absolute price alone.
Implementation checklist
- Confirm whether your store shares compare-at prices through Catalog Mapping in the Shopify admin, and whether that default is right for your pricing model.
- Audit compare-at values across the catalogue for accuracy, since they are now consumed outside your own storefront.
- Update any app or agent integration to read listprice and listprice_range as optional fields.
- Compute discount percentage from price and list_price at presentation time rather than persisting a derived value.
- Test with a buyer context in a region where compare-at prices are hidden, and confirm your output degrades cleanly.
- Document the absent field case for whoever maintains the integration next.
FAQ
Q: Does the price field change in any way?
A: No. price continues to return the current selling price for the buyer's context. list_price is purely additive, which is why Shopify states that no action is required.
Q: Why would a discounted variant still return no list_price?
A: Most often because Catalog Mapping is set not to share compare-at prices, or because the buyer is in a region where your store hides them. Check the admin setting first, then the buyer context.
Resources
Global Catalog responses on shopify.dev
Need guidance? Talk to Makro.