Shopify Developer

Shopify Developer Reference

Comprehensive reference for professional Shopify development - API version 2026-01.

Quick Reference

Choose Your Path

Read the reference file(s) that match your task:

Liquid templating - writing or debugging .liquid files:

• references/liquid-syntax.md - Tags, control flow, iteration, whitespace, LiquidDoc
• references/liquid-filters.md - All filter categories with examples
• references/liquid-objects.md - Product, collection, cart, customer, and global objects

Theme development - building or customising themes:

• references/theme-development.md - OS 2.0 architecture, sections, blocks, JSON templates, settings schema

API integration - fetching or modifying data programmatically:

• references/api-admin.md - GraphQL Admin API (primary), REST (legacy), OAuth, webhooks, rate limiting
• references/api-storefront.md - Storefront API, Ajax API, cart operations

App development - building Shopify apps:

• references/app-development.md - Shopify CLI, extensions, Polaris Web Components, App Bridge

Serverless logic - custom business rules:

• references/functions.md - Shopify Functions (replacing Scripts), Rust/JS targets, deployment

Headless commerce - custom storefronts:

• references/hydrogen.md - Hydrogen framework, React Router 7, Storefront API integration

Optimisation and troubleshooting:

• references/performance.md - Images, JS, CSS, fonts, Liquid, Core Web Vitals
• references/debugging.md - Liquid errors, API errors, cart issues, webhook failures

Deprecation Notices

Liquid Essentials

Three syntax types:

{{ product.title | upcase }}                    {# Output with filter #}
{% if product.available %}In stock{% endif %}   {# Logic tag #}
{% assign sale = product.price | times: 0.8 %}  {# Assignment #}
{%- if condition -%}Stripped whitespace{%- endif -%}

Key patterns:

{% for product in collection.products limit: 5 %}
  {% render 'product-card', product: product %}
{% endfor %}

{% paginate collection.products by 12 %}
  {% for product in paginate.collection.products %}...{% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

API Essentials

// GraphQL Admin - always use GraphQL over REST
const response = await fetch(`https://${store}.myshopify.com/admin/api/2026-01/graphql.json`, {
  method: 'POST',
  headers: {
    'X-Shopify-Access-Token': accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query, variables }),
})
const { data, errors } = await response.json()
if (errors) throw new Error(errors[0].message)

// Ajax API (theme-only cart operations)
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: variantId, quantity: 1 }),
})

Reference Files

Admin API Reference

GraphQL Admin API

Modern API for Shopify Admin operations with efficient data fetching.

Endpoint:

POST https://{store}.myshopify.com/admin/api/2026-01/graphql.json

Headers:

{
  'X-Shopify-Access-Token': 'shpat_...',
  'Content-Type': 'application/json'
}

Basic Query:

query GetProducts($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id
        title
        handle
        status
        vendor
        productType

        # Pricing
        priceRange {
          minVariantPrice { amount currencyCode }
          maxVariantPrice { amount currencyCode }
        }

        # Images
        images(first: 5) {
          edges {
            node {
              id
              url
              altText
            }
          }
        }

        # Variants
        variants(first: 10) {
          edges {
            node {
              id
              title
              sku
              price
              inventoryQuantity
              available: availableForSale
            }
          }
        }
      }
    }

    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Variables:

{
  "first": 10
}

JavaScript Example:

async function getProducts(accessToken, store, limit = 10) {
  const query = `
    query GetProducts($first: Int!) {
      products(first: $first) {
        edges {
          node {
            id
            title
            handle
            priceRange {
              minVariantPrice { amount currencyCode }
            }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  `;

  const response = await fetch(
    `https://${store}.myshopify.com/admin/api/2026-01/graphql.json`,
    {
      method: 'POST',
      headers: {
        'X-Shopify-Access-Token': accessToken,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query,
        variables: { first: limit },
      }),
    }
  );

  const { data, errors } = await response.json();

  if (errors) {
    console.error('GraphQL Errors:', errors);
    throw new Error(errors[0].message);
  }

  return data.products;
}

Common Mutations:

Create product:

mutation CreateProduct($input: ProductInput!) {
  productCreate(input: $input) {
    product {
      id
      title
      handle
    }
    userErrors {
      field
      message
    }
  }
}

Update product:

mutation UpdateProduct($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      title
      status
    }
    userErrors {
      field
      message
    }
  }
}

Set metafield:

mutation SetMetafield($input: MetafieldInput!) {
  metafieldSet(input: $input) {
    metafield {
      id
      namespace
      key
      value
      type
    }
    userErrors {
      field
      message
    }
  }
}

REST Admin API (Legacy)

Note: GraphQL is Shopify's primary API. Use GraphQL for all new development. REST endpoints remain available but receive fewer updates and may be deprecated in future API versions.

Traditional REST API for Shopify Admin operations.

Base URL:

https://{store}.myshopify.com/admin/api/2026-01/

Authentication:

headers: {
  'X-Shopify-Access-Token': 'shpat_...'
}

Common Endpoints:

Get products:

GET /admin/api/2026-01/products.json?limit=50&status=active

// JavaScript
const response = await fetch(
  `https://${store}.myshopify.com/admin/api/2026-01/products.json?limit=50`,
  {
    headers: {
      'X-Shopify-Access-Token': accessToken,
    },
  }
);

const { products } = await response.json();

Get single product:

GET /admin/api/2026-01/products/{product_id}.json

Create product:

POST /admin/api/2026-01/products.json

// Body
{
  "product": {
    "title": "New Product",
    "body_html": "<p>Description</p>",
    "vendor": "My Vendor",
    "product_type": "Shoes",
    "status": "draft"
  }
}

Update product:

PUT /admin/api/2026-01/products/{product_id}.json

// Body
{
  "product": {
    "id": 123456789,
    "title": "Updated Title"
  }
}

Get orders:

GET /admin/api/2026-01/orders.json?status=any&limit=50

Get customers:

GET /admin/api/2026-01/customers.json?limit=50

OAuth 2.0 Authentication

Complete OAuth flow for custom apps.

Step 1: Authorization Request

GET https://{shop}.myshopify.com/admin/oauth/authorize?
  client_id={api_key}&
  redirect_uri={redirect_uri}&
  scope={scopes}&
  state={random_state}

Scopes:

const scopes = [
  'read_products',
  'write_products',
  'read_orders',
  'write_orders',
  'read_customers',
  'write_customers',
  'read_inventory',
  'write_inventory',
  'read_metafields',
  'write_metafields',
].join(',');

Step 2: Handle Callback

// User approves, Shopify redirects to:
GET {redirect_uri}?code={auth_code}&state={state}&hmac={hmac}&shop={shop}

// Verify HMAC for security
function verifyHmac(query, secret) {
  const { hmac, ...params } = query;

  const message = Object.keys(params)
    .sort()
    .map(key => `${key}=${params[key]}`)
    .join('&');

  const hash = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return hash === hmac;
}

Step 3: Exchange Code for Token

POST https://{shop}.myshopify.com/admin/oauth/access_token

// Body
{
  "client_id": "{api_key}",
  "client_secret": "{api_secret}",
  "code": "{auth_code}"
}

// Response
{
  "access_token": "shpat_...",
  "scope": "write_products,read_orders"
}

// Node.js example
async function getAccessToken(shop, code, apiKey, apiSecret) {
  const response = await fetch(
    `https://${shop}/admin/oauth/access_token`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: apiKey,
        client_secret: apiSecret,
        code,
      }),
    }
  );

  const { access_token, scope } = await response.json();
  return { access_token, scope };
}

Rate Limiting

GraphQL uses points-based rate limiting.

Rate Limits:

• 50 cost points per second maximum
• Bucket refills at 50 points/second
• Each query has a calculated cost

Check Rate Limit:

const response = await fetch(graphqlEndpoint, options);

const rateLimitHeader = response.headers.get('X-Shopify-GraphQL-Admin-Api-Call-Limit');
// Example: "42/50" (42 points used, 50 max)

const [used, limit] = rateLimitHeader.split('/').map(Number);

if (used > 40) {
  // Approaching limit, slow down
  await delay(1000);
}

Implement Retry Logic:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      // Rate limited
      const retryAfter = response.headers.get('Retry-After') || 2;
      await delay(retryAfter * 1000 * Math.pow(2, i)); // Exponential backoff
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Webhooks

Event-driven notifications for app integrations.

Common Webhooks:

// Product events
'products/create'
'products/update'
'products/delete'

// Order events
'orders/create'
'orders/updated'
'orders/paid'
'orders/fulfilled'
'orders/cancelled'

// Customer events
'customers/create'
'customers/update'
'customers/delete'

// Cart events
'carts/create'
'carts/update'

// Inventory events
'inventory_levels/update'

// App events
'app/uninstalled'

Register Webhook (GraphQL):

mutation CreateWebhook($input: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(input: $input) {
    webhookSubscription {
      id
      topic
      endpoint {
        __typename
        ... on WebhookHttpEndpoint {
          callbackUrl
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables:

{
  "input": {
    "topic": "ORDERS_CREATE",
    "webhookSubscription": {
      "callbackUrl": "https://your-app.com/webhooks/orders",
      "format": "JSON"
    }
  }
}

Handle Webhook (Node.js/Express):

app.post('/webhooks/orders', async (req, res) => {
  // Verify webhook HMAC
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = JSON.stringify(req.body);

  const hash = crypto
    .createHmac('sha256', SHOPIFY_WEBHOOK_SECRET)
    .update(body)
    .digest('base64');

  if (hash !== hmac) {
    return res.status(401).send('Invalid HMAC');
  }

  // Process order
  const order = req.body;
  console.log('New order:', order.id, order.email);

  // Respond quickly (within 5 seconds)
  res.status(200).send('OK');

  // Process in background
  await processOrder(order);
});

Common Patterns

Pagination (GraphQL)

async function getAllProducts(accessToken, store) {
  let allProducts = [];
  let hasNextPage = true;
  let cursor = null;

  while (hasNextPage) {
    const query = `
      query GetProducts($first: Int!, $after: String) {
        products(first: $first, after: $after) {
          edges {
            node { id title }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    `;

    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'X-Shopify-Access-Token': accessToken,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query,
        variables: { first: 50, after: cursor },
      }),
    });

    const { data } = await response.json();
    allProducts.push(...data.products.edges.map(e => e.node));

    hasNextPage = data.products.pageInfo.hasNextPage;
    cursor = data.products.pageInfo.endCursor;
  }

  return allProducts;
}

Error Handling

async function safeApiCall(query, variables) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'X-Shopify-Access-Token': accessToken,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ query, variables }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const { data, errors } = await response.json();

    if (errors) {
      console.error('GraphQL Errors:', errors);
      throw new Error(errors[0].message);
    }

    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Best Practices

1. Always check API version - Use latest stable (2026-01) 2. Implement rate limit handling - Use exponential backoff 3. Verify webhook HMAC - Security critical 4. Use GraphQL over REST when possible - More efficient 5. Request only needed fields - Reduce response size 6. Handle errors gracefully - Check errors and userErrors 7. Store access tokens securely - Never expose in client code 8. Use minimum necessary scopes - Security best practice 9. Implement retry logic - Handle transient failures 10. Respond to webhooks quickly - Within 5 seconds

Storefront and Ajax API Reference

Storefront API

Public API for headless/custom storefronts.

Endpoint:

POST https://{store}.myshopify.com/api/2026-01/graphql.json

Authentication

The Storefront API supports three types of access tokens:

1. Public Access Token (Client-Side)

• Limited scope, safe for browser-side code
• Create in Shopify Admin: Apps > Manage private apps > Storefront API
• Exposes only public storefront data (products, collections, cart)
• Cannot access customer data or admin functions

{
  'Content-Type': 'application/json',
  'X-Shopify-Storefront-Access-Token': '{public_token}'
}

2. Private Access Token (Server-Side)

• Broader scope, for server-side implementations
• Must be kept secure, never exposed to client
• Can access additional resources based on app permissions

3. Delegate Access Tokens

• Customer-specific tokens for authenticated operations
• Used for customer login, order history, profile management
• Short-lived, scoped to individual customer sessions

Headers (Public Access)

{
  'Content-Type': 'application/json',
  'X-Shopify-Storefront-Access-Token': '{public_token}' // Optional for public stores
}

Query Products

query GetProducts($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id
        title
        handle
        description
        priceRange {
          minVariantPrice { amount currencyCode }
          maxVariantPrice { amount currencyCode }
        }
        images(first: 3) {
          edges {
            node {
              url
              altText
            }
          }
        }
        variants(first: 10) {
          edges {
            node {
              id
              title
              price { amount currencyCode }
              availableForSale
              sku
            }
          }
        }
      }
    }
  }
}

