Theme developer guide
This guide is for theme developers and agencies working on a Shopify store that uses Price History. It describes the app as it works on 18 November 2026: what its theme app blocks render, every setting, how they react to the shopper, and which parts are a stable surface for your theme. Anything not listed as supported is internal and may change without notice.
Which blocks does Price History add?
Section titled “Which blocks does Price History add?”Three theme app blocks, all for product pages:
| Block | What it shows |
|---|---|
| Price note | A “Lowest price in 30 days” badge and a “Prior cheapest price” note for the selected variant. |
| Price history: On page | The price history panel on the page: range tabs and a chart, a 30-day summary and a list of price changes. Behind a “Price history” button or always open. |
| Price history: Side panel | A text link, pill or button that opens the same price history panel in a panel that slides in from the side. |
Merchants add them in the theme editor like any other app block. There is no app embed. A page can hold any number of these blocks, and each one works on its own: the badge and the note are only in the Price note block, and the chart, summary and list are only in the two Price history blocks.
Where can the blocks go?
Section titled “Where can the blocks go?”On product templates only, in any section that accepts app blocks: usually the product information section, or an Apps section on the product template. They can’t be added to other templates, to collection pages or to product cards.
For a block to follow the shopper’s variant choice, the page needs a product form with a variant field, or a theme event (see How do the blocks follow a variant change?).
What does the Price note block show?
Section titled “What does the Price note block show?”Up to two parts, for the selected variant in the shopper’s currency. Either, both or neither can show.
- The badge, “Lowest price in 30 days”. It shows when today’s price is the lowest of the last 30 days, something in those 30 days was higher, and the variant’s recorded history covers all 30 days. The prices counted are the one in place when the 30 days began, every change since, and today’s live price. Crossed-out (compare-at) prices and prices the merchant has hidden never count.
- The note, “Prior cheapest price {price} ⓘ”. It shows when the variant has a crossed-out price above its price, the prior price is known, and the crossed-out price differs from it. The prior price is the lowest price in the 30 days before the current reduction began; in a sale that drops in steps, before the first step. The reduced price itself never counts. The merchant can also choose to show the note whenever there’s a crossed-out price. Tapping or clicking the line, pointing at the ⓘ, or reaching the line with the keyboard opens the ⓘ’s explanation: “The lowest price we charged in the 30 days before this price cut.” When the history doesn’t reach back 30 days before the reduction, the explanation instead says it’s the lowest price recorded, and names the date tracking began.
Where each part shows is set on the app’s Storefront page, for the whole store:
- The badge: on, in every country, unless the merchant changes it.
- The note: on, for shoppers in the EU and EEA (AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK), unless the merchant adds countries, chooses every country or turns it off.
The shopper’s country is Shopify’s localization.country. When neither part applies, the block renders an empty element, which keeps a 0.5rem top and bottom margin.
What are the Price note block’s settings?
Section titled “What are the Price note block’s settings?”| Setting | Options | Default | What it does |
|---|---|---|---|
| Badge and note | Badge above the note, or Side by side when there’s room | Badge above the note | Side by side wraps to two lines when space is narrow. |
| Alignment | Left, Center, Right | Left | Aligns the text, and the two parts when side by side. |
| Badge › Background | Colour | #1d6b3a |
The badge’s background. |
| Badge › Text | Colour | #ffffff |
The badge’s text. |
| Prior cheapest price › Text colour | Colour | None (the theme’s text colour) | The note’s text. |
The wording of the badge, the note and the ⓘ explanation is set on the app’s Labels page, not in the theme editor.
What does the price history panel show?
Section titled “What does the price history panel show?”Both Price history blocks show the same panel, for the selected variant in the shopper’s currency:
- Range tabs: 1M, 3M and 1Y. 3M appears when the variant’s history reaches back 90 days and the Storefront page lets shoppers see at least 3 months; 1Y when it reaches back 365 days and shoppers may see 12 months. With only 1M available, there are no tabs and the chart covers 30 days. The longest available period opens first. The tabs change the chart only.
- The chart. A step line of the listed price over the period, ending today, with the area under it shaded in the accent colour. The period’s highest and lowest prices are labelled inside the chart on dashed lines, with the start date and “Today” beneath. During a price cut (a crossed-out price above the price), for shoppers in the note’s countries while the note is turned on, a third dashed line marks the prior cheapest price, if it’s known and falls between the highest and lowest with room for its label. Pointing at or tapping the chart shows a price, the date it began (with the time when two prices began the same day) and its label, such as “Sale”. The price already in place when the period began is drawn from the start, and the last price runs on to today.
- The 30-day summary. Always the last 30 days, whichever tab is open. Up to three sentences: how the price ranged over those days (or how long it has been steady), today’s price and whether it’s the lowest of the 30 days (by the badge’s rule, so the two always agree), and, during a price cut, the prior cheapest price: for shoppers in the note’s countries while the note is turned on, if it’s known, even when the crossed-out price equals it. Then a footnote: “Prices are the listed price, before discount codes and shipping.” In a converted currency the footnote adds that prices are converted from the store’s currency at each price change.
- The change list (off by default). Newest first, from the period shoppers can see, always including the latest recorded price. A price that repeats the one below it shows once, from the date it began. Each row shows the date, the merchant’s label if any, and the price; the time too when two changes fall on the same day. Ten rows to a page, with ‹ and › arrows.
When it shows is set on the app’s Storefront page, for the whole store:
- Countries: every country, unless the merchant chooses some.
- How far back shoppers can see: 12 months, or 3 months, or 1 month. The tabs and the change list stay within it.
- Hidden when the price hasn’t changed in that time: on. A price that hasn’t moved shows no panel.
The panel also needs at least one recorded price for the variant in the shopper’s currency, and at least one of the chart, summary or list turned on. When it doesn’t show, the block renders an empty element with no height of its own (the theme’s spacing around blocks still applies); for the Side panel block this means the trigger isn’t shown either.
What are the “Price history: On page” block’s settings?
Section titled “What are the “Price history: On page” block’s settings?”| Setting | Options | Default | What it does |
|---|---|---|---|
| Show the chart and list | Behind a button, or Always open | Behind a button | Behind a button puts the panel inside a “Price history” disclosure (a native <details>). Always open shows it on the page with a “Price history” heading. |
| Accent colour | Colour | #1a73e8 |
The chart’s line and shading, the range tabs and focus outlines. |
| Show chart | On or off | On | The range tabs and chart. |
| Show the 30-day summary | On or off | On | The summary sentences and footnote. |
| Show change list | On or off | Off | The list of price changes. |
| Max prices in the list | Number | Empty (all, up to 100) | Only shown when the list is on. 0 also means all. |
| Link the chart and change list | On or off | Off | Only shown when the chart and the list are both on. Pointing at a row lights its point on the chart, and the other way round. |
| Font size (px) | Number | 14 | The panel’s base size; everything in it scales with it. Kept between 10 and 32. Empty or 0 means 14. |
What are the “Price history: Side panel” block’s settings?
Section titled “What are the “Price history: Side panel” block’s settings?”| Setting | Options | Default | What it does |
|---|---|---|---|
| Style | Text link, Pill or Button | Pill | The trigger’s look. A pill is fully rounded. |
| Accent colour | Colour | #1a73e8 |
The chart and tabs, and the trigger’s background unless set below. |
| Button or link › Background | Colour | None (the accent colour) | Hidden for a text link. |
| Button or link › Text | Colour | None (white on a pill or button, the accent colour for a text link) | |
| Button or link › Font size (px) | Number | 14 | Kept between 8 and 48. Empty or 0 means 14. |
| Button or link › Padding left and right (px) | Number | 20 | Kept between 0 and 64. Hidden for a text link, which has no padding. |
| Button or link › Padding top and bottom (px) | Number | 10 | Kept between 0 and 64. Hidden for a text link. |
| Button or link › Margin top (px) | Number | 0 | Kept between 0 and 64. |
| Button or link › Margin bottom (px) | Number | 0 | Kept between 0 and 64. |
| Button or link › Corner radius (px) | Number | 8 | Button only. Kept between 0 and 64; 0 gives square corners. |
| Panel › Show chart | On or off | On | As On page. |
| Panel › Show the 30-day summary | On or off | On | As On page. |
| Panel › Show change list | On or off | Off | As On page. |
| Panel › Max prices in the list | Number | Empty (all, up to 100) | As On page. |
| Panel › Link the chart and change list | On or off | Off | As On page. |
| Panel › Background | Colour | #ffffff |
The panel covers the page, so it has its own colours rather than the theme’s. |
| Panel › Text | Colour | #1f2124 |
|
| Panel › Font size (px) | Number | 14 | Kept between 10 and 32. Empty or 0 means 14. |
The trigger is a <button type="button">, so it’s safe inside a product form. Its text is the panel’s title, “Price history”, which the merchant can reword on the Labels page (“Price history button”). The panel is a modal dialog that slides in from the right, or from the left in right-to-left languages: 90% of the screen’s width, up to 600px. Escape, the ✕ button or a click on the dimmed page closes it. In browsers with CSS :has(), the page behind doesn’t scroll while it’s open.
What do empty and transparent settings do?
Section titled “What do empty and transparent settings do?”In all three blocks, a colour left empty, or set to transparent or nearly transparent, uses the default shown above. In the theme editor, clearing a number box sets it to 0: for font sizes that means the 14px default, and for padding, margins and corner radius it means 0.
How do the blocks follow a variant change?
Section titled “How do the blocks follow a variant change?”They follow the variant the shopper picks, without a page reload, when the theme keeps its product form’s variant field up to date.
- Each block is drawn for one variant: the product’s selected or first available variant when Shopify renders the section.
- The script reads the selected variant from the field named
idin a form whoseactioncontains/cart/add: in the block’s own section first, then anywhere on the page. A form with aproduct-idfield naming another product is skipped. A<select>, a group of radio buttons or a hidden input all work. - It notices a change from a
changeevent on that field, a change to the field’svalueattribute, the field or form being replaced, andpopstateandpageshow. It also listens for ashopify:product:selectevent on the document, withproductandpromiseproperties on the event itself:product.idis the product’s GID, andpromiseresolves to an object whosevariant.idis the variant’s GID. The event is used only when the page has no product form variant field holding a variant id; the form field always wins. - If the theme has already redrawn the block for that variant, for example by re-rendering the whole product section, nothing more happens.
- Otherwise, the Price note block switches its note at once when the page already carries the new variant’s (it does for most reduced variants), else hides it, and hides its badge until the new copy arrives. The script then fetches the block’s section for the new variant from the store’s own domain, through Shopify’s Section Rendering API, using the current page’s path with
?variant=<id>§ion_id=<section id>. One request per section and variant serves every Price History block in that section. Only Price History’s own blocks are swapped in; the theme’s elements are never touched. - The latest choice wins. An earlier request is cancelled, or its late answer ignored. An open panel stays open and the chosen chart period stays chosen. If keyboard focus was inside the block, it moves to the new copy’s button, link or note line, or to the block itself.
- If the fetch fails, or the section comes back without the block for that variant, a Price history block hides its chart, summary, list and trigger rather than show the previous variant’s, until the shopper picks again. The Price note block keeps the note it switched to (or none) and leaves the badge hidden.
While the new copy loads, the block’s outer element has aria-busy="true".
If your theme changes the variant by script, update the field’s value and dispatch a change event on it.
How do currency and country changes work?
Section titled “How do currency and country changes work?”The blocks render for the shopper’s currency (Shopify’s cart.currency) and country (localization.country). When the shopper changes either through the store’s country or currency selector, the page loads again and the blocks render for the new choice.
- History is kept per currency. Only the shopper’s currency’s history is shown, never another currency’s. A currency with no recorded prices for the variant shows no panel, badge or note.
- Converted currencies. In a market whose prices Shopify converts from the store’s currency, the price is recorded in that currency at each change of the store-currency price. Exchange-rate movements between changes aren’t recorded, and the summary’s footnote says so. For the badge, today’s live price stands in for the recorded one, so exchange-rate movement alone never counts as a price drop. Whether a converted crossed-out price differs from the prior price is decided in the store’s currency.
- Prices are formatted with Shopify’s
moneyfilter, in the store’s money format. Currencies without decimals, such as JPY, are handled. - The country decides what shows, by the Storefront page’s lists for the badge, the note and the panel.
What can a theme safely style or rely on?
Section titled “What can a theme safely style or rely on?”Use the block settings first. Beyond them, your theme can rely on the CSS custom properties and classes listed as supported here. Everything else is internal.
Which CSS custom properties are supported?
Section titled “Which CSS custom properties are supported?”| Property | Set by setting | Default | Affects |
|---|---|---|---|
--ph-accent |
Accent colour | #1a73e8 |
The chart’s line, shading and dots, the range tabs, the On page “Price history” button’s text, the change list’s label tags, focus outlines, and the side panel trigger’s background unless set. |
--ph-fs |
On page › Font size | 14px |
The On page panel’s base size. |
--ph-badge-bg |
Badge › Background | #1d6b3a |
The badge’s background. |
--ph-badge-fg |
Badge › Text | #ffffff |
The badge’s text. |
--ph-note-fg |
Prior cheapest price › Text colour | The theme’s text colour | The note’s text. |
--ph-tip-bg |
None | #1f2124 |
The ⓘ explanation’s background and arrow. |
--ph-tip-fg |
None | #ffffff |
The ⓘ explanation’s text. |
--ph-btn-bg |
Button or link › Background | The accent colour | The side panel trigger’s background. |
--ph-btn-fg |
Button or link › Text | #ffffff (the accent colour for a text link) |
The trigger’s text. |
--ph-btn-fs |
Button or link › Font size | 14px |
The trigger’s text size. |
--ph-btn-px, --ph-btn-py |
Padding left and right, top and bottom | 20px, 10px |
The trigger’s padding. |
--ph-btn-mt, --ph-btn-mb |
Margin top, bottom | 0 |
The trigger’s margins. |
--ph-btn-radius |
Corner radius | 8px |
The Button style’s corners. |
--ph-sp-bg, --ph-sp-fg |
Panel › Background, Text | #ffffff, #1f2124 |
The side panel’s colours. In both Price history blocks, also the chart’s hover label (text and background, swapped) and the ring around its dots. |
--ph-sp-fs |
Panel › Font size | 14px |
The side panel’s base size. |
The blocks write their settings as inline custom properties on the block’s outer element (.ph-root). An inline value beats a theme rule on that same element unless the rule uses !important. Where a setting exists, changing the setting is the better route.
--ph-accent is declared on .ph-root by the stylesheet, so a value set on an ancestor, such as :root or the section, doesn’t reach the block. The other properties are only set when their setting has a value, so a value set on an ancestor applies whenever the setting is empty.
Which classes are supported?
Section titled “Which classes are supported?”| Class | Element |
|---|---|
.ph-root |
Every block’s outer element. Always rendered, even when there’s nothing to show, so a variant change has a place to draw into. Has no height when empty (the Price note’s keeps its 0.5rem margins). |
.ph-root--page |
The On page block’s outer element. |
.ph-pn |
The Price note block’s outer element (with .ph-root). |
.ph-pn--inline |
The Price note block set to Side by side. |
.ph-badge |
The badge. |
.ph-note |
The note, a <details> element. |
.ph |
The price history panel: on the page, or inside the side panel. |
.ph-sp__open, with .ph-sp__open--link, .ph-sp__open--pill or .ph-sp__open--button |
The side panel’s trigger and its style. |
.ph-sp |
The side panel, a <dialog>. |
The badge and the note are hidden with the hidden attribute when they don’t apply, and the stylesheet keeps them hidden with display: none !important, so a theme rule that sets display on them won’t make them reappear.
What is internal and may change?
Section titled “What is internal and may change?”- Every class not listed above, including the
ph__*classes inside the panel and theph-note__*andph-sp__*classes other than the trigger’s. - Every
data-ph-*attribute, includingdata-ph-root,data-ph-product,data-ph-variantanddata-ph-stale. - The JSON in
script[data-ph-lines]and the<style>rules the change list adds for paging and linking. - Custom properties not listed above, such as
--ph-hl,--ph-on,--ph-justify,--ph-sp-from,--ph-tip-arrow,--xand--y. - The order and nesting of elements inside the blocks.
- The view-count request and the session storage entry that goes with it.
Is there a JavaScript API or events?
Section titled “Is there a JavaScript API or events?”No. The block script has no global object or public functions and dispatches no events. It only listens, as described above. Shopify loads the script (price-history.js) and stylesheet (price-history.css) once per page, however many Price History blocks the page has.
Can a theme read the app’s metafields?
Section titled “Can a theme read the app’s metafields?”They exist, and a theme’s Liquid can read them, but they aren’t a supported interface. Use the blocks instead.
Price History keeps each variant’s recorded prices and a ready-made prior price in metafields in the app’s reserved namespace, and the store’s labels and settings in a shop metafield. Their format may change without notice. A theme reading them directly also bypasses the merchant’s choices on the Storefront page (countries, how far back, hiding an unchanged price) and the Free plan’s chosen products, which only the blocks apply.
Does Price History make requests when the page loads?
Section titled “Does Price History make requests when the page loads?”No. Everything the blocks show is drawn by Liquid when Shopify renders the page, from data stored in the store’s metafields. The script makes a request in only two cases:
-
A variant change the theme doesn’t redraw: one request to the store’s own domain per section and variant, as described above.
-
Counting a view, so the merchant can see how often shoppers look:
- when the shopper opens the panel (Behind a button, or the side panel), or once an Always open panel has been at least half on screen for one second;
- at most once per product per page, and once per product per visit;
- only with analytics consent from Shopify’s Customer Privacy API, which Shopify may load at that moment to answer;
- one
POSTto the store’s own domain, through the app proxy, atapps/pricehistory/viewunder the storefront’s root (so/apps/pricehistory/view, or/fr/apps/pricehistory/viewin a French storefront), with a small JSON body (sent astext/plain) carrying the product and the selected variant and no shopper data; - never in the theme editor;
- it never waits for an answer or shows an error.
With consent, the script keeps a note in the browser’s session storage that the product was counted this visit. Without consent, it reads and writes nothing on the shopper’s device.
The script is about 9.6 KB minified and the stylesheet about 19 KB. To render, Liquid reads the selected variant’s metafields; for shoppers the note applies to, the Price note block also reads a small metafield for each of the product’s other reduced variants (up to the 250 variants Shopify gives Liquid), so a variant change can show the right note at once.
How accessible are the blocks?
Section titled “How accessible are the blocks?”- They work without JavaScript. Behind a button is a native
<details>, the ⓘ explanation is a native disclosure (tap, click, Enter or Space), and the range tabs and list pages are radio buttons switched by CSS. The side panel opens without script in browsers that support button commands (commandandcommandfor); in others the script opens it. - The side panel is a modal dialog. Focus moves into it and stays there, Escape closes it, and focus returns to the trigger. It’s labelled by its title, the close button is named “Close” in the shopper’s language, and the trigger has
aria-haspopup="dialog". - The chart is an image with the accessible name “Price history chart”. Its price and date labels can be read; its hover points are hidden from screen readers. The summary describes the last 30 days in text, and the change list, when it’s turned on, gives each price.
- The range tabs are a radio group named “Chart period”. The list’s pages are radio buttons named by page number; the arrows are hidden from screen readers.
- The ⓘ is hidden from screen readers; its explanation is the disclosure’s content. Keyboard focus on the note’s line shows the explanation, and Escape closes it.
- The “Price history” title (the Always open heading and the side panel’s title) is a paragraph, not a heading, so it doesn’t change the page’s heading outline.
- Focus is always visible on the trigger, the close button, the tabs and the note’s line.
- Motion: with “reduce motion” set, the side panel appears without sliding.
- Contrast: the colours come from the block settings and the theme, so contrast depends on the merchant’s choices. The chosen tab’s text mixes the accent with the text colour, for more contrast than the accent alone; with the default accent and the side panel’s default colours it’s 6.6:1.
Which languages do the blocks support?
Section titled “Which languages do the blocks support?”Shopper-facing text comes in English and 27 more languages: Bulgarian, Chinese (Simplified, zh-CN, and Traditional, zh-TW), Croatian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian Bokmål, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish and Turkish.
- The language follows the storefront’s (
localization.language): the exact code (such asfr-CA) first, then the language (fr), then English. - Merchants can reword the texts on the app’s Labels page, in each of the store’s published languages, except four short ones: the chart’s screen-reader name, “Chart period”, “Today” and “Close”.
- Labels on prices: four built-in labels (Sale, Black Friday, Clearance and Price correction) come translated and can’t be changed. Merchants can add their own labels and translate them.
- The texts and the Storefront page’s settings are written to the store when the app is installed, and again whenever the merchant changes them. If writing them ever fails, the app tries again each time the merchant opens it; until then, the blocks show their built-in English.
- Dates use Shopify’s abbreviated date format in the shopper’s language, in the store’s time zone. Times, when shown, are 24-hour.
- Right-to-left languages: the side panel slides in from the left, and the list’s arrows are mirrored.
- The theme editor’s setting names and its preview messages are in English only.
What happens in the theme editor?
Section titled “What happens in the theme editor?”- Price note: when neither part applies to the product being previewed, the editor shows the parts that are turned on, with the product’s own price standing in for the prior price, and a line saying it’s a preview. If both parts are turned off, or the product isn’t one of the Free plan’s chosen products, a line says so instead.
- Price history blocks: when the panel wouldn’t show to shoppers, a short message says why, the first that applies: the product isn’t one of the Free plan’s chosen products; no price change has been recorded yet; it’s hidden for the previewed country; or the price hasn’t changed in the period shoppers can see.
- Side panel: selecting the block doesn’t open the panel, which would cover the trigger being styled. Click the trigger to open it. Deselecting the block closes it. When the panel wouldn’t show for the previewed product, the editor shows the message instead of the trigger, so preview a product whose price has changed to style it.
- Chart, summary and list all turned off: a Price history block shows nothing at all, in the editor too.
- No views are counted in the theme editor.
How does the Free plan’s limit show on the storefront?
Section titled “How does the Free plan’s limit show on the storefront?”On the Free plan, the blocks show only on the products the merchant has chosen in the app, up to 25. On any other product all three blocks render an empty element, and in the theme editor a line explains why. No products are chosen automatically, so a store on Free shows nothing until the merchant chooses some. On the Unlimited plan they show on every product. Prices are recorded for every product on both plans, so a product that’s chosen later, or a move to Unlimited, shows its full history.
Why might a block show nothing?
Section titled “Why might a block show nothing?”Check these, roughly in order:
- The store is open. Nothing is recorded while the store is behind its password page; products are first recorded on the daily check after it opens.
- The product is active and published to the Online Store. Prices are only recorded for products shoppers can buy. Existing products’ prices are recorded when the app is installed; a product published later is recorded by the daily check, within about a day. If its price changes before then, the changed price is the first one recorded.
- The price has changed. With the default “hide when the price hasn’t changed”, the panel waits for a change in the period shoppers can see.
- The badge needs 30 days of history. The note needs a crossed-out price above the price and a price recorded before that reduction began, so a sale already running when the app was installed shows no note until a later reduction.
- The shopper’s country is in the Storefront page’s list for that part.
- On the Free plan, the product is one of the chosen products.
- The shopper’s currency has recorded prices for that variant.
What are the known limitations?
Section titled “What are the known limitations?”- Product pages only. The blocks can’t be placed on collection pages, search results or product cards.
- Listed prices only. Discount codes, automatic discounts and shipping aren’t part of the history, the badge or the prior price.
- Up to 12 months of history, and only as far back as the Storefront page allows shoppers to see.
- Converted currencies are recorded at each price change, not as exchange rates move.
- Products with more than 250 variants: for variants past the 250 that Shopify gives Liquid, the note switches only once the section has been fetched, not at once.
- Browsers without CSS
:has()show only the chart that opens first (the longest period), without tabs; every row of the list, without pages or chart linking; and don’t stop the page behind the side panel from scrolling. - Without JavaScript, the side panel opens only in browsers that support button commands, and the blocks don’t follow a variant change.
- Quick view: if a theme shows the product section on another page, such as a collection page, a variant change there may hide the chart instead of updating it, because the section is fetched from the current page’s address.
- View counts need the shopper’s analytics consent, and stop if the merchant renames the app proxy’s path.