Section Rendering API: ?sections= and ?section_id=
Fetch the HTML of up to five Shopify theme sections with ?sections= or one with ?section_id=, in the context of any page, to update content without a reload.
- Several
- ?sections=a,b (JSON, max 5)
- One
- ?section_id=a (HTML)
- Context
- The URL you call
- Plan
- Every plan
- Last checked
In short
Append ?sections=<id>,<id> to any storefront URL and Shopify returns JSON with the rendered HTML of up to five sections, in the context of that page; ?section_id=<id> returns one section as plain HTML. Themes use it to refresh a product grid after filtering, paginate without a reload or update the cart drawer. Query parameters such as q and page still apply. Section IDs come from section.id.
How to use it
- Find the section ID: {{ section.id }} in Liquid, or the id="shopify-section-…" wrapper in the HTML.
- Request it on the page whose data it needs: /collections/summer?sections=<id>&page=2.
- Replace the element shopify-section-<id> with the returned HTML.
- For cart changes, pass sections in the /cart/add.js or /cart/change.js call instead (bundled section rendering).
Code
refresh-section.js// Re-renders one section in the context of the current page (for example a
// product grid after a filter change) without reloading the page.
// A section that fails to render comes back as null with HTTP 200.
async function refreshSection(sectionId, search = window.location.search) {
const params = new URLSearchParams(search);
params.set('sections', sectionId);
const response = await fetch(`${window.location.pathname}?${params}`);
if (!response.ok) throw new Error(`Section Rendering API: HTTP ${response.status}`);
const sections = await response.json();
const html = sections[sectionId];
if (html == null) throw new Error(`Section ${sectionId} did not render`);
document.getElementById(`shopify-section-${sectionId}`).outerHTML = html;
}
refreshSection('template--5678__main').catch((error) => console.error(error.message));
urls.txt# Up to five sections as JSON, rendered in the context of the page you call
https://your-store.com/?sections=header,footer
https://your-store.com/collections/summer?sections=template--5678__main&page=2
https://your-store.com/products/example-product?sections[]=template--5678__main§ions[]=sections--1234__header
# One section as plain HTML (404 if the section ID doesn't exist)
https://your-store.com/products/example-product?section_id=template--5678__main
# Section IDs
static section file sections/social.liquid -> social
JSON template section -> template--5678__image_banner
section group section -> sections--1234__header
in Liquid: {{ section.id }} in HTML: id="shopify-section-<section ID>"
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- Sections in JSON templates and section groups have generated IDs such as template--5678__main; read them from section.id rather than hardcoding.
- A section that fails to render comes back as null with HTTP 200 in ?sections=; ?section_id= returns 404 for an unknown ID.
- You can’t pass setting values; the section renders with its saved settings or defaults.
- Build URLs from Shopify.routes.root or location.pathname so the market’s language path is kept.
Questions
- How do I reload one section in Shopify without reloading the page?
- Fetch the page URL with ?sections=<section id> and swap the returned HTML into the shopify-section-<id> element.
- How many sections can I request at once?
- Up to five with the sections parameter, in the same request.
- What is the difference between sections and section_id?
- sections returns JSON for one to five sections; section_id returns one section as plain HTML.
- Where do I find the section ID?
- In Liquid it’s section.id. In the page HTML it’s the part after shopify-section- in the wrapper’s id. For a static section it’s the file name.
Shopify documentation
- Checked on a Shopify store on the date shown. Shopify changes its admin often; if a step looks different, the idea usually still works.
- Examples use placeholder IDs and your-store.myshopify.com. Replace them with your own.
- MIT license for the code snippets.
Need this built, tested and maintained for your store? See Shopify development.