Cart Operations

Create cart:

mutation CreateCart($input: CartInput!) {
  cartCreate(input: $input) {
    cart {
      id
      checkoutUrl
      lines(first: 10) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                price { amount }
              }
            }
          }
        }
      }
      cost {
        totalAmount { amount currencyCode }
        subtotalAmount { amount }
        totalTaxAmount { amount }
      }
    }
  }
}

Add to cart:

mutation AddToCart($cartId: ID!, $lines: [CartLineInput!]!) {
  cartLinesAdd(cartId: $cartId, lines: $lines) {
    cart {
      id
      lines(first: 10) {
        edges {
          node {
            id
            quantity
          }
        }
      }
    }
  }
}

Ajax API (Theme-Only)

JavaScript API for cart operations in themes.

Get Cart:

fetch('/cart.js')
  .then(response => response.json())
  .then(cart => {
    console.log('Cart:', cart);
    console.log('Item count:', cart.item_count);
    console.log('Total:', cart.total_price);
    console.log('Items:', cart.items);
  });

Add to Cart:

fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: variantId,              // Required: variant ID
    quantity: 1,                 // Optional: default 1
    properties: {                // Optional: custom data
      'Gift wrap': 'Yes',
      'Note': 'Happy Birthday!'
    }
  })
})
  .then(response => response.json())
  .then(item => {
    console.log('Added to cart:', item);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Update Cart:

fetch('/cart/change.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    line: 1,          // Line item index (1-based)
    quantity: 2       // New quantity (0 = remove)
  })
})
  .then(response => response.json())
  .then(cart => console.log('Updated cart:', cart));

Clear Cart:

fetch('/cart/clear.js', { method: 'POST' })
  .then(response => response.json())
  .then(cart => console.log('Cart cleared'));

Update Cart Attributes:

fetch('/cart/update.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    attributes: {
      'gift_wrap': 'true',
      'gift_message': 'Happy Birthday!'
    },
    note: 'Please handle with care'
  })
})
  .then(response => response.json())
  .then(cart => console.log('Cart updated'));

Customer Account API

Shopify's newer API for customer-facing account operations (replaces legacy customer endpoints):

Endpoint:

POST https://{store}.myshopify.com/account/customer/api/2026-01/graphql

Key operations:

• Customer login and registration
• Order history and tracking
• Address management
• Profile updates

Note: This API uses a different authentication flow via customer access tokens. See Shopify docs for implementation details.

App Development Reference

Expert guidance for building custom Shopify apps using Shopify CLI, modern frameworks, and best practices.

Core Capabilities

1. Shopify CLI Setup

Install and configure Shopify CLI for app development.

Install Shopify CLI:

# Using npm
npm install -g @shopify/cli @shopify/app

# Using Homebrew (macOS)
brew tap shopify/shopify
brew install shopify-cli

# Verify installation
shopify version

Create New App:

# Create app with Node.js/React
shopify app init

# Choose template:
# - React Router 7 (recommended)
# - Node.js + React
# - PHP
# - Ruby

# App structure created:
my-app/
├── app/                    # React Router app routes
├── extensions/             # App extensions
├── shopify.app.toml       # App configuration
├── package.json
└── README.md

Note: As of Hydrogen 2025.5.0+, Shopify templates default to React Router 7 instead of Remix.

App Configuration (shopify.app.toml):

# This file stores app configuration

name = "my-app"
client_id = "your-client-id"
application_url = "https://your-app.com"
embedded = true

[access_scopes]
# API access scopes
scopes = "write_products,read_orders,read_customers"

[auth]
redirect_urls = [
  "https://your-app.com/auth/callback",
  "https://your-app.com/auth/shopify/callback"
]

[webhooks]
api_version = "2026-01"

[[webhooks.subscriptions]]
topics = ["products/create", "products/update"]
uri = "/webhooks"

2. Development Workflow

Start Development Server:

# Start dev server with tunnelling
shopify app dev

# Server starts with:
# - Local development URL: http://localhost:3000
# - Public tunnel URL: https://random-subdomain.ngrok.io
# - App installed in development store

Deploy App:

# Deploy to production
shopify app deploy

# Generate app version and deploy extensions

Environment Variables (.env):

SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret
SCOPES=write_products,read_orders
HOST=your-app-domain.com
SHOPIFY_APP_URL=https://your-app.com
DATABASE_URL=postgresql://...

3. App Architecture (React Router 7)

Modern Shopify app using React Router 7 framework.

app/routes/app._index.jsx (Home Page):

import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";
import {
  Page,
  Layout,
  Card,
  DataTable,
  Button,
} from "@shopify/polaris";

export async function loader({ request }) {
  const { admin, session } = await authenticate.admin(request);

  // Fetch products using GraphQL
  const response = await admin.graphql(`
    query {
      products(first: 10) {
        edges {
          node {
            id
            title
            handle
            status
          }
        }
      }
    }
  `);

  const { data } = await response.json();

  return {
    products: data.products.edges.map(e => e.node),
    shop: session.shop,
  };
}

export default function Index() {
  const { products, shop } = useLoaderData();

  const rows = products.map((product) => [
    product.title,
    product.handle,
    product.status,
  ]);

  return (
    <Page title="Products">
      <Layout>
        <Layout.Section>
          <Card>
            <DataTable
              columnContentTypes={["text", "text", "text"]}
              headings={["Title", "Handle", "Status"]}
              rows={rows}
            />
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

app/routes/app.product.$id.jsx (Product Detail):

import { data } from "react-router";
import { useLoaderData, useSubmit } from "react-router";
import { authenticate } from "../shopify.server";
import {
  Page,
  Layout,
  Card,
  Form,
  FormLayout,
  TextField,
  Button,
} from "@shopify/polaris";
import { useState } from "react";

export async function loader({ request, params }) {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(`
    query GetProduct($id: ID!) {
      product(id: $id) {
        id
        title
        description
        status
        vendor
      }
    }
  `, {
    variables: { id: `gid://shopify/Product/${params.id}` },
  });

  const { data: responseData } = await response.json();

  return data({ product: responseData.product });
}

export async function action({ request, params }) {
  const { admin } = await authenticate.admin(request);

  const formData = await request.formData();
  const title = formData.get("title");
  const description = formData.get("description");

  const response = await admin.graphql(`
    mutation UpdateProduct($input: ProductInput!) {
      productUpdate(input: $input) {
        product {
          id
          title
        }
        userErrors {
          field
          message
        }
      }
    }
  `, {
    variables: {
      input: {
        id: `gid://shopify/Product/${params.id}`,
        title,
        description,
      },
    },
  });

  const { data: responseData } = await response.json();

  if (responseData.productUpdate.userErrors.length > 0) {
    return data({ errors: responseData.productUpdate.userErrors }, { status: 400 });
  }

  return data({ success: true });
}

export default function ProductDetail() {
  const { product } = useLoaderData();
  const submit = useSubmit();

  const [title, setTitle] = useState(product.title);
  const [description, setDescription] = useState(product.description);

  const handleSubmit = () => {
    const formData = new FormData();
    formData.append("title", title);
    formData.append("description", description);

    submit(formData, { method: "post" });
  };

  return (
    <Page title="Edit Product" backAction={{ url: "/app" }}>
      <Layout>
        <Layout.Section>
          <Card>
            <FormLayout>
              <TextField
                label="Title"
                value={title}
                onChange={setTitle}
                autoComplete="off"
              />
              <TextField
                label="Description"
                value={description}
                onChange={setDescription}
                multiline={4}
                autoComplete="off"
              />
              <Button primary onClick={handleSubmit}>
                Save
              </Button>
            </FormLayout>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

4. App Extensions

Extend Shopify functionality with various extension types.

Admin Action Extension:

Create button in admin product page:

shopify app generate extension

# Choose: Admin action
# Name: Export Product

extensions/export-product/src/index.jsx:

import { extend, AdminAction } from "@shopify/admin-ui-extensions";

extend("Admin::Product::SubscriptionAction", (root, { data }) => {
  const { id, title } = data.selected[0];

  const button = root.createComponent(AdminAction, {
    title: "Export Product",
    onPress: async () => {
      // Call your app API
      const response = await fetch("/api/export", {
        method: "POST",
        body: JSON.stringify({ productId: id }),
        headers: { "Content-Type": "application/json" },
      });

      if (response.ok) {
        root.toast.show("Product exported successfully!");
      } else {
        root.toast.show("Export failed", { isError: true });
      }
    },
  });

  root.append(button);
});

Theme App Extension:

Add app block to themes:

shopify app generate extension

# Choose: Theme app extension
# Name: Product Reviews

extensions/product-reviews/blocks/reviews.liquid:

{% schema %}
{
  "name": "Product Reviews",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Customer Reviews"
    },
    {
      "type": "range",
      "id": "reviews_to_show",
      "label": "Reviews to Show",
      "min": 1,
      "max": 10,
      "default": 5
    }
  ]
}
{% endschema %}

<div class="product-reviews">
  <h2>{{ block.settings.heading }}</h2>

  {% comment %}
    Fetch reviews from your app API
  {% endcomment %}

  <div id="reviews-container" data-product-id="{{ product.id }}"></div>
</div>

<script>
  // Fetch and render reviews
  // Note: In production, sanitise HTML to prevent XSS vulnerabilities
  fetch(`/apps/reviews/api/reviews?product_id={{ product.id }}&limit={{ block.settings.reviews_to_show }}`)
    .then(r => r.json())
    .then(reviews => {
      const container = document.getElementById('reviews-container');
      container.innerHTML = reviews.map(review => `
        <div class="review">
          <div class="rating">${'⭐'.repeat(review.rating)}</div>
          <h3>${review.title}</h3>
          <p>${review.content}</p>
          <p class="author">- ${review.author}</p>
        </div>
      `).join('');
    });
</script>

{% stylesheet %}
  .product-reviews {
    padding: 2rem;
  }

  .review {
    margin-bottom: 1.5rem;
    padding-bottom: 1.5rem;
    border-bottom: 1px solid #eee;
  }

  .rating {
    color: #ffa500;
    margin-bottom: 0.5rem;
  }
{% endstylesheet %}

5. Webhooks in Apps

Handle Shopify events in your app.

app/routes/webhooks.jsx:

import { authenticate } from "../shopify.server";
import db from "../db.server";

export async function action({ request }) {
  const { topic, shop, session, admin, payload } = await authenticate.webhook(request);

  console.log(`Webhook received: ${topic} from ${shop}`);

  switch (topic) {
    case "APP_UNINSTALLED":
      // Clean up app data
      await db.session.deleteMany({ where: { shop } });
      break;

    case "PRODUCTS_CREATE":
      // Handle new product
      console.log("New product created:", payload.id, payload.title);
      await handleProductCreated(payload);
      break;

    case "PRODUCTS_UPDATE":
      // Handle product update
      console.log("Product updated:", payload.id);
      await handleProductUpdated(payload);
      break;

    case "ORDERS_CREATE":
      // Handle new order
      console.log("New order:", payload.id, payload.email);
      await handleOrderCreated(payload);
      break;

    case "CUSTOMERS_CREATE":
      // Handle new customer
      await handleCustomerCreated(payload);
      break;

    default:
      console.log("Unhandled webhook topic:", topic);
  }

  return new Response("OK", { status: 200 });
}

async function handleProductCreated(product) {
  // Process new product
  await db.product.create({
    data: {
      shopifyId: product.id,
      title: product.title,
      handle: product.handle,
    },
  });
}

async function handleOrderCreated(order) {
  // Send email notification, update inventory, etc.
  console.log(`Order ${order.id} received for ${order.email}`);
}

Register Webhooks (app/shopify.server.js):

import "@shopify/shopify-app-remix/adapters/node";
import {
  ApiVersion,
  AppDistribution,
  shopifyApp,
  DeliveryMethod,
} from "@shopify/shopify-app-remix/server";

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  scopes: process.env.SCOPES?.split(","),
  appUrl: process.env.SHOPIFY_APP_URL,
  authPathPrefix: "/auth",
  sessionStorage: new SQLiteSessionStorage(),
  distribution: AppDistribution.AppStore,
  apiVersion: ApiVersion.January26,

  webhooks: {
    APP_UNINSTALLED: {
      deliveryMethod: DeliveryMethod.Http,
      callbackUrl: "/webhooks",
    },
    PRODUCTS_CREATE: {
      deliveryMethod: DeliveryMethod.Http,
      callbackUrl: "/webhooks",
    },
    PRODUCTS_UPDATE: {
      deliveryMethod: DeliveryMethod.Http,
      callbackUrl: "/webhooks",
    },
    ORDERS_CREATE: {
      deliveryMethod: DeliveryMethod.Http,
      callbackUrl: "/webhooks",
    },
  },
});

