Skip to main content
The <product-item> tag allows you to create dynamic product listings on your pages. It automatically loops through products that match your criteria and displays them using a template you define.

​
Overview

The product item tag is perfect for:
  • Product catalogs and listings
  • Featured products sections
  • Related products
  • Category pages
  • Upsell product displays
Each product matching your filter criteria will be rendered using your template, with product data automatically inserted.

​
Basic Usage

​
Simple Product Listing

<product-item data-type="any">
  <div class="product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>

​
With Filtering

<product-item data-type="physical" data-classification="main">
  <div class="product-card">
    <img src="{product.image_url}" alt="{product.name}">
    <h4>{product.name}</h4>
    <p class="price">{product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>

​
Attributes

​
Required Attributes

​
data-type

Filters products by type. Values:
  • "any" - All product types (default if not specified)
  • "physical" - Physical products only
  • "digital" - Digital products only
  • "service" - Service products only
  • Any other product type defined in your system
Example: 
<product-item data-type="physical">
  <!-- Only physical products will be displayed -->
</product-item>

​
Optional Attributes

​
data-classification

Filters products by classification. Values:
  • "any" - All classifications (default)
  • "main" - Main products only
  • "upsell" - Upsell products only
  • "downsell" - Downsell products only
  • "bump" - Bump products only
  • Any other classification defined in your system
Example: 
<product-item data-type="any" data-classification="upsell">
  <!-- Only upsell products will be displayed -->
</product-item>

​
data-codes

Filter by specific product codes (comma-separated). Format: Comma-separated list of product codes Example: 
<product-item data-codes="PROD001,PROD002,PROD003">
  <!-- Only products with these codes will be displayed -->
</product-item>

​
id

Optional element ID applied to each product wrapper. Example: 
<product-item data-type="physical" id="product-item">
  <!-- Each product will be wrapped in <div id="product-item"> -->
</product-item>

​
Product Placeholders

Within the <product-item> template, you can use these placeholders to display product information:

​
Standard Product Fields

Use {product.field_name} to access standard product attributes:
  • {product.name} - Product name
  • {product.code} - Product code
  • {product.price} - Product price
  • {product.description} - Product description
  • {product.image_url} - Product image URL
  • {product.type} - Product type
  • {product.classification} - Product classification
  • {product.currency} - Currency code
  • {product.status} - Product status
Example: 
<product-item data-type="physical">
  <div class="product">
    <img src="{product.image_url}" alt="{product.name}">
    <h3>{product.name}</h3>
    <p class="code">SKU: {product.code}</p>
    <p class="price">${product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>

​
Custom Product Attributes

Use {product.attributes.attribute_name} to access custom product attributes. Example: 
<product-item data-type="physical">
  <div class="product">
    <h3>{product.name}</h3>
    <p>Color: {product.attributes.color}</p>
    <p>Size: {product.attributes.size}</p>
    <p>Material: {product.attributes.material}</p>
  </div>
</product-item>
Note: Custom attributes must be defined in your product settings. If an attribute doesn’t exist, it will be empty.

​
Filtering Examples

​
Filter by Type Only

<!-- Show only digital products -->
<product-item data-type="digital">
  <div class="digital-product">
    <h3>{product.name}</h3>
    <p>Download: {product.attributes.download_link}</p>
  </div>
</product-item>

​
Filter by Classification

<!-- Show only main products -->
<product-item data-type="any" data-classification="main">
  <div class="main-product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>

​
Filter by Specific Codes

<!-- Show only specific products -->
<product-item data-codes="FEATURED001,FEATURED002,FEATURED003">
  <div class="featured-product">
    <span class="badge">Featured</span>
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>

​
Combined Filters

<!-- Physical upsell products -->
<product-item data-type="physical" data-classification="upsell">
  <div class="upsell-product">
    <h3>{product.name}</h3>
    <p>Add to order: {product.price}</p>
  </div>
</product-item>

​
Complete Example

Here’s a complete example of a product catalog page: 
<!DOCTYPE html>
<html>
<head>
  <title>Our Products</title>
  <style>
    .product-grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
      gap: 20px;
      padding: 20px;
    }
    .product-card {
      border: 1px solid #ddd;
      border-radius: 8px;
      padding: 15px;
      text-align: center;
    }
    .product-card img {
      width: 100%;
      height: 200px;
      object-fit: cover;
      border-radius: 4px;
    }
    .product-card h3 {
      margin: 10px 0;
    }
    .product-card .price {
      font-size: 1.5em;
      font-weight: bold;
      color: #1d4ed8;
    }
  </style>
</head>
<body>
  <h1>Our Products</h1>
  
  <div class="product-grid">
    <product-item data-type="physical" data-classification="main">
      <div class="product-card">
        <img src="{product.image_url}" alt="{product.name}">
        <h3>{product.name}</h3>
        <p class="price">${product.price}</p>
        <p>{product.description}</p>
        <button>Add to Cart</button>
      </div>
    </product-item>
  </div>
</body>
</html>

​
How It Works

  1. Tag Detection: The system finds all <product-item> tags in your page
  2. Filter Application: Products are filtered based on data-type, data-classification, and data-codes attributes
  3. Template Rendering: For each matching product, the template is rendered
  4. Placeholder Replacement: Product placeholders ({product.*}) are replaced with actual product data
  5. Output: Each product is wrapped in a <div> with the specified id (if provided)

​
Best Practices

​
Performance

  • Limit Results: Use specific data-codes when you only need a few products
  • Filter Early: Use data-type and data-classification to reduce the product pool
  • Optimize Images: Ensure product images are optimized for web

​
User Experience

  • Consistent Layout: Keep product card layouts consistent
  • Clear Pricing: Always display price clearly
  • Product Images: Include product images for better visual appeal
  • Call-to-Action: Include clear CTAs (buy buttons, learn more, etc.)

​
Template Design

  • Responsive: Design templates that work on mobile and desktop
  • Accessible: Use semantic HTML and proper alt text for images
  • Flexible: Design templates that work with varying product data

​
Troubleshooting

​
No Products Displaying

Possible Causes:
  • No products match your filter criteria
  • data-type is too restrictive
  • Product codes in data-codes don’t exist
  • Products are inactive or unpublished
Solutions:
  • Check your filter attributes
  • Verify products exist in your system
  • Try data-type="any" to see all products
  • Check product status in your dashboard

​
Placeholders Not Replacing

Issue: Placeholders show as literal text (e.g., {product.name}) Solutions:
  • Check placeholder spelling (case-sensitive)
  • Ensure you’re using {product.*} format, not %product.*%
  • Verify the product field exists

​
Custom Attributes Empty

Issue: {product.attributes.*} is empty Solutions:
  • Verify the custom attribute is defined in product settings
  • Check attribute name spelling (case-sensitive)
  • Ensure the attribute has a value for that product