How to Add Speculation Rules API in Shopify

November 3, 2025

Introduction
What is the Speculation Rules API?
Why Use the Speculation Rules API in Shopify?
Prerequisites Before Adding the API
Step-by-Step Guide to Adding Speculation Rules API in Shopify
Example Implementations
Common Mistakes and How to Avoid Them
Best Practices for Using the Speculation Rules API in Shopify
FAQs About Speculation Rules API in Shopify
Conclusion

1. Introduction

Performance is one of the most critical factors in driving conversions and improving SEO rankings for your Shopify store. Customers expect your pages to load almost instantly, and even a one-second delay can impact conversion rates significantly.

To address this, Shopify developers can take advantage of the Speculation Rules API, a new browser technology that helps preload, prefetch, or prerender key pages based on user intent. By using the Speculation Rules API in Shopify, you can dramatically speed up user journeys such as moving from a product page to checkout.

This article will walk you through everything you need to know about adding the Speculation Rules API to your Shopify store, including setup, examples, best practices, and common pitfalls.

2. What is the Speculation Rules API?

The Speculation Rules API is a browser API that allows developers to define rules for preloading or prerendering pages before the user even clicks a link.

Prefetching: Downloads resources or page data ahead of time.
Prerendering: Fully renders a page in the background so it loads instantly when the user clicks.

For example, if a customer hovers over the “Buy Now” button or is very likely to visit the checkout page, the browser can prerender the checkout in the background. When the customer clicks, it loads instantly.

3. Why Use the Speculation Rules API in Shopify?

Shopify stores often rely on speed and seamless navigation. Implementing the Speculation Rules API provides several benefits:

Instant page transitions: Checkout, cart, or product pages load almost immediately.
Higher conversions: Faster checkout = reduced cart abandonment.
SEO benefits: Google rewards faster load times.
Mobile-friendly: Reduces bounce rates on slower mobile networks.

Example use case in Shopify:

Prefetch related product pages from a collection.
Prerender the checkout page when a customer is on a product page.
Speed up blog or content navigation for SEO engagement.

4. Prerequisites Before Adding the API

Before implementing the Speculation Rules API in Shopify, make sure you have:

A Shopify Online Store 2.0 theme (like Dawn or custom OS 2.0).
Access to edit your theme.liquid file.
Basic understanding of HTML/JavaScript.
Browser compatibility awareness (currently Chrome and Chromium-based browsers support it best).

5. Step-by-Step Guide to Adding Speculation Rules API in Shopify

Step 1: Understand Where to Add Speculation Rules

Shopify themes are built with Liquid templates. The best place to add speculation rules is in the theme.liquid file, inside the <head> or right before the </body> tag.

Step 2: Writing Speculation Rules

Speculation rules are written in JSON format inside a <script type="speculationrules"> tag.

Example:

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "list",
      "urls": ["/checkout", "/cart"]
    }
  ]
}
</script>

This tells the browser to prerender the checkout and cart pages.

Step 3: Inserting the Code in Shopify Theme

Go to your Shopify Admin.
Navigate to Online Store > Themes > Edit code.
Open the theme.liquid file.
Insert the speculation rules script inside the <head> or before the </body>.

Example:

<!DOCTYPE html>
<html lang="en">
<head>
  {{ content_for_header }}
  <script type="speculationrules">
  {
    "prerender": [
      {
        "source": "list",
        "urls": ["/checkout", "/cart"]
      }
    ]
  }
  </script>
</head>

Step 4: Testing Speculation Rules in Your Store

Open your store in Chrome Canary or a Chromium browser.
Right-click > Inspect > Application > Prerendered Pages.
Hover or click links to verify that prerendering is happening.

Step 5: Optimizing for Performance

Only prerender high-intent pages like checkout.
Avoid prerendering large collections (to save bandwidth).
Use prefetch for less-critical pages.

6. Example Implementations

Prefetching Product Pages

<script type="speculationrules">
{
  "prefetch": [
    {
      "source": "list",
      "urls": ["/products/product-1", "/products/product-2"]
    }
  ]
}
</script>

Prerendering Checkout Pages

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "list",
      "urls": ["/checkout"]
    }
  ]
}
</script>

Speculation Rules for Collections

<script type="speculationrules">
{
  "prefetch": [
    {
      "source": "document",
      "where": {
        "selector_matches": "a.collection-link"
      }
    }
  ]
}
</script>

7. Common Mistakes and How to Avoid Them

Over-prerendering
Don’t prerender every page; it wastes bandwidth.
Focus on high-value pages like checkout, cart, or top products.
Not Testing Browser Support
Safari and Firefox may not support speculation rules fully. Always provide fallbacks.
Incorrect URL Paths
Shopify uses relative URLs like /checkout instead of full domain paths.
Placing Scripts in Wrong Location
Make sure speculation rules are inside the <head> or just before </body>.

8. Best Practices for Using the Speculation Rules API in Shopify

Use prerender for checkout/cart.
Use prefetch for related products.
Avoid preloading huge collections or blogs.
Target only high-intent links (e.g., "Buy Now").
Monitor performance in Chrome DevTools.
Track results with Shopify Analytics + GA4.

9. FAQs About Speculation Rules API in Shopify

Q1. What browsers support the Speculation Rules API?

Currently, Chrome and Chromium-based browsers support it best. Safari and Firefox may not fully support prerender yet.

Q2. Does it affect SEO in Shopify?

No. Googlebot does not interact with speculation rules. It only impacts user experience.

Q3. Where should I add speculation rules in Shopify?

In the theme.liquid file, inside the <head> tag.

Q4. Can I prerender all pages in my Shopify store?

Not recommended. It will waste resources and may slow down performance. Focus on checkout, cart, and key products.

Q5. Do speculation rules increase bandwidth costs?

Yes, slightly. That’s why targeting only high-value pages is important.

10. Conclusion

Adding the Speculation Rules API in Shopify is one of the most effective ways to improve speed and conversion rates in your online store. By prefetching and prerendering high-intent pages, you ensure a seamless experience for users, especially during critical moments like checkout.

The key is to implement it strategically—prerender only where it drives business results and monitor performance closely. With the growing importance of speed in eCommerce, this API can give your Shopify store a competitive edge.

By following this guide, you can confidently add and optimize the Speculation Rules API in Shopify, helping your D2C brand deliver lightning-fast experiences that boost both customer satisfaction and revenue.