export default shopify;
export const authenticate = shopify.authenticate;

6. App Proxy

Create custom storefront routes that access your app.

Setup in Partner Dashboard:

Subpath prefix: apps
Subpath: reviews
Proxy URL: https://your-app.com/api/proxy

Result:

https://store.com/apps/reviews → proxies to → https://your-app.com/api/proxy

Handle Proxy Requests (app/routes/api.proxy.jsx):

import { data } from "react-router";

export async function loader({ request }) {
  const url = new URL(request.url);

  // Verify proxy request
  const signature = url.searchParams.get("signature");
  const shop = url.searchParams.get("shop");

  if (!verifyProxySignature(signature, request)) {
    return data({ error: "Invalid signature" }, { status: 401 });
  }

  // Handle different paths
  const path = url.searchParams.get("path_prefix");

  if (path === "/apps/reviews/product") {
    const productId = url.searchParams.get("product_id");
    const reviews = await getProductReviews(productId);

    return data({ reviews });
  }

  return data({ message: "App Proxy" });
}

function verifyProxySignature(signature, request) {
  // Verify HMAC signature
  // Implementation depends on your setup
  return true;
}

7. Polaris UI Components

Use Shopify's design system for consistent admin UI.

Common Components:

import {
  Page,
  Layout,
  Card,
  Button,
  TextField,
  Select,
  Checkbox,
  Badge,
  Banner,
  DataTable,
  Modal,
  Toast,
  Frame,
} from "@shopify/polaris";

export default function MyPage() {
  return (
    <Page
      title="Settings"
      primaryAction={{ content: "Save", onAction: handleSave }}
      secondaryActions={[{ content: "Cancel", onAction: handleCancel }]}
    >
      <Layout>
        <Layout.Section>
          <Card title="General Settings" sectioned>
            <TextField
              label="App Name"
              value={name}
              onChange={setName}
            />

            <Select
              label="Status"
              options={[
                { label: "Active", value: "active" },
                { label: "Draft", value: "draft" },
              ]}
              value={status}
              onChange={setStatus}
            />

            <Checkbox
              label="Enable notifications"
              checked={notifications}
              onChange={setNotifications}
            />
          </Card>
        </Layout.Section>

        <Layout.Section secondary>
          <Card title="Status" sectioned>
            <Badge status="success">Active</Badge>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

Polaris Web Components (Preview)

Shopify is migrating from Polaris React to framework-agnostic Web Components:

<!-- Web Component syntax (replacing React components) -->
<ui-page title="Settings">
  <ui-layout>
    <ui-layout-section>
      <ui-card>
        <ui-text-field label="App Name" value="My App"></ui-text-field>
        <ui-select label="Status">
          <option value="active">Active</option>
          <option value="draft">Draft</option>
        </ui-select>
        <ui-checkbox label="Enable notifications"></ui-checkbox>
      </ui-card>
    </ui-layout-section>
  </ui-layout>
</ui-page>

Migration status: Polaris React remains fully supported. Web Components are in preview for new projects. Existing apps do not need to migrate immediately.

8. Shopify Dev MCP Server

The @anthropic/shopify-dev-mcp server provides AI-assisted Shopify development:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["@anthropic/shopify-dev-mcp"]
    }
  }
}

Provides tools for querying Shopify documentation, generating GraphQL queries, and scaffolding app components.

9. Deployment

Deploy Shopify apps to production.

Deploy to Cloudflare Workers:

wrangler.toml:

name = "shopify-app"
compatibility_date = "2026-01-10"
main = "build/index.js"

[vars]
SHOPIFY_API_KEY = "your_api_key"

[[kv_namespaces]]
binding = "SESSIONS"
id = "your_kv_namespace_id"

Deploy:

# Build app
npm run build

# Deploy to Cloudflare
wrangler deploy

Environment Secrets:

# Add secrets
wrangler secret put SHOPIFY_API_SECRET
wrangler secret put DATABASE_URL

Best Practices

1. Use Shopify CLI for app scaffolding and development 2. Implement proper OAuth with HMAC verification 3. Handle webhook events for real-time updates 4. Use Polaris for consistent admin UI 5. Test in development store before production 6. Implement error handling for all API calls 7. Store session data securely (encrypted database) 8. Follow Shopify app requirements for listing 9. Implement app billing for monetisation 10. Use app extensions to enhance merchant experience

Debugging and Troubleshooting Reference

Expert guidance for debugging Shopify themes, apps, and API integrations with practical solutions to common issues.

Core Capabilities

1. Liquid Debugging

Debug Liquid template errors and rendering issues.

Enable Theme Preview:

1. Go to Online Store > Themes
2. Click "Customise" on your theme
3. Open browser DevTools (F12)
4. Check Console for Liquid errors

Common Liquid Errors:

Syntax Error:

{# ❌ Error: Missing endif #}
{% if product.available %}
  <button>Add to Cart</button>
{# Missing {% endif %} #}

{# ✅ Fixed #}
{% if product.available %}
  <button>Add to Cart</button>
{% endif %}

Undefined Variable:

{# ❌ Error: product undefined on collection page #}
{{ product.title }}

{# ✅ Fixed: Check context #}
{% if product %}
  {{ product.title }}
{% else %}
  {# Not on product page #}
{% endif %}

Invalid Filter:

{# ❌ Error: Unknown filter #}
{{ product.price | format_money }}

{# ✅ Fixed: Correct filter name #}
{{ product.price | money }}

Debug Output:

{# Output variable as JSON #}
{{ product | json }}

{# Check variable type #}
{{ product.class }}

{# Check if variable exists #}
{% if product %}
  Product exists
{% else %}
  Product is nil
{% endif %}

{# Output all properties #}
<pre>{{ product | json }}</pre>

Console Logging from Liquid:

<script>
  console.log('Product ID:', {{ product.id }});
  console.log('Product data:', {{ product | json }});
  console.log('Cart:', {{ cart | json }});
</script>

2. JavaScript Debugging

Debug JavaScript errors in themes and apps.

Browser Console:

// Log to console
console.log('Debug:', variable);
console.error('Error:', error);
console.warn('Warning:', warning);

// Log object properties
console.table(data);

// Group related logs
console.group('Cart Operations');
console.log('Cart ID:', cartId);
console.log('Items:', items);
console.groupEnd();

// Time operations
console.time('API Call');
await fetch('/api/data');
console.timeEnd('API Call');

// Stack trace
console.trace('Execution path');

Breakpoints:

// Programmatic breakpoint
debugger;

// Set in browser DevTools:
// Sources tab > Click line number

Error Handling:

// ❌ Unhandled error
const data = await fetch('/api/data').then(r => r.json());

// ✅ Proper error handling
try {
  const response = await fetch('/api/data');

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Data:', data);
} catch (error) {
  console.error('Failed to fetch data:', error);
  // Show user-friendly error message
  alert('Failed to load data. Please try again.');
}

Network Debugging:

1. Open DevTools > Network tab
2. Filter by XHR or Fetch
3. Click request to see:
   - Request headers
   - Request payload
   - Response headers
   - Response body
   - Timing information

3. API Error Debugging

Debug GraphQL and REST API errors.

GraphQL Errors:

Error response format:

{
  "errors": [
    {
      "message": "Field 'invalidField' doesn't exist on type 'Product'",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["product", "invalidField"],
      "extensions": {
        "code": "FIELD_NOT_FOUND",
        "typeName": "Product"
      }
    }
  ],
  "data": null
}

Check for errors BEFORE accessing data:

const response = await fetch(graphqlEndpoint, {
  method: 'POST',
  headers: {
    'X-Shopify-Access-Token': accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query, variables }),
});

const { data, errors } = await response.json();

// ✅ Always check errors first
if (errors) {
  console.error('GraphQL Errors:');
  errors.forEach(error => {
    console.error('Message:', error.message);
    console.error('Location:', error.locations);
    console.error('Path:', error.path);
    console.error('Code:', error.extensions?.code);
  });
  throw new Error(errors[0].message);
}

// Now safe to use data
console.log('Products:', data.products);

Common GraphQL Errors:

Authentication Error:

{
  "errors": [{
    "message": "Access denied",
    "extensions": { "code": "UNAUTHENTICATED" }
  }]
}

Fix: Check access token:

// Verify token is valid
const token = 'shpat_...';

// Check token format (should start with shpat_)
if (!token.startsWith('shpat_')) {
  console.error('Invalid token format');
}

// Verify in headers
headers: {
  'X-Shopify-Access-Token': token,  // ✅ Correct header
  'Authorization': `Bearer ${token}`, // ❌ Wrong for Admin API
}

Field Not Found:

{
  "errors": [{
    "message": "Field 'invalidField' doesn't exist on type 'Product'"
  }]
}

Fix: Check field name in API docs:

# ❌ Wrong field name
query {
  product(id: "gid://shopify/Product/123") {
    invalidField
  }
}

# ✅ Correct field name
query {
  product(id: "gid://shopify/Product/123") {
    title
    handle
    status
  }
}

Rate Limit Error:

// Check rate limit header
const response = await fetch(graphqlEndpoint, options);

const rateLimit = response.headers.get('X-Shopify-GraphQL-Admin-Api-Call-Limit');
console.log('Rate limit:', rateLimit); // "42/50"

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
}

REST API Errors:

404 Not Found:

const response = await fetch(`https://${shop}/admin/api/2026-01/products/999999.json`, {
  headers: { 'X-Shopify-Access-Token': token },
});

if (response.status === 404) {
  console.error('Product not found');
  // Check:
  // 1. Product ID is correct
  // 2. Product exists in store
  // 3. Using correct endpoint
}

422 Unprocessable Entity:

{
  "errors": {
    "title": ["can't be blank"],
    "price": ["must be greater than 0"]
  }
}

Fix: Validate input:

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'X-Shopify-Access-Token': token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product: {
      title: '',  // ❌ Empty title
      price: -10, // ❌ Negative price
    },
  }),
});

if (response.status === 422) {
  const { errors } = await response.json();
  console.error('Validation errors:', errors);

  // Fix data
  const validProduct = {
    title: 'Product Name',  // ✅ Valid title
    price: 19.99,           // ✅ Valid price
  };
}

4. Cart Debugging

Debug cart and Ajax API issues.

Cart Not Updating:

// ❌ Common mistake: Wrong variant ID
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: '123',  // ❌ Wrong: using product ID instead of variant ID
    quantity: 1,
  }),
});

// ✅ Fixed: Use variant ID
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 123456789,  // ✅ Variant ID (numeric)
    quantity: 1,
  }),
})
  .then(response => {
    if (!response.ok) {
      return response.json().then(err => {
        console.error('Cart error:', err);
        throw err;
      });
    }
    return response.json();
  })
  .then(item => {
    console.log('Added to cart:', item);
    // Update cart UI
  })
  .catch(error => {
    console.error('Failed to add to cart:', error);
  });

Get Current Cart:

// Debug current cart state
fetch('/cart.js')
  .then(r => r.json())
  .then(cart => {
    console.log('Cart:', cart);
    console.log('Item count:', cart.item_count);
    console.log('Total:', cart.total_price);
    console.log('Items:', cart.items);

    cart.items.forEach(item => {
      console.log('Item:', item.product_id, item.variant_id, item.quantity);
    });
  });

Cart AJAX Errors:

// Common error: Insufficient inventory
{
  "status": 422,
  "message": "You can only add 5 of this item to your cart",
  "description": "Cannot add more than 5 to cart"
}

// Fix: Check inventory before adding
const variant = product.variants.find(v => v.id === variantId);

if (variant.inventory_quantity < quantity) {
  alert(`Only ${variant.inventory_quantity} available`);
} else {
  // Add to cart
}

5. Theme Preview Debugging

Debug issues in the theme customiser.

Theme Editor Console:

1. Open theme customiser
2. Open DevTools (F12)
3. Check Console for errors
4. Look for:
   - Liquid errors (red text)
   - JavaScript errors
   - Network failures

Section Not Rendering:

