Shopify just rolled out a subtle but powerful tweak to the Catalog API: every product variant now returns the merchant’s compare‑at price in a new list_price field. While the existing price field stays untouched, list_price gives you a reliable signal when a product is marked down and by how much. In this post we’ll unpack the change, identify who needs to pay attention, and show you how to start leveraging list_price in your apps, themes, or custom integrations.
Why This Update Matters
For developers, the Catalog API has long required you to infer a compare‑at price by cross‑referencing the price and the merchant’s storefront settings—a fragile process that broke in edge cases (e.g., regional pricing, hidden compare‑at displays). With list_price, the API does the heavy lifting for you, returning the exact compare‑at amount that the shopper would see, if any. This makes discount‑driven experiences—like price‑comparison widgets, dynamic badge generators, or AI pricing agents—more accurate and easier to build.
Who Is Affected?
*Developers* – Anyone pulling product data via the Catalog API (including the Global Catalog, Storefront API, or any private app that maps catalog data) will now see an optional list_price object on each variant. If you already expose compare‑at prices, you’ll receive them automatically; if you don’t, nothing changes.
*Merchants* – The change is transparent on the storefront. Shopify enables compare‑at sharing by default for most stores, so merchants who already show compare‑at prices will see no UI change. The only scenario where list_price is omitted is when a store has turned off compare‑at sharing (e.g., using compare‑at for MSRP or hiding it from certain regions). No action is required from merchants.
When Does list_price Appear?
A variant includes list_price only when three conditions are met:
price for the buyer’s context (currency, region, discount tier, etc.).list_price for those visitors.If any of those checks fail, the list_price field is simply omitted, signalling that there is no visible compare‑at price for that buyer.
Technical Details & Data Shape
list_price follows the same schema as the existing price object: it contains an amount (in minor units) and a currency_code. The API also surfaces a list_price_range at the product level, which aggregates the lowest and highest list_price across all its variants. This mirrors the existing price_range field and is useful for collection‑wide discount displays.
Example of a variant payload (truncated for clarity):
{\n "id": "gid://shopify/ProductVariant/1234567890",\n "price": {\n "amount": "1999",\n "currency_code": "USD"\n },\n "list_price": {\n "amount": "2499",\n "currency_code": "USD"\n }\n}
If the variant has no compare‑at price for the current buyer, the list_price key is simply absent.
How to Update Your Code
Most integrations already parse the price object, so adding list_price is a matter of a few defensive checks. Below is a minimal Node.js/JavaScript example using the GraphQL Catalog API endpoint.
js\nconst query = \n query GetProductVariants($ids: [ID!]!) {\n productVariants(ids: $ids) {\n id\n price { amount currencyCode }\n listPrice { amount currencyCode }\n }\n }\n;\n\nconst response = await shopify.graphql(query, { ids: variantIds });\n\nresponse.productVariants.forEach(v => {\n const price = Number(v.price.amount) / 100;\n const listPrice = v.listPrice ? Number(v.listPrice.amount) / 100 : null;\n\n if (listPrice && listPrice > price) {\n const discount = ((listPrice - price) / listPrice) * 100;\n console.log(${v.id} is on sale – ${discount.toFixed(1)}% off);\n } else {\n console.log(${v.id} has no compare‑at price);\n }\n});\n
Key takeaways from the snippet:
listPrice may be null – always guard against missing data.Do You Need to Take Action?
For the majority of apps and agents, no immediate changes are required. The API will include list_price when applicable, and existing logic that ignores unknown fields will continue to work. However, consider the following optional steps to unlock the full potential of the new field:
list_price attribute to your variant schema so you can store and query it later.list_price directly instead of calculating it from merchant settings. This eliminates edge‑case mismatches.list_price respects the buyer’s context. If you serve multiple regions, test that the field appears (or not) as expected for each locale.list_price is part of the UCP catalog specification version 2026‑08‑25. Ensure your app is using a compatible version or newer to avoid missing the field.Testing the New Field
You can verify the presence of list_price in a sandbox store by:
/admin/api/2026-08/catalog/variants.json endpoint) for that variant.list_price object matching $30.If the field is missing, double‑check the store’s Catalog Mapping settings and regional display preferences.
Conclusion & Next Steps
Shopify’s addition of list_price to the Catalog API is a small change with a big payoff: developers can now reliably surface compare‑at prices without extra heuristics, and merchants get more consistent discount signals across apps. While no urgent migration is needed, updating your data models and UI to consume list_price will future‑proof your integrations and improve the shopper experience.
Ready to put the new field to work? Grab the latest API version, add list_price to your variant schema, and start highlighting markdowns in your storefront or dashboard today. Need help customizing your integration? Reach out to our Shopify developer community or drop a comment below!
