dotCMS logodotCMS logo
dotCMS Github RepodotCMS Github RepodotCMS Discourse CommunityChat With Us

Shopify Integration for dotCMS - Setup Guide

Community plugin that connects dotCMS to a Shopify storefront, enabling content editors to display and manage Shopify product and collection data directly within dotCMS templates and pages.

What It Does#

The dotCMS Shopify plugin bridges your content management and e-commerce platforms. Once configured, you can query Shopify products and collections from within dotCMS Velocity templates, REST API endpoints, or custom GraphQL queries — without leaving dotCMS.

Key capabilities:

  • Display Shopify product data in dotCMS pages and templates
  • Search and browse products and collections via Velocity viewtool
  • Expose Shopify data through REST endpoints for headless frontends
  • Execute custom GraphQL queries against the Shopify Storefront API
  • Automatically creates ShopifyProduct and ShopifyCollection content types
  • Link dotCMS content directly to Shopify products with thumbnail syncing

Important: This integration provides read-only access to Shopify data via the Storefront API. It does not support writing data back to Shopify, managing orders, or accessing inventory levels.

Prerequisites#

Before setting up this integration, you need:

  1. dotCMS 25.10.03 or higher
  2. Active Shopify store
  3. Shopify Headless Sales Channel installed in your Shopify Admin
  4. Storefront API private access token from Shopify

Shopify Setup#

Step 1: Install the Headless Sales Channel#

  1. Log into your Shopify Admin
  2. Go to Apps → App Store
  3. Search for "Headless"
  4. Install the Headless Sales Channel app
  5. Click Add app

Step 2: Generate a Storefront API Token#

  1. In Shopify Admin, open the Headless app you just installed
  2. Click Add Storefront
  3. Give it a name (e.g., "dotCMS Integration")
  4. Under Storefront API, click Generate token
  5. Select the required permissions:
    • unauthenticated_read_products
    • unauthenticated_read_collections
  6. Click Save
  7. Copy the private access token - you'll need this for dotCMS configuration

Step 3: Get Your Store Key#

Your store key is your Shopify store name (subdomain):

  • If your store URL is dot-demo-store.myshopify.com
  • Your store key is dot-demo-store

Plugin Installation#

Step 1: Download the Plugin#

  1. Go to Releases
  2. Download the latest com.dotcms.shopify-XX.XX.XX.jar file

Step 2: Upload to dotCMS#

  1. Log into your dotCMS instance as admin
  2. Go to System → Dynamic Plugins
  3. Click Upload Plugin
  4. Select the JAR file you downloaded
  5. Wait for installation to complete
  6. The plugin automatically deploys templates and components to /application/shopify

Step 3: Configure the App#

  1. Go to Settings → Apps
  2. Find Shopify in the list
  3. Click to configure
  4. Select your site from the dropdown
  5. Fill in:
    • Store Key: Your Shopify store name (e.g., dot-demo-store)
    • Storefront Token: The private access token from Shopify Step 2
  6. Click Save
  7. Verify connectivity by visiting /api/v1/shopify/product/test

Usage#

Velocity ViewTool ($dotshopify)#

The plugin registers a $dotshopify viewtool available in all Velocity templates.

Fetch a Product by Handle#

#set($product = $dotshopify.getProductByHandle("awesome-tshirt"))
#if($product)
  <h1>$product.data.productByHandle.title</h1>
  <p>$product.data.productByHandle.description</p>
  <p>Price: $product.data.productByHandle.priceRange.minVariantPrice.amount</p>
#end

Fetch a Product by ID#

#set($product = $dotshopify.getProduct("gid://shopify/Product/123456789"))

Search Products#

#set($results = $dotshopify.searchProducts("t-shirt", 20))
#foreach($edge in $results.data.products.edges)
  #set($p = $edge.node)
  <div class="product">
    <h2>$p.title</h2>
    <p>$p.priceRange.minVariantPrice.amount $p.priceRange.minVariantPrice.currencyCode</p>
  </div>
#end

Fetch a Collection#

#set($collection = $dotshopify.getCollectionById("gid://shopify/Collection/123456789"))
<h2>$collection.data.collection.title</h2>
<p>$collection.data.collection.description</p>

Custom GraphQL Query#

#set($query = '{
  products(first: 5, query: "tag:featured") {
    edges {
      node {
        id
        title
        handle
        images(first: 1) {
          edges {
            node { url altText }
          }
        }
      }
    }
  }
}')
#set($result = $dotshopify.gql($query, {}))

REST API Endpoints#

All endpoints require a valid dotCMS user session.

Get Product by ID#

GET /api/v1/shopify/product/?id=gid://shopify/Product/123456789

Search Products#

GET /api/v1/shopify/product/_search?query=t-shirt&limit=20

Search Collections#

GET /api/v1/shopify/collection/_search?query=summer

Execute Custom GraphQL#

POST /api/v1/shopify/product/_gql
Content-Type: application/json

{
  "query": "{ products(first: 10) { edges { node { id title } } } }",
  "variables": {}
}

Redirect to Shopify Product URL#

GET /api/v1/shopify/product/_redirect?id=gid://shopify/Product/123456789

Test Connectivity#

GET /api/v1/shopify/product/test

Content Types#

The plugin automatically creates two content types on installation:

ShopifyProduct

  • Links dotCMS content items to Shopify products
  • Syncs product thumbnails from Shopify
  • Available in the Content Types list after plugin installation

ShopifyCollection

  • Widget type for managing Shopify collections
  • Embeddable in dotCMS pages and layouts

Architecture#

The plugin communicates with Shopify exclusively through the Storefront GraphQL API:

dotCMS Template / REST Request
  → $dotshopify ViewTool / REST Endpoint
    → ShopifyAPI (GraphQL client)
      → Shopify Storefront API (token-authenticated)
        → Product / Collection data

All queries are read-only. The Storefront API is the public-facing API designed for customer-facing applications and headless storefronts.

Troubleshooting#

Connectivity test fails (/api/v1/shopify/product/test)#

Check:

  1. Store Key is correct (just the subdomain, not full URL)
  2. Storefront Token is valid and not expired
  3. Headless Sales Channel is installed in Shopify Admin
  4. Token has the required unauthenticated_read_products permission

$dotshopify not available in templates#

Cause: Plugin may not have installed correctly.

Solution:

  1. Check dotCMS logs for plugin startup errors
  2. Go to System → Dynamic Plugins and verify the plugin status is active
  3. Restart dotCMS if needed

Products return empty results#

Possible causes:

  1. Products are not published/active in Shopify
  2. Products are not available in the Headless Sales Channel
  3. Search query doesn't match any products

Solution:

  • In Shopify Admin, go to your Headless Sales Channel and verify products are enabled for it
  • Products must be explicitly made available to the sales channel

GraphQL rate limiting errors#

Shopify enforces rate limits on the Storefront API. If you hit limits:

  • Reduce the number of products/collections fetched per query
  • Add caching to your Velocity templates using dotCMS cache mechanisms
  • Spread requests across page renders rather than fetching all at once

Token expires or is revoked#

The Storefront token does not expire automatically, but can be revoked manually in Shopify Admin. If the integration stops working:

  1. Go to Shopify Admin → Headless app
  2. Regenerate the token
  3. Update the token in dotCMS Settings → Apps → Shopify

Resources#

Next Steps#

This guide will be used as the basis for:

  1. Shopify integration page on dotcms.com
  2. Updated documentation on dev.dotcms.com/docs