{# Check section schema #}
{% schema %}
{
  "name": "My Section",
  "settings": [...]  {# ✅ Must have settings #}
}
{% endschema %}

{# ❌ Missing schema = won't show in customiser #}

Settings Not Updating:

{# ❌ Wrong: Using hardcoded value #}
<h1>Hardcoded Title</h1>

{# ✅ Fixed: Use setting #}
<h1>{{ section.settings.title }}</h1>

{% schema %}
{
  "name": "Hero",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "Welcome"
    }
  ]
}
{% endschema %}

Block Attributes Missing:

{# ❌ Missing shopify_attributes #}
<div class="block">
  {{ block.settings.text }}
</div>

{# ✅ Fixed: Add shopify_attributes for theme editor #}
<div class="block" {{ block.shopify_attributes }}>
  {{ block.settings.text }}
</div>

6. Webhook Debugging

Debug webhook delivery and processing.

Webhook Not Received:

Check in Shopify Admin:

1. Settings > Notifications > Webhooks
2. Click webhook
3. Check "Recent deliveries"
4. Look for delivery status:
   - ✅ Success (200 OK)
   - ❌ Failed (4xx/5xx errors)

Verify Webhook HMAC:

import crypto from 'crypto';

function verifyWebhook(body, hmac, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmac;
}

// Express example
app.post('/webhooks/orders', (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = JSON.stringify(req.body);

  if (!verifyWebhook(body, hmac, process.env.SHOPIFY_WEBHOOK_SECRET)) {
    console.error('Invalid webhook HMAC');
    return res.status(401).send('Unauthorised');
  }

  console.log('Webhook verified');

  // Process webhook
  const order = req.body;
  console.log('Order:', order.id, order.email);

  // Respond quickly (< 5 seconds)
  res.status(200).send('OK');
});

Webhook Timeout:

// ❌ Processing takes too long (> 5 seconds)
app.post('/webhooks/orders', async (req, res) => {
  await processOrder(req.body);  // Slow operation
  res.send('OK');  // Response delayed
});

// ✅ Respond immediately, process async
app.post('/webhooks/orders', async (req, res) => {
  const order = req.body;

  // Respond quickly
  res.status(200).send('OK');

  // Process in background
  processOrder(order).catch(console.error);
});

7. Common Error Messages

Liquid Errors:

Error: Liquid syntax error: Unknown tag 'section'
Fix: Use {% section %} only in JSON templates, not .liquid files

Error: undefined method 'title' for nil:NilClass
Fix: Variable is nil. Add {% if %} check or provide default:
{{ product.title | default: "No title" }}

Error: Exceeded maximum number of allowed iterations
Fix: Infinite loop detected. Check loop conditions.

JavaScript Errors:

TypeError: Cannot read property 'forEach' of undefined
Fix: Array is undefined. Check:
if (items && Array.isArray(items)) {
  items.forEach(item => { ... });
}

ReferenceError: $ is not defined
Fix: jQuery not loaded or script runs before jQuery loads

SyntaxError: Unexpected token <
Fix: API returned HTML error page instead of JSON. Check API endpoint.

API Errors:

Access denied - check your access scopes
Fix: App needs additional permissions. Update scopes in Partner Dashboard.

Throttled: Exceeded API rate limit
Fix: Implement rate limit handling with exponential backoff.

Field doesn't exist on type
Fix: Check API version and field availability in docs.

Debugging Toolkit

Browser DevTools:

- Console: View errors and logs
- Network: Inspect API requests
- Sources: Set breakpoints
- Application: View cookies, localStorage
- Performance: Profile page load

Shopify Tools:

- Theme Preview: Test changes before publishing
- Theme Inspector: View section data
- API Explorer: Test GraphQL queries
- Webhook Logs: Check delivery status

Useful Console Commands:

// Get all form data
new FormData(document.querySelector('form'))

// View all cookies
document.cookie

// Check localStorage
localStorage

// View all global variables
console.log(window)

// Get computed styles
getComputedStyle(element)

Best Practices

1. Always check for errors before accessing data (API responses) 2. Use try-catch blocks for all async operations 3. Log meaningful messages with context 4. Verify HMAC for all webhooks 5. Test in theme preview before publishing 6. Monitor API rate limits and implement backoff 7. Handle edge cases (nil values, empty arrays) 8. Use browser DevTools for network debugging 9. Check API version compatibility 10. Validate input before API calls

Shopify Functions Reference

Shopify Functions replace Scripts as the way to customise backend logic. They run in a WebAssembly sandbox with strict performance guarantees.

Overview

Function Types

Getting Started

Create a Function

# Generate a new function extension
shopify app generate extension --template discount_function_rust
# or
shopify app generate extension --template discount_function_javascript

# Structure created:
extensions/my-discount/
├── src/
│   ├── main.rs          # Rust: function logic
│   └── run.graphql      # Input query
├── Cargo.toml           # Rust dependencies
├── shopify.extension.toml
└── schema.graphql       # Generated API schema

Input Query (run.graphql)

Define what data your function receives:

query RunInput {
  cart {
    lines {
      quantity
      merchandise {
        ... on ProductVariant {
          id
          product {
            id
            hasAnyTag(tags: ["VIP"])
          }
        }
      }
      cost {
        amountPerQuantity {
          amount
          currencyCode
        }
      }
    }
  }
  discountNode {
    metafield(namespace: "discount", key: "config") {
      value
    }
  }
}

Rust Implementation

use shopify_function::prelude::*;
use shopify_function::Result;

#[shopify_function_target(rename = "function")]
fn function(input: input::ResponseData) -> Result<output::FunctionRunResult> {
    let config: serde_json::Value = serde_json::from_str(
        input.discount_node.metafield
            .as_ref()
            .map(|m| m.value.as_str())
            .unwrap_or("{}"),
    )?;

    let percentage = config.get("percentage")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.0);

    let targets: Vec<output::Target> = input
        .cart
        .lines
        .iter()
        .filter_map(|line| {
            let variant = match &line.merchandise {
                input::InputCartLinesMerchandise::ProductVariant(v) => v,
                _ => return None,
            };

            if variant.product.has_any_tag {
                Some(output::Target::ProductVariant(
                    output::ProductVariantTarget {
                        id: variant.id.clone(),
                        quantity: None,
                    },
                ))
            } else {
                None
            }
        })
        .collect();

    if targets.is_empty() {
        return Ok(output::FunctionRunResult {
            discounts: vec![],
            discount_application_strategy:
                output::DiscountApplicationStrategy::FIRST,
        });
    }

    Ok(output::FunctionRunResult {
        discounts: vec![output::Discount {
            message: Some(format!("{}% VIP discount", percentage)),
            targets,
            value: output::Value::Percentage(output::Percentage {
                value: percentage.to_string(),
            }),
        }],
        discount_application_strategy:
            output::DiscountApplicationStrategy::FIRST,
    })
}

JavaScript Implementation

// src/run.js
export function run(input) {
  const config = JSON.parse(
    input?.discountNode?.metafield?.value ?? "{}"
  );

  const percentage = parseFloat(config.percentage) || 0;

  const targets = input.cart.lines
    .filter((line) => {
      return line.merchandise?.__typename === "ProductVariant"
        && line.merchandise.product.hasAnyTag;
    })
    .map((line) => ({
      productVariant: { id: line.merchandise.id },
    }));

  if (targets.length === 0) {
    return { discounts: [], discountApplicationStrategy: "FIRST" };
  }

  return {
    discounts: [
      {
        message: `${percentage}% VIP discount`,
        targets,
        value: {
          percentage: { value: percentage.toString() },
        },
      },
    ],
    discountApplicationStrategy: "FIRST",
  };
}

Configuration

shopify.extension.toml

api_version = "2026-01"

[[extensions]]
name = "VIP Discount"
handle = "vip-discount"
type = "function"

  [extensions.build]
  command = "cargo wasi build --release"
  path = "target/wasm32-wasi/release/vip-discount.wasm"

  # For JavaScript:
  # command = "npx javy compile src/run.js -o dist/function.wasm"
  # path = "dist/function.wasm"

  [extensions.targeting]
  target = "purchase.product-discount.run"

  [extensions.ui]
  handle = "vip-discount-ui"

  [extensions.input.variables]
  namespace = "discount"
  key = "config"

Testing

Unit tests (Rust)

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_no_discount_without_tag() {
        let input = input::ResponseData {
            cart: input::InputCart {
                lines: vec![/* line without VIP tag */],
            },
            discount_node: input::InputDiscountNode {
                metafield: Some(input::InputDiscountNodeMetafield {
                    value: r#"{"percentage": 10}"#.to_string(),
                }),
            },
        };

        let result = function(input).unwrap();
        assert!(result.discounts.is_empty());
    }
}

Local testing

# Test with sample input
shopify app function run --path extensions/my-discount

# Build and preview
shopify app dev

Deployment

# Deploy function with app
shopify app deploy

# Functions are versioned with the app
# Each deploy creates a new function version

Migration from Scripts

Migration steps:

1. Identify Scripts in use (Settings > Apps > Script Editor) 2. Map each Script to a Function type (see table above) 3. Rewrite logic in Rust or JavaScript 4. Test with shopify app function run 5. Deploy and activate via Shopify admin 6. Disable old Scripts

Performance Guidelines

• Functions must complete within the instruction count limit (~11ms equivalent)
• Minimise allocations - reuse buffers where possible
• Avoid complex string operations in hot paths
• Rust compiles to smaller, faster Wasm than JavaScript
• Use cargo wasi build --release for optimised builds
• Profile with shopify app function run --export-timing

Best Practices

1. Use Rust for production - smaller binaries, faster execution 2. Use JavaScript for prototyping - faster iteration, familiar syntax 3. Keep input queries minimal - request only the fields you need 4. Store configuration in metafields - avoid hardcoded values 5. Test edge cases - empty carts, missing metafields, zero quantities 6. Version your functions - use semantic versioning with app deploys 7. Monitor execution - check function logs in Partner Dashboard

Hydrogen Reference

Hydrogen is Shopify's framework for building custom headless storefronts, powered by React Router 7 (since Hydrogen 2025.5.0, replacing Remix).

Overview

Getting Started

Create a Hydrogen project

# Create new project
npx shopify hydrogen init

# Options:
# - Template: skeleton, demo-store
# - Language: TypeScript (recommended), JavaScript
# - Styling: Tailwind CSS, vanilla CSS

# Project structure:
my-store/
├── app/
│   ├── components/          # Shared components
│   ├── lib/                 # Utilities and helpers
│   ├── routes/              # File-based routing
│   │   ├── _index.tsx       # Homepage
│   │   ├── products.$handle.tsx  # Product page
│   │   ├── collections.$handle.tsx
│   │   └── cart.tsx
│   ├── entry.client.tsx     # Client entry
│   ├── entry.server.tsx     # Server entry
│   └── root.tsx             # Root layout
├── public/                  # Static assets
├── .env                     # Environment variables
├── hydrogen.config.ts       # Hydrogen config
├── react-router.config.ts   # Route config
├── package.json
└── vite.config.ts

Environment variables

# .env
SESSION_SECRET=your-secret
PUBLIC_STOREFRONT_API_TOKEN=your-public-token
PUBLIC_STORE_DOMAIN=your-store.myshopify.com

# Optional: for authenticated Storefront API
PRIVATE_STOREFRONT_API_TOKEN=your-private-token

Routing

Hydrogen uses React Router 7 file-based routing:

Data Loading

Loader pattern (server-side data fetching)

import { useLoaderData, type LoaderFunctionArgs } from 'react-router';

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { storefront } = context;

  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: { handle: params.handle },
  });

  if (!product) {
    throw new Response('Product not found', { status: 404 });
  }

  return { product };
}

export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
      <ProductPrice price={product.priceRange.minVariantPrice} />
    </div>
  );
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      handle
      description
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
      images(first: 10) {
        nodes {
          url
          altText
          width
          height
        }
      }
      variants(first: 100) {
        nodes {
          id
          title
          availableForSale
          price {
            amount
            currencyCode
          }
          selectedOptions {
            name
            value
          }
        }
      }
    }
  }
