Section rendering API​

Use the section rendering API to fetch HTML for theme sections through AJAX requests. This enables you to update page content dynamically by obtaining and replacing specific elements without reloading the entire page.

For example, you can implement pagination for research results using the section rendering API, allowing for page changes without a full page reload when switching between pages.

Request sections​

You can use the sections query parameter to render specific page sections. The values of sections are unique IDs to identify sections. See Obtain section IDs for how to get values of sections. The sections query parameter is a list of IDs separated by commas, as shown in the following example:

?sections=header,footer

You can render sections on any page position by appending the sections parameter to any page URL. For example, you can query for the following recommended products and render them on a certain page position:

• Query for recommended products on the homepage: /?sections=product-recommendations.
• Query for recommended products on a specific product collection page: /collections/featured?sections=product-recommendations

The response for the API is a JSON object, including the IDs and HTML files for each section. Refer to Example for a response sample.

Example​

The following code sample requests and renders two sections of header and footer using the JavaScript fetch method:

fetch('/?sections=header,footer').then((response) => {
    const renderSections = response.json();
    
    const headerHtml = renderSections.header;
    const footerHtml = renderSections.footer;
})

The example of the API response is as follows:

{
  "header": "<div id=\"shopline-section-header\" class=\"shopline-section\">\n<!-- section content -->\n</div>",
  "footer": "<div id=\"shopline-section-footer\" class=\"shopline-section custom-footer\">\n<!-- section content -->\n</div>"
}

Error codes​

Sections that fail to be rendered, such as due to non-existent themes, will return null in JSON response. The response may have an HTTP 200 status code, but still contain one or more sections with null values. Be prepared to handle situations when null values are returned.

Request a single section​

If you want to render a single section, you can use the section_id and sections query parameters to request the section. However, it is highly recommended that you use section_id to request a section.

?section_id=header

Similar to sections, you can usesection_id to render a single section at any position on a page. If you use the section_id parameter to request a section, HTML files for the section are returned.

<div id=\"shopline-section-header\" class=\"shopline-section\">\n<!-- section content -->\n</div>

Obtain section IDs​

You can obtain section IDs through the following ways:

• Use Handlebars to obtain section IDs.
• Extract section IDs from ID attributes in a section's HTML code.

Extract section IDs from ID attributes​

You can obtain a section ID from the ID attribute in a div element that represents a section. Take the following HTML snippet for example, you can extract the section ID from [section-id].

<div id="shopline-section-[section-id]" class="shopline-section">
  <!-- section content -->
</div>

If you add a new section to the JSON template, a unique ID is generated for the section. For example, if two product list sections are added to the same page, each will have a unique ID. This allows you to easily identify and work with each section.