`;

Action pattern (form submissions)

import { type ActionFunctionArgs } from 'react-router';

export async function action({ request, context }: ActionFunctionArgs) {
  const formData = await request.formData();
  const variantId = formData.get('variantId') as string;
  const quantity = parseInt(formData.get('quantity') as string) || 1;

  const { cart } = context;

  const result = await cart.addLines([
    { merchandiseId: variantId, quantity },
  ]);

  return { cart: result.cart };
}

Storefront API Client

Hydrogen provides a typed Storefront API client:

// app/lib/storefront.ts - automatically configured

// Usage in loaders:
export async function loader({ context }: LoaderFunctionArgs) {
  const { storefront } = context;

  // Simple query
  const { products } = await storefront.query(PRODUCTS_QUERY, {
    variables: { first: 10 },
  });

  // With cache control
  const { collection } = await storefront.query(COLLECTION_QUERY, {
    variables: { handle: 'winter' },
    cache: storefront.CacheLong(),  // Cache for 1 hour
  });

  return { products, collection };
}

Cache strategies

// Built-in cache strategies
storefront.CacheNone()     // No caching (default for mutations)
storefront.CacheShort()    // 1 second stale, 60 seconds max
storefront.CacheLong()     // 1 hour stale, 1 day max
storefront.CacheCustom({
  mode: 'public',
  maxAge: 60,              // seconds
  staleWhileRevalidate: 300,
})

Cart Operations

Hydrogen provides a cart API abstraction:

// In loaders/actions, use context.cart
export async function action({ request, context }: ActionFunctionArgs) {
  const { cart } = context;
  const formData = await request.formData();

  switch (formData.get('action')) {
    case 'add':
      return cart.addLines([{
        merchandiseId: formData.get('variantId') as string,
        quantity: 1,
      }]);

    case 'update':
      return cart.updateLines([{
        id: formData.get('lineId') as string,
        quantity: parseInt(formData.get('quantity') as string),
      }]);

    case 'remove':
      return cart.removeLines([
        formData.get('lineId') as string,
      ]);

    case 'updateNote':
      return cart.updateNote(
        formData.get('note') as string,
      );

    default:
      throw new Error('Unknown cart action');
  }
}

Cart component

import { useFetcher } from 'react-router';
import { CartLineQuantity, CartLinePrice, Money } from '@shopify/hydrogen';

function AddToCartButton({ variantId }: { variantId: string }) {
  const fetcher = useFetcher();
  const isAdding = fetcher.state !== 'idle';

  return (
    <fetcher.Form method="post" action="/cart">
      <input type="hidden" name="action" value="add" />
      <input type="hidden" name="variantId" value={variantId} />
      <button type="submit" disabled={isAdding}>
        {isAdding ? 'Adding...' : 'Add to Cart'}
      </button>
    </fetcher.Form>
  );
}

Hydrogen Components

Built-in components for common e-commerce patterns:

import {
  Image,
  Money,
  ShopPayButton,
  Video,
  ExternalVideo,
  ModelViewer,
  MediaFile,
  CartLineQuantity,
  CartLinePrice,
} from '@shopify/hydrogen';

// Optimised image with CDN sizing
<Image
  data={product.images.nodes[0]}
  sizes="(min-width: 768px) 50vw, 100vw"
  aspectRatio="1/1"
/>

// Formatted price
<Money data={product.priceRange.minVariantPrice} />

// Shop Pay button
<ShopPayButton
  variantIds={[selectedVariant.id]}
  storeDomain={shop.primaryDomain.url}
/>

SEO

// In root.tsx or individual routes
import { getSeoMeta } from '@shopify/hydrogen';

export const meta = ({ data }) => {
  return getSeoMeta({
    title: data.product.title,
    description: data.product.description,
    url: `https://store.com/products/${data.product.handle}`,
    image: data.product.images.nodes[0]?.url,
  });
};

Deployment

Shopify Oxygen (recommended)

# Deploy to Oxygen
npx shopify hydrogen deploy

# Environment variables managed in Shopify admin:
# Settings > Hydrogen > Environment variables

Self-hosted (Cloudflare Workers, Vercel, etc.)

# Build for production
npm run build

# Cloudflare Workers
npx wrangler deploy

# Node.js server
npm start

Vite configuration

// vite.config.ts
import { defineConfig } from 'vite';
import { hydrogen } from '@shopify/hydrogen/vite';
import { reactRouter } from '@react-router/dev/vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [
    tailwindcss(),
    hydrogen(),
    reactRouter(),
  ],
});

Best Practices

1. Use cache strategies - CacheLong() for collections, CacheShort() for cart 2. Minimise Storefront API queries - request only needed fields 3. Use `defer` for non-critical data to improve time-to-first-byte 4. Implement SEO with getSeoMeta on all public routes 5. Use Hydrogen components (Image, Money) for built-in optimisations 6. Handle loading states with useFetcher for cart operations 7. Set up analytics with Hydrogen's built-in analytics utilities 8. Test with Oxygen before deploying to production 9. Use TypeScript for type safety with Storefront API responses 10. Keep queries colocated with route files for maintainability

Liquid Filters Reference

Filters modify output using pipe syntax: {{ value | filter: parameter }}

String Filters

upcase

Convert to uppercase:

{{ "hello world" | upcase }}
{# Output: HELLO WORLD #}

downcase

Convert to lowercase:

{{ "HELLO WORLD" | downcase }}
{# Output: hello world #}

capitalize

Capitalize first letter only:

{{ "hello world" | capitalize }}
{# Output: Hello world #}

reverse

Reverse string or array:

{{ "hello" | reverse }}
{# Output: olleh #}

{{ array | reverse }}
{# Reverses array order #}

size

Get character count or array length:

{{ "hello" | size }}
{# Output: 5 #}

{{ collection.products | size }}
{# Output: number of products #}

remove

Remove all occurrences of substring:

{{ "hello world world" | remove: "world" }}
{# Output: hello   #}

remove_first

Remove first occurrence only:

{{ "hello world world" | remove_first: "world" }}
{# Output: hello  world #}

replace

Replace all occurrences:

{{ "hello" | replace: "l", "L" }}
{# Output: heLLo #}

replace_first

Replace first occurrence only:

{{ "hello" | replace_first: "l", "L" }}
{# Output: heLlo #}

split

Split string into array:

{{ "a,b,c,d" | split: "," }}
{# Output: ["a", "b", "c", "d"] #}

{% assign tags = "sale,new,featured" | split: "," %}
{% for tag in tags %}
  {{ tag }}
{% endfor %}

strip

Remove leading and trailing whitespace:

{{ "  hello  " | strip }}
{# Output: hello #}

lstrip

Remove leading whitespace only:

{{ "  hello  " | lstrip }}
{# Output: hello   #}

rstrip

Remove trailing whitespace only:

{{ "  hello  " | rstrip }}
{# Output:   hello #}

truncate

Limit string length with ellipsis:

{{ "hello world" | truncate: 8 }}
{# Output: hello... #}

{{ "hello world" | truncate: 10, "!" }}
{# Output: hello worl! #}

{{ "hello world" | truncate: 50 }}
{# Output: hello world (no truncation if shorter) #}

truncatewords

Limit by word count:

{{ "hello world testing" | truncatewords: 2 }}
{# Output: hello world... #}

{{ "hello world testing" | truncatewords: 2, "--" }}
{# Output: hello world-- #}

append

Add string to end:

{{ "hello" | append: " world" }}
{# Output: hello world #}

{% assign file_name = "image" | append: ".jpg" %}
{# file_name: image.jpg #}

prepend

Add string to beginning:

{{ "world" | prepend: "hello " }}
{# Output: hello world #}

newline_to_br

Convert newlines to <br> tags:

{{ product.description | newline_to_br }}
{# Converts \n to <br> #}

strip_html

Remove all HTML tags:

{{ "<p>Hello <strong>world</strong></p>" | strip_html }}
{# Output: Hello world #}

escape

Escape HTML special characters:

{{ "<div>Test</div>" | escape }}
{# Output: &lt;div&gt;Test&lt;/div&gt; #}

escape_once

Escape HTML but don't double-escape:

{{ "<div>" | escape_once }}
{# Output: <div> (not double-escaped) #}

url_encode

URL-encode string:

{{ "hello world" | url_encode }}
{# Output: hello+world #}

{{ "foo@bar.com" | url_encode }}
{# Output: foo%40bar.com #}

url_decode

Decode URL-encoded string:

{{ "hello+world" | url_decode }}
{# Output: hello world #}

base64_encode

Encode to base64:

{{ "hello" | base64_encode }}
{# Output: aGVsbG8= #}

base64_decode

Decode from base64:

{{ "aGVsbG8=" | base64_decode }}
{# Output: hello #}

slice

Extract substring or array slice:

{{ "hello" | slice: 0, 3 }}
{# Output: hel #}

{{ "hello" | slice: -3, 3 }}
{# Output: llo #}

Numeric Filters

abs

Absolute value:

{{ -5 | abs }}
{# Output: 5 #}

{{ 5 | abs }}
{# Output: 5 #}

ceil

Round up to nearest integer:

{{ 1.2 | ceil }}
{# Output: 2 #}

{{ 1.9 | ceil }}
{# Output: 2 #}

floor

Round down to nearest integer:

{{ 1.9 | floor }}
{# Output: 1 #}

{{ 1.1 | floor }}
{# Output: 1 #}

round

Round to specified decimal places:

{{ 1.5 | round }}
{# Output: 2 #}

{{ 1.567 | round: 2 }}
{# Output: 1.57 #}

{{ 1.234 | round: 1 }}
{# Output: 1.2 #}

plus

Addition:

{{ 5 | plus: 3 }}
{# Output: 8 #}

{{ product.price | plus: 1000 }}
{# Add $10.00 (prices in cents) #}

minus

Subtraction:

{{ 5 | minus: 3 }}
{# Output: 2 #}

times

Multiplication:

{{ 5 | times: 3 }}
{# Output: 15 #}

{{ product.price | times: 0.8 }}
{# 20% discount #}

divided_by

Integer division:

{{ 10 | divided_by: 2 }}
{# Output: 5 #}

{{ 10 | divided_by: 3 }}
{# Output: 3 (integer division) #}

{{ 10.0 | divided_by: 3 }}
{# Output: 3.33... (float division) #}

modulo

Get remainder:

{{ 10 | modulo: 3 }}
{# Output: 1 #}

{# Check if even #}
{% if forloop.index | modulo: 2 == 0 %}
  Even row
{% endif %}

at_least

Ensure minimum value:

{{ 1 | at_least: 5 }}
{# Output: 5 #}

{{ 10 | at_least: 5 }}
{# Output: 10 #}

at_most

Ensure maximum value:

{{ 100 | at_most: 50 }}
{# Output: 50 #}

{{ 10 | at_most: 50 }}
{# Output: 10 #}

Array/Collection Filters

first

Get first element:

{{ collection.products | first }}
{# Returns first product #}

{{ "a,b,c" | split: "," | first }}
{# Output: a #}

last

Get last element:

{{ collection.products | last }}
{# Returns last product #}

join

Join array with separator:

{{ product.tags | join: ", " }}
{# Output: sale, new, featured #}

map

Extract property from each object:

{{ collection.products | map: "title" }}
{# Returns array of product titles #}

{{ collection.products | map: "title" | join: ", " }}
{# Output: Product 1, Product 2, Product 3 #}

sort

Sort array by property:

{{ collection.products | sort: "price" }}
{# Sort by price ascending #}

{{ collection.products | sort: "title" }}
{# Sort alphabetically #}

sort_natural

Case-insensitive sort:

{{ collection.products | sort_natural: "title" }}
{# Sorts: Apple, banana, Cherry (natural order) #}

where

Filter array by property value:

{{ collection.products | where: "vendor", "Nike" }}
{# Only Nike products #}

{{ collection.products | where: "available", true }}
{# Only available products #}

{{ collection.products | where: "type", "shoes" | map: "title" }}
{# Combine with map #}

uniq

Remove duplicates:

{{ collection.all_vendors | uniq }}
{# Unique vendor names #}

limit

Limit array to N items:

{{ collection.products | limit: 5 }}
{# First 5 products #}

offset

Skip first N items:

{{ collection.products | offset: 10 }}
{# Products from 11th onward #}

concat

Merge two arrays:

{% assign array1 = "a,b,c" | split: "," %}
{% assign array2 = "d,e,f" | split: "," %}
{{ array1 | concat: array2 | join: ", " }}
{# Output: a, b, c, d, e, f #}

compact

Remove nil values from array:

{{ array | compact }}
{# Removes nil/null elements #}

Shopify-Specific Filters

money

Format as currency with symbol:

{{ 1000 | money }}
{# Output: $10.00 #}

{{ 1599 | money }}
{# Output: $15.99 #}

money_without_currency

Format without currency symbol:

{{ 1000 | money_without_currency }}
{# Output: 10.00 #}

money_without_trailing_zeros

Remove unnecessary decimals:

{{ 1000 | money_without_trailing_zeros }}
{# Output: $10 #}

{{ 1050 | money_without_trailing_zeros }}
{# Output: $10.50 #}

weight_with_unit

Add weight unit:

{{ 500 | weight_with_unit }}
{# Output: 500 g #}

{{ product.variants.first.weight | weight_with_unit }}

asset_url

Get theme asset CDN URL:

{{ 'logo.png' | asset_url }}
{# Output: //cdn.shopify.com/s/files/1/0000/0000/t/1/assets/logo.png #}

img_url

Generate image URL with size:

{{ product.featured_image | img_url: '500x500' }}
{# Resize to 500x500 #}

{{ product.featured_image | img_url: 'large' }}
{# Named size: pico, icon, thumb, small, compact, medium, large, grande, 1024x1024, 2048x2048 #}

{{ product.featured_image | img_url: '500x500', crop: 'center' }}
{# With crop #}

link_to_type

Create link to product type collection:

{{ product.type | link_to_type }}
{# Output: <a href="/collections/types?q=Shoes">Shoes</a> #}

link_to_vendor

Create link to vendor collection:

{{ product.vendor | link_to_vendor }}
{# Output: <a href="/collections/vendors?q=Nike">Nike</a> #}

link_to_tag

Create link to tag filter:

{{ tag | link_to_tag: tag }}
{# Output: <a href="/collections/all/sale">sale</a> #}

highlight

Highlight search terms:

{{ product.title | highlight: search.terms }}
{# Wraps search terms in <strong class="highlight"> tags #}

highlight_active_tag

Highlight current tag:

{{ tag | highlight_active_tag: tag }}
{# Wraps current tag in <span class="active"> #}

payment_type_img_url

Get payment icon URL:

{{ 'visa' | payment_type_img_url }}
{# Returns Shopify-hosted Visa icon URL #}

placeholder_svg_tag

Generate placeholder SVG:

{{ 'product-1' | placeholder_svg_tag }}
{# Generates placeholder product image SVG #}

{{ 'collection-1' | placeholder_svg_tag: 'custom-class' }}
{# With custom CSS class #}

color_to_rgb

Convert hex to RGB:

{{ '#ff0000' | color_to_rgb }}
{# Output: rgb(255, 0, 0) #}

color_to_hsl

Convert hex to HSL:

{{ '#ff0000' | color_to_hsl }}
{# Output: hsl(0, 100%, 50%) #}

color_extract

Extract colour component:

{{ '#ff0000' | color_extract: 'red' }}
{# Output: 255 #}

color_brightness

Calculate brightness:

{{ '#ff0000' | color_brightness }}
{# Output: brightness value 0-255 #}

color_modify

Modify colour properties:

{{ '#ff0000' | color_modify: 'alpha', 0.5 }}
{# Adjust alpha channel #}

Date Filters

date

Format date using strftime:

{{ order.created_at | date: '%B %d, %Y' }}
{# Output: November 10, 2026 #}

{{ order.created_at | date: '%m/%d/%Y' }}
{# Output: 11/10/2026 #}

{{ order.created_at | date: '%Y-%m-%d %H:%M:%S' }}
{# Output: 2026-11-10 14:30:00 #}

Common format codes:

• %Y - 4-digit year (2026)
• %y - 2-digit year (26)
• %m - Month number (11)
• %B - Full month (November)
• %b - Short month (Nov)
• %d - Day of month (10)
• %e - Day without leading zero (10)
• %A - Full weekday (Monday)
• %a - Short weekday (Mon)
• %H - Hour 24-hour (14)
• %I - Hour 12-hour (02)
• %M - Minutes (30)
• %S - Seconds (45)
• %p - AM/PM
• %z - Timezone offset (+0000)

Examples:

{{ "now" | date: "%Y-%m-%d" }}
{# Current date: 2026-11-10 #}

{{ article.published_at | date: "%B %d, %Y at %I:%M %p" }}
{# November 10, 2026 at 02:30 PM #}

URL Filters

url_for_type

Get collection URL for product type:

{{ product.type | url_for_type }}
{# Output: /collections/types?q=Shoes #}

url_for_vendor

Get collection URL for vendor:

{{ product.vendor | url_for_vendor }}
{# Output: /collections/vendors?q=Nike #}

within

Scope URL within collection:

{{ product.url | within: collection }}
{# Output: /collections/sale/products/product-handle #}

default_pagination

Generate pagination HTML:

{{ paginate | default_pagination }}
{# Outputs complete pagination HTML #}

Utility Filters

default

Provide fallback value:

{{ product.metafield | default: "N/A" }}
{# If metafield is nil, outputs "N/A" #}

{{ variant.title | default: "Default" }}

json

Convert to JSON:

{{ product | json }}
{# Outputs product object as JSON string #}

<script>
var productData = {{ product | json }};
</script>

Filter Chaining

Filters execute left-to-right and can be chained:

{{ "hello world" | upcase | replace: "WORLD", "SHOPIFY" }}
{# Output: HELLO SHOPIFY #}

{{ collection.products | where: "available" | map: "title" | sort | join: ", " }}
{# Filter → extract → sort → join #}

{{ product.price | times: 0.8 | round: 2 | money }}
{# Calculate 20% discount, round, format as money #}

{{ product.description | strip_html | truncatewords: 50 | escape }}
{# Strip HTML → truncate → escape for safety #}

Performance Tips

1. Cache filtered results if used multiple times:

{# ❌ Inefficient: #}
{% for i in (1..10) %}
  {{ collection.products | where: "available" | size }}
{% endfor %}

{# ✅ Efficient: #}
{% assign available_products = collection.products | where: "available" %}
{% for i in (1..10) %}
  {{ available_products.size }}
{% endfor %}

2. Use `limit` and `offset` filters instead of manual iteration control

3. Combine filters intelligently to reduce operations:

{# ❌ Less efficient: #}
{% assign titles = collection.products | map: "title" %}
{% assign sorted = titles | sort %}
{% assign limited = sorted | limit: 5 %}

{# ✅ More efficient: #}
{% assign limited_titles = collection.products | map: "title" | sort | limit: 5 %}

Liquid Objects Reference

Global Objects (Available Everywhere)

shop

Store-level information:

{{ shop.name }}              {# Store name #}
{{ shop.url }}               {# Store URL (https://...) #}
{{ shop.description }}       {# Store tagline/description #}
{{ shop.currency }}          {# ISO currency code: USD, GBP, EUR #}
{{ shop.money_format }}      {# Money format string: ${{amount}} #}
{{ shop.permanent_domain }}  {# Domain: store.myshopify.com #}
{{ shop.domain }}            {# Primary domain #}
{{ shop.email }}             {# Support email #}
{{ shop.phone }}             {# Support phone #}
{{ shop.address }}           {# Store address object #}
{{ shop.address.city }}
{{ shop.address.province }}
{{ shop.address.country }}
{{ shop.address.zip }}
{{ shop.enabled_payment_types }}  {# Array of enabled payment methods #}
{{ shop.checkout.privacy_policy_url }}
{{ shop.checkout.terms_of_service_url }}
{{ shop.checkout.refund_policy_url }}

request

Request context and routing:

{{ request.path }}                {# Current URL path: /products/handle #}
{{ request.host }}                {# Current domain #}
{{ request.origin }}              {# Protocol + host #}
{{ request.page_type }}           {# "product", "collection", "index", etc. #}
{{ request.locale.iso_code }}     {# Language: "en", "fr", "es" #}
{{ request.locale.root_url }}     {# Root URL for locale #}
{{ request.design_mode }}         {# Boolean: theme editor active #}
{{ request.visual_preview_mode }} {# Boolean: theme preview active #}

{# Query parameters #}
{{ request.query_string }}        {# Full query string #}

{# Build canonical URL #}
{{ request.canonical_url }}       {# Full canonical URL #}
{{ request.path_with_query }}     {# Path + query string #}

settings

Theme settings (from settings_schema.json):

{# Colours #}
{{ settings.color_primary }}
{{ settings.color_secondary }}
{{ settings.color_body_bg }}

{# Typography #}
{{ settings.type_header_font }}
{{ settings.type_body_font }}

{# Layout #}
{{ settings.layout_container_width }}
{{ settings.layout_sidebar_enabled }}

{# Media #}
{{ settings.logo }}              {# Image object #}
{{ settings.logo.src }}
{{ settings.logo.width }}
{{ settings.logo.height }}
{{ settings.logo.alt }}

{# Text content #}
{{ settings.announcement_text }}
{{ settings.footer_text }}

{# Boolean settings #}
{% if settings.show_breadcrumbs %}
  {# Render breadcrumbs #}
{% endif %}

{# URL settings #}
{{ settings.social_twitter_link }}
{{ settings.social_facebook_link }}

routes

URL routes to standard pages:

{{ routes.root_url }}               {# / #}
{{ routes.account_url }}            {# /account #}
{{ routes.account_login_url }}      {# /account/login #}
{{ routes.account_logout_url }}     {# /account/logout #}
{{ routes.account_register_url }}   {# /account/register #}
{{ routes.account_addresses_url }}  {# /account/addresses #}
{{ routes.collections_url }}        {# /collections #}
{{ routes.all_products_collection_url }}  {# /collections/all #}
{{ routes.search_url }}             {# /search #}
{{ routes.cart_url }}               {# /cart #}
{{ routes.cart_add_url }}           {# /cart/add #}
{{ routes.cart_change_url }}        {# /cart/change #}
{{ routes.cart_clear_url }}         {# /cart/clear #}
{{ routes.cart_update_url }}        {# /cart/update #}

section

Current section context (within sections):

{{ section.id }}                  {# Unique ID: "section-1234567890" #}
{{ section.settings.title }}      {# Section setting #}
{{ section.settings.background_color }}
{{ section.index }}               {# Position on page #}
{{ section.location }}            {# Where section appears #}

{# Blocks #}
{{ section.blocks }}              {# Array of blocks #}
{{ section.blocks.size }}         {# Number of blocks #}

{% for block in section.blocks %}
  {{ block.id }}
  {{ block.type }}
  {{ block.settings.text }}
  {{ block.shopify_attributes }}  {# Required for theme editor #}
{% endfor %}

{# Blocks by type #}
{{ section.blocks_by_type }}      {# Organised by type #}

block

Current block context (within section blocks):

{{ block.id }}                    {# Unique ID: "block-9876543210" #}
{{ block.type }}                  {# Block type name #}
{{ block.settings.text }}         {# Block setting #}
{{ block.shopify_attributes }}    {# Required for theme editor #}

{# Example usage in section #}
{% for block in section.blocks %}
  <div {{ block.shopify_attributes }}>
    {% case block.type %}
      {% when 'heading' %}
        <h2>{{ block.settings.title }}</h2>
      {% when 'text' %}
        <p>{{ block.settings.content }}</p>
    {% endcase %}
  </div>
{% endfor %}

Page Context Objects

product

Product object (on product pages):

{# Core properties #}
{{ product.id }}                   {# Numeric ID #}
{{ product.title }}                {# Product name #}
{{ product.handle }}               {# URL slug #}
{{ product.description }}          {# Full HTML description #}
{{ product.vendor }}               {# Brand/manufacturer #}
{{ product.type }}                 {# Category #}
{{ product.url }}                  {# Product URL #}
{{ product.available }}            {# Boolean: any variant in stock #}
{{ product.published_at }}         {# Publication timestamp #}
{{ product.created_at }}           {# Creation timestamp #}
{{ product.updated_at }}           {# Last modified timestamp #}

{# Pricing (in cents) #}
{{ product.price }}                {# Current variant price #}
{{ product.price_min }}            {# Cheapest variant #}
{{ product.price_max }}            {# Most expensive variant #}
{{ product.price_varies }}         {# Boolean: different prices #}
{{ product.compare_at_price }}     {# Original price for sales #}
{{ product.compare_at_price_min }}
{{ product.compare_at_price_max }}
{{ product.compare_at_price_varies }}

{# Images #}
{{ product.featured_image }}       {# Primary image object #}
{{ product.featured_image.src }}
{{ product.featured_image.width }}
{{ product.featured_image.height }}
{{ product.featured_image.alt }}
{{ product.featured_image | img_url: '500x500' }}

{{ product.images }}               {# Array of all images #}
{{ product.images.size }}          {# Image count #}

{% for image in product.images %}
  <img src="{{ image | img_url: '300x300' }}" alt="{{ image.alt }}">
{% endfor %}

{{ product.media }}                {# Array of all media (images, videos, 3D) #}

{# Variants #}
{{ product.variants }}             {# Array of variants #}
{{ product.variants.size }}        {# Variant count #}
{{ product.selected_variant }}     {# Currently selected variant #}
{{ product.selected_or_first_available_variant }}
{{ product.first_available_variant }}
{{ product.has_only_default_variant }}  {# Boolean: single variant #}

{# Options #}
{{ product.options }}              {# Array: ["Size", "Color"] #}
{{ product.options_with_values }}  {# Array of option objects #}

{% for option in product.options_with_values %}
  <label>{{ option.name }}</label>
  <select>
    {% for value in option.values %}
      <option>{{ value }}</option>
    {% endfor %}
  </select>
{% endfor %}

{# Collections #}
{{ product.collections }}          {# Array of collections #}
{{ product.collections.size }}

{# Tags #}
{{ product.tags }}                 {# Array of tags #}
{{ product.tags | join: ", " }}

{# Custom data #}
{{ product.metafields.namespace.key }}
{{ product.metafields.custom.field_name }}

{# Template #}
{{ product.template_suffix }}      {# Template variant: "alternate" #}

variant

Variant object (product.variants, product.selected_variant):

{{ variant.id }}                   {# Variant ID #}
{{ variant.product_id }}           {# Parent product ID #}
{{ variant.title }}                {# "Red / Medium" #}
{{ variant.price }}                {# Price in cents #}
{{ variant.compare_at_price }}     {# Original price #}
{{ variant.sku }}                  {# SKU code #}
{{ variant.barcode }}              {# Barcode #}
{{ variant.weight }}               {# Weight in grams #}
{{ variant.weight_unit }}          {# "kg", "lb", etc. #}
{{ variant.weight_in_unit }}       {# Weight in configured unit #}

{# Availability #}
{{ variant.available }}            {# Boolean: in stock #}
{{ variant.inventory_quantity }}   {# Current stock level #}
{{ variant.inventory_policy }}     {# "continue" or "deny" #}
{{ variant.inventory_management }} {# "shopify" or null #}

{# Options #}
{{ variant.option1 }}              {# First option value: "Red" #}
{{ variant.option2 }}              {# Second option value: "Medium" #}
{{ variant.option3 }}              {# Third option value #}
{{ variant.options }}              {# Array: ["Red", "Medium"] #}

{# Image #}
{{ variant.featured_image }}       {# Variant-specific image #}
{{ variant.image }}                {# Same as featured_image #}

{# URL #}
{{ variant.url }}                  {# Product URL with variant param #}

{# Metafields #}
{{ variant.metafields.namespace.key }}

collection

Collection object (on collection pages):

{# Core properties #}
{{ collection.id }}                {# Numeric ID #}
{{ collection.title }}             {# Collection name #}
{{ collection.handle }}            {# URL slug #}
{{ collection.description }}       {# HTML description #}
{{ collection.url }}               {# Collection URL #}
{{ collection.published_at }}      {# Publication date #}

{# Image #}
{{ collection.image }}             {# Featured image object #}
{{ collection.image.src }}
{{ collection.image | img_url: '1024x1024' }}

{# Products #}
{{ collection.products }}          {# Array of products #}
{{ collection.products_count }}    {# Current page count #}
{{ collection.all_products_count }}{# Total count #}

{# Filtering & sorting #}
{{ collection.all_tags }}          {# All tags (max 1000) #}
{{ collection.all_types }}         {# All product types #}
{{ collection.all_vendors }}       {# All vendors #}
{{ collection.current_type }}      {# Active type filter #}
{{ collection.current_vendor }}    {# Active vendor filter #}
{{ collection.sort_by }}           {# Current sort method #}
{{ collection.default_sort_by }}   {# Default sort #}
{{ collection.sort_options }}      {# Available sort methods #}

{# Filters (Storefront Filtering) #}
{{ collection.filters }}           {# Array of filter objects #}

{% for filter in collection.filters %}
  {{ filter.label }}               {# Filter name #}
  {{ filter.type }}                {# "list", "price_range" #}
  {{ filter.active_values }}       {# Currently active #}
  {{ filter.values }}              {# Available values #}
{% endfor %}

{# Navigation (on product pages within collection) #}
{{ collection.next_product }}      {# Next product in collection #}
{{ collection.previous_product }}  {# Previous product #}

{# Metafields #}
{{ collection.metafields.namespace.key }}

{# Template #}
{{ collection.template_suffix }}

cart

Cart object (global - always available):

{# Cart state #}
{{ cart.item_count }}              {# Total line items #}
{{ cart.total_price }}             {# Total in cents #}
{{ cart.total_weight }}            {# Weight sum #}
{{ cart.empty? }}                  {# Boolean: is cart empty #}

{# Items #}
{{ cart.items }}                   {# Array of line items #}
{{ cart.items.size }}              {# Number of line items #}

{% for item in cart.items %}
  {{ item.product_id }}
  {{ item.variant_id }}
  {{ item.title }}
  {{ item.quantity }}
  {{ item.price }}
  {{ item.line_price }}            {# price × quantity #}
  {{ item.image }}
{% endfor %}

{# Notes and attributes #}
{{ cart.note }}                    {# Customer note #}
{{ cart.attributes }}              {# Custom cart attributes #}

{# Access specific attribute #}
{% if cart.attributes.gift_wrap %}
  Gift wrap requested
{% endif %}

{# Discounts #}
{{ cart.cart_level_discount_applications }}
{{ cart.total_discount }}          {# Total discount amount #}

{# Checkout #}
{{ cart.requires_shipping }}       {# Boolean #}

line_item

Line item object (cart.items):

{% for item in cart.items %}
  {{ item.id }}                    {# Line item ID #}
  {{ item.key }}                   {# Unique key #}
  {{ item.product_id }}            {# Product ID #}
  {{ item.variant_id }}            {# Variant ID #}

  {# Product info #}
  {{ item.product }}               {# Product object #}
  {{ item.variant }}               {# Variant object #}
  {{ item.title }}                 {# Product title #}
  {{ item.product_title }}         {# Same as title #}
  {{ item.variant_title }}         {# Variant options #}

  {# Pricing #}
  {{ item.quantity }}              {# Quantity ordered #}
  {{ item.price }}                 {# Price per unit (cents) #}
  {{ item.line_price }}            {# Total: price × quantity #}
  {{ item.original_price }}        {# Before discounts #}
  {{ item.original_line_price }}
  {{ item.final_price }}           {# After discounts #}
  {{ item.final_line_price }}

  {# Images #}
  {{ item.image }}                 {# Line item image #}
  {{ item.featured_image.src }}

  {# URL #}
  {{ item.url }}                   {# Link to product #}

  {# SKU #}
  {{ item.sku }}                   {# Variant SKU #}

  {# Properties (custom line item data) #}
  {{ item.properties }}            {# Hash of properties #}
  {% for property in item.properties %}
    {{ property.first }}: {{ property.last }}
  {% endfor %}

  {# Discounts #}
  {{ item.discount_allocations }}
  {% for discount in item.discount_allocations %}
    {{ discount.amount }}
    {{ discount.discount_application.title }}
  {% endfor %}

  {# Fulfilment #}
  {{ item.requires_shipping }}     {# Boolean #}
  {{ item.taxable }}               {# Boolean #}
{% endfor %}

customer

Customer object (when logged in):

{% if customer %}
  {{ customer.id }}                    {# Numeric ID #}
  {{ customer.email }}                 {# Email address #}
  {{ customer.first_name }}
  {{ customer.last_name }}
  {{ customer.name }}                  {# Full name #}
  {{ customer.phone }}

  {# Account status #}
  {{ customer.has_account }}           {# Boolean: registered #}
  {{ customer.accepts_marketing }}     {# Email marketing opt-in #}
  {{ customer.email_marketing_consent }}

  {# Addresses #}
  {{ customer.addresses }}             {# Array of addresses #}
  {{ customer.addresses_count }}
  {{ customer.default_address }}       {# Primary address #}

  {% for address in customer.addresses %}
    {{ address.first_name }}
    {{ address.last_name }}
    {{ address.address1 }}
    {{ address.address2 }}
    {{ address.city }}
    {{ address.province }}
    {{ address.province_code }}        {# State/region code #}
    {{ address.country }}
    {{ address.country_code }}         {# Country code: US, CA, etc. #}
    {{ address.zip }}
    {{ address.phone }}
    {{ address.company }}
  {% endfor %}

  {# Orders #}
  {{ customer.orders }}                {# Array of orders #}
  {{ customer.orders_count }}          {# Total orders #}
  {{ customer.total_spent }}           {# Lifetime value (cents) #}

  {# Tags #}
  {{ customer.tags }}                  {# Array of customer tags #}

  {# Metafields #}
  {{ customer.metafields.namespace.key }}
{% endif %}

order

Order object (order confirmation, customer account):

{{ order.id }}                     {# Numeric ID #}
{{ order.name }}                   {# Order name: "#1001" #}
{{ order.order_number }}           {# 1001 #}
{{ order.confirmation_number }}    {# Unique confirmation #}
{{ order.email }}                  {# Customer email #}
{{ order.phone }}                  {# Customer phone #}
{{ order.customer_url }}           {# Link to view order #}

{# Timestamps #}
{{ order.created_at }}             {# Order date/time #}
{{ order.updated_at }}
{{ order.cancelled_at }}           {# If cancelled #}
{{ order.processed_at }}

{# Customer #}
{{ order.customer }}               {# Customer object #}
{{ order.customer.name }}

{# Items #}
{{ order.line_items }}             {# Array of line items #}
{{ order.line_items_count }}

{% for item in order.line_items %}
  {{ item.title }}
  {{ item.quantity }}
  {{ item.price }}
  {{ item.line_price }}
{% endfor %}

{# Pricing #}
{{ order.subtotal_price }}         {# Before tax/shipping #}
{{ order.total_price }}            {# Grand total #}
{{ order.tax_price }}              {# Total tax #}
{{ order.shipping_price }}         {# Shipping cost #}
{{ order.total_discounts }}        {# Discount amount #}

{# Status #}
{{ order.financial_status }}       {# "paid", "pending", "refunded" #}
{{ order.fulfilment_status }}      {# "fulfilled", "partial", null #}
{{ order.cancelled }}              {# Boolean #}
{{ order.cancel_reason }}

{# Addresses #}
{{ order.shipping_address }}
{{ order.billing_address }}

{# Shipping #}
{{ order.shipping_method.title }}  {# Shipping method name #}
{{ order.shipping_method.price }}

{# Discounts #}
{{ order.discount_applications }}
{% for discount in order.discount_applications %}
  {{ discount.title }}
  {{ discount.total_allocated_amount }}
{% endfor %}

{# Notes #}
{{ order.note }}                   {# Customer note #}
{{ order.attributes }}             {# Custom attributes #}

{# Tags #}
{{ order.tags }}

article

Article object (blog post pages):

{{ article.id }}                   {# Numeric ID #}
{{ article.title }}                {# Article headline #}
{{ article.handle }}               {# URL slug #}
{{ article.content }}              {# Full HTML content #}
{{ article.excerpt }}              {# Summary/teaser #}
{{ article.excerpt_or_content }}   {# Excerpt if set, else content #}

{# Author #}
{{ article.author }}               {# Author name #}
{{ article.author_url }}           {# Author profile URL #}

{# Dates #}
{{ article.published_at }}         {# Publication date #}
{{ article.created_at }}
{{ article.updated_at }}

{# URL #}
{{ article.url }}                  {# Article URL #}

{# Image #}
{{ article.image }}                {# Featured image #}
{{ article.image.src }}
{{ article.image | img_url: 'large' }}

{# Comments #}
{{ article.comments }}             {# Array of comments #}
{{ article.comments_count }}
{{ article.comments_enabled }}     {# Boolean #}
{{ article.moderated }}            {# Comment moderation enabled #}

{# Tags #}
{{ article.tags }}                 {# Array of tags #}

{# Blog reference #}
{{ article.blog }}                 {# Parent blog object #}
{{ article.blog.title }}

{# Metafields #}
{{ article.metafields.namespace.key }}

blog

Blog object (blog listing page):

{{ blog.id }}                      {# Numeric ID #}
{{ blog.title }}                   {# Blog name #}
{{ blog.handle }}                  {# URL slug #}
{{ blog.url }}                     {# Blog URL #}

{# Articles #}
{{ blog.articles }}                {# Array of articles #}
{{ blog.articles_count }}          {# Total articles #}

{# Tags #}
{{ blog.all_tags }}                {# All article tags #}

{# Metafields #}
{{ blog.metafields.namespace.key }}

search

Search results object:

{{ search.performed }}             {# Boolean: search executed #}
{{ search.results }}               {# Results array #}
{{ search.results_count }}         {# Number of results #}
{{ search.terms }}                 {# Search query #}
{{ search.types }}                 {# Resource types found #}

{% for item in search.results %}
  {% case item.object_type %}
    {% when 'product' %}
      {{ item.title }}
      {{ item.price | money }}
    {% when 'article' %}
      {{ item.title }}
      {{ item.excerpt }}
    {% when 'page' %}
      {{ item.title }}
      {{ item.content | strip_html | truncatewords: 50 }}
  {% endcase %}
{% endfor %}

Metafields

Access custom data on any object:

{# Product metafields #}
{{ product.metafields.namespace.key }}
{{ product.metafields.custom.warranty_info }}
{{ product.metafields.specifications.material }}

{# Collection metafields #}
{{ collection.metafields.seo.custom_title }}

{# Customer metafields #}
{{ customer.metafields.loyalty.points }}

{# Shop metafields #}
{{ shop.metafields.global.announcement }}

{# Check for existence #}
{% if product.metafields.custom.size_guide %}
  {{ product.metafields.custom.size_guide }}
{% endif %}

{# Use default filter for safety #}
{{ product.metafields.custom.field | default: "Not specified" }}

Metaobjects

Access metaobject definitions:

{# Access metaobject by handle #}
{% assign testimonial = shop.metaobjects.testimonials['customer-review-1'] %}

{{ testimonial.name }}
{{ testimonial.rating }}
{{ testimonial.content }}

{# Loop through metaobjects #}
{% for testimonial in shop.metaobjects.testimonials.values %}
  {{ testimonial.fields.author }}
  {{ testimonial.fields.quote }}
{% endfor %}

Liquid Syntax Reference

Tag Categories

Control Flow Tags

if/elsif/else/endif

{% if product.available %}
  <button>Add to Cart</button>
{% elsif product.coming_soon %}
  <p>Coming Soon</p>
{% else %}
  <p>Sold Out</p>
{% endif %}

Operators:

• == - equals
• != - not equals
• > - greater than
• < - less than
• >= - greater than or equal
• <= - less than or equal
• contains - substring or array contains
• and - logical AND
• or - logical OR

Examples:

{% if product.price > 100 and product.available %}
  Premium item in stock
{% endif %}

{% if product.tags contains 'sale' or product.type == 'clearance' %}
  On sale!
{% endif %}

unless

Negated if statement:

{% unless customer.name == blank %}
  Hello, {{ customer.name }}
{% endunless %}

{# Equivalent to: #}
{% if customer.name != blank %}
  Hello, {{ customer.name }}
{% endif %}

case/when

Switch-case statement:

{% case product.type %}
  {% when 'shoes' %}
    <icon>👟</icon>
  {% when 'boots' %}
    <icon>👢</icon>
  {% when 'sneakers' %}
    <icon>👟</icon>
  {% else %}
    <icon>📦</icon>
{% endcase %}

Iteration Tags

for loop

{% for product in collection.products %}
  {{ product.title }}
{% endfor %}

Modifiers:

{# Limit to first 5 #}
{% for product in collection.products limit: 5 %}
  {{ product.title }}
{% endfor %}

{# Skip first 10 #}
{% for product in collection.products offset: 10 %}
  {{ product.title }}
{% endfor %}

{# Reverse order #}
{% for product in collection.products reversed %}
  {{ product.title }}
{% endfor %}

{# Combine modifiers #}
{% for product in collection.products limit: 5 offset: 10 %}
  {# Items 11-15 #}
{% endfor %}

forloop object (available inside loops):

{% for item in array %}
  {{ forloop.index }}        {# 1-based: 1, 2, 3, ... #}
  {{ forloop.index0 }}       {# 0-based: 0, 1, 2, ... #}
  {{ forloop.rindex }}       {# Reverse 1-based: 3, 2, 1 #}
  {{ forloop.rindex0 }}      {# Reverse 0-based: 2, 1, 0 #}
  {{ forloop.first }}        {# true on first iteration #}
  {{ forloop.last }}         {# true on last iteration #}
  {{ forloop.length }}       {# Total number of items #}
{% endfor %}

Example usage:

{% for product in collection.products %}
  {% if forloop.first %}
    <h2>Featured Product</h2>
  {% endif %}

  <div class="product-{{ forloop.index }}">
    {{ product.title }}
  </div>

  {% if forloop.index == 3 %}
    <hr> {# Divider after 3rd item #}
  {% endif %}

  {% if forloop.last %}
    <p>Showing {{ forloop.length }} products</p>
  {% endif %}
{% endfor %}

break and continue

{% for product in collection.products %}
  {% if product.handle == 'target' %}
    {% break %}  {# Exit loop entirely #}
  {% endif %}

  {% if product.available == false %}
    {% continue %}  {# Skip to next iteration #}
  {% endif %}

  {{ product.title }}
{% endfor %}

tablerow

Creates HTML table rows:

{% tablerow product in collection.products cols: 3 %}
  {{ product.title }}
{% endtablerow %}

{# Output: #}
<table>
  <tr class="row1">
    <td class="col1">Product 1</td>
    <td class="col2">Product 2</td>
    <td class="col3">Product 3</td>
  </tr>
  <tr class="row2">
    <td class="col1">Product 4</td>
    ...
  </tr>
</table>

tablerow object:

{% tablerow product in products cols: 3 limit: 12 %}
  {{ tablerow.col }}         {# Current column (1-based) #}
  {{ tablerow.col0 }}        {# Current column (0-based) #}
  {{ tablerow.row }}         {# Current row (1-based) #}
  {{ tablerow.index }}       {# Item index (1-based) #}
  {{ tablerow.first }}       {# true on first item #}
  {{ tablerow.last }}        {# true on last item #}
  {{ tablerow.col_first }}   {# true on first column #}
  {{ tablerow.col_last }}    {# true on last column #}
{% endtablerow %}

paginate

For paginating large collections:

{% paginate collection.products by 12 %}

  {% for product in paginate.collection.products %}
    {% render 'product-card', product: product %}
  {% endfor %}

  {# Pagination controls #}
  {% if paginate.pages > 1 %}
    {{ paginate | default_pagination }}
  {% endif %}

{% endpaginate %}

paginate object:

{{ paginate.current_page }}      {# Current page number #}
{{ paginate.pages }}              {# Total pages #}
{{ paginate.items }}              {# Total items #}
{{ paginate.page_size }}          {# Items per page #}

{{ paginate.previous.url }}       {# Previous page URL (if exists) #}
{{ paginate.previous.title }}     {# Previous page title #}
{{ paginate.previous.is_link }}   {# Boolean #}

{{ paginate.next.url }}           {# Next page URL (if exists) #}
{{ paginate.next.title }}         {# Next page title #}
{{ paginate.next.is_link }}       {# Boolean #}

{{ paginate.parts }}              {# Array of page links #}

Custom pagination:

{% paginate collection.products by 20 %}

  <div class="pagination">
    {% if paginate.previous %}
      <a href="{{ paginate.previous.url }}">← Previous</a>
    {% endif %}

    {% for part in paginate.parts %}
      {% if part.is_link %}
        <a href="{{ part.url }}">{{ part.title }}</a>
      {% else %}
        <span class="current">{{ part.title }}</span>
      {% endif %}
    {% endfor %}

    {% if paginate.next %}
      <a href="{{ paginate.next.url }}">Next →</a>
    {% endif %}
  </div>

{% endpaginate %}

Variable Assignment

assign

Single-line variable assignment:

{% assign sale_price = product.price | times: 0.8 %}
{% assign is_available = product.available %}
{% assign product_count = collection.products.size %}
{% assign full_name = customer.first_name | append: ' ' | append: customer.last_name %}

capture

Multi-line content capture:

{% capture product_title %}
  {{ collection.title }} - {{ product.title }}
{% endcapture %}

{{ product_title }}  {# "Summer Sale - Blue T-Shirt" #}

{% capture greeting %}
  <h1>Welcome, {{ customer.name }}!</h1>
  <p>You have {{ customer.orders_count }} orders.</p>
{% endcapture %}

{{ greeting }}

liquid (multi-statement)

Cleaner syntax for multiple statements:

{% liquid
  assign product_type = product.type
  assign is_on_sale = product.on_sale
  assign sale_percentage = product.discount_percent

  if is_on_sale
    assign status = 'SALE'
  else
    assign status = 'REGULAR'
  endif

  echo status
%}

Template Inclusion

render

Isolated scope (preferred method):

{# Basic usage #}
{% render 'product-card', product: product %}

{# Multiple parameters #}
{% render 'product-card',
  product: product,
  show_price: true,
  show_vendor: false,
  css_class: 'featured'
%}

{# Render for each item #}
{% render 'product-card' for collection.products as item %}

{# Pass arrays #}
{% render 'gallery', images: product.images %}

Inside product-card.liquid:

{# Only has access to passed parameters #}
<div class="product {% if css_class %}{{ css_class }}{% endif %}">
  <h3>{{ product.title }}</h3>

  {% if show_price %}
    <p>{{ product.price | money }}</p>
  {% endif %}

  {% if show_vendor %}
    <p>{{ product.vendor }}</p>
  {% endif %}
</div>

include

Shared scope (legacy, avoid in new code):

{% include 'product-details' %}

{# Can access all parent template variables #}
{# Harder to debug and reason about #}

section

Load dynamic sections:

{% section 'featured-product' %}
{% section 'newsletter-signup' %}

Utility Tags

comment

Multi-line comments:

{% comment %}
  This entire block is ignored
  by the Liquid renderer.
  Use for documentation.
{% endcomment %}

{# Single-line comment #}

echo

Output shorthand (alternative to {{ }}):

{% echo product.title %}
{# Equivalent to: {{ product.title }} #}

raw

Output Liquid code without processing:

{% raw %}
  {{ This will be output as-is }}
  {% Liquid tags won't be processed %}
{% endraw %}

Useful for documentation or code examples.

Whitespace Control

Strip whitespace using hyphens:

{%- if condition -%}
  Content (whitespace stripped on both sides)
{%- endif -%}

{{ "hello" -}}world
{# Output: helloworld (no space) #}

{{- product.title }}
{# Strips whitespace before output #}

{{ product.title -}}
{# Strips whitespace after output #}

Example:

{# Without whitespace control: #}
{% for item in array %}
  {{ item }}
{% endfor %}

{# Output has newlines and indentation #}

{# With whitespace control: #}
{%- for item in array -%}
  {{ item }}
{%- endfor -%}

{# Output is compact #}

Operator Precedence

Order of evaluation (right-to-left):

{% if true or false and false %}
  {# Evaluates as: true or (false and false) = true #}
{% endif %}

IMPORTANT: No parentheses support in Liquid. Break complex conditions into variables:

{# ❌ DOESN'T WORK: #}
{% if (x > 5 and y < 10) or z == 0 %}

{# ✅ WORKS: #}
{% assign condition1 = false %}
{% if x > 5 and y < 10 %}
  {% assign condition1 = true %}
{% endif %}

{% if condition1 or z == 0 %}
  {# Logic here #}
{% endif %}

Performance Tips

1. Cache repeated calculations:

{# ❌ Inefficient: #}
{% for i in (1..10) %}
  {{ collection.products.size }}  {# Calculated 10 times #}
{% endfor %}

{# ✅ Efficient: #}
{% assign product_count = collection.products.size %}
{% for i in (1..10) %}
  {{ product_count }}
{% endfor %}

2. Use `limit` and `offset` instead of iterating full arrays:

{# ❌ Inefficient: #}
{% for product in collection.products %}
  {% if forloop.index <= 5 %}
    {{ product.title }}
  {% endif %}
{% endfor %}

{# ✅ Efficient: #}
{% for product in collection.products limit: 5 %}
  {{ product.title }}
{% endfor %}

3. Prefer `render` over `include` for better performance and variable scoping

4. Use `liquid` tag for cleaner multi-statement blocks

Common Gotchas

1. No parentheses in conditions - Use variables instead 2. Right-to-left evaluation - Be careful with operator precedence 3. String concatenation - Use append filter or capture tag 4. Array/object mutation - Not possible; create new variables 5. Integer division - {{ 5 | divided_by: 2 }} returns 2, not 2.5 6. Truthy/falsy values:

• false and nil are falsy
• Everything else (including 0, "", []) is truthy

LiquidDoc

Document snippet parameters with structured comments (available since 2024):

Basic usage

{% doc %}
  @param {String} title - The product title to display
  @param {Number} price - Price in cents
  @param {Boolean} [show_vendor] - Whether to show vendor (optional)
  @example
    {% render 'product-card', title: product.title, price: product.price %}
{% enddoc %}

<div class="product-card">
  <h3>{{ title }}</h3>
  <p>{{ price | money }}</p>
  {% if show_vendor %}
    <span>{{ vendor }}</span>
  {% endif %}
</div>

Supported types

• {String} - text values
• {Number} - numeric values
• {Boolean} - true/false
• {Object} - Shopify objects (product, collection, etc.)
• {Array} - arrays of values
• {Image} - image objects

Optional parameters

Wrap parameter name in square brackets:

{% doc %}
  @param {String} heading - Section heading
  @param {String} [subheading] - Optional subheading
  @param {Number} [limit=5] - Items to show (default: 5)
{% enddoc %}

Benefits

• Theme editor shows parameter hints when editing render tags
• IDE extensions can provide autocomplete
• Self-documenting code for team collaboration
• Theme Check validates parameter usage

Debugging Tips

1. Output variable types:

{{ product | json }}  {# Output entire object as JSON #}
{{ product.class }}   {# Output object type #}
{{ variable.size }}   {# Check array/string length #}

2. Check for nil/existence:

{% if product.metafield %}
  Metafield exists
{% else %}
  Metafield is nil
{% endif %}

3. Use default filter for safety:

{{ product.metafield.value | default: "Not set" }}

4. Enable theme preview console to see Liquid errors in real-time