# Authentication
Source: https://quickbutik.dev/api-v1/authentication

Secure your API requests with Basic Authentication

The Quickbutik API uses **Basic Authentication** with API keys to authenticate requests. All API calls must be made over HTTPS, and requests made over HTTP will be rejected.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.quickbutik.com/v1/orders \
    -u your_api_key:your_api_key
  ```

  ```javascript Node.js theme={null}
  const apiKey = 'your_api_key';
  const credentials = Buffer.from(`${apiKey}:${apiKey}`).toString('base64');

  fetch('https://api.quickbutik.com/v1/orders', {
    headers: {
      'Authorization': `Basic ${credentials}`
    }
  });
  ```

  ```python Python theme={null}
  import requests
  import base64

  api_key = 'your_api_key'
  credentials = base64.b64encode(f'{api_key}:{api_key}'.encode()).decode()

  response = requests.get(
      'https://api.quickbutik.com/v1/orders',
      headers={'Authorization': f'Basic {credentials}'}
  )
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = 'your_api_key';
  $credentials = base64_encode($apiKey . ':' . $apiKey);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.quickbutik.com/v1/orders');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Basic ' . $credentials
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  ?>
  ```
</CodeGroup>

## How it works

Basic Authentication requires you to include an `Authorization` header with every request. The header value consists of the word "Basic" followed by a space and a base64-encoded string of your credentials.

### Format

```
Authorization: Basic BASE64_ENCODED_CREDENTIALS
```

### Credential encoding

Your credentials should be formatted as `api_key:api_key` and then base64-encoded.

<Steps>
  <Step title="Format your credentials">
    Take your API key and format it as: `your_api_key:your_api_key`
  </Step>

  <Step title="Encode with base64">
    Encode the formatted string using base64 encoding
  </Step>

  <Step title="Add to Authorization header">
    Include the encoded string in your request headers as: `Authorization: Basic ENCODED_STRING`
  </Step>
</Steps>

## Example

Let's say your API key is `sk_live_abc123`. Here's how you'd construct the Authorization header:

<CodeGroup>
  ```text Step 1: Format theme={null}
  sk_live_abc123:sk_live_abc123
  ```

  ```text Step 2: Base64 encode theme={null}
  c2tfbGl2ZV9hYmMxMjM6c2tfbGl2ZV9hYmMxMjM=
  ```

  ```text Step 3: Authorization header theme={null}
  Authorization: Basic c2tfbGl2ZV9hYmMxMjM6c2tfbGl2ZV9hYmMxMjM=
  ```
</CodeGroup>

## Getting your API key

<Card title="Quickbutik Control Panel" icon="key">
  API keys can be generated and managed in the Quickbutik Control Panel by the store owner.

  Navigate to **Settings → API** to create and manage your API keys.
</Card>

## Security best practices

<Warning>
  **Keep your API keys secure**

  * Never expose API keys in client-side code
  * Use environment variables to store API keys
  * Rotate API keys regularly
  * Only grant necessary permissions
</Warning>

<Callout type="info">
  **HTTPS Required**

  All API requests must be made over HTTPS. Requests made over plain HTTP will be automatically rejected for security reasons.
</Callout>

## Migration from legacy authentication

<Callout type="warning">
  **Deprecation Notice**

  If you're currently using the legacy `apiKey` query parameter for authentication, please migrate to Basic Authentication as described above. The legacy method will be discontinued soon.
</Callout>

### Before (Legacy - Deprecated)

```bash theme={null}
curl "https://api.quickbutik.com/v1/orders?apiKey=your_api_key"
```

### After (Current)

```bash theme={null}
curl https://api.quickbutik.com/v1/orders \
  -u your_api_key:your_api_key
```

## Error responses

When authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "code": 401,
  "error": "Unauthorized - Invalid or missing authentication"
}
```

Common authentication errors:

* Missing `Authorization` header
* Invalid API key
* Malformed base64 encoding
* Using HTTP instead of HTTPS

## Testing your authentication

You can quickly test your authentication setup with a simple API call:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.quickbutik.com/v1/products/count \
    -u your_api_key:your_api_key
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.quickbutik.com/v1/products/count', {
    headers: {
      'Authorization': `Basic ${btoa('your_api_key:your_api_key')}`
    }
  });

  if (response.ok) {
    console.log('Authentication successful!');
    const data = await response.json();
    console.log(data);
  } else {
    console.log('Authentication failed');
  }
  ```
</CodeGroup>

A successful response will return your product count, confirming your authentication is working correctly.


# Create category
Source: https://quickbutik.dev/api-v1/categories/create-category

post /v1/categories
Create a new product category



# Get categories
Source: https://quickbutik.dev/api-v1/categories/get-categories

get /v1/categories
Fetch store categories



# Inventory Management
Source: https://quickbutik.dev/api-v1/guides/inventory-management

Keep your product stock levels synchronized across platforms

Learn how to build a robust inventory synchronization system that keeps stock levels accurate across Quickbutik and your external systems in real-time.

<Info>
  **Use cases covered:**

  * Real-time stock level synchronization
  * Bulk inventory updates
  * Low stock alerts and management
  * Multi-location inventory tracking
  * Prevention of overselling
</Info>

## Quick Example

Here's a complete example of syncing inventory when stock changes:

<CodeGroup>
  ```javascript Node.js theme={null}
  const QuickbutikAPI = require('./quickbutik-api');

  class InventoryManager {
    constructor(apiKey) {
      this.api = new QuickbutikAPI(apiKey);
    }

    async updateProductStock(sku, newQuantity, location = 'main') {
      try {
        const result = await this.api.updateProducts({
          sku: sku,
          stock: newQuantity,
          qty_location: location
        });

        console.log(`Updated ${sku} stock to ${newQuantity} at ${location}`);
        return result;
      } catch (error) {
        console.error(`Failed to update stock for ${sku}:`, error);
        throw error;
      }
    }

    async bulkUpdateInventory(inventoryUpdates) {
      const results = [];
      const batchSize = 10;

      for (let i = 0; i < inventoryUpdates.length; i += batchSize) {
        const batch = inventoryUpdates.slice(i, i + batchSize);
        
        const batchPromises = batch.map(update => 
          this.updateProductStock(update.sku, update.quantity, update.location)
            .catch(error => ({ error: error.message, sku: update.sku }))
        );

        const batchResults = await Promise.all(batchPromises);
        results.push(...batchResults);

        // Small delay to avoid rate limiting
        if (i + batchSize < inventoryUpdates.length) {
          await new Promise(resolve => setTimeout(resolve, 100));
        }
      }

      return results;
    }
  }

  // Usage
  const inventory = new InventoryManager(process.env.QUICKBUTIK_API_KEY);

  // Update single product
  await inventory.updateProductStock('SHIRT-123', 45);

  // Bulk update
  await inventory.bulkUpdateInventory([
    { sku: 'SHIRT-123', quantity: 45, location: 'warehouse-1' },
    { sku: 'PANTS-456', quantity: 12, location: 'warehouse-1' },
    { sku: 'HAT-789', quantity: 0, location: 'warehouse-2' }
  ]);
  ```

  ```python Python theme={null}
  import asyncio
  import time
  from typing import List, Dict
  from quickbutik_api import QuickbutikAPI

  class InventoryManager:
      def __init__(self, api_key: str):
          self.api = QuickbutikAPI(api_key)
      
      async def update_product_stock(self, sku: str, new_quantity: int, location: str = 'main'):
          try:
              result = await self.api.update_products({
                  'sku': sku,
                  'stock': new_quantity,
                  'qty_location': location
              })
              
              print(f'Updated {sku} stock to {new_quantity} at {location}')
              return result
          except Exception as error:
              print(f'Failed to update stock for {sku}: {error}')
              raise error
      
      async def bulk_update_inventory(self, inventory_updates: List[Dict]):
          results = []
          batch_size = 10
          
          for i in range(0, len(inventory_updates), batch_size):
              batch = inventory_updates[i:i + batch_size]
              
              batch_tasks = []
              for update in batch:
                  task = self.update_product_stock(
                      update['sku'], 
                      update['quantity'], 
                      update.get('location', 'main')
                  )
                  batch_tasks.append(task)
              
              try:
                  batch_results = await asyncio.gather(*batch_tasks, return_exceptions=True)
                  results.extend(batch_results)
              except Exception as error:
                  print(f'Batch update error: {error}')
              
              # Small delay to avoid rate limiting
              if i + batch_size < len(inventory_updates):
                  await asyncio.sleep(0.1)
          
          return results

  # Usage
  async def main():
      inventory = InventoryManager(os.getenv('QUICKBUTIK_API_KEY'))
      
      # Update single product
      await inventory.update_product_stock('SHIRT-123', 45)
      
      # Bulk update
      await inventory.bulk_update_inventory([
          {'sku': 'SHIRT-123', 'quantity': 45, 'location': 'warehouse-1'},
          {'sku': 'PANTS-456', 'quantity': 12, 'location': 'warehouse-1'},
          {'sku': 'HAT-789', 'quantity': 0, 'location': 'warehouse-2'}
      ])

  asyncio.run(main())
  ```
</CodeGroup>

## Webhook-Based Inventory Sync

Set up real-time inventory synchronization using webhooks:

<CodeGroup>
  ```javascript Express.js Webhook Handler theme={null}
  app.post('/webhooks/quickbutik', async (req, res) => {
    const { event_type, product_id } = req.query;
    
    // Acknowledge webhook immediately
    res.status(200).send('OK');
    
    if (event_type === 'product.update') {
      await handleProductUpdate(product_id);
    }
  });

  async function handleProductUpdate(productId) {
    try {
      // Fetch updated product details
      const products = await api.getProducts({ 
        product_id: productId,
        include_details: true 
      });
      
      if (!products || products.length === 0) {
        throw new Error(`Product ${productId} not found`);
      }
      
      const product = products[0];
      
      // Check if stock changed
      if (await hasStockChanged(product)) {
        await syncInventoryToExternalSystem(product);
      }
      
    } catch (error) {
      console.error(`Failed to handle product update for ${productId}:`, error);
    }
  }

  async function hasStockChanged(product) {
    // Compare with your local inventory database
    const localInventory = await getLocalInventory(product.sku);
    return localInventory.quantity !== parseInt(product.qty || 0);
  }

  async function syncInventoryToExternalSystem(product) {
    try {
      const inventoryUpdate = {
        sku: product.sku,
        quantity: parseInt(product.qty || 0),
        location: product.qty_location || 'default',
        updated_at: new Date().toISOString()
      };
      
      const response = await fetch('https://your-system.com/api/inventory', {
        method: 'PUT',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.EXTERNAL_API_TOKEN}`
        },
        body: JSON.stringify(inventoryUpdate)
      });
      
      if (!response.ok) {
        throw new Error(`External API error: ${response.status}`);
      }
      
      console.log(`Synced inventory for ${product.sku}: ${product.qty} units`);
      
    } catch (error) {
      console.error(`Failed to sync inventory for ${product.sku}:`, error);
      
      // Add to retry queue
      await addToRetryQueue({
        type: 'inventory_sync',
        product,
        timestamp: new Date()
      });
    }
  }
  ```

  ```python Flask Webhook Handler theme={null}
  @app.route('/webhooks/quickbutik', methods=['POST'])
  def quickbutik_webhook():
      event_type = request.args.get('event_type')
      product_id = request.args.get('product_id')
      
      # Acknowledge webhook immediately
      response = jsonify({'status': 'received'})
      
      if event_type == 'product.update':
          asyncio.create_task(handle_product_update(product_id))
      
      return response, 200

  async def handle_product_update(product_id):
      try:
          # Fetch updated product details
          products = await api.get_products(
              product_id=product_id,
              include_details=True
          )
          
          if not products:
              raise Exception(f'Product {product_id} not found')
          
          product = products[0]
          
          # Check if stock changed
          if await has_stock_changed(product):
              await sync_inventory_to_external_system(product)
      
      except Exception as error:
          app.logger.error(f'Failed to handle product update for {product_id}: {error}')

  async def has_stock_changed(product):
      # Compare with your local inventory database
      local_inventory = await get_local_inventory(product['sku'])
      return local_inventory['quantity'] != int(product.get('qty', 0))

  async def sync_inventory_to_external_system(product):
      try:
          inventory_update = {
              'sku': product['sku'],
              'quantity': int(product.get('qty', 0)),
              'location': product.get('qty_location', 'default'),
              'updated_at': datetime.now().isoformat()
          }
          
          async with aiohttp.ClientSession() as session:
              async with session.put(
                  'https://your-system.com/api/inventory',
                  headers={
                      'Content-Type': 'application/json',
                      'Authorization': f'Bearer {os.getenv("EXTERNAL_API_TOKEN")}'
                  },
                  json=inventory_update
              ) as response:
                  if not response.ok:
                      raise Exception(f'External API error: {response.status}')
          
          app.logger.info(f'Synced inventory for {product["sku"]}: {product.get("qty", 0)} units')
          
      except Exception as error:
          app.logger.error(f'Failed to sync inventory for {product["sku"]}: {error}')
          
          # Add to retry queue
          await add_to_retry_queue({
              'type': 'inventory_sync',
              'product': product,
              'timestamp': datetime.now()
          })
  ```
</CodeGroup>

## Low Stock Monitoring

Implement automated low stock alerts and reordering:

<CodeGroup>
  ```javascript Low Stock Monitor theme={null}
  class LowStockMonitor {
    constructor(apiKey, thresholds = {}) {
      this.api = new QuickbutikAPI(apiKey);
      this.defaultThreshold = thresholds.default || 10;
      this.customThresholds = thresholds.custom || {};
    }

    async checkLowStock() {
      try {
        const products = await this.api.getProducts({ 
          include_details: true,
          limit: 500
        });

        const lowStockProducts = [];

        for (const product of products) {
          if (product.variants && product.variants.length > 0) {
            // Check variants
            for (const variant of product.variants) {
              if (this.isLowStock(variant)) {
                lowStockProducts.push({
                  ...variant,
                  parent_sku: product.sku,
                  parent_title: product.title
                });
              }
            }
          } else {
            // Check main product
            if (this.isLowStock(product)) {
              lowStockProducts.push(product);
            }
          }
        }

        if (lowStockProducts.length > 0) {
          await this.handleLowStockAlert(lowStockProducts);
        }

        return lowStockProducts;

      } catch (error) {
        console.error('Failed to check low stock:', error);
        throw error;
      }
    }

    isLowStock(product) {
      const currentStock = parseInt(product.qty || 0);
      const threshold = this.customThresholds[product.sku] || this.defaultThreshold;
      
      return currentStock > 0 && currentStock <= threshold;
    }

    async handleLowStockAlert(lowStockProducts) {
      // Send alert notification
      await this.sendLowStockNotification(lowStockProducts);
      
      // Auto-reorder if configured
      const autoReorderProducts = lowStockProducts.filter(p => 
        this.shouldAutoReorder(p)
      );
      
      if (autoReorderProducts.length > 0) {
        await this.createReorderRequests(autoReorderProducts);
      }
    }

    async sendLowStockNotification(products) {
      const message = `🚨 Low Stock Alert!\n\n${products.map(p => 
        `${p.title || p.parent_title} (${p.sku}): ${p.qty} units remaining`
      ).join('\n')}`;

      // Send to Slack
      if (process.env.SLACK_WEBHOOK_URL) {
        await fetch(process.env.SLACK_WEBHOOK_URL, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ text: message })
        });
      }

      // Send email
      if (process.env.EMAIL_WEBHOOK_URL) {
        await fetch(process.env.EMAIL_WEBHOOK_URL, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            to: process.env.INVENTORY_EMAIL,
            subject: 'Low Stock Alert',
            body: message
          })
        });
      }
    }

    shouldAutoReorder(product) {
      // Add your auto-reorder logic here
      return product.supplier_sku && product.auto_reorder_enabled;
    }

    async createReorderRequests(products) {
      for (const product of products) {
        try {
          const reorderQuantity = this.calculateReorderQuantity(product);
          
          await this.createPurchaseOrder({
            sku: product.sku,
            supplier_sku: product.supplier_sku,
            quantity: reorderQuantity,
            supplier: product.supplier_name
          });

          console.log(`Created reorder for ${product.sku}: ${reorderQuantity} units`);
        } catch (error) {
          console.error(`Failed to create reorder for ${product.sku}:`, error);
        }
      }
    }

    calculateReorderQuantity(product) {
      // Simple reorder logic - you can make this more sophisticated
      const currentStock = parseInt(product.qty || 0);
      const threshold = this.customThresholds[product.sku] || this.defaultThreshold;
      const targetStock = threshold * 3; // Reorder to 3x threshold
      
      return Math.max(targetStock - currentStock, threshold);
    }
  }

  // Usage
  const monitor = new LowStockMonitor(process.env.QUICKBUTIK_API_KEY, {
    default: 10,
    custom: {
      'POPULAR-ITEM-123': 50,
      'SEASONAL-456': 5
    }
  });

  // Run every hour
  setInterval(async () => {
    try {
      const lowStockProducts = await monitor.checkLowStock();
      console.log(`Found ${lowStockProducts.length} low stock products`);
    } catch (error) {
      console.error('Low stock check failed:', error);
    }
  }, 60 * 60 * 1000);
  ```
</CodeGroup>

## Multi-Location Inventory

Handle inventory across multiple locations:

<CodeGroup>
  ```javascript Multi-Location Manager theme={null}
  class MultiLocationInventory {
    constructor(apiKey) {
      this.api = new QuickbutikAPI(apiKey);
      this.locations = {
        'warehouse-1': { name: 'Main Warehouse', priority: 1 },
        'warehouse-2': { name: 'Secondary Warehouse', priority: 2 },
        'store-front': { name: 'Physical Store', priority: 3 }
      };
    }

    async getInventoryByLocation(sku) {
      try {
        const products = await this.api.getProducts({ 
          product_id: sku,
          include_details: true 
        });

        if (!products || products.length === 0) {
          return null;
        }

        const product = products[0];
        const inventory = {};

        // If product has variants, aggregate by location
        if (product.variants && product.variants.length > 0) {
          for (const variant of product.variants) {
            const location = variant.qty_location || 'default';
            const quantity = parseInt(variant.qty || 0);
            
            inventory[location] = (inventory[location] || 0) + quantity;
          }
        } else {
          const location = product.qty_location || 'default';
          inventory[location] = parseInt(product.qty || 0);
        }

        return {
          sku: product.sku,
          title: product.title,
          total_quantity: Object.values(inventory).reduce((sum, qty) => sum + qty, 0),
          locations: inventory
        };

      } catch (error) {
        console.error(`Failed to get inventory for ${sku}:`, error);
        throw error;
      }
    }

    async transferStock(sku, fromLocation, toLocation, quantity) {
      try {
        // Get current inventory
        const inventory = await this.getInventoryByLocation(sku);
        
        if (!inventory || !inventory.locations[fromLocation]) {
          throw new Error(`No inventory found for ${sku} at ${fromLocation}`);
        }

        if (inventory.locations[fromLocation] < quantity) {
          throw new Error(`Insufficient stock at ${fromLocation}. Available: ${inventory.locations[fromLocation]}, Requested: ${quantity}`);
        }

        // Update source location (decrease)
        await this.updateLocationStock(sku, fromLocation, inventory.locations[fromLocation] - quantity);

        // Update destination location (increase)
        const currentDestStock = inventory.locations[toLocation] || 0;
        await this.updateLocationStock(sku, toLocation, currentDestStock + quantity);

        console.log(`Transferred ${quantity} units of ${sku} from ${fromLocation} to ${toLocation}`);

        return {
          sku,
          quantity,
          from: fromLocation,
          to: toLocation,
          timestamp: new Date().toISOString()
        };

      } catch (error) {
        console.error(`Failed to transfer stock for ${sku}:`, error);
        throw error;
      }
    }

    async updateLocationStock(sku, location, newQuantity) {
      return this.api.updateProducts({
        sku,
        stock: newQuantity,
        qty_location: location
      });
    }

    async getOptimalFulfillmentLocation(sku, requestedQuantity) {
      const inventory = await this.getInventoryByLocation(sku);
      
      if (!inventory) {
        return null;
      }

      // Sort locations by priority and availability
      const availableLocations = Object.entries(inventory.locations)
        .filter(([location, quantity]) => quantity >= requestedQuantity)
        .map(([location, quantity]) => ({
          location,
          quantity,
          priority: this.locations[location]?.priority || 999
        }))
        .sort((a, b) => a.priority - b.priority);

      return availableLocations.length > 0 ? availableLocations[0] : null;
    }
  }

  // Usage
  const multiLocation = new MultiLocationInventory(process.env.QUICKBUTIK_API_KEY);

  // Get inventory across all locations
  const inventory = await multiLocation.getInventoryByLocation('SHIRT-123');
  console.log('Inventory:', inventory);

  // Transfer stock between locations
  await multiLocation.transferStock('SHIRT-123', 'warehouse-1', 'store-front', 5);

  // Find optimal fulfillment location
  const optimal = await multiLocation.getOptimalFulfillmentLocation('SHIRT-123', 10);
  console.log('Optimal location:', optimal);
  ```
</CodeGroup>

## Preventing Overselling

Implement safeguards to prevent overselling:

<CodeGroup>
  ```javascript Overselling Prevention theme={null}
  class OversellProtection {
    constructor(apiKey) {
      this.api = new QuickbutikAPI(apiKey);
      this.safetyBuffer = 1; // Keep 1 unit as safety buffer
      this.checkInterval = 5 * 60 * 1000; // Check every 5 minutes
    }

    async enableOversellProtection() {
      // Start monitoring
      setInterval(() => {
        this.checkAndProtectInventory();
      }, this.checkInterval);

      console.log('Oversell protection enabled');
    }

    async checkAndProtectInventory() {
      try {
        const products = await this.api.getProducts({ 
          include_details: true,
          limit: 500
        });

        const protectionActions = [];

        for (const product of products) {
          // Skip if minus quantity is already disabled
          if (product.disable_minusqty === '1') {
            continue;
          }

          const currentStock = parseInt(product.qty || 0);
          
          if (currentStock <= this.safetyBuffer) {
            protectionActions.push({
              sku: product.sku,
              title: product.title,
              currentStock,
              action: 'disable_minus_qty'
            });

            await this.protectProduct(product.sku);
          }
        }

        if (protectionActions.length > 0) {
          await this.notifyProtectionActions(protectionActions);
        }

      } catch (error) {
        console.error('Failed to check oversell protection:', error);
      }
    }

    async protectProduct(sku) {
      try {
        await this.api.updateProducts({
          sku,
          disable_minusqty: '1'
        });

        console.log(`Enabled oversell protection for ${sku}`);
      } catch (error) {
        console.error(`Failed to protect product ${sku}:`, error);
      }
    }

    async unprotectProduct(sku) {
      try {
        await this.api.updateProducts({
          sku,
          disable_minusqty: '0'
        });

        console.log(`Disabled oversell protection for ${sku}`);
      } catch (error) {
        console.error(`Failed to unprotect product ${sku}:`, error);
      }
    }

    async notifyProtectionActions(actions) {
      const message = `🛡️ Oversell Protection Activated!\n\n${actions.map(action => 
        `${action.title} (${action.sku}): ${action.currentStock} units remaining - Protection enabled`
      ).join('\n')}`;

      // Send notification
      if (process.env.SLACK_WEBHOOK_URL) {
        await fetch(process.env.SLACK_WEBHOOK_URL, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ text: message })
        });
      }
    }

    async manualStockCheck(sku) {
      try {
        const products = await this.api.getProducts({ 
          product_id: sku,
          include_details: true 
        });

        if (!products || products.length === 0) {
          throw new Error(`Product ${sku} not found`);
        }

        const product = products[0];
        const currentStock = parseInt(product.qty || 0);
        const isProtected = product.disable_minusqty === '1';

        return {
          sku: product.sku,
          title: product.title,
          currentStock,
          isProtected,
          recommendedAction: this.getRecommendedAction(currentStock, isProtected)
        };

      } catch (error) {
        console.error(`Failed manual stock check for ${sku}:`, error);
        throw error;
      }
    }

    getRecommendedAction(currentStock, isProtected) {
      if (currentStock <= this.safetyBuffer && !isProtected) {
        return 'ENABLE_PROTECTION';
      } else if (currentStock > this.safetyBuffer && isProtected) {
        return 'DISABLE_PROTECTION';
      } else {
        return 'NO_ACTION_NEEDED';
      }
    }
  }

  // Usage
  const protection = new OversellProtection(process.env.QUICKBUTIK_API_KEY);

  // Enable automatic protection
  await protection.enableOversellProtection();

  // Manual check for specific product
  const status = await protection.manualStockCheck('SHIRT-123');
  console.log('Stock status:', status);

  if (status.recommendedAction === 'ENABLE_PROTECTION') {
    await protection.protectProduct(status.sku);
  } else if (status.recommendedAction === 'DISABLE_PROTECTION') {
    await protection.unprotectProduct(status.sku);
  }
  ```
</CodeGroup>

## 🎯 Best Practices

<CardGroup>
  <Card title="Batch Processing" icon="layer-group">
    **Process inventory updates in batches** to avoid rate limiting and improve performance.
  </Card>

  <Card title="Error Recovery" icon="arrows-rotate">
    **Implement retry logic** for failed inventory updates with exponential backoff.
  </Card>

  <Card title="Data Validation" icon="shield-check">
    **Validate inventory data** before updates to prevent incorrect stock levels.
  </Card>

  <Card title="Monitoring" icon="chart-line">
    **Monitor inventory sync health** with metrics and alerts for critical failures.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Product Catalog Sync" icon="box" href="/api-v1/guides/product-catalog-sync">
    Learn how to sync complete product catalogs between systems
  </Card>
</CardGroup>


# Order Synchronization Tutorial
Source: https://quickbutik.dev/api-v1/guides/order-sync-tutorial

Build a complete order sync system with webhooks and automatic retry logic

This tutorial shows you how to build a robust order synchronization system that automatically syncs orders from Quickbutik to your external system using webhooks and the API.

<Info>
  **What you'll learn:**

  * Set up webhook endpoints to receive order notifications
  * Implement automatic retry logic for failed API calls
  * Handle order status updates bidirectionally
  * Build a production-ready integration with proper error handling
</Info>

## Architecture Overview

```mermaid theme={null}
graph LR
    A[Quickbutik Store] -->|Webhook| B[Your Webhook Endpoint]
    B --> C[Order Processing Service]
    C --> D[External System]
    C -->|Status Updates| E[Quickbutik API]
    C --> F[Database/Queue]
```

## Part 1: Setting Up Webhook Endpoint

First, let's create a webhook endpoint to receive order notifications:

<CodeGroup>
  ```javascript Express.js theme={null}
  const express = require('express');
  const crypto = require('crypto');
  const app = express();

  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  // Webhook endpoint for order notifications
  app.post('/webhooks/quickbutik', async (req, res) => {
    try {
      const { event_type, order_id } = req.query;
      
      console.log(`Received webhook: ${event_type} for order ${order_id}`);
      
      // Acknowledge webhook immediately
      res.status(200).send('OK');
      
      // Process webhook asynchronously
      await processOrderWebhook(event_type, order_id);
      
    } catch (error) {
      console.error('Webhook processing error:', error);
      res.status(500).send('Error processing webhook');
    }
  });

  async function processOrderWebhook(eventType, orderId) {
    switch (eventType) {
      case 'order.new':
        await handleNewOrder(orderId);
        break;
      case 'order.done':
        await handleOrderShipped(orderId);
        break;
      case 'order.cancelled':
        await handleOrderCancelled(orderId);
        break;
      default:
        console.log(`Unhandled event type: ${eventType}`);
    }
  }

  app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
  });
  ```

  ```python Flask theme={null}
  from flask import Flask, request, jsonify
  import asyncio
  import logging

  app = Flask(__name__)
  logging.basicConfig(level=logging.INFO)

  @app.route('/webhooks/quickbutik', methods=['POST'])
  def quickbutik_webhook():
      try:
          event_type = request.args.get('event_type')
          order_id = request.args.get('order_id')
          
          app.logger.info(f'Received webhook: {event_type} for order {order_id}')
          
          # Acknowledge webhook immediately
          response = jsonify({'status': 'received'})
          
          # Process webhook asynchronously (in production, use a task queue)
          asyncio.create_task(process_order_webhook(event_type, order_id))
          
          return response, 200
          
      except Exception as error:
          app.logger.error(f'Webhook processing error: {error}')
          return jsonify({'error': 'Error processing webhook'}), 500

  async def process_order_webhook(event_type, order_id):
      try:
          if event_type == 'order.new':
              await handle_new_order(order_id)
          elif event_type == 'order.done':
              await handle_order_shipped(order_id)
          elif event_type == 'order.cancelled':
              await handle_order_cancelled(order_id)
          else:
              app.logger.info(f'Unhandled event type: {event_type}')
      except Exception as error:
          app.logger.error(f'Error processing webhook: {error}')

  if __name__ == '__main__':
      app.run(debug=True, port=3000)
  ```
</CodeGroup>

<Warning>
  **Important:** Always acknowledge webhooks quickly (within 10 seconds) to avoid retries. Process the actual work asynchronously.
</Warning>

## Part 2: Fetching Order Details

When you receive a webhook, fetch the complete order details:

<CodeGroup>
  ```javascript Node.js theme={null}
  const QuickbutikAPI = require('./quickbutik-api'); // From our previous tutorial

  class OrderSyncService {
    constructor(apiKey) {
      this.api = new QuickbutikAPI(apiKey);
      this.retryAttempts = 3;
      this.retryDelay = 1000; // 1 second
    }

    async handleNewOrder(orderId) {
      try {
        // Fetch complete order details
        const orders = await this.retryAPICall(() => 
          this.api.getOrders({ 
            order_id: orderId, 
            include_details: true,
            apps_load: true 
          })
        );

        if (!orders || orders.length === 0) {
          throw new Error(`Order ${orderId} not found`);
        }

        const order = orders[0];
        
        // Validate order data
        if (!this.validateOrder(order)) {
          throw new Error(`Invalid order data for order ${orderId}`);
        }

        // Sync to external system
        await this.syncOrderToExternalSystem(order);
        
        // Log success
        console.log(`Successfully synced order ${orderId} to external system`);

      } catch (error) {
        console.error(`Failed to process new order ${orderId}:`, error);
        
        // Add to retry queue or send alert
        await this.handleOrderSyncFailure(orderId, error);
      }
    }

    async retryAPICall(apiCall, attempt = 1) {
      try {
        return await apiCall();
      } catch (error) {
        if (attempt < this.retryAttempts) {
          console.log(`API call failed, retrying in ${this.retryDelay}ms (attempt ${attempt}/${this.retryAttempts})`);
          
          await new Promise(resolve => setTimeout(resolve, this.retryDelay * attempt));
          return this.retryAPICall(apiCall, attempt + 1);
        }
        throw error;
      }
    }

    validateOrder(order) {
      return order.order_id && 
             order.total_amount && 
             order.customer && 
             order.customer.email;
    }

    async syncOrderToExternalSystem(order) {
      // Transform Quickbutik order to your system's format
      const externalOrder = this.transformOrder(order);
      
      // Make API call to your external system
      const response = await fetch('https://your-system.com/api/orders', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.EXTERNAL_API_TOKEN}`
        },
        body: JSON.stringify(externalOrder)
      });

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

      return response.json();
    }

    transformOrder(quickbutikOrder) {
      return {
        external_order_id: quickbutikOrder.order_id,
        customer_email: quickbutikOrder.customer.email,
        total_amount: parseFloat(quickbutikOrder.total_amount),
        currency: quickbutikOrder.payment?.currency || 'SEK',
        items: quickbutikOrder.products?.map(product => ({
          sku: product.sku,
          quantity: product.qty || 1,
          price: parseFloat(product.price || 0)
        })) || [],
        shipping_address: quickbutikOrder.customer.shipping_details,
        billing_address: quickbutikOrder.customer.billing_details,
        created_at: quickbutikOrder.date_created
      };
    }

    async handleOrderSyncFailure(orderId, error) {
      // In production, you might:
      // 1. Add to a retry queue (Redis, SQS, etc.)
      // 2. Send alerts to monitoring system
      // 3. Log to error tracking service
      
      console.error(`Order sync failed for ${orderId}:`, error.message);
      
      // Example: Add to retry queue
      // await this.addToRetryQueue({ orderId, error: error.message, timestamp: new Date() });
    }
  }

  // Usage
  const orderSync = new OrderSyncService(process.env.QUICKBUTIK_API_KEY);

  async function handleNewOrder(orderId) {
    await orderSync.handleNewOrder(orderId);
  }
  ```

  ```python Python theme={null}
  import asyncio
  import aiohttp
  import json
  from typing import Dict, List, Optional
  from quickbutik_api import QuickbutikAPI  # From previous tutorial

  class OrderSyncService:
      def __init__(self, api_key: str):
          self.api = QuickbutikAPI(api_key)
          self.retry_attempts = 3
          self.retry_delay = 1  # seconds
      
      async def handle_new_order(self, order_id: str):
          try:
              # Fetch complete order details
              orders = await self.retry_api_call(
                  lambda: self.api.get_orders(
                      order_id=order_id,
                      include_details=True,
                      apps_load=True
                  )
              )
              
              if not orders:
                  raise Exception(f'Order {order_id} not found')
              
              order = orders[0]
              
              # Validate order data
              if not self.validate_order(order):
                  raise Exception(f'Invalid order data for order {order_id}')
              
              # Sync to external system
              await self.sync_order_to_external_system(order)
              
              print(f'Successfully synced order {order_id} to external system')
              
          except Exception as error:
              print(f'Failed to process new order {order_id}: {error}')
              await self.handle_order_sync_failure(order_id, error)
      
      async def retry_api_call(self, api_call, attempt: int = 1):
          try:
              return await api_call()
          except Exception as error:
              if attempt < self.retry_attempts:
                  print(f'API call failed, retrying in {self.retry_delay * attempt}s (attempt {attempt}/{self.retry_attempts})')
                  await asyncio.sleep(self.retry_delay * attempt)
                  return await self.retry_api_call(api_call, attempt + 1)
              raise error
      
      def validate_order(self, order: Dict) -> bool:
          return (order.get('order_id') and 
                  order.get('total_amount') and 
                  order.get('customer') and 
                  order.get('customer', {}).get('email'))
      
      async def sync_order_to_external_system(self, order: Dict):
          # Transform Quickbutik order to your system's format
          external_order = self.transform_order(order)
          
          # Make API call to your external system
          async with aiohttp.ClientSession() as session:
              async with session.post(
                  'https://your-system.com/api/orders',
                  headers={
                      'Content-Type': 'application/json',
                      'Authorization': f'Bearer {os.getenv("EXTERNAL_API_TOKEN")}'
                  },
                  json=external_order
              ) as response:
                  if not response.ok:
                      raise Exception(f'External API error: {response.status} {await response.text()}')
                  return await response.json()
      
      def transform_order(self, quickbutik_order: Dict) -> Dict:
          return {
              'external_order_id': quickbutik_order['order_id'],
              'customer_email': quickbutik_order['customer']['email'],
              'total_amount': float(quickbutik_order['total_amount']),
              'currency': quickbutik_order.get('payment', {}).get('currency', 'SEK'),
              'items': [
                  {
                      'sku': product.get('sku'),
                      'quantity': product.get('qty', 1),
                      'price': float(product.get('price', 0))
                  }
                  for product in quickbutik_order.get('products', [])
              ],
              'shipping_address': quickbutik_order['customer'].get('shipping_details'),
              'billing_address': quickbutik_order['customer'].get('billing_details'),
              'created_at': quickbutik_order.get('date_created')
          }
      
      async def handle_order_sync_failure(self, order_id: str, error: Exception):
          # In production, you might:
          # 1. Add to a retry queue (Redis, Celery, etc.)
          # 2. Send alerts to monitoring system
          # 3. Log to error tracking service
          
          print(f'Order sync failed for {order_id}: {error}')
          
          # Example: Add to retry queue
          # await self.add_to_retry_queue({'order_id': order_id, 'error': str(error), 'timestamp': datetime.now()})

  # Usage
  order_sync = OrderSyncService(os.getenv('QUICKBUTIK_API_KEY'))

  async def handle_new_order(order_id: str):
      await order_sync.handle_new_order(order_id)
  ```
</CodeGroup>

## Part 3: Bidirectional Status Updates

Update Quickbutik when orders are processed in your external system:

<CodeGroup>
  ```javascript Node.js theme={null}
  class OrderStatusManager {
    constructor(apiKey) {
      this.api = new QuickbutikAPI(apiKey);
    }

    async markOrderAsShipped(orderId, shippingInfo) {
      try {
        const statusUpdate = {
          order_id: orderId,
          status: 'done',
          shipping_info: {
            trackingnumber: shippingInfo.trackingNumber,
            company: shippingInfo.carrier
          },
          email_confirmation: 'true'
        };

        const result = await this.api.updateOrderStatus(statusUpdate);
        
        console.log(`Order ${orderId} marked as shipped with tracking ${shippingInfo.trackingNumber}`);
        return result;

      } catch (error) {
        console.error(`Failed to update order ${orderId} status:`, error);
        throw error;
      }
    }

    async markOrderAsPaid(orderId, paymentInfo = {}) {
      try {
        const statusUpdate = {
          order_id: orderId,
          status: 'paid',
          skip_email_confirmation: paymentInfo.skipEmail ? 'true' : 'false'
        };

        const result = await this.api.updateOrderStatus(statusUpdate);
        
        console.log(`Order ${orderId} marked as paid`);
        return result;

      } catch (error) {
        console.error(`Failed to mark order ${orderId} as paid:`, error);
        throw error;
      }
    }

    async cancelOrder(orderId, reason = '') {
      try {
        const statusUpdate = {
          order_id: orderId,
          status: 'cancelled'
        };

        const result = await this.api.updateOrderStatus(statusUpdate);
        
        console.log(`Order ${orderId} cancelled. Reason: ${reason}`);
        return result;

      } catch (error) {
        console.error(`Failed to cancel order ${orderId}:`, error);
        throw error;
      }
    }
  }

  // Usage example - webhook from your external system
  app.post('/webhooks/external-system', async (req, res) => {
    const { event_type, order_id, data } = req.body;
    const statusManager = new OrderStatusManager(process.env.QUICKBUTIK_API_KEY);

    try {
      switch (event_type) {
        case 'order.shipped':
          await statusManager.markOrderAsShipped(order_id, {
            trackingNumber: data.tracking_number,
            carrier: data.carrier
          });
          break;
          
        case 'order.payment_confirmed':
          await statusManager.markOrderAsPaid(order_id);
          break;
          
        case 'order.cancelled':
          await statusManager.cancelOrder(order_id, data.reason);
          break;
      }

      res.status(200).json({ status: 'success' });
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  });
  ```

  ```python Python theme={null}
  class OrderStatusManager:
      def __init__(self, api_key: str):
          self.api = QuickbutikAPI(api_key)
      
      async def mark_order_as_shipped(self, order_id: str, shipping_info: Dict):
          try:
              status_update = {
                  'order_id': order_id,
                  'status': 'done',
                  'shipping_info': {
                      'trackingnumber': shipping_info['tracking_number'],
                      'company': shipping_info['carrier']
                  },
                  'email_confirmation': 'true'
              }
              
              result = await self.api.update_order_status(status_update)
              
              print(f'Order {order_id} marked as shipped with tracking {shipping_info["tracking_number"]}')
              return result
              
          except Exception as error:
              print(f'Failed to update order {order_id} status: {error}')
              raise error
      
      async def mark_order_as_paid(self, order_id: str, payment_info: Dict = {}):
          try:
              status_update = {
                  'order_id': order_id,
                  'status': 'paid',
                  'skip_email_confirmation': 'true' if payment_info.get('skip_email') else 'false'
              }
              
              result = await self.api.update_order_status(status_update)
              
              print(f'Order {order_id} marked as paid')
              return result
              
          except Exception as error:
              print(f'Failed to mark order {order_id} as paid: {error}')
              raise error
      
      async def cancel_order(self, order_id: str, reason: str = ''):
          try:
              status_update = {
                  'order_id': order_id,
                  'status': 'cancelled'
              }
              
              result = await self.api.update_order_status(status_update)
              
              print(f'Order {order_id} cancelled. Reason: {reason}')
              return result
              
          except Exception as error:
              print(f'Failed to cancel order {order_id}: {error}')
              raise error

  # Usage example - webhook from your external system
  @app.route('/webhooks/external-system', methods=['POST'])
  async def external_system_webhook():
      data = request.get_json()
      event_type = data.get('event_type')
      order_id = data.get('order_id')
      event_data = data.get('data', {})
      
      status_manager = OrderStatusManager(os.getenv('QUICKBUTIK_API_KEY'))
      
      try:
          if event_type == 'order.shipped':
              await status_manager.mark_order_as_shipped(order_id, {
                  'tracking_number': event_data['tracking_number'],
                  'carrier': event_data['carrier']
              })
          elif event_type == 'order.payment_confirmed':
              await status_manager.mark_order_as_paid(order_id)
          elif event_type == 'order.cancelled':
              await status_manager.cancel_order(order_id, event_data.get('reason', ''))
          
          return jsonify({'status': 'success'}), 200
      except Exception as error:
          return jsonify({'error': str(error)}), 500
  ```
</CodeGroup>

## Part 4: Production Deployment

Here's a production-ready setup with Docker:

<CodeGroup>
  ```dockerfile Dockerfile theme={null}
  FROM node:18-alpine

  WORKDIR /app

  # Copy package files
  COPY package*.json ./
  RUN npm ci --only=production

  # Copy application code
  COPY . .

  # Create non-root user
  RUN addgroup -g 1001 -S nodejs
  RUN adduser -S nodejs -u 1001

  # Change ownership and switch to non-root user
  RUN chown -R nodejs:nodejs /app
  USER nodejs

  EXPOSE 3000

  # Health check
  HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:3000/health || exit 1

  CMD ["node", "server.js"]
  ```

  ```yaml docker-compose.yml theme={null}
  version: '3.8'

  services:
    order-sync:
      build: .
      ports:
        - "3000:3000"
      environment:
        - QUICKBUTIK_API_KEY=${QUICKBUTIK_API_KEY}
        - EXTERNAL_API_TOKEN=${EXTERNAL_API_TOKEN}
        - REDIS_URL=${REDIS_URL}
        - NODE_ENV=production
      depends_on:
        - redis
      restart: unless-stopped
      
    redis:
      image: redis:7-alpine
      ports:
        - "6379:6379"
      volumes:
        - redis_data:/data
      restart: unless-stopped

    nginx:
      image: nginx:alpine
      ports:
        - "80:80"
        - "443:443"
      volumes:
        - ./nginx.conf:/etc/nginx/nginx.conf
        - ./ssl:/etc/nginx/ssl
      depends_on:
        - order-sync
      restart: unless-stopped

  volumes:
    redis_data:
  ```
</CodeGroup>

## Part 5: Monitoring and Alerting

Add comprehensive monitoring to your integration:

<CodeGroup>
  ```javascript Monitoring theme={null}
  const prometheus = require('prom-client');

  // Create metrics
  const webhookCounter = new prometheus.Counter({
    name: 'quickbutik_webhooks_total',
    help: 'Total number of webhooks received',
    labelNames: ['event_type', 'status']
  });

  const orderSyncDuration = new prometheus.Histogram({
    name: 'order_sync_duration_seconds',
    help: 'Time spent syncing orders',
    buckets: [0.1, 0.5, 1, 2, 5, 10]
  });

  const orderSyncErrors = new prometheus.Counter({
    name: 'order_sync_errors_total',
    help: 'Total number of order sync errors',
    labelNames: ['error_type']
  });

  // Add metrics to webhook handler
  app.post('/webhooks/quickbutik', async (req, res) => {
    const { event_type, order_id } = req.query;
    const timer = orderSyncDuration.startTimer();
    
    try {
      webhookCounter.inc({ event_type, status: 'received' });
      
      res.status(200).send('OK');
      
      await processOrderWebhook(event_type, order_id);
      
      webhookCounter.inc({ event_type, status: 'processed' });
      timer();
      
    } catch (error) {
      orderSyncErrors.inc({ error_type: error.constructor.name });
      webhookCounter.inc({ event_type, status: 'error' });
      timer();
      
      // Send alert
      await sendAlert({
        type: 'order_sync_error',
        orderId,
        error: error.message,
        timestamp: new Date()
      });
    }
  });

  // Metrics endpoint
  app.get('/metrics', async (req, res) => {
    res.set('Content-Type', prometheus.register.contentType);
    res.end(await prometheus.register.metrics());
  });

  // Health check endpoint
  app.get('/health', (req, res) => {
    res.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      uptime: process.uptime()
    });
  });

  async function sendAlert(alert) {
    // Send to Slack, PagerDuty, email, etc.
    console.error('ALERT:', alert);
    
    // Example: Slack webhook
    if (process.env.SLACK_WEBHOOK_URL) {
      await fetch(process.env.SLACK_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          text: `🚨 Order sync error for order ${alert.orderId}: ${alert.error}`
        })
      });
    }
  }
  ```
</CodeGroup>

## 🎉 You Did It!

You now have a production-ready order synchronization system with:

* ✅ Webhook handling with proper acknowledgment
* ✅ Automatic retry logic for failed API calls
* ✅ Bidirectional order status updates
* ✅ Comprehensive error handling and monitoring
* ✅ Production deployment configuration

## Next Steps

<CardGroup>
  <Card title="Inventory Management" icon="boxes-stacked" href="/api-v1/guides/inventory-management">
    Learn how to keep product stock levels synchronized
  </Card>
</CardGroup>


# Introduction
Source: https://quickbutik.dev/api-v1/introduction

Everything you need to start integrating with the Quickbutik API

Welcome to the **Quickbutik API**! Our REST API allows you to manage your store's orders, products, categories, and more programmatically. Build powerful integrations to automate your e-commerce operations.

## Base URL

All API requests are made to our base URL:

```
https://api.quickbutik.com/v1
```

**OpenAPI Specification:** [https://quickbutik.dev/openapi.yaml](https://quickbutik.dev/openapi.yaml)

## Key Features

<CardGroup>
  <Card title="Order Management" icon="cart-shopping">
    Create, update, and retrieve orders with full order lifecycle support
  </Card>

  <Card title="Product Catalog" icon="box">
    Manage your product inventory, pricing, and product information
  </Card>

  <Card title="Category Management" icon="folder">
    Organize products with hierarchical category structures
  </Card>

  <Card title="Real-time Updates" icon="bolt">
    Get instant updates via webhooks when important events occur
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Get your API key">
    Generate an API key in the Quickbutik Control Panel under **Settings → API**
  </Step>

  <Step title="Set up authentication">
    All requests require [Basic Authentication](/api-v1/authentication) using your API key
  </Step>

  <Step title="Make your first request">
    Try fetching your product count to test your setup:

    ```bash theme={null}
    curl https://api.quickbutik.com/v1/products/count \
      -u your_api_key:your_api_key
    ```
  </Step>
</Steps>

## Response Format

All API responses are returned in JSON format, including error messages. Successful responses will contain the requested data, while errors will include helpful error codes and descriptions.

### Success Response Example

```json theme={null}
{
  "count": "42"
}
```

### Error Response Example

```json theme={null}
{
  "code": 404,
  "error": "Resource not found"
}
```

## HTTP Status Codes

The API uses conventional HTTP response codes:

* `200` - OK: The request was successful
* `400` - Bad Request: The request was invalid
* `401` - Unauthorized: Authentication failed
* `404` - Not Found: The requested resource doesn't exist
* `500` - Internal Server Error: Something went wrong on our end

## Rate Limiting

To ensure fair usage and optimal performance for all users, please be mindful of your request frequency. If you encounter rate limiting, implement exponential backoff in your retry logic.

## Support

We're here to help! For feature requests, feedback, or technical questions:

<Card title="Contact Support" icon="envelope">
  Email us at [support@quickbutik.com](mailto:support@quickbutik.com)

  We greatly appreciate your feedback and are always working to improve our API.
</Card>

Ready to get started? Check out our [Authentication guide](/api-v1/authentication) to begin integrating with the Quickbutik API.


# Create metadata
Source: https://quickbutik.dev/api-v1/metadata/create-metadata

post /v1/metadata/{scope}/{id}
Add metadata to selected scope



# Get metadata
Source: https://quickbutik.dev/api-v1/metadata/get-metadata

get /v1/metadata/{scope}/{id}
Get metadata for selected scope and id



# Update metadata
Source: https://quickbutik.dev/api-v1/metadata/update-metadata

put /v1/metadata/{scope}/{id}
Update metadata to selected scope. Delete when empty value



# Create orders
Source: https://quickbutik.dev/api-v1/orders/create-orders

post /v1/orders
Create new order and add order content. Status for new orders will always be set to **unpaid**



# Get orders
Source: https://quickbutik.dev/api-v1/orders/get-orders

get /v1/orders
Retrieve a list of orders with optional filtering, pagination and sorting.




# Update orders
Source: https://quickbutik.dev/api-v1/orders/update-orders

put /v1/orders
Update one or more existing orders. Each request object must include the `order_id` of the order to update, plus any fields you want to change



# Get payment methods
Source: https://quickbutik.dev/api-v1/payment-methods/get-payment-methods

get /v1/paymentmethods
Fetch store payment methods



# Count products
Source: https://quickbutik.dev/api-v1/products/count-products

get /v1/products/count
Fetches a count of the total number of products



# Create products
Source: https://quickbutik.dev/api-v1/products/create-products

post /v1/products
Create and add products to store



# Delete products
Source: https://quickbutik.dev/api-v1/products/delete-products

delete /v1/products
Deletes a product from the store entirely. **NOTE:** This is non-reversible



# Get products
Source: https://quickbutik.dev/api-v1/products/get-products

get /v1/products
Fetch products in store with optional filtering. When no specific product_id or sku is provided,
the following filters can be used to search and filter products.

**Important - Response Structure Varies:**
- When using the `search` parameter: Returns a direct array `[...]`
- When NOT using the `search` parameter: Returns `{product: [...]}`
- When requesting a specific product by `product_id` or `sku`: Returns `{product: {...}}`




# Update products
Source: https://quickbutik.dev/api-v1/products/update-products

put /v1/products
Update products in store. Product can be identified by product_id/variant_id or directly with SKU/Article Number if unique



# Quickstart Tutorial
Source: https://quickbutik.dev/api-v1/quickstart-tutorial

Build your first Quickbutik integration in 15 minutes

This tutorial will walk you through building your first Quickbutik integration. You'll learn how to authenticate, fetch data, and handle responses.

<Note>
  **Prerequisites**: You'll need a Quickbutik store and an API key. If you don't have an API key yet, generate one in your store's Control Panel under **Settings → API**.
</Note>

## What we'll build

By the end of this tutorial, you'll have a simple integration that:

* ✅ Authenticates with the Quickbutik API
* ✅ Fetches your store's product count
* ✅ Retrieves your latest orders
* ✅ Handles errors gracefully

## Step 1: Set up authentication

First, let's test your API connection with a simple request to count your products:

<CodeGroup>
  ```bash cURL theme={null}
  # Replace 'your_api_key' with your actual API key
  curl https://api.quickbutik.com/v1/products/count \
    -u your_api_key:your_api_key \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch'); // or use built-in fetch in Node 18+

  const apiKey = 'your_api_key';
  const credentials = Buffer.from(`${apiKey}:${apiKey}`).toString('base64');

  async function getProductCount() {
    try {
      const response = await fetch('https://api.quickbutik.com/v1/products/count', {
        headers: {
          'Authorization': `Basic ${credentials}`,
          'Content-Type': 'application/json'
        }
      });

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

      const data = await response.json();
      console.log('Product count:', data.count);
      return data;
    } catch (error) {
      console.error('Error:', error.message);
    }
  }

  getProductCount();
  ```

  ```python Python theme={null}
  import requests
  import base64
  import json

  api_key = 'your_api_key'
  credentials = base64.b64encode(f'{api_key}:{api_key}'.encode()).decode()

  def get_product_count():
      try:
          response = requests.get(
              'https://api.quickbutik.com/v1/products/count',
              headers={
                  'Authorization': f'Basic {credentials}',
                  'Content-Type': 'application/json'
              }
          )
          response.raise_for_status()
          
          data = response.json()
          print(f"Product count: {data['count']}")
          return data
          
      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")

  get_product_count()
  ```
</CodeGroup>

### Expected Response

```json theme={null}
{
  "count": "42"
}
```

<Accordion title="Troubleshooting authentication">
  **Common issues:**

  * **401 Unauthorized**: Check that your API key is correct
  * **Invalid base64**: Ensure you're encoding `api_key:api_key` format
  * **SSL errors**: Make sure you're using `https://` not `http://`

  **Test your base64 encoding:**

  ```bash theme={null}
  echo -n "your_api_key:your_api_key" | base64
  ```
</Accordion>

## Step 2: Fetch your latest orders

Now let's retrieve your most recent orders:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.quickbutik.com/v1/orders?limit=5&include_details=true" \
    -u your_api_key:your_api_key \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  async function getLatestOrders() {
    try {
      const response = await fetch('https://api.quickbutik.com/v1/orders?limit=5&include_details=true', {
        headers: {
          'Authorization': `Basic ${credentials}`,
          'Content-Type': 'application/json'
        }
      });

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

      const orders = await response.json();
      console.log(`Found ${orders.length} recent orders`);
      
      orders.forEach(order => {
        console.log(`Order #${order.order_id}: ${order.total_amount} (${order.status})`);
      });
      
      return orders;
    } catch (error) {
      console.error('Error fetching orders:', error.message);
    }
  }

  getLatestOrders();
  ```

  ```python Python theme={null}
  def get_latest_orders():
      try:
          response = requests.get(
              'https://api.quickbutik.com/v1/orders',
              params={'limit': 5, 'include_details': True},
              headers={
                  'Authorization': f'Basic {credentials}',
                  'Content-Type': 'application/json'
              }
          )
          response.raise_for_status()
          
          orders = response.json()
          print(f"Found {len(orders)} recent orders")
          
          for order in orders:
              print(f"Order #{order['order_id']}: {order['total_amount']} ({order['status']})")
          
          return orders
          
      except requests.exceptions.RequestException as error:
          print(f"Error fetching orders: {error}")

  get_latest_orders()
  ```
</CodeGroup>

### Expected Response

```json theme={null}
[
  {
    "order_id": "12345",
    "date_created": "2025-01-29 11:35:39",
    "total_amount": "148.95",
    "status": "1"
  }
]
```

## Step 3: Update an order status

Let's mark an order as "done" (shipped):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.quickbutik.com/v1/orders \
    -u your_api_key:your_api_key \
    -H "Content-Type: application/json" \
    -d '[{
      "order_id": "12345",
      "status": "done",
      "shipping_info": {
        "trackingnumber": "1Z999AA1234567890",
        "company": "UPS"
      },
      "email_confirmation": "true"
    }]'
  ```

  ```javascript Node.js theme={null}
  async function markOrderAsShipped(orderId, trackingNumber) {
    try {
      const response = await fetch('https://api.quickbutik.com/v1/orders', {
        method: 'PUT',
        headers: {
          'Authorization': `Basic ${credentials}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify([{
          order_id: orderId,
          status: 'done',
          shipping_info: {
            trackingnumber: trackingNumber,
            company: 'UPS'
          },
          email_confirmation: 'true'
        }])
      });

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

      const result = await response.json();
      console.log('Order updated successfully:', result);
      return result;
    } catch (error) {
      console.error('Error updating order:', error.message);
    }
  }

  markOrderAsShipped('12345', '1Z999AA1234567890');
  ```

  ```python Python theme={null}
  def mark_order_as_shipped(order_id, tracking_number):
      try:
          response = requests.put(
              'https://api.quickbutik.com/v1/orders',
              headers={
                  'Authorization': f'Basic {credentials}',
                  'Content-Type': 'application/json'
              },
              json=[{
                  'order_id': order_id,
                  'status': 'done',
                  'shipping_info': {
                      'trackingnumber': tracking_number,
                      'company': 'UPS'
                  },
                  'email_confirmation': 'true'
              }]
          )
          response.raise_for_status()
          
          result = response.json()
          print('Order updated successfully:', result)
          return result
          
      except requests.exceptions.RequestException as error:
          print(f"Error updating order: {error}")

  mark_order_as_shipped('12345', '1Z999AA1234567890')
  ```
</CodeGroup>

## Step 4: Handle errors like a pro

Here's how to build robust error handling:

<CodeGroup>
  ```javascript Node.js theme={null}
  class QuickbutikAPI {
    constructor(apiKey) {
      this.apiKey = apiKey;
      this.credentials = Buffer.from(`${apiKey}:${apiKey}`).toString('base64');
      this.baseUrl = 'https://api.quickbutik.com/v1';
    }

    async request(endpoint, options = {}) {
      const url = `${this.baseUrl}${endpoint}`;
      
      try {
        const response = await fetch(url, {
          ...options,
          headers: {
            'Authorization': `Basic ${this.credentials}`,
            'Content-Type': 'application/json',
            ...options.headers
          }
        });

        // Handle different HTTP status codes
        if (!response.ok) {
          const errorData = await response.json().catch(() => ({}));
          
          switch (response.status) {
            case 401:
              throw new Error('Authentication failed. Check your API key.');
            case 404:
              throw new Error(`Resource not found: ${errorData.error || 'Unknown error'}`);
            case 400:
              throw new Error(`Bad request: ${errorData.error || 'Invalid data provided'}`);
            case 500:
              throw new Error('Server error. Please try again later.');
            default:
              throw new Error(`HTTP ${response.status}: ${errorData.error || response.statusText}`);
          }
        }

        return await response.json();
      } catch (error) {
        if (error.name === 'TypeError' && error.message.includes('fetch')) {
          throw new Error('Network error. Check your internet connection.');
        }
        throw error;
      }
    }

    async getOrders(params = {}) {
      const queryString = new URLSearchParams(params).toString();
      const endpoint = queryString ? `/orders?${queryString}` : '/orders';
      return this.request(endpoint);
    }

    async updateOrderStatus(updates) {
      return this.request('/orders', {
        method: 'PUT',
        body: JSON.stringify(Array.isArray(updates) ? updates : [updates])
      });
    }
  }

  // Usage
  const api = new QuickbutikAPI('your_api_key');

  async function example() {
    try {
      const orders = await api.getOrders({ limit: 5 });
      console.log('Orders fetched successfully:', orders.length);
    } catch (error) {
      console.error('Failed to fetch orders:', error.message);
    }
  }
  ```

  ```python Python theme={null}
  import requests
  import base64
  from typing import Dict, List, Optional

  class QuickbutikAPI:
      def __init__(self, api_key: str):
          self.api_key = api_key
          self.credentials = base64.b64encode(f'{api_key}:{api_key}'.encode()).decode()
          self.base_url = 'https://api.quickbutik.com/v1'
          
      def _request(self, endpoint: str, method: str = 'GET', data: Optional[Dict] = None):
          url = f'{self.base_url}{endpoint}'
          headers = {
              'Authorization': f'Basic {self.credentials}',
              'Content-Type': 'application/json'
          }
          
          try:
              response = requests.request(method, url, headers=headers, json=data)
              
              # Handle different HTTP status codes
              if response.status_code == 401:
                  raise Exception('Authentication failed. Check your API key.')
              elif response.status_code == 404:
                  error_data = response.json() if response.content else {}
                  raise Exception(f"Resource not found: {error_data.get('error', 'Unknown error')}")
              elif response.status_code == 400:
                  error_data = response.json() if response.content else {}
                  raise Exception(f"Bad request: {error_data.get('error', 'Invalid data provided')}")
              elif response.status_code == 500:
                  raise Exception('Server error. Please try again later.')
              
              response.raise_for_status()
              return response.json()
              
          except requests.exceptions.ConnectionError:
              raise Exception('Network error. Check your internet connection.')
          except requests.exceptions.Timeout:
              raise Exception('Request timed out. Please try again.')
          except requests.exceptions.RequestException as e:
              raise Exception(f'Request failed: {str(e)}')
      
      def get_orders(self, **params) -> List[Dict]:
          endpoint = '/orders'
          if params:
              query_string = '&'.join([f'{k}={v}' for k, v in params.items()])
              endpoint += f'?{query_string}'
          return self._request(endpoint)
      
      def update_order_status(self, updates) -> Dict:
          if not isinstance(updates, list):
              updates = [updates]
          return self._request('/orders', method='PUT', data=updates)

  # Usage
  api = QuickbutikAPI('your_api_key')

  try:
      orders = api.get_orders(limit=5)
      print(f'Orders fetched successfully: {len(orders)}')
  except Exception as error:
      print(f'Failed to fetch orders: {error}')
  ```
</CodeGroup>

## 🎉 Congratulations!

You've successfully built your first Quickbutik integration! You now know how to:

* ✅ Authenticate with the API
* ✅ Fetch orders and products
* ✅ Update order statuses
* ✅ Handle errors gracefully

## Next steps

<CardGroup>
  <Card title="Set up webhooks" icon="webhook" href="/webhooks/introduction">
    Get real-time notifications when orders are created or updated
  </Card>

  <Card title="Order sync tutorial" icon="arrows-rotate" href="/api-v1/guides/order-sync-tutorial">
    Learn how to build a complete order synchronization system
  </Card>
</CardGroup>

## Need help?

<Card title="Get Support" icon="question">
  Stuck on something? We're here to help! Reach out to [support@quickbutik.com](mailto:support@quickbutik.com) with your questions.
</Card>


# Create script
Source: https://quickbutik.dev/api-v1/scripts/create-script

/openapi.yaml post /v1/scripts
Create a new storefront script



# Delete script
Source: https://quickbutik.dev/api-v1/scripts/delete-script

/openapi.yaml delete /v1/scripts/{id}
Delete a storefront script



# Get scripts
Source: https://quickbutik.dev/api-v1/scripts/get-scripts

/openapi.yaml get /v1/scripts
List all storefront scripts or get a specific script by ID



# Update or create script
Source: https://quickbutik.dev/api-v1/scripts/update-or-create-script

/openapi.yaml put /v1/scripts/{id}
Update an existing script or create one with a specific ID



# Get preorder options
Source: https://quickbutik.dev/api-v1/settings/get-preorder-options

/openapi.yaml get /v1/settings/preorders
Retrieve all preorder options configured for the store. These options can be assigned to products and variants to indicate pre-order availability and estimated delivery windows.

**Required scope:** `products:read` or `read_only`

**Note:** This endpoint is not available to storefront-only API keys.




# Get preorders
Source: https://quickbutik.dev/api-v1/settings/get-preorders

get /v1/preorders



# Get shipping methods
Source: https://quickbutik.dev/api-v1/shipping-methods/get-shipping-methods

get /v1/shippingmethods
Fetch store shipping methods



# Build with AI
Source: https://quickbutik.dev/build-with-ai

Use AI tools to accelerate your Quickbutik integration development with our OpenAPI specification

## Quickbutik API (OpenAPI Specification)

**[https://quickbutik.dev/openapi.yaml](https://quickbutik.dev/openapi.yaml)**

## Supercharge your development with AI

The Quickbutik API is fully documented with an OpenAPI 3.1 specification, making it easy to use with AI-powered development tools like Cursor, GitHub Copilot, and ChatGPT.

<Card title="OpenAPI Specification" icon="file-code" href="https://quickbutik.dev/openapi.yaml">
  Access our complete OpenAPI specification file
</Card>

## What you can do with the OpenAPI spec

Our OpenAPI specification provides a machine-readable description of the entire Quickbutik API, including:

* **All endpoints** - Complete paths for orders, products, categories, and more
* **Request schemas** - Exact structure of request bodies and parameters
* **Response formats** - Expected response structures and status codes
* **Authentication details** - How to authenticate your API requests
* **Data types and validation** - Field types, constraints, and validation rules

## Using with AI coding assistants

### Cursor AI

If you're using Cursor, you can reference the OpenAPI spec directly in your prompts:

```
@https://quickbutik.dev/openapi.yaml
Create a function to fetch all orders from the last 30 days
```

### GitHub Copilot & ChatGPT

Share the OpenAPI specification with these tools to get context-aware code suggestions:

1. Download or reference the OpenAPI spec: `https://quickbutik.dev/openapi.yaml`
2. Paste relevant sections or the full spec into your conversation
3. Ask the AI to generate code based on the specification

## Example prompts

Here are some example prompts you can use with AI assistants:

<AccordionGroup>
  <Accordion title="Generate API client code">
    "Using the Quickbutik OpenAPI spec at [https://quickbutik.dev/openapi.yaml](https://quickbutik.dev/openapi.yaml), generate a TypeScript client for fetching and updating products"
  </Accordion>

  <Accordion title="Create integration functions">
    "Based on the Quickbutik API spec, create Python functions to sync orders between my system and Quickbutik"
  </Accordion>

  <Accordion title="Build webhooks handler">
    "Using the Quickbutik OpenAPI specification, create a Node.js Express server that handles order webhook events"
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="API Documentation" icon="code" href="/api-v1/introduction">
    Explore the full API documentation
  </Card>

  <Card title="Quick Start Tutorial" icon="play" href="/api-v1/quickstart-tutorial">
    Follow a step-by-step tutorial
  </Card>
</CardGroup>


# Quickbutik Developers
Source: https://quickbutik.dev/index

Welcome! Here you'll find everything you need to create beautiful themes and powerful integrations for e-commerce stores.

## Getting started

Where would you like to begin?

<CardGroup>
  <Card title="Customize your storefront" icon="paintbrush" href="/theme-development/introduction">
    Handle all your frontend needs with our templating system. Design layouts, customize functionality, and create responsive storefronts for your customers.
  </Card>

  <Card title="API documentation" icon="code" href="/api-v1/introduction">
    Manage your backend operations with our API & Webhooks. Integrate products, orders, customers and more through our straightforward endpoints and webhooks.
  </Card>

  <Card title="Build with AI" icon="sparkles" href="/build-with-ai">
    Use AI tools like Cursor, GitHub Copilot, and ChatGPT with our OpenAPI specification to accelerate your development.
  </Card>

  <Card title="Quickbutik OpenAPI.yaml" icon="file-code" href="https://quickbutik.dev/openapi.yaml">
    Direct access to our complete OpenAPI 3.1 specification for AI tools and API client generators.
  </Card>
</CardGroup>


# Resources
Source: https://quickbutik.dev/resources

Essential resources, tools, and references for Quickbutik developers

# Developer Resources

Everything you need to accelerate your development with Quickbutik - from quick references to comprehensive guides.

## Popular Resources

Quick access to the most commonly used documentation:

<CardGroup>
  <Card title="Mustache Basics" icon="file-code" href="/theme-development/mustache-basics">
    Learn the templating language fundamentals and start building your first theme
  </Card>

  <Card title="API Quickstart" icon="rocket" href="/api-v1/quickstart-tutorial">
    Get started with your first API call and understand authentication
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Access store settings, configuration, and global shop data in your themes
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/introduction">
    Set up real-time event notifications for orders, products, and more
  </Card>
</CardGroup>

## Quick Links by Category

### Theme Development

<CardGroup>
  <Card title="Objects & Attributes" icon="brackets-curly" href="/theme-development/objects-and-attributes">
    Access and display data in your themes
  </Card>

  <Card title="Conditionals" icon="code-branch" href="/theme-development/conditionals">
    Control flow and conditional rendering
  </Card>

  <Card title="Wrappers & Functions" icon="wrench" href="/theme-development/wrappers-and-functions">
    Image processing, translations, and utilities
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Shop, user, basket, and navigation data
  </Card>

  <Card title="Page Objects" icon="file-text" href="/theme-development/pages/product">
    Product, category, order, and blog objects
  </Card>

  <Card title="Best Practices" icon="star" href="/theme-development/advanced/best-practices">
    Performance, SEO, and development tips
  </Card>
</CardGroup>

### API Integration

<CardGroup>
  <Card title="Authentication" icon="key" href="/api-v1/authentication">
    API keys, tokens, and security
  </Card>

  <Card title="Products API" icon="box" href="/api-v1/products/get-products">
    Manage product catalog and inventory
  </Card>

  <Card title="Orders API" icon="shopping-bag" href="/api-v1/orders/get-orders">
    Process and manage orders
  </Card>

  <Card title="Webhook Events" icon="bolt" href="/webhooks/events">
    Set up real-time event notifications for orders, products, and more
  </Card>
</CardGroup>


# Conditionals
Source: https://quickbutik.dev/theme-development/conditionals

Master advanced conditional logic, boolean operations, and dynamic content display in Mustache templates

Conditionals in Mustache allow you to display content based on whether certain conditions are met. This guide covers advanced conditional patterns and techniques for building dynamic, responsive themes using only supported Quickbutik properties.

<Info>
  **Prerequisites**: This guide assumes you understand basic Mustache syntax. Review [Mustache Basics](/theme-development/mustache-basics) first if you're new to Mustache conditionals.
</Info>

## Advanced Conditional Logic

### Complex If-Else Patterns

Combine positive and negative conditionals for sophisticated logic:

<CodeGroup>
  ```mustache User Authentication States theme={null}
  <!-- Handle user login states -->
  {{#shop.login_active}}
      {{#user.logged_in}}
          <div class="user-menu authenticated">
              <span>{{#lang}}Welcome back{{/lang}}</span>
              <a href="{{user.login_url}}" class="account-link">
                  {{#lang}}My Account{{/lang}}
              </a>
          </div>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
          <div class="user-menu guest">
              <a href="{{user.login_url}}" class="btn btn-primary">
                  {{#lang}}Login{{/lang}}
              </a>
              <div class="auth-benefits">
                  <p>{{#lang}}Join for exclusive deals and faster checkout{{/lang}}</p>
              </div>
          </div>
      {{/user.logged_in}}
  {{/shop.login_active}}

  {{^shop.login_active}}
      <div class="no-accounts">
          <p>{{#lang}}Guest checkout available{{/lang}}</p>
      </div>
  {{/shop.login_active}}
  ```

  ```mustache Product Pricing Display theme={null}
  <!-- Product pricing with sale conditions -->
  {{#product.has_before_price}}
      <div class="price-container sale">
          <div class="price-display">
              <span class="original-price">{{product.before_price}}</span>
              <span class="sale-price">{{product.price}}</span>
              <span class="discount-badge">{{#lang}}Sale{{/lang}}</span>
          </div>
      </div>
  {{/product.has_before_price}}

  {{^product.has_before_price}}
      <div class="price-container regular">
          <div class="price-display">
              <span class="current-price">{{product.price}}</span>
          </div>
      </div>
  {{/product.has_before_price}}
  ```
</CodeGroup>

### Deeply Nested Conditionals

Handle complex business logic with multiple levels of conditions:

<CodeGroup>
  ```mustache Product Availability Management theme={null}
  <!-- Product stock and availability logic -->
  {{#product.soldOut}}
      <div class="stock-info unavailable">
          <div class="out-of-stock">
              {{#shop.soldout_text}}
                  <p>{{shop.soldout_text}}</p>
              {{/shop.soldout_text}}
              {{^shop.soldout_text}}
                  <p>{{#lang}}Currently unavailable{{/lang}}</p>
              {{/shop.soldout_text}}
          </div>
      </div>
  {{/product.soldOut}}

  {{^product.soldOut}}
      <div class="stock-info available">
          <div class="stock-good">
              <i class="icon-check"></i>
              <span>{{#lang}}Available{{/lang}}</span>
              <button class="add-to-cart">{{#lang}}Add to Cart{{/lang}}</button>
          </div>
      </div>
  {{/product.soldOut}}
  ```
</CodeGroup>

## Working with Arrays and Collections

### Advanced Array Conditionals

Handle complex array states and conditions:

<CodeGroup>
  ```mustache Smart Image Gallery theme={null}
  <!-- Handle different image gallery states -->
  {{#product.images}}
      <div class="product-gallery">
          {{#product.images}}
              <div class="image-item">
                  <img src="{{#img}}{{image}}_400x400{{/img}}" alt="{{alttext}}">
              </div>
          {{/product.images}}
      </div>
  {{/product.images}}

  {{^product.images}}
      <div class="no-images">
          {{#product.firstimage}}
              <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}" class="main-image">
          {{/product.firstimage}}
          
          {{^product.firstimage}}
              <div class="placeholder-container">
                  <img src="{{#assets}}images/placeholder.jpg{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
              </div>
          {{/product.firstimage}}
      </div>
  {{/product.images}}
  ```

  ```mustache Advanced Product Grid theme={null}
  <!-- Complex product listing with conditional features -->
  {{#products}}
      <div class="product-card {{#has_before_price}}sale{{/has_before_price}} {{#soldOut}}unavailable{{/soldOut}}">
          <div class="product-badges">
              {{#has_before_price}}
                  <span class="badge sale">{{#lang}}Sale{{/lang}}</span>
              {{/has_before_price}}
          </div>
          
          <div class="product-image">
              {{#firstimage}}
                  <img src="{{#img}}{{firstimage}}_300x300{{/img}}" alt="{{title}}">
              {{/firstimage}}
              {{^firstimage}}
                  <img src="{{#assets}}images/no-image.png{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
              {{/firstimage}}
          </div>
          
          <div class="product-info">
              <h3>{{title}}</h3>
              
              <div class="price-section">
                  {{#has_before_price}}
                      <span class="old-price">{{before_price}}</span>
                      <span class="sale-price">{{price}}</span>
                  {{/has_before_price}}
                  
                  {{^has_before_price}}
                      <span class="price">{{price}}</span>
                  {{/has_before_price}}
              </div>
              
              <div class="product-actions">
                  {{^soldOut}}
                      <a href="{{url}}" class="view-product">{{#lang}}View Product{{/lang}}</a>
                  {{/soldOut}}
                  
                  {{#soldOut}}
                      <button class="out-of-stock" disabled>{{#lang}}Out of Stock{{/lang}}</button>
                  {{/soldOut}}
              </div>
          </div>
      </div>
  {{/products}}

  {{^products}}
      <div class="no-products">
          <div class="empty-category">
              <h3>{{#lang}}No products in this category yet{{/lang}}</h3>
              <p>{{#lang}}Check back soon for new arrivals{{/lang}}</p>
              <a href="{{shop.url}}" class="btn">{{#lang}}Browse All Products{{/lang}}</a>
          </div>
      </div>
  {{/products}}
  ```
</CodeGroup>

## Conditional Classes and Attributes

Use conditionals to dynamically apply CSS classes and HTML attributes:

<CodeGroup>
  ```mustache Dynamic Navigation theme={null}
  <!-- Navigation with supported properties -->
  {{#linklist.main}}
      <div class="nav-item {{#current}}active{{/current}} {{#hasChildren}}has-dropdown{{/hasChildren}}">
          <a href="{{url}}" class="nav-link">
              {{name}}
              {{#hasChildren}}
                  <i class="icon-chevron"></i>
              {{/hasChildren}}
          </a>
          
          {{#hasChildren}}
              <div class="dropdown-menu">
                  {{#children}}
                      <a href="{{url}}" class="dropdown-link {{#current}}active{{/current}}">
                          {{name}}
                      </a>
                  {{/children}}
              </div>
          {{/hasChildren}}
      </div>
  {{/linklist.main}}
  ```

  ```mustache Responsive Form Elements theme={null}
  <!-- Forms with conditional validation and styling -->
  <form class="contact-form {{#user.logged_in}}authenticated{{/user.logged_in}}">
      {{#response_data}}
          {{#success}}
              <div class="form-success">
                  {{&success_message}}
              </div>
          {{/success}}
          
          {{#errors}}
              <div class="form-errors">
                  {{#error_message}}
                      <p class="error-text">{{.}}</p>
                  {{/error_message}}
              </div>
          {{/errors}}
      {{/response_data}}
      
      <div class="form-group">
          <label for="name">{{#lang}}Name{{/lang}} *</label>
          <input type="text" 
                 id="name" 
                 name="name"
                 placeholder="{{#lang}}Enter your name{{/lang}}"
                 required>
      </div>
      
      <div class="form-group">
          <label for="email">{{#lang}}Email{{/lang}} *</label>
          <input type="email" 
                 id="email" 
                 name="email"
                 placeholder="{{#lang}}Enter your email{{/lang}}"
                 required>
      </div>
      
      <div class="form-group">
          <label for="message">{{#lang}}Message{{/lang}}</label>
          <textarea id="message" 
                    name="message"
                    placeholder="{{#lang}}Write your message here{{/lang}}"></textarea>
      </div>
      
      <button type="submit">{{#lang}}Send Message{{/lang}}</button>
  </form>
  ```
</CodeGroup>

## Theme and Settings Conditionals

Advanced conditional logic based on theme settings and store configuration:

<CodeGroup>
  ```mustache Store Feature Toggles theme={null}
  <!-- Conditional features based on store settings -->
  {{#shop.login_active}}
      <div class="account-section">
          {{#user.logged_in}}
              <div class="logged-in-user">
                  <a href="{{user.login_url}}" class="account-btn">
                      {{#lang}}My Account{{/lang}}
                  </a>
              </div>
          {{/user.logged_in}}
          
          {{^user.logged_in}}
              <div class="guest-user">
                  <a href="{{user.login_url}}" class="login-btn">
                      {{#lang}}Sign In{{/lang}}
                  </a>
              </div>
          {{/user.logged_in}}
      </div>
  {{/shop.login_active}}

  {{#shop.cconverter_active}}
      <div class="currency-selector">
          {{#shop.cconverter_currencies}}
              <button class="currency-option {{#current}}active{{/current}}" 
                      data-currency="{{currency}}">
                  {{currency}}
              </button>
          {{/shop.cconverter_currencies}}
      </div>
  {{/shop.cconverter_active}}

  {{#shop.app.languages}}
      <div class="language-selector">
          {{#shop.languages}}
              <a href="{{url}}" class="lang-option">
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
                  <span>{{id}}</span>
              </a>
          {{/shop.languages}}
      </div>
  {{/shop.app.languages}}
  ```

  ```mustache Settings-Based Content theme={null}
  <!-- Conditional content based on settings -->
  {{#settings.home_elements}}
      {{#is_slider}}
          <div class="home-slider">
              {{#element}}
                  {{#title}}
                      <h2 class="slider-title">{{title}}</h2>
                  {{/title}}
                  
                  {{#image1_link}}
                      <div class="slider-image">
                          <img src="{{#img}}{{image1_link}}_1200x600{{/img}}" alt="{{title}}">
                      </div>
                  {{/image1_link}}
                  
                  {{#page.content}}
                      <div class="slider-content">
                          {{&page.content}}
                      </div>
                  {{/page.content}}
              {{/element}}
          </div>
      {{/is_slider}}
      
      {{#is_title}}
          <div class="home-title-section">
              {{#element}}
                  {{#title}}
                      <h1 class="main-title">{{title}}</h1>
                  {{/title}}
                  
                  {{#page.content}}
                      <div class="title-content">
                          {{&page.content}}
                      </div>
                  {{/page.content}}
              {{/element}}
          </div>
      {{/is_title}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Error Handling and Edge Cases

Handle various error states and edge cases with conditionals:

<CodeGroup>
  ```mustache Robust Error Handling theme={null}
  <!-- Contact form response handling -->
  {{#response_data}}
      {{#success}}
          <div class="success-message">
              <i class="icon-check-circle"></i>
              {{&success_message}}
          </div>
      {{/success}}
      
      {{#errors}}
          <div class="error-messages">
              <i class="icon-alert-circle"></i>
              {{#error_message}}
                  <p class="error-text">{{.}}</p>
              {{/error_message}}
          </div>
      {{/errors}}
  {{/response_data}}

  <!-- Basket state handling -->
  {{#basket.isEmpty}}
      <div class="empty-cart">
          <i class="icon-shopping-cart"></i>
          <p>{{#lang}}Your cart is empty{{/lang}}</p>
          <a href="{{shop.url}}" class="continue-shopping">
              {{#lang}}Start Shopping{{/lang}}
          </a>
      </div>
  {{/basket.isEmpty}}

  {{^basket.isEmpty}}
      <div class="cart-contents">
          <p>{{basket.items_count}} {{#lang}}items in cart{{/lang}}</p>
          <p>{{#lang}}Total{{/lang}}: {{basket.total_amount}}</p>
          <a href="{{paylink}}" class="checkout-btn">
              {{#lang}}Checkout{{/lang}}
          </a>
      </div>
  {{/basket.isEmpty}}
  ```
</CodeGroup>

## Blog and Content Conditionals

Handle blog and content page states:

<CodeGroup>
  ```mustache Blog Content Logic theme={null}
  <!-- Blog page conditionals -->
  {{#is_list}}
      <div class="blog-list">
          <h1>{{blog.title_current}}</h1>
          
          {{#blog.filter_tags}}
              <div class="tag-filters">
                  {{#available_tags}}
                      <a href="{{url}}" class="tag-link">{{title}}</a>
                  {{/available_tags}}
              </div>
          {{/blog.filter_tags}}
          
          {{#posts}}
              <article class="blog-post-preview">
                  {{#hasImage}}
                      <div class="post-image">
                          <img src="{{#img}}{{image}}_400x300{{/img}}" alt="{{title}}">
                      </div>
                  {{/hasImage}}
                  
                  <div class="post-content">
                      <h2><a href="{{url}}">{{title}}</a></h2>
                      <div class="post-meta">
                          <span>{{author}}</span>
                          <span>{{date_pretty}}</span>
                      </div>
                      <div class="post-excerpt">
                          {{&content_short}}
                      </div>
                  </div>
              </article>
          {{/posts}}
      </div>
  {{/is_list}}

  {{#is_post}}
      <article class="blog-post-single">
          <header class="post-header">
              <h1>{{post.title}}</h1>
              <div class="post-meta">
                  <span>{{post.author}}</span>
                  <span>{{post.date_pretty}}</span>
              </div>
          </header>
          
          {{#post.hasImage}}
              <div class="post-featured-image">
                  <img src="{{#img}}{{post.image}}_800x400{{/img}}" alt="{{post.title}}">
              </div>
          {{/post.hasImage}}
          
          <div class="post-content">
              {{&post.content}}
          </div>
      </article>
  {{/is_post}}
  ```
</CodeGroup>

## Order and Thank You Page Conditionals

<CodeGroup>
  ```mustache Order Confirmation Logic theme={null}
  <!-- Order page conditionals -->
  {{#order}}
      <div class="order-confirmation">
          <h1>{{#lang}}Thank you for your order{{/lang}}</h1>
          <p>{{#lang}}Order number{{/lang}}: {{order.id}}</p>
          
          <div class="order-summary">
              <h3>{{#lang}}Order Summary{{/lang}}</h3>
              <div class="order-totals">
                  <div class="total-line">
                      <span>{{#lang}}Subtotal{{/lang}}</span>
                      <span>{{order.value_excl_tax}}</span>
                  </div>
                  
                  {{#order.tax_amount}}
                      <div class="total-line">
                          <span>{{#lang}}Tax{{/lang}}</span>
                          <span>{{order.tax_amount}}</span>
                      </div>
                  {{/order.tax_amount}}
                  
                  {{#order.shipping_amount}}
                      <div class="total-line">
                          <span>{{#lang}}Shipping{{/lang}}</span>
                          <span>{{order.shipping_amount}}</span>
                      </div>
                  {{/order.shipping_amount}}
                  
                  <div class="total-line total">
                      <span>{{#lang}}Total{{/lang}}</span>
                      <span>{{order.value}}</span>
                  </div>
              </div>
          </div>
          
          <div class="order-items">
              {{#order.items}}
                  <div class="order-item">
                      <h4>{{title}}</h4>
                      {{#variant}}
                          <p class="variant">{{variant}}</p>
                      {{/variant}}
                      <p>{{#lang}}Quantity{{/lang}}: {{qty}}</p>
                      <p>{{#lang}}Price{{/lang}}: {{price}}</p>
                  </div>
              {{/order.items}}
          </div>
      </div>
  {{/order}}
  ```
</CodeGroup>

## Best Practices for Complex Conditionals

<CardGroup>
  <Card title="Provide Fallbacks" icon="shield">
    Always consider what happens when conditions are false and provide appropriate content
  </Card>

  <Card title="Test Edge Cases" icon="bug">
    Test your conditionals with different data states, including empty and error conditions
  </Card>

  <Card title="Keep Logic Readable" icon="eye">
    Use clear indentation and comments to make complex conditionals easy to follow
  </Card>
</CardGroup>

## Debugging Complex Conditionals

<CodeGroup>
  ```mustache Debug Conditional Logic theme={null}
  <!-- Debug what conditions are being evaluated -->
  <div class="debug-conditionals" style="display: none;">
      <h4>Conditional Debug Info:</h4>
      <ul>
          <li>User logged in: {{#user.logged_in}}Yes{{/user.logged_in}}{{^user.logged_in}}No{{/user.logged_in}}</li>
          <li>Product sold out: {{#product.soldOut}}Yes{{/product.soldOut}}{{^product.soldOut}}No{{/product.soldOut}}</li>
          <li>Has before price: {{#product.has_before_price}}Yes{{/product.has_before_price}}{{^product.has_before_price}}No{{/product.has_before_price}}</li>
          <li>Has images: {{#product.images}}Yes{{/product.images}}{{^product.images}}No{{/product.images}}</li>
          <li>Basket empty: {{#basket.isEmpty}}Yes{{/basket.isEmpty}}{{^basket.isEmpty}}No{{/basket.isEmpty}}</li>
      </ul>
  </div>
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Wrappers and Functions" icon="function" href="/theme-development/wrappers-and-functions">
    Learn how to combine conditionals with helper functions
  </Card>

  <Card title="Objects and Attributes" icon="database" href="/theme-development/objects-and-attributes">
    Understanding what properties are available for conditional logic
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Explore conditional properties in store and user objects
  </Card>

  <Card title="Advanced Patterns" icon="rocket" href="/theme-development/advanced/dynamic-elements">
    Discover advanced templating techniques and patterns
  </Card>
</CardGroup>


# Basket Object
Source: https://quickbutik.dev/theme-development/global/basket

Access shopping cart data, items, and checkout functionality

The `basket` object contains all information about the customer's shopping cart. It's available globally across all pages, making it perfect for cart widgets, mini-carts, and checkout processes.

<Info>
  **Usage**: Available globally - use anywhere to display cart contents, totals, and checkout links
</Info>

## Basic Cart Information

Access the essential cart data for displaying cart status and totals:

<CodeGroup>
  ```mustache Cart Overview theme={null}
  <!-- Basic cart status -->
  {{^basket.isEmpty}}
      <div class="cart-summary">
          <span class="cart-count">{{basket.items_count}}</span>
          <span class="cart-total">{{basket.total_amount}}</span>
          <a href="{{paylink}}" class="checkout-btn">{{#lang}}Checkout{{/lang}}</a>
      </div>
  {{/basket.isEmpty}}

  {{#basket.isEmpty}}
      <p class="empty-cart">{{#lang}}Your cart is empty{{/lang}}</p>
  {{/basket.isEmpty}}
  ```

  ```mustache Cart Header Widget theme={null}
  <div class="cart-widget">
      <button class="cart-toggle" aria-expanded="false">
          <i class="icon-shopping-cart"></i>
          <span class="cart-label">{{#lang}}Cart{{/lang}}</span>
          {{^basket.isEmpty}}
              <span class="cart-badge">{{basket.items_count}}</span>
          {{/basket.isEmpty}}
      </button>
      
      <div class="cart-dropdown">
          {{#basket.isEmpty}}
              <p class="empty-message">{{#lang}}Your cart is empty{{/lang}}</p>
          {{/basket.isEmpty}}
          
          {{^basket.isEmpty}}
              <div class="cart-items">
                  <!-- Cart items will go here -->
              </div>
              <div class="cart-footer">
                  <div class="cart-total">
                      {{#lang}}Total{{/lang}}: {{basket.total_amount}}
                  </div>
                  <a href="{{paylink}}" class="checkout-btn">
                      {{#lang}}Checkout{{/lang}}
                  </a>
              </div>
          {{/basket.isEmpty}}
      </div>
  </div>
  ```
</CodeGroup>

## Available Properties

| Property              | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| `basket.isEmpty`      | Boolean | Check if cart is empty                 |
| `basket.items_count`  | Number  | Number of items in cart                |
| `basket.total_amount` | String  | Total amount for items in cart         |
| `basket.items`        | Array   | Object containing all products in cart |

## Cart Items

Loop through cart items to display detailed cart contents:

<CodeGroup>
  ```mustache Basic Cart Items theme={null}
  {{#basket.items}}
  <div class="cart-item">
      <div class="item-image">
          {{#item.firstimage}}
              <img src="{{#img}}{{item.firstimage}}_100x100{{/img}}" alt="{{item.title}}">
          {{/item.firstimage}}
      </div>
      
      <div class="item-details">
          <h4 class="item-title">
              <a href="{{item.url}}">{{item.title}}</a>
          </h4>
          
          {{#is_variant}}
              <p class="variant-info">{{variant_name}}</p>
          {{/is_variant}}
          
          <div class="item-pricing">
              <span class="item-price">{{item.price}}</span>
              <span class="item-qty">× {{qty}}</span>
              <span class="item-total">{{amount}}</span>
          </div>
      </div>
  </div>
  {{/basket.items}}
  ```

  ```mustache Detailed Cart Table theme={null}
  <table class="cart-table">
      <thead>
          <tr>
              <th>{{#lang}}Product{{/lang}}</th>
              <th>{{#lang}}Price{{/lang}}</th>
              <th>{{#lang}}Quantity{{/lang}}</th>
              <th>{{#lang}}Total{{/lang}}</th>
          </tr>
      </thead>
      <tbody>
          {{#basket.items}}
          <tr class="cart-row">
              <td class="product-cell">
                  <div class="product-info">
                      {{#item.firstimage}}
                          <img src="{{#img}}{{item.firstimage}}_80x80{{/img}}" 
                               alt="{{item.title}}" 
                               class="product-thumb">
                      {{/item.firstimage}}
                      
                      <div class="product-details">
                          <h4><a href="{{item.url}}">{{item.title}}</a></h4>
                          <p class="product-sku">{{#lang}}SKU{{/lang}}: {{item.sku}}</p>
                          
                          {{#is_variant}}
                              <p class="variant-details">{{variant_name}}</p>
                          {{/is_variant}}
                      </div>
                  </div>
              </td>
              <td class="price-cell">{{item.price}}</td>
              <td class="quantity-cell">{{qty}}</td>
              <td class="total-cell">{{amount}}</td>
          </tr>
          {{/basket.items}}
      </tbody>
      <tfoot>
          <tr class="cart-total-row">
              <td colspan="3">{{#lang}}Total{{/lang}}</td>
              <td class="total-amount">{{basket.total_amount}}</td>
          </tr>
      </tfoot>
  </table>
  ```
</CodeGroup>

### Cart Item Properties

When looping through `basket.items`, each item has these properties:

| Property          | Type    | Description                                  |
| ----------------- | ------- | -------------------------------------------- |
| `item.id`         | String  | Product ID                                   |
| `item.sku`        | String  | Product article number                       |
| `item.url`        | String  | Product link address                         |
| `item.title`      | String  | Product title                                |
| `item.firstimage` | String  | Product image                                |
| `is_variant`      | Boolean | True if it's a product variant               |
| `variant_name`    | String  | Variant designation                          |
| `item.price`      | String  | Product unit price                           |
| `qty`             | Number  | Quantity of product added to cart            |
| `amount`          | String  | Product total amount (unit price x quantity) |

## Checkout Integration

### Paylink Usage

The `paylink` provides the correct checkout URL when the cart is not empty:

<CodeGroup>
  ```mustache Checkout Integration theme={null}
  {{^basket.isEmpty}}
  <div class="checkout-section">
      <div class="checkout-summary">
          <h3>{{#lang}}Ready to checkout?{{/lang}}</h3>
          <p>{{basket.items_count}} {{#lang}}items{{/lang}} • {{basket.total_amount}}</p>
      </div>
      
      <a href="{{paylink}}" class="main-checkout-btn">
          {{#lang}}Secure Checkout{{/lang}}
      </a>
      
      <div class="checkout-security">
          <i class="icon-shield"></i>
          <span>{{#lang}}SSL Secure Checkout{{/lang}}</span>
      </div>
  </div>
  {{/basket.isEmpty}}
  ```
</CodeGroup>

## Mini Cart Examples

### Slide-out Cart

<CodeGroup>
  ```mustache Slide-out Mini Cart theme={null}
  <div class="mini-cart-overlay">
      <div class="mini-cart">
          <div class="mini-cart-header">
              <h3>{{#lang}}Shopping Cart{{/lang}}</h3>
              <button class="close-cart" aria-label="{{#lang}}Close cart{{/lang}}">×</button>
          </div>
          
          <div class="mini-cart-body">
              {{#basket.isEmpty}}
                  <div class="empty-cart-message">
                      <i class="icon-shopping-cart"></i>
                      <p>{{#lang}}Your cart is empty{{/lang}}</p>
                      <a href="/" class="continue-shopping">
                          {{#lang}}Continue Shopping{{/lang}}
                      </a>
                  </div>
              {{/basket.isEmpty}}
              
              {{^basket.isEmpty}}
                  <div class="cart-items-list">
                      {{#basket.items}}
                      <div class="mini-cart-item">
                          <div class="item-image">
                              {{#item.firstimage}}
                                  <img src="{{#img}}{{item.firstimage}}_60x60{{/img}}" alt="{{item.title}}">
                              {{/item.firstimage}}
                          </div>
                          
                          <div class="item-info">
                              <h4><a href="{{item.url}}">{{item.title}}</a></h4>
                              {{#is_variant}}<p class="variant">{{variant_name}}</p>{{/is_variant}}
                              <div class="item-meta">
                                  <span class="quantity">{{qty}}</span>
                                  <span class="price">{{item.price}}</span>
                              </div>
                          </div>
                          
                          <div class="item-total">{{amount}}</div>
                      </div>
                      {{/basket.items}}
                  </div>
              {{/basket.isEmpty}}
          </div>
          
          {{^basket.isEmpty}}
          <div class="mini-cart-footer">
              <div class="cart-summary">
                  <div class="subtotal">
                      <span>{{#lang}}Subtotal{{/lang}} ({{basket.items_count}} {{#lang}}items{{/lang}})</span>
                      <span class="amount">{{basket.total_amount}}</span>
                  </div>
              </div>
              
              <div class="cart-actions">
                  <a href="/cart" class="view-cart-btn">
                      {{#lang}}View Cart{{/lang}}
                  </a>
                  <a href="{{paylink}}" class="checkout-btn">
                      {{#lang}}Checkout{{/lang}}
                  </a>
              </div>
          </div>
          {{/basket.isEmpty}}
      </div>
  </div>
  ```
</CodeGroup>

### Cart Page Template

<CodeGroup>
  ```mustache Full Cart Page theme={null}
  <div class="cart-page">
      <h1>{{#lang}}Shopping Cart{{/lang}}</h1>
      
      {{#basket.isEmpty}}
          <div class="empty-cart">
              <div class="empty-cart-content">
                  <i class="icon-shopping-cart-empty"></i>
                  <h2>{{#lang}}Your cart is empty{{/lang}}</h2>
                  <p>{{#lang}}Looks like you haven't added anything to your cart yet{{/lang}}</p>
                  <a href="/" class="continue-shopping-btn">
                      {{#lang}}Start Shopping{{/lang}}
                  </a>
              </div>
          </div>
      {{/basket.isEmpty}}
      
      {{^basket.isEmpty}}
          <div class="cart-content">
              <div class="cart-items-section">
                  <h2>{{#lang}}Cart Items{{/lang}} ({{basket.items_count}})</h2>
                  
                  <div class="cart-items">
                      {{#basket.items}}
                      <div class="cart-item">
                          <div class="item-image">
                              {{#item.firstimage}}
                                  <img src="{{#img}}{{item.firstimage}}_150x150{{/img}}" alt="{{item.title}}">
                              {{/item.firstimage}}
                          </div>
                          
                          <div class="item-details">
                              <h3><a href="{{item.url}}">{{item.title}}</a></h3>
                              <p class="item-sku">{{#lang}}SKU{{/lang}}: {{item.sku}}</p>
                              
                              {{#is_variant}}
                                  <p class="item-variant">{{variant_name}}</p>
                              {{/is_variant}}
                              
                              <div class="item-price">
                                  <span class="unit-price">{{item.price}}</span>
                                  <span class="quantity-label">× {{qty}}</span>
                              </div>
                          </div>
                          
                          <div class="item-total">
                              <span class="total-price">{{amount}}</span>
                          </div>
                      </div>
                      {{/basket.items}}
                  </div>
              </div>
              
              <div class="cart-summary-section">
                  <div class="cart-totals">
                      <h3>{{#lang}}Order Summary{{/lang}}</h3>
                      
                      <div class="totals-line">
                          <span>{{#lang}}Subtotal{{/lang}} ({{basket.items_count}} {{#lang}}items{{/lang}})</span>
                          <span>{{basket.total_amount}}</span>
                      </div>
                      
                      <div class="totals-line total">
                          <span>{{#lang}}Total{{/lang}}</span>
                          <span>{{basket.total_amount}}</span>
                      </div>
                      
                      <div class="checkout-actions">
                          <a href="{{paylink}}" class="checkout-button">
                              {{#lang}}Proceed to Checkout{{/lang}}
                          </a>
                          <a href="/" class="continue-shopping">
                              {{#lang}}Continue Shopping{{/lang}}
                          </a>
                      </div>
                  </div>
              </div>
          </div>
      {{/basket.isEmpty}}
  </div>
  ```
</CodeGroup>

## Mobile Cart Examples

### Mobile Cart Badge

<CodeGroup>
  ```mustache Mobile Cart Badge theme={null}
  <div class="mobile-cart-badge">
      <a href="/cart" class="cart-link">
          <div class="cart-icon-wrapper">
              <i class="icon-shopping-bag"></i>
              {{^basket.isEmpty}}
                  <span class="cart-count-badge">{{basket.items_count}}</span>
              {{/basket.isEmpty}}
          </div>
          
          <div class="cart-info">
              <span class="cart-label">{{#lang}}Cart{{/lang}}</span>
              {{^basket.isEmpty}}
                  <span class="cart-total">{{basket.total_amount}}</span>
              {{/basket.isEmpty}}
              {{#basket.isEmpty}}
                  <span class="cart-empty">{{#lang}}Empty{{/lang}}</span>
              {{/basket.isEmpty}}
          </div>
      </a>
  </div>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Empty State Handling" icon="circle-xmark">
    Always provide meaningful empty cart states with clear calls-to-action
  </Card>

  <Card title="Performance" icon="gauge">
    Use image optimization with the `{{#img}}` wrapper for cart item thumbnails
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Include proper ARIA labels and semantic HTML for cart interactions
  </Card>

  <Card title="Mobile First" icon="mobile">
    Design cart widgets to work well on all screen sizes
  </Card>
</CardGroup>

## Common Patterns

### Cart Item Counter

<CodeGroup>
  ```mustache Dynamic Cart Counter theme={null}
  <div class="cart-counter">
      {{#basket.isEmpty}}
          <span class="counter-text">{{#lang}}Cart{{/lang}}</span>
      {{/basket.isEmpty}}
      
      {{^basket.isEmpty}}
          <span class="counter-text">
              {{basket.items_count}} 
              {{#lang}}item{{/lang}}{{#basket.items_count}}s{{/basket.items_count}}
          </span>
      {{/basket.isEmpty}}
  </div>
  ```
</CodeGroup>

### Quick Add Success Message

<CodeGroup>
  ```mustache Add to Cart Success theme={null}
  <!-- This would typically be shown after adding an item -->
  {{^basket.isEmpty}}
  <div class="cart-success-message">
      <i class="icon-check-circle"></i>
      <span>{{#lang}}Item added to cart{{/lang}}</span>
      <a href="{{paylink}}" class="quick-checkout">
          {{#lang}}Checkout now{{/lang}}
      </a>
  </div>
  {{/basket.isEmpty}}
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build dynamic navigation menus and breadcrumbs
  </Card>

  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Learn about displaying individual product information
  </Card>

  <Card title="Order Object" icon="receipt" href="/theme-development/pages/order">
    Display order confirmation and thank you page content
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Explore store-wide settings and information
  </Card>
</CardGroup>


# Navigation Object
Source: https://quickbutik.dev/theme-development/global/navigation

Build dynamic navigation menus and breadcrumbs using available link lists

The navigation system in Quickbutik provides link lists and breadcrumbs for creating basic menus and navigation elements. These are essential for building site structure and user experience.

<Info>
  **Usage**: Available globally - create main menus, top menus, footer links, and breadcrumbs
</Info>

## Link Lists (Linklist)

Link lists are customizable navigation menus that you can create and manage in your Control Panel. Three predefined link lists are available: main, top, and footer.

<CodeGroup>
  ```mustache Basic Navigation Menu theme={null}
  <nav class="main-navigation">
      {{#linklist.main}}
          <a href="{{url}}" 
             class="nav-link {{#current}}active{{/current}}">
              {{name}}
          </a>
      {{/linklist.main}}
  </nav>
  ```

  ```mustache Dropdown Navigation theme={null}
  <nav class="navbar">
      <ul class="nav-menu">
          {{#linklist.main}}
          <li class="nav-item {{#current}}current{{/current}}">
              <a href="{{url}}" class="nav-link">
                  {{name}}
                  {{#hasChildren}}<i class="dropdown-arrow"></i>{{/hasChildren}}
              </a>
              
              {{#children}}
              <ul class="dropdown-menu">
                  {{#children}}
                  <li><a href="{{url}}" class="dropdown-link">{{name}}</a></li>
                  {{/children}}
              </ul>
              {{/children}}
          </li>
          {{/linklist.main}}
      </ul>
  </nav>
  ```
</CodeGroup>

## Available Link Lists

| Linklist          | Description                  | Usage                        |
| ----------------- | ---------------------------- | ---------------------------- |
| `linklist.main`   | Contains theme's Main Menu   | Primary navigation           |
| `linklist.top`    | Contains theme's Top Menu    | Utility/secondary navigation |
| `linklist.footer` | Contains theme's Footer Menu | Footer navigation            |

### Linklist Properties

When looping through `linklist.{name}`, each link has these properties:

| Property       | Type    | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| `name`         | String  | Menu item's designation                          |
| `url`          | String  | Menu item's link address                         |
| `current`      | Boolean | True if visitor is on the current menu item      |
| `hasChildren`  | Boolean | Check if menu item has sub-menu items            |
| `hasChildren2` | Boolean | Check if second sub-menu item has sub-menu items |
| `hasChildren3` | Boolean | Check if third sub-menu item has sub-menu items  |
| `hasChildren4` | Boolean | Check if fourth sub-menu item has sub-menu items |
| `children`     | Array   | Object containing sub-menu items                 |

## Multi-Level Navigation

Handle nested menu structures with multiple levels:

<CodeGroup>
  ```mustache Multi-Level Menu theme={null}
  <nav class="multi-level-nav">
      {{#linklist.main}}
      <div class="nav-item {{#current}}active{{/current}}">
          <a href="{{url}}" class="nav-link">{{name}}</a>
          
          {{#hasChildren}}
          <div class="level-1-menu">
              {{#children}}
              <div class="level-1-item">
                  <a href="{{url}}" class="level-1-link">{{name}}</a>
                  
                  {{#hasChildren2}}
                  <div class="level-2-menu">
                      {{#children}}
                      <div class="level-2-item">
                          <a href="{{url}}" class="level-2-link">{{name}}</a>
                          
                          {{#hasChildren3}}
                          <div class="level-3-menu">
                              {{#children}}
                              <a href="{{url}}" class="level-3-link">{{name}}</a>
                              {{/children}}
                          </div>
                          {{/hasChildren3}}
                      </div>
                      {{/children}}
                  </div>
                  {{/hasChildren2}}
              </div>
              {{/children}}
          </div>
          {{/hasChildren}}
      </div>
      {{/linklist.main}}
  </nav>
  ```
</CodeGroup>

## Breadcrumbs

Show the navigation path to help users understand their location:

<CodeGroup>
  ```mustache Basic Breadcrumbs theme={null}
  <nav class="breadcrumbs" aria-label="{{#lang}}Breadcrumb navigation{{/lang}}">
      <ol class="breadcrumb-list">
          {{#breadcrumbs}}
          <li class="breadcrumb-item">
              {{^last}}
                  <a href="{{url}}" class="breadcrumb-link">{{title}}</a>
                  <span class="breadcrumb-separator"> / </span>
              {{/last}}
              {{#last}}
                  <span class="breadcrumb-current" aria-current="page">{{title}}</span>
              {{/last}}
          </li>
          {{/breadcrumbs}}
      </ol>
  </nav>
  ```

  ```mustache Rich Breadcrumbs theme={null}
  <nav class="breadcrumbs-enhanced">
      <div class="breadcrumb-container">
          {{#breadcrumbs}}
              {{^last}}
                  <a href="{{url}}" class="breadcrumb-link">
                      <span class="breadcrumb-text">{{title}}</span>
                  </a>
                  <i class="breadcrumb-separator icon-chevron-right"></i>
              {{/last}}
              
              {{#last}}
                  <span class="breadcrumb-current">
                      <i class="breadcrumb-icon icon-map-marker"></i>
                      <span class="breadcrumb-text">{{title}}</span>
                  </span>
              {{/last}}
          {{/breadcrumbs}}
      </div>
  </nav>
  ```
</CodeGroup>

### Breadcrumb Properties

When using `breadcrumbs`:

| Property | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `title`  | String  | Display text for this breadcrumb      |
| `url`    | String  | Link URL (empty for current page)     |
| `last`   | Boolean | True if this is the current/last item |

## Complete Navigation Examples

### Full Header Navigation

<CodeGroup>
  ```mustache Complete Header theme={null}
  <header class="site-header">
      <!-- Top utility bar -->
      {{#linklist.top}}
      <div class="header-utility">
          <div class="container">
              {{#linklist.top}}
                  <a href="{{url}}" class="utility-link {{#current}}active{{/current}}">{{name}}</a>
              {{/linklist.top}}
          </div>
      </div>
      {{/linklist.top}}
      
      <!-- Main header -->
      <div class="header-main">
          <div class="container">
              <!-- Logo -->
              <div class="header-logo">
                  <a href="{{shop.url}}">
                      <h1>{{shop.name}}</h1>
                  </a>
              </div>
              
              <!-- Main navigation -->
              <nav class="header-nav">
                  {{#linklist.main}}
                  <div class="nav-item {{#current}}active{{/current}}">
                      <a href="{{url}}" class="nav-link">{{name}}</a>
                      
                      {{#children}}
                      <div class="mega-menu">
                          <div class="mega-menu-content">
                              {{#children}}
                              <div class="mega-menu-section">
                                  <a href="{{url}}" class="mega-menu-link">{{name}}</a>
                              </div>
                              {{/children}}
                          </div>
                      </div>
                      {{/children}}
                  </div>
                  {{/linklist.main}}
              </nav>
          </div>
      </div>
  </header>
  ```
</CodeGroup>

### Footer Navigation

<CodeGroup>
  ```mustache Complete Footer theme={null}
  <footer class="site-footer">
      <div class="footer-content">
          <div class="container">
              <div class="footer-sections">
                  <!-- Footer links -->
                  {{#linklist.footer}}
                  <div class="footer-section">
                      <h4>{{#lang}}Links{{/lang}}</h4>
                      <ul class="footer-links">
                          {{#linklist.footer}}
                          <li><a href="{{url}}" class="{{#current}}active{{/current}}">{{name}}</a></li>
                          {{/linklist.footer}}
                      </ul>
                  </div>
                  {{/linklist.footer}}
              </div>
          </div>
      </div>
      
      <!-- Footer bottom -->
      <div class="footer-bottom">
          <div class="container">
              <div class="footer-bottom-content">
                  <p>&copy; {{shop.name}}</p>
              </div>
          </div>
      </div>
  </footer>
  ```
</CodeGroup>

### Mobile Navigation

<CodeGroup>
  ```mustache Mobile Menu theme={null}
  <div class="mobile-navigation">
      <button class="mobile-menu-toggle" aria-expanded="false">
          <span class="hamburger-line"></span>
          <span class="hamburger-line"></span>
          <span class="hamburger-line"></span>
          <span class="sr-only">{{#lang}}Toggle navigation{{/lang}}</span>
      </button>
      
      <div class="mobile-menu-overlay">
          <div class="mobile-menu">
              <div class="mobile-menu-header">
                  <h3>{{#lang}}Menu{{/lang}}</h3>
                  <button class="mobile-menu-close" aria-label="{{#lang}}Close menu{{/lang}}">×</button>
              </div>
              
              <nav class="mobile-menu-nav">
                  <!-- Main navigation -->
                  <div class="mobile-nav-section">
                      {{#linklist.main}}
                      <div class="mobile-nav-item">
                          <a href="{{url}}" class="mobile-nav-link {{#current}}active{{/current}}">
                              {{name}}
                              {{#children}}<i class="expand-icon"></i>{{/children}}
                          </a>
                          
                          {{#children}}
                          <div class="mobile-submenu">
                              {{#children}}
                              <a href="{{url}}" class="mobile-submenu-link">{{name}}</a>
                              {{/children}}
                          </div>
                          {{/children}}
                      </div>
                      {{/linklist.main}}
                  </div>
                  
                  <!-- Top menu items -->
                  {{#linklist.top}}
                  <div class="mobile-nav-section">
                      <h4 class="mobile-nav-heading">{{#lang}}Quick Links{{/lang}}</h4>
                      {{#linklist.top}}
                      <a href="{{url}}" class="mobile-utility-link {{#current}}active{{/current}}">
                          {{name}}
                      </a>
                      {{/linklist.top}}
                  </div>
                  {{/linklist.top}}
              </nav>
          </div>
      </div>
  </div>
  ```
</CodeGroup>

## Conditional Navigation

Use global conditionals to show context-specific navigation:

<CodeGroup>
  ```mustache Context-Aware Navigation theme={null}
  <nav class="context-navigation">
      {{#isProduct}}
          <!-- Product page navigation -->
          <div class="product-nav">
              {{#breadcrumbs}}
                  <a href="{{url}}" class="back-link">
                      <i class="icon-arrow-left"></i>
                      {{#lang}}Back to{{/lang}} {{title}}
                  </a>
              {{/breadcrumbs}}
          </div>
      {{/isProduct}}
      
      {{#isCategory}}
          <!-- Category page navigation -->
          <div class="category-nav">
              {{#breadcrumbs}}
                  {{^last}}
                      <a href="{{url}}" class="category-parent">{{title}}</a>
                  {{/last}}
              {{/breadcrumbs}}
          </div>
      {{/isCategory}}
      
      <!-- Always show main navigation -->
      <div class="main-nav">
          {{#linklist.main}}
              <a href="{{url}}" class="nav-item {{#current}}current{{/current}}">{{name}}</a>
          {{/linklist.main}}
      </div>
  </nav>
  ```
</CodeGroup>

## Usage Notes

<Warning>
  **Limited Navigation Objects**: Only three predefined link lists are available (main, top, footer) and basic breadcrumbs. Category navigation, custom link lists, and external link properties are not supported.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Accessibility" icon="universal-access">
    Use proper ARIA labels, semantic HTML, and keyboard navigation support
  </Card>

  <Card title="Current State" icon="location-dot">
    Always highlight the current page/section using the current property
  </Card>

  <Card title="Mobile First" icon="mobile">
    Design navigation that works well on small screens first
  </Card>

  <Card title="Nested Levels" icon="sitemap">
    Use hasChildren properties to check for sub-menus before rendering
  </Card>
</CardGroup>

## Complete Navigation Template

<CodeGroup>
  ```mustache Full Navigation System theme={null}
  <!DOCTYPE html>
  <html>
  <head>
      <title>{{seo.title}}</title>
  </head>
  <body>
      <!-- Header with navigation -->
      <header class="site-header">
          {{#linklist.top}}
          <div class="top-bar">
              {{#linklist.top}}
                  <a href="{{url}}" class="top-link {{#current}}active{{/current}}">{{name}}</a>
              {{/linklist.top}}
          </div>
          {{/linklist.top}}
          
          <div class="main-header">
              <a href="{{shop.url}}" class="logo">{{shop.name}}</a>
              
              <nav class="main-nav">
                  {{#linklist.main}}
                      <a href="{{url}}" class="nav-link {{#current}}active{{/current}}">
                          {{name}}
                      </a>
                  {{/linklist.main}}
              </nav>
          </div>
      </header>
      
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              {{^last}}<a href="{{url}}">{{title}}</a> > {{/last}}
              {{#last}}<span>{{title}}</span>{{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <!-- Main content -->
      <main class="main-content">
          <!-- Page content here -->
      </main>
      
      <!-- Footer -->
      <footer class="site-footer">
          {{#linklist.footer}}
          <nav class="footer-nav">
              {{#linklist.footer}}
                  <a href="{{url}}" class="footer-link">{{name}}</a>
              {{/linklist.footer}}
          </nav>
          {{/linklist.footer}}
          
          <p>&copy; {{shop.name}}</p>
      </footer>
  </body>
  </html>
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Learn about SEO meta tags and structured data
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Explore store-wide settings and information
  </Card>

  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Display individual product information
  </Card>

  <Card title="Category Object" icon="folder" href="/theme-development/pages/category">
    Build basic category pages
  </Card>
</CardGroup>


# SEO Object
Source: https://quickbutik.dev/theme-development/global/seo

Access basic SEO meta tags for search engine optimization

The `seo` object provides basic data needed for search engine optimization. It automatically generates appropriate titles and descriptions based on the current page content.

<Info>
  **Usage**: Available globally - use in your `<head>` section to output basic SEO meta tags for each page
</Info>

## Basic SEO Meta Tags

The essential SEO elements that are available for each page's `<head>` section:

<CodeGroup>
  ```mustache Basic SEO Tags theme={null}
  <head>
      <!-- Page title -->
      <title>{{seo.title}}</title>
      
      <!-- Meta description -->
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
  </head>
  ```

  ```mustache Complete Basic SEO Head theme={null}
  <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      
      <!-- Core SEO -->
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Basic favicon -->
      <link rel="icon" type="image/x-icon" href="/favicon.ico">
  </head>
  ```
</CodeGroup>

## Available Properties

| Property          | Type   | Description                         |
| ----------------- | ------ | ----------------------------------- |
| `seo.title`       | String | Search title for current page       |
| `seo.description` | String | Search description for current page |

## Page-Specific SEO

Different page types automatically generate appropriate SEO data using the available properties:

### Product Pages

<CodeGroup>
  ```mustache Product SEO theme={null}
  <head>
      <!-- Product-specific title and description -->
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Basic product meta using available product properties -->
      {{#product.price}}
          <meta name="product-price" content="{{product.price}}">
      {{/product.price}}
      {{#product.currency}}
          <meta name="product-currency" content="{{product.currency}}">
      {{/product.currency}}
  </head>
  ```
</CodeGroup>

### Category Pages

<CodeGroup>
  ```mustache Category SEO theme={null}
  <head>
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Category-specific meta -->
      {{#category.name}}
          <meta name="category" content="{{category.name}}">
      {{/category.name}}
  </head>
  ```
</CodeGroup>

### Blog Pages

<CodeGroup>
  ```mustache Blog SEO theme={null}
  <head>
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Blog-specific meta -->
      {{#blog.title_current}}
          <meta name="blog-title" content="{{blog.title_current}}">
      {{/blog.title_current}}
  </head>
  ```
</CodeGroup>

## Structured Data (JSON-LD)

Add basic structured data using available shop information:

<CodeGroup>
  ```mustache Organization Schema theme={null}
  <script type="application/ld+json">
  {
      "@context": "https://schema.org",
      "@type": "Organization",
      "name": "{{shop.name}}",
      "url": "{{shop.url}}"
      {{#shop.address}},
      "address": {
          "@type": "PostalAddress",
          "streetAddress": "{{shop.address}}",
          "addressLocality": "{{shop.city}}",
          "postalCode": "{{shop.zipcode}}"
      }{{/shop.address}}
      {{#shop.phone}},"telephone": "{{shop.phone}}"{{/shop.phone}}
  }
  </script>
  ```

  ```mustache Product Schema theme={null}
  {{#isProduct}}
  <script type="application/ld+json">
  {
      "@context": "https://schema.org/",
      "@type": "Product",
      "name": "{{product.title}}",
      "description": "{{product.description}}",
      {{#product.firstimage}}"image": "{{product.firstimage}}",{{/product.firstimage}}
      "offers": {
          "@type": "Offer",
          "price": "{{product.price_raw}}",
          "priceCurrency": "{{product.currency}}",
          "availability": "{{#product.soldOut}}https://schema.org/OutOfStock{{/product.soldOut}}{{^product.soldOut}}https://schema.org/InStock{{/product.soldOut}}"
      }
  }
  </script>
  {{/isProduct}}
  ```
</CodeGroup>

## Breadcrumb Schema

Add breadcrumb structured data using the available breadcrumbs wrapper:

<CodeGroup>
  ```mustache Breadcrumb Schema theme={null}
  <script type="application/ld+json">
  {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": [
          {{#breadcrumbs}}
          {
              "@type": "ListItem",
              "position": {{@index}},
              "name": "{{title}}",
              "item": "{{url}}"
          }{{^last}},{{/last}}
          {{/breadcrumbs}}
      ]
  }
  </script>
  ```
</CodeGroup>

## Multi-Language Support

If your store supports multiple languages, add language links:

<CodeGroup>
  ```mustache Language Links theme={null}
  <head>
      <!-- Current page in different languages -->
      {{#shop.languages}}
      <link rel="alternate" hreflang="{{id}}" href="{{url}}">
      {{/shop.languages}}
  </head>
  ```
</CodeGroup>

## Complete SEO Template

<CodeGroup>
  ```mustache Complete SEO Head Section theme={null}
  <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <meta http-equiv="X-UA-Compatible" content="IE=edge">
      
      <!-- Primary SEO -->
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Multi-language support -->
      {{#shop.languages}}
      <link rel="alternate" hreflang="{{id}}" href="{{url}}">
      {{/shop.languages}}
      
      <!-- Favicon -->
      <link rel="icon" type="image/x-icon" href="/favicon.ico">
      <link rel="apple-touch-icon" href="/apple-touch-icon.png">
      
      <!-- Basic organization structured data -->
      <script type="application/ld+json">
      {
          "@context": "https://schema.org",
          "@type": "Organization",
          "name": "{{shop.name}}",
          "url": "{{shop.url}}"
          {{#shop.address}},
          "address": {
              "@type": "PostalAddress",
              "streetAddress": "{{shop.address}}",
              "addressLocality": "{{shop.city}}",
              "postalCode": "{{shop.zipcode}}"
          }{{/shop.address}}
          {{#shop.phone}},"telephone": "{{shop.phone}}"{{/shop.phone}}
      }
      </script>
  </head>
  ```
</CodeGroup>

## Page Context Examples

Use global conditionals to add context-specific SEO:

<CodeGroup>
  ```mustache Context-Specific SEO theme={null}
  <head>
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      {{#isProduct}}
          <!-- Product page specific -->
          <meta name="page-type" content="product">
          {{#product.gtin}}
              <meta name="product-gtin" content="{{product.gtin}}">
          {{/product.gtin}}
      {{/isProduct}}
      
      {{#isCategory}}
          <!-- Category page specific -->
          <meta name="page-type" content="category">
      {{/isCategory}}
      
      {{#isStart}}
          <!-- Homepage specific -->
          <meta name="page-type" content="homepage">
      {{/isStart}}
      
      {{#isPage}}
          <!-- Static page specific -->
          <meta name="page-type" content="page">
      {{/isPage}}
  </head>
  ```
</CodeGroup>

## Usage Notes

<Warning>
  **Limited SEO Object**: The SEO object only provides basic title and description properties. Advanced SEO features like Open Graph tags, Twitter Cards, canonical URLs, robots meta tags, and analytics integration are not available through the SEO object.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Title Length" icon="ruler">
    Keep page titles under 60 characters for optimal display in search results
  </Card>

  <Card title="Description Length" icon="text-size">
    Meta descriptions should be 150-160 characters for best truncation
  </Card>

  <Card title="Unique Content" icon="fingerprint">
    The system automatically generates unique titles and descriptions for each page
  </Card>

  <Card title="Structured Data" icon="code">
    Use available shop and product properties to create basic structured data
  </Card>
</CardGroup>

## Manual SEO Enhancement

For additional SEO features, you can manually add them using available properties:

<CodeGroup>
  ```mustache Manual SEO Enhancements theme={null}
  <head>
      <!-- Basic SEO from system -->
      <title>{{seo.title}}</title>
      {{#seo.description}}
          <meta name="description" content="{{seo.description}}">
      {{/seo.description}}
      
      <!-- Manual canonical URL -->
      <link rel="canonical" href="{{url_current}}">
      
      <!-- Manual Open Graph using available properties -->
      <meta property="og:title" content="{{seo.title}}">
      {{#seo.description}}
          <meta property="og:description" content="{{seo.description}}">
      {{/seo.description}}
      <meta property="og:url" content="{{url_current}}">
      <meta property="og:site_name" content="{{shop.name}}">
      
      {{#isProduct}}
          <meta property="og:type" content="product">
          {{#product.firstimage}}
              <meta property="og:image" content="{{product.firstimage}}">
          {{/product.firstimage}}
      {{/isProduct}}
      
      {{^isProduct}}
          <meta property="og:type" content="website">
      {{/isProduct}}
  </head>
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Learn about displaying individual product information with SEO optimization
  </Card>

  <Card title="Category Object" icon="folder" href="/theme-development/pages/category">
    Build SEO-optimized category pages
  </Card>

  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Create SEO-friendly navigation and breadcrumbs
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Learn about store-wide settings and global information
  </Card>
</CardGroup>


# Settings Object
Source: https://quickbutik.dev/theme-development/global/settings

Access theme-specific customizable settings and configuration

The `settings` object contains theme-specific configuration options that you can customize through your Control Panel. Currently, the primary use of settings is for configurable home page elements.

<Info>
  **Usage**: Available globally - use to access theme customization settings configured in the Control Panel

  **Theme Dependency**: The `settings` object is fully dependent on the theme settings available for your specific theme. Different themes may have different settings configurations.
</Info>

## Theme Dependency

<Warning>
  **Important**: The `settings` object and its available properties are entirely dependent on your theme's configuration. The settings shown in this documentation represent the standard Quickbutik theme settings structure. Your specific theme may have different settings available, or may not use the settings object at all.

  Always check your theme's documentation or Control Panel to see what settings are actually available for your theme.
</Warning>

## Home Page Elements

The `settings.home_elements` object allows you to create dynamic, customizable content sections for your homepage that can be managed through the admin interface:

<CodeGroup>
  ```mustache Home Page Elements Loop theme={null}
  {{#settings.home_elements}}
      {{#is_slider}}
      <div class="home-slider">
          {{#element}}
          <div class="slider-item">
              {{#title}}
                  <h2 class="slider-title">{{title}}</h2>
              {{/title}}
              
              {{#image1_link}}
                  <div class="slider-image">
                      <img src="{{#img}}{{image1_link}}_1200x600{{/img}}" alt="{{title}}">
                  </div>
              {{/image1_link}}
              
              {{#use_image2}}
                  {{#image2_link}}
                      <div class="slider-image-secondary">
                          <img src="{{#img}}{{image2_link}}_600x400{{/img}}" alt="{{title}}">
                      </div>
                  {{/image2_link}}
              {{/use_image2}}
              
              {{#page.content}}
                  <div class="slider-content">
                      {{&page.content}}
                  </div>
              {{/page.content}}
          </div>
          {{/element}}
      </div>
      {{/is_slider}}
      
      {{#is_title}}
      <div class="home-title-section">
          {{#element}}
              {{#title}}
                  <h1 class="main-title">{{title}}</h1>
              {{/title}}
              
              {{#page.content}}
                  <div class="title-content">
                      {{&page.content}}
                  </div>
              {{/page.content}}
          {{/element}}
      </div>
      {{/is_title}}
      
      {{#is_title_2}}
      <div class="home-subtitle-section">
          {{#element}}
              {{#title}}
                  <h2 class="subtitle">{{title}}</h2>
              {{/title}}
              
              {{#page.content}}
                  <div class="subtitle-content">
                      {{&page.content}}
                  </div>
              {{/page.content}}
          {{/element}}
      </div>
      {{/is_title_2}}
      
      {{#is_page}}
      <div class="home-page-section">
          {{#element}}
              {{#title}}
                  <h3 class="page-section-title">{{title}}</h3>
              {{/title}}
              
              {{#image1_link}}
                  <div class="page-section-image">
                      <img src="{{#img}}{{image1_link}}_800x400{{/img}}" alt="{{title}}">
                  </div>
              {{/image1_link}}
              
              {{#page.content}}
                  <div class="page-section-content">
                      {{&page.content}}
                  </div>
              {{/page.content}}
          {{/element}}
      </div>
      {{/is_page}}
  {{/settings.home_elements}}
  ```

  ```mustache Flexible Home Elements theme={null}
  {{#settings.home_elements}}
  <section class="home-element" data-type="{{#is_slider}}slider{{/is_slider}}{{#is_title}}title{{/is_title}}{{#is_title_2}}subtitle{{/is_title_2}}{{#is_page}}page{{/is_page}}">
      <div class="container">
          {{#element}}
          <div class="element-content">
              {{#title}}
                  <header class="element-header">
                      {{#is_title}}<h1>{{title}}</h1>{{/is_title}}
                      {{#is_title_2}}<h2>{{title}}</h2>{{/is_title_2}}
                      {{#is_slider}}<h2>{{title}}</h2>{{/is_slider}}
                      {{#is_page}}<h3>{{title}}</h3>{{/is_page}}
                  </header>
              {{/title}}
              
              <div class="element-media">
                  {{#image1_link}}
                      <div class="primary-image">
                          <img src="{{#img}}{{image1_link}}_1200x600{{/img}}" 
                               alt="{{title}}"
                               loading="lazy">
                      </div>
                  {{/image1_link}}
                  
                  {{#use_image2}}
                      {{#image2_link}}
                          <div class="secondary-image">
                              <img src="{{#img}}{{image2_link}}_600x400{{/img}}" 
                                   alt="{{title}}"
                                   loading="lazy">
                          </div>
                      {{/image2_link}}
                  {{/use_image2}}
              </div>
              
              {{#page.content}}
                  <div class="element-text">
                      {{&page.content}}
                  </div>
              {{/page.content}}
          </div>
          {{/element}}
      </div>
  </section>
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Available Properties

### Home Elements Structure

| Property                 | Type  | Description                                 |
| ------------------------ | ----- | ------------------------------------------- |
| `settings.home_elements` | Array | Dynamic elements for homepage customization |

### Element Type Conditionals

Within the `settings.home_elements` loop:

| Property     | Type    | Description                            |
| ------------ | ------- | -------------------------------------- |
| `is_slider`  | Boolean | Check if element/section is a slider   |
| `is_title`   | Boolean | Check if element/section is a title    |
| `is_title_2` | Boolean | Check if element/section is a subtitle |
| `is_page`    | Boolean | Check if element/section is a page     |

### Element Properties

Within `settings.home_elements.element`:

| Property       | Type    | Description                   |
| -------------- | ------- | ----------------------------- |
| `title`        | String  | Element title                 |
| `image1_link`  | String  | Image 1 link content          |
| `use_image2`   | Boolean | Should image 2 be used        |
| `image2_link`  | String  | Image 2 link content          |
| `page.content` | String  | Page content for page element |

## Element Type Examples

### Slider Elements

<CodeGroup>
  ```mustache Slider Implementation theme={null}
  {{#settings.home_elements}}
      {{#is_slider}}
      <div class="hero-slider">
          <div class="slider-container">
              {{#element}}
              <div class="slide">
                  <div class="slide-background">
                      {{#image1_link}}
                          <img src="{{#img}}{{image1_link}}_1920x800{{/img}}" alt="{{title}}">
                      {{/image1_link}}
                  </div>
                  
                  <div class="slide-content">
                      {{#title}}
                          <h1 class="slide-title">{{title}}</h1>
                      {{/title}}
                      
                      {{#page.content}}
                          <div class="slide-description">
                              {{&page.content}}
                          </div>
                      {{/page.content}}
                      
                      {{#use_image2}}
                          {{#image2_link}}
                              <div class="slide-secondary-image">
                                  <img src="{{#img}}{{image2_link}}_400x300{{/img}}" alt="{{title}}">
                              </div>
                          {{/image2_link}}
                      {{/use_image2}}
                  </div>
              </div>
              {{/element}}
          </div>
      </div>
      {{/is_slider}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

### Title Elements

<CodeGroup>
  ```mustache Title Sections theme={null}
  {{#settings.home_elements}}
      {{#is_title}}
      <section class="hero-title">
          <div class="container">
              {{#element}}
                  {{#title}}
                      <h1 class="hero-heading">{{title}}</h1>
                  {{/title}}
                  
                  {{#page.content}}
                      <div class="hero-content">
                          {{&page.content}}
                      </div>
                  {{/page.content}}
                  
                  {{#image1_link}}
                      <div class="hero-image">
                          <img src="{{#img}}{{image1_link}}_1200x600{{/img}}" alt="{{title}}">
                      </div>
                  {{/image1_link}}
              {{/element}}
          </div>
      </section>
      {{/is_title}}
      
      {{#is_title_2}}
      <section class="section-subtitle">
          <div class="container">
              {{#element}}
                  {{#title}}
                      <h2 class="section-heading">{{title}}</h2>
                  {{/title}}
                  
                  {{#page.content}}
                      <div class="section-content">
                          {{&page.content}}
                      </div>
                  {{/page.content}}
              {{/element}}
          </div>
      </section>
      {{/is_title_2}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

### Page Elements

<CodeGroup>
  ```mustache Page Content Sections theme={null}
  {{#settings.home_elements}}
      {{#is_page}}
      <section class="content-section">
          <div class="container">
              {{#element}}
              <div class="content-block">
                  {{#title}}
                      <header class="content-header">
                          <h3>{{title}}</h3>
                      </header>
                  {{/title}}
                  
                  <div class="content-body">
                      {{#image1_link}}
                          <div class="content-image">
                              <img src="{{#img}}{{image1_link}}_800x500{{/img}}" alt="{{title}}">
                          </div>
                      {{/image1_link}}
                      
                      {{#page.content}}
                          <div class="content-text">
                              {{&page.content}}
                          </div>
                      {{/page.content}}
                      
                      {{#use_image2}}
                          {{#image2_link}}
                              <div class="content-secondary-image">
                                  <img src="{{#img}}{{image2_link}}_400x300{{/img}}" alt="{{title}}">
                              </div>
                          {{/image2_link}}
                      {{/use_image2}}
                  </div>
              </div>
              {{/element}}
          </div>
      </section>
      {{/is_page}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Complete Homepage Example

<CodeGroup>
  ```mustache Full Homepage Implementation theme={null}
  <!DOCTYPE html>
  <html>
  <head>
      <title>{{seo.title}}</title>
      <meta name="description" content="{{seo.description}}">
  </head>
  <body>
      <header class="site-header">
          <!-- Navigation and header content -->
      </header>
      
      <main class="homepage">
          {{#settings.home_elements}}
          <section class="home-section home-section--{{#is_slider}}slider{{/is_slider}}{{#is_title}}title{{/is_title}}{{#is_title_2}}subtitle{{/is_title_2}}{{#is_page}}page{{/is_page}}">
              
              {{#is_slider}}
              <div class="slider-wrapper">
                  {{#element}}
                  <div class="slider-slide">
                      {{#image1_link}}
                          <div class="slide-bg" style="background-image: url('{{#img}}{{image1_link}}_1920x800{{/img}}');">
                      {{/image1_link}}
                      {{^image1_link}}
                          <div class="slide-bg">
                      {{/image1_link}}
                          <div class="slide-overlay">
                              <div class="container">
                                  {{#title}}
                                      <h1 class="slide-title">{{title}}</h1>
                                  {{/title}}
                                  
                                  {{#page.content}}
                                      <div class="slide-content">
                                          {{&page.content}}
                                      </div>
                                  {{/page.content}}
                                  
                                  {{#use_image2}}
                                      {{#image2_link}}
                                          <div class="slide-feature-image">
                                              <img src="{{#img}}{{image2_link}}_500x400{{/img}}" alt="{{title}}">
                                          </div>
                                      {{/image2_link}}
                                  {{/use_image2}}
                              </div>
                          </div>
                      </div>
                  </div>
                  {{/element}}
              </div>
              {{/is_slider}}
              
              {{#is_title}}
              <div class="title-section">
                  <div class="container">
                      {{#element}}
                          {{#title}}
                              <h1 class="page-title">{{title}}</h1>
                          {{/title}}
                          
                          {{#page.content}}
                              <div class="title-description">
                                  {{&page.content}}
                              </div>
                          {{/page.content}}
                          
                          {{#image1_link}}
                              <div class="title-image">
                                  <img src="{{#img}}{{image1_link}}_1200x600{{/img}}" alt="{{title}}">
                              </div>
                          {{/image1_link}}
                      {{/element}}
                  </div>
              </div>
              {{/is_title}}
              
              {{#is_title_2}}
              <div class="subtitle-section">
                  <div class="container">
                      {{#element}}
                          {{#title}}
                              <h2 class="section-subtitle">{{title}}</h2>
                          {{/title}}
                          
                          {{#page.content}}
                              <div class="subtitle-description">
                                  {{&page.content}}
                              </div>
                          {{/page.content}}
                      {{/element}}
                  </div>
              </div>
              {{/is_title_2}}
              
              {{#is_page}}
              <div class="page-section">
                  <div class="container">
                      {{#element}}
                      <div class="page-content-block">
                          {{#title}}
                              <h3 class="block-title">{{title}}</h3>
                          {{/title}}
                          
                          <div class="block-layout">
                              {{#image1_link}}
                                  <div class="block-image">
                                      <img src="{{#img}}{{image1_link}}_800x500{{/img}}" alt="{{title}}">
                                  </div>
                              {{/image1_link}}
                              
                              <div class="block-content">
                                  {{#page.content}}
                                      {{&page.content}}
                                  {{/page.content}}
                                  
                                  {{#use_image2}}
                                      {{#image2_link}}
                                          <div class="block-secondary-image">
                                              <img src="{{#img}}{{image2_link}}_400x300{{/img}}" alt="{{title}}">
                                          </div>
                                      {{/image2_link}}
                                  {{/use_image2}}
                              </div>
                          </div>
                      </div>
                      {{/element}}
                  </div>
              </div>
              {{/is_page}}
              
          </section>
          {{/settings.home_elements}}
      </main>
      
      <footer class="site-footer">
          <!-- Footer content -->
      </footer>
  </body>
  </html>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Content Management" icon="edit">
    Use home elements to give store owners flexible content control without code changes
  </Card>

  <Card title="Image Optimization" icon="image">
    Always use the `{{#img}}` wrapper with appropriate dimensions for different element types
  </Card>

  <Card title="Responsive Design" icon="mobile">
    Design elements to work well across all device sizes
  </Card>

  <Card title="Performance" icon="gauge">
    Use lazy loading for images and optimize element rendering
  </Card>
</CardGroup>

## Common Implementation Patterns

### Conditional Element Display

<CodeGroup>
  ```mustache Element Type Detection theme={null}
  {{#settings.home_elements}}
  <div class="home-element" 
       data-slider="{{#is_slider}}true{{/is_slider}}"
       data-title="{{#is_title}}true{{/is_title}}"
       data-subtitle="{{#is_title_2}}true{{/is_title_2}}"
       data-page="{{#is_page}}true{{/is_page}}">
      
      {{#element}}
      <!-- Element content based on type -->
      {{/element}}
  </div>
  {{/settings.home_elements}}
  ```
</CodeGroup>

### Image Fallbacks

<CodeGroup>
  ```mustache Image with Fallbacks theme={null}
  {{#element}}
      {{#image1_link}}
          <img src="{{#img}}{{image1_link}}_800x400{{/img}}" alt="{{title}}">
      {{/image1_link}}
      
      {{^image1_link}}
          <div class="placeholder-image">
              <i class="icon-image"></i>
              <span>{{#lang}}No image available{{/lang}}</span>
          </div>
      {{/image1_link}}
  {{/element}}
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Learn about SEO meta tags and structured data
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Explore store-wide settings and information
  </Card>

  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build dynamic navigation menus and breadcrumbs
  </Card>

  <Card title="Best Practices" icon="star" href="/theme-development/advanced/best-practices">
    Learn about theme development best practices
  </Card>
</CardGroup>


# Shop Object
Source: https://quickbutik.dev/theme-development/global/shop

Access store settings, configuration, and global information

The `shop` object contains your store's fundamental settings and configuration. It's available globally across all pages and templates, making it perfect for headers, footers, and any store-wide functionality.

<Info>
  **Usage**: Available globally - use anywhere in your templates to access store information
</Info>

## Basic Store Information

Access your store's core details that you've configured in the Control Panel:

<CodeGroup>
  ```mustache Store Basics theme={null}
  <!-- Store name and URL -->
  <header>
      <h1><a href="{{shop.url}}">{{shop.name}}</a></h1>
  </header>

  <!-- Contact information -->
  <footer>
      <div class="contact-info">
          <h3>Contact Us</h3>
          <p>{{shop.address}}</p>
          <p>{{shop.zipcode}} {{shop.city}}</p>
          <p>Phone: {{shop.phone}}</p>
      </div>
  </footer>

  <!-- Contact page content -->
  <div class="contact-content">
      {{&shop.contact_text}}
  </div>
  ```
</CodeGroup>

### Available Properties

| Property            | Description          | Example                 |
| ------------------- | -------------------- | ----------------------- |
| `shop.name`         | Your store's name    | `"My Awesome Store"`    |
| `shop.url`          | Your store's URL     | `"https://mystore.com"` |
| `shop.address`      | Street address       | `"123 Main Street"`     |
| `shop.zipcode`      | Postal code          | `"12345"`               |
| `shop.city`         | City name            | `"Stockholm"`           |
| `shop.phone`        | Phone number         | `"+46 123 456 789"`     |
| `shop.contact_text` | Contact page content | HTML content            |

## Currency Conversion

If you have multiple currencies enabled, display a currency picker:

<CodeGroup>
  ```mustache Currency Picker theme={null}
  {{#shop.cconverter_active}}
  <form method="get" action="{{url_current}}" class="currency-selector">
      <label for="currency">{{#lang}}Currency{{/lang}}:</label>
      <select name="currency" id="currency" onchange="this.form.submit()">
          {{#shop.cconverter_currencies}}
          <option value="{{currency}}" {{#current}}selected{{/current}}>
              {{currency}}
          </option>
          {{/shop.cconverter_currencies}}
      </select>
  </form>
  {{/shop.cconverter_active}}
  ```

  ```mustache Advanced Currency Picker theme={null}
  {{#shop.cconverter_active}}
  <div class="currency-dropdown">
      <button class="currency-toggle">
          {{#shop.cconverter_currencies}}
              {{#current}}{{currency}}{{/current}}
          {{/shop.cconverter_currencies}}
          <span class="arrow">▼</span>
      </button>
      
      <div class="currency-options">
          {{#shop.cconverter_currencies}}
          <a href="{{url_current}}?currency={{currency}}" 
             class="currency-option {{#current}}active{{/current}}">
              {{currency}}
          </a>
          {{/shop.cconverter_currencies}}
      </div>
  </div>
  {{/shop.cconverter_active}}
  ```
</CodeGroup>

### Currency Object Properties

When looping through `shop.cconverter_currencies`:

| Property   | Description                                               |
| ---------- | --------------------------------------------------------- |
| `currency` | Currency code (e.g., "SEK", "EUR", "USD")                 |
| `current`  | Boolean - true if this is the currently selected currency |

## Multi-Language Support

Display language options when multiple languages are configured:

<CodeGroup>
  ```mustache Language Selector theme={null}
  {{#shop.app.languages}}
  <div class="language-selector">
      <h4>{{#lang}}Choose Language{{/lang}}</h4>
      {{#shop.languages}}
      <a href="{{url}}" class="language-option">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" 
               alt="{{id}}" 
               class="flag">
          {{id}}
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```

  ```mustache Compact Language Switcher theme={null}
  {{#shop.app.languages}}
  <div class="lang-switcher">
      {{#shop.languages}}
      <a href="{{url}}" class="lang-link" title="{{id}}">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```
</CodeGroup>

### Language Object Properties

When looping through `shop.languages`:

| Property      | Description                                  |
| ------------- | -------------------------------------------- |
| `id`          | Language identifier (e.g., "en", "sv", "no") |
| `url`         | URL to switch to this language               |
| `asset_flags` | Helper to get flag image for this language   |

## Tax Toggle

If tax toggling is enabled, allow customers to switch between prices including/excluding tax:

<CodeGroup>
  ```mustache Tax Toggle theme={null}
  {{#shop.taxtoggle_active}}
  <div class="tax-toggle">
      {{#shop.exclude_tax}}
      <a href="{{shop.incl_tax_url}}" 
         class="tax-link"
         title="{{#lang}}Prices are excluding tax. Click to toggle{{/lang}}">
          {{#lang}}Tax Excl.{{/lang}}
      </a>
      {{/shop.exclude_tax}}
      
      {{^shop.exclude_tax}}
      <a href="{{shop.excl_tax_url}}" 
         class="tax-link"
         title="{{#lang}}Prices are including tax. Click to toggle{{/lang}}">
          {{#lang}}Tax Incl.{{/lang}}
      </a>
      {{/shop.exclude_tax}}
  </div>
  {{/shop.taxtoggle_active}}
  ```

  ```mustache Tax Status Display theme={null}
  <div class="price-info">
      {{#shop.exclude_tax}}
          <small>{{#lang}}Prices excluding tax{{/lang}}</small>
      {{/shop.exclude_tax}}
      {{^shop.exclude_tax}}
          <small>{{#lang}}Prices including tax{{/lang}}</small>
      {{/shop.exclude_tax}}
  </div>
  ```
</CodeGroup>

### Tax-Related Properties

| Property                | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `shop.taxtoggle_active` | Boolean - true if tax toggle is enabled                  |
| `shop.exclude_tax`      | Boolean - true if currently showing prices excluding tax |
| `shop.incl_tax_url`     | URL to switch to prices including tax                    |
| `shop.excl_tax_url`     | URL to switch to prices excluding tax                    |

## Customer Login Integration

Display login/account links when customer accounts are enabled:

<CodeGroup>
  ```mustache Login/Account Links theme={null}
  {{#shop.login_active}}
  <div class="account-links">
      {{#user.logged_in}}
      <a href="{{user.login_url}}" class="account-link">
          <i class="icon-user"></i>
          {{#lang}}My Account{{/lang}}
      </a>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
      <a href="{{user.login_url}}" class="login-link">
          <i class="icon-login"></i>
          {{#lang}}Log In{{/lang}}
      </a>
      {{/user.logged_in}}
  </div>
  {{/shop.login_active}}
  ```

  ```mustache Header Account Menu theme={null}
  {{#shop.login_active}}
  <nav class="account-nav">
      {{#user.logged_in}}
      <div class="dropdown">
          <button class="account-toggle">
              <i class="icon-user"></i>
              {{#lang}}Account{{/lang}}
          </button>
          <div class="dropdown-menu">
              <a href="{{user.login_url}}">{{#lang}}My Orders{{/lang}}</a>
              <a href="{{user.login_url}}">{{#lang}}Settings{{/lang}}</a>
              <a href="/logout">{{#lang}}Log Out{{/lang}}</a>
          </div>
      </div>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
      <a href="{{user.login_url}}" class="login-btn">
          {{#lang}}Log In{{/lang}}
      </a>
      {{/user.logged_in}}
  </nav>
  {{/shop.login_active}}
  ```
</CodeGroup>

## Stock Messages

Display custom out-of-stock messages:

<CodeGroup>
  ```mustache Stock Messages theme={null}
  <!-- Use custom sold out message if available -->
  {{#product.soldOut}}
      <div class="sold-out-notice">
          {{#shop.soldout_text}}
              {{shop.soldout_text}}
          {{/shop.soldout_text}}
          {{^shop.soldout_text}}
              {{#lang}}Sorry, this item is currently out of stock{{/lang}}
          {{/shop.soldout_text}}
      </div>
  {{/product.soldOut}}
  ```
</CodeGroup>

## Complete Examples

### Store Header with All Features

<CodeGroup>
  ```mustache Complete Store Header theme={null}
  <header class="store-header">
      <!-- Main branding -->
      <div class="brand">
          <h1><a href="{{shop.url}}">{{shop.name}}</a></h1>
      </div>
      
      <!-- Utility navigation -->
      <div class="header-utils">
          <!-- Currency selector -->
          {{#shop.cconverter_active}}
          <div class="currency-selector">
              <select name="currency" onchange="window.location=this.value">
                  {{#shop.cconverter_currencies}}
                  <option value="{{url_current}}?currency={{currency}}" 
                          {{#current}}selected{{/current}}>
                      {{currency}}
                  </option>
                  {{/shop.cconverter_currencies}}
              </select>
          </div>
          {{/shop.cconverter_active}}
          
          <!-- Language selector -->
          {{#shop.app.languages}}
          <div class="language-selector">
              {{#shop.languages}}
              <a href="{{url}}" class="lang-link">
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
              </a>
              {{/shop.languages}}
          </div>
          {{/shop.app.languages}}
          
          <!-- Tax toggle -->
          {{#shop.taxtoggle_active}}
          <div class="tax-toggle">
              {{#shop.exclude_tax}}
              <a href="{{shop.incl_tax_url}}">{{#lang}}Incl. Tax{{/lang}}</a>
              {{/shop.exclude_tax}}
              {{^shop.exclude_tax}}
              <a href="{{shop.excl_tax_url}}">{{#lang}}Excl. Tax{{/lang}}</a>
              {{/shop.exclude_tax}}
          </div>
          {{/shop.taxtoggle_active}}
          
          <!-- Account links -->
          {{#shop.login_active}}
          <div class="account-links">
              {{#user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}Account{{/lang}}</a>
              {{/user.logged_in}}
              {{^user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
              {{/user.logged_in}}
          </div>
          {{/shop.login_active}}
      </div>
  </header>
  ```
</CodeGroup>

### Store Footer with Contact Information

<CodeGroup>
  ```mustache Store Footer theme={null}
  <footer class="store-footer">
      <div class="footer-content">
          <!-- Store information -->
          <div class="footer-section">
              <h3>{{shop.name}}</h3>
              {{#shop.address}}
              <div class="address">
                  <p>{{shop.address}}</p>
                  <p>{{shop.zipcode}} {{shop.city}}</p>
              </div>
              {{/shop.address}}
              
              {{#shop.phone}}
              <div class="contact">
                  <p>{{#lang}}Phone{{/lang}}: {{shop.phone}}</p>
              </div>
              {{/shop.phone}}
          </div>
          
          <!-- Contact text -->
          {{#shop.contact_text}}
          <div class="footer-section">
              <h3>{{#lang}}Contact{{/lang}}</h3>
              <div class="contact-text">
                  {{&shop.contact_text}}
              </div>
          </div>
          {{/shop.contact_text}}
          
          <!-- Currency and language options -->
          <div class="footer-section">
              {{#shop.cconverter_active}}
              <div class="footer-currencies">
                  <h4>{{#lang}}Currency{{/lang}}</h4>
                  {{#shop.cconverter_currencies}}
                  <a href="{{url_current}}?currency={{currency}}" 
                     {{#current}}class="current"{{/current}}>
                      {{currency}}
                  </a>
                  {{/shop.cconverter_currencies}}
              </div>
              {{/shop.cconverter_active}}
              
              {{#shop.app.languages}}
              <div class="footer-languages">
                  <h4>{{#lang}}Language{{/lang}}</h4>
                  {{#shop.languages}}
                  <a href="{{url}}">{{id}}</a>
                  {{/shop.languages}}
              </div>
              {{/shop.app.languages}}
          </div>
      </div>
  </footer>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Check Before Using" icon="shield-check">
    Always check if features are enabled before displaying related UI elements (e.g., `{{#shop.cconverter_active}}`)
  </Card>

  <Card title="Provide Fallbacks" icon="life-ring">
    Provide fallback content when optional settings aren't configured
  </Card>

  <Card title="Use Semantic HTML" icon="code">
    Structure your shop information with proper semantic HTML elements
  </Card>

  <Card title="Cache Considerations" icon="clock">
    Shop data is cached and updates when you change store settings in the Control Panel
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="User Object" icon="user" href="/theme-development/global/user">
    Learn about customer account and authentication data
  </Card>

  <Card title="Settings Object" icon="gear" href="/theme-development/global/settings">
    Explore theme-specific customizable settings
  </Card>

  <Card title="Basket Object" icon="shopping-cart" href="/theme-development/global/basket">
    Work with shopping cart data and functionality
  </Card>

  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build dynamic navigation menus
  </Card>
</CardGroup>


# User Object
Source: https://quickbutik.dev/theme-development/global/user

Access customer account and authentication information

The `user` object contains information about logged-in customers when the login/account feature is enabled in your store. It's used to create account management functionality and personalized experiences.

<Info>
  **Usage**: Available globally when `shop.login_active` is true - check login status and display account-related content
</Info>

## Basic Usage

The user object helps you create login/logout functionality and personalized content:

<CodeGroup>
  ```mustache Basic Login Status theme={null}
  <!-- Check if customer accounts are enabled -->
  {{#shop.login_active}}
      {{#user.logged_in}}
          <p>Welcome back!</p>
          <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
          <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```

  ```mustache Account Navigation theme={null}
  {{#shop.login_active}}
  <nav class="account-nav">
      {{#user.logged_in}}
      <!-- Logged in user menu -->
      <div class="user-menu">
          <a href="{{user.login_url}}" class="account-link">
              <i class="icon-user"></i>
              {{#lang}}My Account{{/lang}}
          </a>
          <a href="/logout" class="logout-link">
              {{#lang}}Log Out{{/lang}}
          </a>
      </div>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
      <!-- Guest user options -->
      <div class="guest-menu">
          <a href="{{user.login_url}}" class="login-link">
              {{#lang}}Log In{{/lang}}
          </a>
      </div>
      {{/user.logged_in}}
  </nav>
  {{/shop.login_active}}
  ```
</CodeGroup>

## Available Properties

| Property         | Type    | Description                            |
| ---------------- | ------- | -------------------------------------- |
| `user.logged_in` | Boolean | Check if visitor is logged in          |
| `user.login_url` | String  | Output link to Login / My Account page |

## Conditional Content Examples

### Personalized Header

<CodeGroup>
  ```mustache Personalized Header theme={null}
  <header class="site-header">
      <div class="user-section">
          {{#shop.login_active}}
              {{#user.logged_in}}
                  <!-- Logged in state -->
                  <div class="logged-in-user">
                      <span class="welcome-text">{{#lang}}Welcome back{{/lang}}</span>
                      <a href="{{user.login_url}}" class="account-btn">
                          {{#lang}}My Account{{/lang}}
                      </a>
                  </div>
              {{/user.logged_in}}
              
              {{^user.logged_in}}
                  <!-- Guest state -->
                  <div class="guest-user">
                      <a href="{{user.login_url}}" class="login-btn">
                          {{#lang}}Sign In{{/lang}}
                      </a>
                  </div>
              {{/user.logged_in}}
          {{/shop.login_active}}
      </div>
  </header>
  ```
</CodeGroup>

### Account Dashboard Link

<CodeGroup>
  ```mustache Account Dashboard theme={null}
  {{#shop.login_active}}
      {{#user.logged_in}}
      <div class="account-dashboard">
          <h2>{{#lang}}Account Dashboard{{/lang}}</h2>
          <div class="dashboard-links">
              <a href="{{user.login_url}}" class="dashboard-link">
                  <i class="icon-orders"></i>
                  <span>{{#lang}}My Orders{{/lang}}</span>
              </a>
              <a href="{{user.login_url}}" class="dashboard-link">
                  <i class="icon-settings"></i>
                  <span>{{#lang}}Account Settings{{/lang}}</span>
              </a>
              <a href="{{user.login_url}}" class="dashboard-link">
                  <i class="icon-addresses"></i>
                  <span>{{#lang}}My Addresses{{/lang}}</span>
              </a>
          </div>
      </div>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```
</CodeGroup>

### Checkout Experience

<CodeGroup>
  ```mustache Checkout Login Prompt theme={null}
  {{#shop.login_active}}
      {{^user.logged_in}}
      <div class="checkout-login-prompt">
          <h3>{{#lang}}Returning Customer?{{/lang}}</h3>
          <p>{{#lang}}Sign in for faster checkout{{/lang}}</p>
          <a href="{{user.login_url}}" class="signin-btn">
              {{#lang}}Sign In{{/lang}}
          </a>
      </div>
      {{/user.logged_in}}
      
      {{#user.logged_in}}
      <div class="checkout-welcome">
          <p>{{#lang}}Signed in and ready to checkout{{/lang}}</p>
      </div>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```
</CodeGroup>

## Complete Examples

### Responsive Account Menu

<CodeGroup>
  ```mustache Complete Account Menu theme={null}
  {{#shop.login_active}}
  <div class="account-menu">
      {{#user.logged_in}}
      <!-- Logged in: Account dropdown -->
      <div class="account-dropdown">
          <button class="account-toggle" aria-expanded="false">
              <i class="icon-user"></i>
              <span>{{#lang}}Account{{/lang}}</span>
              <i class="icon-chevron-down"></i>
          </button>
          
          <div class="dropdown-content">
              <div class="dropdown-header">
                  <span class="user-status">{{#lang}}Signed in{{/lang}}</span>
              </div>
              
              <div class="dropdown-links">
                  <a href="{{user.login_url}}" class="dropdown-link">
                      <i class="icon-orders"></i>
                      {{#lang}}My Orders{{/lang}}
                  </a>
                  <a href="{{user.login_url}}" class="dropdown-link">
                      <i class="icon-user"></i>
                      {{#lang}}Account Details{{/lang}}
                  </a>
                  <a href="{{user.login_url}}" class="dropdown-link">
                      <i class="icon-location"></i>
                      {{#lang}}Address Book{{/lang}}
                  </a>
                  <div class="dropdown-divider"></div>
                  <a href="/logout" class="dropdown-link logout">
                      <i class="icon-logout"></i>
                      {{#lang}}Sign Out{{/lang}}
                  </a>
              </div>
          </div>
      </div>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
      <!-- Logged out: Simple login link -->
      <a href="{{user.login_url}}" class="login-link">
          <i class="icon-login"></i>
          <span>{{#lang}}Sign In{{/lang}}</span>
      </a>
      {{/user.logged_in}}
  </div>
  {{/shop.login_active}}
  ```
</CodeGroup>

### Mobile-Friendly Account Section

<CodeGroup>
  ```mustache Mobile Account Section theme={null}
  {{#shop.login_active}}
  <div class="mobile-account-section">
      {{#user.logged_in}}
      <!-- Mobile logged in menu -->
      <div class="mobile-account-menu">
          <div class="account-header">
              <i class="icon-user-circle"></i>
              <span class="account-title">{{#lang}}My Account{{/lang}}</span>
          </div>
          
          <nav class="account-nav">
              <a href="{{user.login_url}}" class="nav-item">
                  <i class="icon-orders"></i>
                  <span>{{#lang}}Order History{{/lang}}</span>
                  <i class="icon-chevron-right"></i>
              </a>
              <a href="{{user.login_url}}" class="nav-item">
                  <i class="icon-settings"></i>
                  <span>{{#lang}}Account Settings{{/lang}}</span>
                  <i class="icon-chevron-right"></i>
              </a>
              <a href="/logout" class="nav-item logout">
                  <i class="icon-logout"></i>
                  <span>{{#lang}}Sign Out{{/lang}}</span>
              </a>
          </nav>
      </div>
      {{/user.logged_in}}
      
      {{^user.logged_in}}
      <!-- Mobile login prompt -->
      <div class="mobile-login-prompt">
          <div class="login-content">
              <i class="icon-user-plus"></i>
              <h3>{{#lang}}Sign In{{/lang}}</h3>
              <p>{{#lang}}Access your account and order history{{/lang}}</p>
              <a href="{{user.login_url}}" class="login-btn-mobile">
                  {{#lang}}Sign In{{/lang}}
              </a>
          </div>
      </div>
      {{/user.logged_in}}
  </div>
  {{/shop.login_active}}
  ```
</CodeGroup>

## Implementation Notes

<CardGroup>
  <Card title="Feature Check" icon="shield-check">
    Always wrap user object usage with `{{#shop.login_active}}` to ensure the feature is enabled
  </Card>

  <Card title="Login URL" icon="link">
    The `user.login_url` leads to the same page for both login and account management
  </Card>

  <Card title="Logout Handling" icon="sign-out">
    Logout is typically handled via `/logout` endpoint, not through the login\_url
  </Card>

  <Card title="State Management" icon="toggle-on">
    Use `{{#user.logged_in}}` and `{{^user.logged_in}}` for clear conditional logic
  </Card>
</CardGroup>

## Best Practices

### Accessible Login Forms

<CodeGroup>
  ```mustache Accessible Login theme={null}
  {{#shop.login_active}}
      {{^user.logged_in}}
      <div class="login-section" role="region" aria-label="{{#lang}}User Login{{/lang}}">
          <a href="{{user.login_url}}" 
             class="login-button"
             aria-describedby="login-description">
              {{#lang}}Sign In{{/lang}}
          </a>
          <p id="login-description" class="sr-only">
              {{#lang}}Access your account to view orders and manage settings{{/lang}}
          </p>
      </div>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```
</CodeGroup>

### SEO-Friendly Account Links

<CodeGroup>
  ```mustache SEO Account Links theme={null}
  {{#shop.login_active}}
      {{#user.logged_in}}
      <nav aria-label="{{#lang}}Account Navigation{{/lang}}">
          <a href="{{user.login_url}}" 
             title="{{#lang}}View and manage your account{{/lang}}">
              {{#lang}}My Account{{/lang}}
          </a>
      </nav>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Settings Object" icon="gear" href="/theme-development/global/settings">
    Learn about theme-specific customizable settings
  </Card>

  <Card title="Basket Object" icon="shopping-cart" href="/theme-development/global/basket">
    Work with shopping cart data and functionality
  </Card>

  <Card title="Order Object" icon="receipt" href="/theme-development/pages/order">
    Display order information on thank you pages
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Back to shop settings and global store information
  </Card>
</CardGroup>


# Introduction
Source: https://quickbutik.dev/theme-development/introduction

Build beautiful, dynamic storefronts with Quickbutik's powerful templating system

Welcome to Quickbutik's theme development documentation! This guide will teach you everything you need to know about building custom storefronts using our powerful Mustache-based templating system.

<Info>
  **What you'll learn:**

  * How to work with Quickbutik's theme engine
  * Mustache templating language fundamentals
  * Available objects and data structures
  * Best practices for theme development
</Info>

## What is Quickbutik Theme Development?

Quickbutik uses **Mustache**, an open-source logic-less templating language, to create dynamic ecommerce storefronts. With our templating system, you can customize every aspect of the shopping experience.

## Key Concepts

Before diving in, let's understand the core concepts you'll work with:

<CardGroup>
  <Card title="Objects" icon="box">
    **Data containers** that hold information like products, orders, or store settings. Example: `{{product.title}}`
  </Card>

  <Card title="Attributes" icon="list">
    **Properties** of objects that contain specific data. Example: `{{product.price}}`, `{{customer.email}}`
  </Card>

  <Card title="Conditionals" icon="code-branch">
    **If-statements** that show content based on conditions. Example: `{{#product.soldOut}}Out of stock{{/product.soldOut}}`
  </Card>

  <Card title="Wrappers" icon="brackets-curly">
    **Helper functions** that process and transform data. Example: `{{#img}}{{product.image}}_400x400{{/img}}`
  </Card>
</CardGroup>

## Template Structure

All Quickbutik themes follow a structured approach where dynamic content is embedded using double curly braces:

```mustache theme={null}
{{object.attribute}}
```

### Basic Examples

<CodeGroup>
  ```mustache Product Title theme={null}
  <!-- Display a product's title -->
  <h1>{{product.title}}</h1>

  <!-- Output: <h1>Amazing T-Shirt</h1> -->
  ```

  ```mustache Price with Currency theme={null}
  <!-- Display price with currency -->
  <span class="price">{{product.price}} {{product.currency}}</span>

  <!-- Output: <span class="price">299 SEK</span> -->
  ```

  ```mustache Conditional Content theme={null}
  <!-- Show different content based on stock status -->
  {{#product.soldOut}}
    <div class="alert alert-warning">Out of stock</div>
  {{/product.soldOut}}
  {{^product.soldOut}}
    <button class="btn btn-primary">Add to Cart</button>
  {{/product.soldOut}}
  ```
</CodeGroup>

## Where to Edit Your Theme

You can access and modify your theme code through the Quickbutik Control Panel:

<Steps>
  <Step title="Access theme editor">
    Navigate to **Appearance → Theme → Under the Hood** in your control panel
  </Step>

  <Step title="Browse template files">
    Explore the different template files like `product.mustache`, `list.mustache`, `cartsuccess.mustache`
  </Step>

  <Step title="Edit and preview">
    Make changes to the code and use the preview function to see your changes
  </Step>

  <Step title="Save and publish">
    Save your changes and publish them to your live store
  </Step>
</Steps>

## Common Use Cases

Here are some popular things you can accomplish with theme development:

<AccordionGroup>
  <Accordion title="Custom Product Displays">
    Create unique product layouts, image galleries, and variant selectors tailored to your brand.

    ```mustache theme={null}
    {{#product.images}}
      <img src="{{#img}}{{image}}_800x600{{/img}}" alt="{{alttext}}" />
    {{/product.images}}
    ```
  </Accordion>

  <Accordion title="Dynamic Navigation">
    Build responsive menus that adapt based on your store's categories and pages.

    ```mustache theme={null}
    <nav>
      {{#linklist.main}}
        <a href="{{url}}" {{#current}}class="active"{{/current}}>{{name}}</a>
      {{/linklist.main}}
    </nav>
    ```
  </Accordion>

  <Accordion title="Shopping Cart Integration">
    Display cart contents, quantities, and totals anywhere in your theme.

    ```mustache theme={null}
    {{^basket.isEmpty}}
      <div class="cart-summary">
        {{basket.items_count}} items - {{basket.total_amount}}
        <a href="{{paylink}}">Checkout</a>
      </div>
    {{/basket.isEmpty}}
    ```
  </Accordion>

  <Accordion title="Multi-language Support">
    Create themes that work seamlessly with Quickbutik's translation system.

    ```mustache theme={null}
    <button>{{#lang}}Add to Cart{{/lang}}</button>
    <!-- Automatically translates based on store language settings -->
    ```
  </Accordion>
</AccordionGroup>

## Development Workflow

<Tip>
  **Pro tip**: Always test your changes in a theme under construction before publishing to your live version!
</Tip>

### Recommended Development Process

1. **Plan your layout** - Sketch out the design and identify what data you need
2. **Start with static HTML** - Build the basic structure without dynamic content
3. **Add dynamic elements** - Replace static content with Mustache templates
4. **Test thoroughly** - Check different scenarios (empty cart, sold out products, etc.)
5. **Optimize performance** - Minimize template complexity and optimize images

## Getting Help

<CardGroup>
  <Card title="Search Function" icon="magnifying-glass">
    Use the search function (top left) or browser search to quickly find specific objects or functions
  </Card>

  <Card title="Contact Support" icon="envelope">
    Technical questions? Email us at [support@quickbutik.com](mailto:support@quickbutik.com)
  </Card>

  <Card title="Community" icon="users">
    Join our developer community for tips, tricks, and peer support
  </Card>

  <Card title="Examples" icon="code">
    Browse our comprehensive examples library for common implementation patterns
  </Card>
</CardGroup>

## Next Steps

Ready to start building? Here's your learning path:

<CardGroup>
  <Card title="Quickstart Tutorial" icon="rocket" href="/theme-development/quickstart">
    Build your first custom template in 15 minutes
  </Card>

  <Card title="Mustache Basics" icon="code" href="/theme-development/mustache-basics">
    Learn the fundamental syntax and concepts
  </Card>

  <Card title="Template Structure" icon="sitemap" href="/theme-development/template-structure">
    Understand how Quickbutik themes are organized
  </Card>

  <Card title="Development Setup" icon="tools" href="/theme-development/development-setup">
    Set up your local development environment
  </Card>
</CardGroup>

***

<Warning>
  **Important**: Always backup your theme before making significant changes. You can download a copy of your theme files from the control panel.
</Warning>


# Mustache Template Basics
Source: https://quickbutik.dev/theme-development/mustache-basics

Master the fundamentals of Mustache templating for Quickbutik themes

Mustache is a logic-less templating language that Quickbutik uses to create dynamic storefronts. This guide covers the core syntax and fundamental concepts you need to get started with Mustache templates.

<Info>
  **Why Mustache?**

  * Simple, readable syntax
  * Logic-less design prevents complex business logic in templates
  * Cross-platform compatibility
  * Secure by design - prevents code injection
</Info>

## Template Syntax Overview

All Mustache templates use double curly braces `{{}}` to denote dynamic content. Here are the basic patterns:

<CardGroup>
  <Card title="Variables" icon="tag">
    `{{variable}}` - Outputs the value of a variable
  </Card>

  <Card title="Sections" icon="code-branch">
    `{{#section}}...{{/section}}` - Conditional blocks or loops
  </Card>

  <Card title="Inverted Sections" icon="x">
    `{{^section}}...{{/section}}` - Shows content when condition is false
  </Card>

  <Card title="Comments" icon="comment">
    `{{! This is a comment }}` - Not rendered in output
  </Card>
</CardGroup>

## Variables and Output

The simplest Mustache tag outputs a variable's value:

<CodeGroup>
  ```mustache Basic Variables theme={null}
  <!-- Display product information -->
  <h1>{{product.title}}</h1>
  <p>Price: {{product.price}} {{product.currency}}</p>
  <p>SKU: {{product.sku}}</p>

  <!-- Display store information -->
  <footer>© {{shop.name}}</footer>
  ```

  ```html Expected Output theme={null}
  <!-- Display product information -->
  <h1>Amazing T-Shirt</h1>
  <p>Price: 299 SEK</p>
  <p>SKU: SHIRT-001</p>

  <!-- Display store information -->
  <footer>© My Awesome Store</footer>
  ```
</CodeGroup>

### HTML Escaping

By default, Mustache escapes HTML characters for security. Use `{{{variable}}}` or `{{&variable}}` to render unescaped HTML:

<CodeGroup>
  ```mustache HTML Escaping Examples theme={null}
  <!-- Escaped HTML (safe) -->
  <div>{{product.description}}</div>

  <!-- Unescaped HTML (renders HTML tags) -->
  <div>{{&product.description}}</div>
  <div>{{{product.description}}}</div>
  ```

  ```html Output Comparison theme={null}
  <!-- If product.description contains: "<strong>Bold text</strong>" -->

  <!-- Escaped version -->
  <div>&lt;strong&gt;Bold text&lt;/strong&gt;</div>

  <!-- Unescaped version -->
  <div><strong>Bold text</strong></div>
  ```
</CodeGroup>

<Warning>
  **Security Note**: Only use unescaped output (`{{&}}` or `{{{}}}`) with trusted content like product descriptions that you control. Never use it with user-generated content.
</Warning>

## Basic Sections and Conditionals

Sections are the core of Mustache's logic. They render content based on the truthiness of a value:

<CodeGroup>
  ```mustache Simple Conditionals theme={null}
  <!-- Show content if product is on sale -->
  {{#product.has_before_price}}
      <div class="sale-badge">SALE!</div>
      <span class="original-price">{{product.before_price}}</span>
  {{/product.has_before_price}}

  <!-- Show content if product is NOT sold out -->
  {{^product.soldOut}}
      <button class="add-to-cart">Add to Cart</button>
  {{/product.soldOut}}

  <!-- Show content if product IS sold out -->
  {{#product.soldOut}}
      <div class="sold-out-notice">Sorry, this item is sold out</div>
  {{/product.soldOut}}
  ```
</CodeGroup>

### Basic Loops

When a section's value is an array, Mustache loops through each item:

<CodeGroup>
  ```mustache Simple Loops theme={null}
  <!-- Loop through product images -->
  <div class="product-gallery">
      {{#product.images}}
          <img src="{{image}}" alt="{{alttext}}" class="product-image">
      {{/product.images}}
  </div>

  <!-- Loop through navigation items -->
  <nav>
      {{#linklist.main}}
          <a href="{{url}}">{{name}}</a>
      {{/linklist.main}}
  </nav>

  <!-- Handle empty arrays -->
  {{#basket.items}}
      <div class="cart-item">{{item.title}} - {{qty}}</div>
  {{/basket.items}}
  {{^basket.items}}
      <p>Your cart is empty</p>
  {{/basket.items}}
  ```
</CodeGroup>

## Basic Object Access

Use dot notation to access object properties:

<CodeGroup>
  ```mustache Object Properties theme={null}
  <!-- Simple object properties -->
  {{product.title}}
  {{product.price}}
  {{shop.name}}

  <!-- Nested object properties -->
  {{order.customer.firstname}}
  {{order.customer.lastname}}
  {{order.customer.ship_address}}
  ```
</CodeGroup>

### Understanding Context

Inside a section, the context changes to that object:

<CodeGroup>
  ```mustache Context Changes theme={null}
  <!-- Outside any section, we're in global context -->
  <h1>Welcome to {{shop.name}}</h1>

  {{#basket.items}}
      <!-- Inside this section, context is each basket item -->
      <div class="cart-item">
          <h3>{{item.title}}</h3>  <!-- item.title, not basket.items.item.title -->
          <p>Quantity: {{qty}}</p>  <!-- qty, not basket.items.qty -->
          <p>Price: {{item.price}}</p>
      </div>
  {{/basket.items}}

  {{#product}}
      <!-- Inside this section, context is the product object -->
      <h1>{{title}}</h1>  <!-- product.title is now just title -->
      <p>{{description}}</p>  <!-- product.description is now just description -->
  {{/product}}
  ```
</CodeGroup>

## Helper Functions Overview

Quickbutik provides special wrapper functions for common tasks:

<CodeGroup>
  ```mustache Helper Function Examples theme={null}
  <!-- Image resizing -->
  <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}">

  <!-- Text translation -->
  <button>{{#lang}}Add to Cart{{/lang}}</button>

  <!-- Asset linking -->
  <link rel="stylesheet" href="{{#assets}}css/styles.css{{/assets}}">
  ```
</CodeGroup>

<Info>
  **Learn More**: Helper functions are covered in detail in the [Wrappers and Functions](/theme-development/wrappers-and-functions) guide.
</Info>

## Best Practices

<CardGroup>
  <Card title="Keep It Simple" icon="heart">
    Mustache is designed to be logic-less. Keep business logic in your data, not your templates.
  </Card>

  <Card title="Use Descriptive Names" icon="tag">
    Use clear, descriptive variable names in your templates for better maintainability.
  </Card>

  <Card title="Handle Empty States" icon="circle-xmark">
    Always provide fallbacks for empty arrays and missing data.
  </Card>

  <Card title="Escape User Content" icon="shield">
    Use default (escaped) output for any user-generated content.
  </Card>
</CardGroup>

### Template Organization

<CodeGroup>
  ```mustache Good Structure theme={null}
  <!-- Clear sections with comments -->
  {{! Product Gallery Section }}
  <div class="product-gallery">
      {{#product.images}}
          <img src="{{#img}}{{image}}_600x600{{/img}}" alt="{{alttext}}">
      {{/product.images}}
  </div>

  {{! Product Information Section }}
  <div class="product-info">
      <h1>{{product.title}}</h1>
      
      {{! Price Display }}
      <div class="price">
          {{#product.has_before_price}}
              <span class="was-price">{{product.before_price}}</span>
          {{/product.has_before_price}}
          <span class="current-price">{{product.price}}</span>
      </div>
  </div>
  ```
</CodeGroup>

## Common Mistakes to Avoid

<AccordionGroup>
  <Accordion title="Forgetting to close sections">
    ```mustache theme={null}
    <!-- Wrong: Missing closing tag -->
    {{#product.soldOut}}
        <p>Sold out!</p>

    <!-- Correct: Properly closed -->
    {{#product.soldOut}}
        <p>Sold out!</p>
    {{/product.soldOut}}
    ```
  </Accordion>

  <Accordion title="Incorrect context assumptions">
    ```mustache theme={null}
    <!-- Wrong: Assuming global context inside a loop -->
    {{#basket.items}}
        <p>{{product.title}}</p>  <!-- product is not available here -->
    {{/basket.items}}

    <!-- Correct: Using the actual context -->
    {{#basket.items}}
        <p>{{item.title}}</p>  <!-- item is the correct context -->
    {{/basket.items}}
    ```
  </Accordion>

  <Accordion title="Using unescaped output unnecessarily">
    ```mustache theme={null}
    <!-- Wrong: Unescaping when not needed -->
    <h1>{{{product.title}}}</h1>

    <!-- Correct: Default escaping is usually fine -->
    <h1>{{product.title}}</h1>

    <!-- Only unescaped when rendering HTML content -->
    <div>{{&product.description}}</div>
    ```
  </Accordion>
</AccordionGroup>

## Testing Your Templates

<Steps>
  <Step title="Use the preview function">
    Always test your templates using Quickbutik's preview feature before publishing
  </Step>

  <Step title="Test edge cases">
    Test with products that have no images, are sold out, or have no variants
  </Step>

  <Step title="Check different page types">
    Make sure your templates work across different contexts (product pages, category pages, etc.)
  </Step>

  <Step title="Validate HTML output">
    Use browser developer tools to ensure your templates generate valid HTML
  </Step>
</Steps>

## Next Steps

Now that you understand the basics, dive deeper into specific aspects:

<CardGroup>
  <Card title="Objects and Attributes" icon="box" href="/theme-development/objects-and-attributes">
    Learn about all the data objects and how to access their properties
  </Card>

  <Card title="Conditionals" icon="code-branch" href="/theme-development/conditionals">
    Master advanced conditional logic and pattern matching
  </Card>

  <Card title="Wrappers and Functions" icon="brackets-curly" href="/theme-development/wrappers-and-functions">
    Discover all available helper functions and their usage
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Explore store-wide data like settings, navigation, and cart
  </Card>
</CardGroup>


# Objects and Attributes
Source: https://quickbutik.dev/theme-development/objects-and-attributes

Understanding Mustache objects, attributes, and property access in Quickbutik themes

Objects and attributes form the foundation of Mustache templating in Quickbutik. Understanding how to access and manipulate object properties is essential for building dynamic, data-driven themes using only supported Quickbutik properties.

## What are Objects?

Objects in Mustache are data structures that contain information about your store, products, users, and other entities. Each object has attributes (properties) that hold specific values.

<CodeGroup>
  ```mustache Basic Object Access theme={null}
  <!-- Accessing shop object attributes -->
  <h1>{{shop.name}}</h1>
  <p>{{shop.contact_text}}</p>

  <!-- Accessing product object attributes -->
  <h2>{{product.title}}</h2>
  <p>Price: {{product.price}}</p>
  ```

  ```mustache Nested Object Access theme={null}
  <!-- Accessing nested attributes -->
  <p>{{shop.address}}</p>
  <p>{{shop.city}}, {{shop.zipcode}}</p>

  <!-- Accessing array items -->
  {{#product.images}}
      <img src="{{#img}}{{image}}_400x400{{/img}}" alt="{{alttext}}">
  {{/product.images}}
  ```
</CodeGroup>

## Available Object Types

Quickbutik provides several types of objects you can work with:

### Global Objects

Available on all pages throughout your theme:

| Object     | Description                    | Availability |
| ---------- | ------------------------------ | ------------ |
| `shop`     | Store information and settings | All pages    |
| `user`     | Current user/customer data     | All pages    |
| `basket`   | Shopping cart contents         | All pages    |
| `linklist` | Menu and navigation data       | All pages    |
| `settings` | Theme customization options    | All pages    |
| `seo`      | SEO meta information           | All pages    |

### Page-Specific Objects

Available only on specific page types:

| Object     | Description                   | Available On          |
| ---------- | ----------------------------- | --------------------- |
| `product`  | Individual product data       | Product pages         |
| `category` | Category and product listings | Category pages        |
| `order`    | Order confirmation details    | Order/Thank you pages |
| `blog`     | Blog post and article data    | Blog pages            |
| `page`     | Static page content           | Static pages          |

## Object Property Access

### Dot Notation for Nested Properties

Use dot notation to access nested properties:

<CodeGroup>
  ```mustache Property Access Patterns theme={null}
  <!-- Simple properties -->
  {{shop.name}}
  {{product.title}}
  {{user.login_url}}

  <!-- Nested properties -->
  {{order.customer.email}}
  {{order.customer.firstname}}
  {{order.customer.ship_address}}

  <!-- Settings properties -->
  {{settings.home_elements}}
  ```
</CodeGroup>

### Array Index Access

Access specific array items by their index position:

<CodeGroup>
  ```mustache Array Index Examples theme={null}
  <!-- Access first item (index 0) -->
  {{product.images.0.image}}
  {{linklist.main.0.name}}

  <!-- Access second item (index 1) -->
  {{product.images.1.image}}
  {{shop.cconverter_currencies.1.currency}}

  <!-- Access nested array items -->
  {{linklist.main.0.children.0.name}}
  ```
</CodeGroup>

## Working with Different Property Types

Understanding the different types of data that object properties can contain:

### String Properties

<CodeGroup>
  ```mustache Text Data theme={null}
  <!-- Simple text values -->
  <h1>{{product.title}}</h1>
  <p>{{product.description}}</p>
  <span class="sku">{{product.sku}}</span>
  <p>{{shop.contact_text}}</p>
  ```
</CodeGroup>

### Number Properties

<CodeGroup>
  ```mustache Numeric Data theme={null}
  <!-- Numeric values -->
  <p>Price: {{product.price}}</p>
  <p>Items: {{basket.items_count}}</p>
  <p>Order ID: {{order.id}}</p>
  <p>Quantity: {{qty}}</p>
  ```
</CodeGroup>

### Boolean Properties

<CodeGroup>
  ```mustache Boolean Values theme={null}
  <!-- Boolean properties for conditions -->
  {{#product.soldOut}}
      <span class="sold-out-badge">{{#lang}}Sold Out{{/lang}}</span>
  {{/product.soldOut}}

  {{#product.has_before_price}}
      <span class="sale-badge">{{#lang}}Sale{{/lang}}</span>
  {{/product.has_before_price}}

  {{#user.logged_in}}
      <p>{{#lang}}Welcome back{{/lang}}</p>
  {{/user.logged_in}}

  {{#basket.isEmpty}}
      <p>{{#lang}}Your cart is empty{{/lang}}</p>
  {{/basket.isEmpty}}
  ```
</CodeGroup>

### Array Properties

<CodeGroup>
  ```mustache Array Data theme={null}
  <!-- Arrays of objects -->
  {{#product.images}}
      <img src="{{#img}}{{image}}_400x400{{/img}}" alt="{{alttext}}">
  {{/product.images}}

  <!-- Navigation arrays -->
  {{#linklist.main}}
      <a href="{{url}}" class="nav-link">{{name}}</a>
  {{/linklist.main}}

  <!-- Order items array -->
  {{#order.items}}
      <div class="order-item">
          <h4>{{title}}</h4>
          <p>{{#lang}}Quantity{{/lang}}: {{qty}}</p>
      </div>
  {{/order.items}}
  ```
</CodeGroup>

### Object Properties (Nested Objects)

<CodeGroup>
  ```mustache Nested Objects theme={null}
  <!-- Customer address object -->
  <div class="address">
      <p>{{order.customer.ship_address}}</p>
      <p>{{order.customer.ship_city}}, {{order.customer.ship_zipcode}}</p>
      <p>{{order.customer.ship_country}}</p>
  </div>

  <!-- Settings home elements -->
  {{#settings.home_elements}}
      {{#element}}
          <h2>{{title}}</h2>
          {{#image1_link}}
              <img src="{{#img}}{{image1_link}}_600x400{{/img}}" alt="{{title}}">
          {{/image1_link}}
      {{/element}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Common Object Usage Patterns

### Store Information Display

<CodeGroup>
  ```mustache Shop Object Examples theme={null}
  <header class="site-header">
      <h1>{{shop.name}}</h1>
      <a href="{{shop.url}}">{{#lang}}Visit Store{{/lang}}</a>
  </header>

  <div class="contact-info">
      {{#shop.address}}
          <p>{{shop.address}}</p>
          <p>{{shop.zipcode}} {{shop.city}}</p>
      {{/shop.address}}
      
      {{#shop.phone}}
          <p>{{#lang}}Phone{{/lang}}: {{shop.phone}}</p>
      {{/shop.phone}}
      
      {{#shop.contact_text}}
          <div class="contact-content">
              {{&shop.contact_text}}
          </div>
      {{/shop.contact_text}}
  </div>
  ```
</CodeGroup>

### Product Data Management

<CodeGroup>
  ```mustache Product Object Examples theme={null}
  <div class="product-details">
      <h1>{{product.title}}</h1>
      
      <div class="product-price">
          {{#product.has_before_price}}
              <span class="original-price">{{product.before_price}}</span>
          {{/product.has_before_price}}
          <span class="current-price">{{product.price}} {{product.currency}}</span>
      </div>
      
      <div class="product-meta">
          <p>{{#lang}}SKU{{/lang}}: {{product.sku}}</p>
          {{#product.gtin}}
              <p>{{#lang}}EAN{{/lang}}: {{product.gtin}}</p>
          {{/product.gtin}}
          
          <div class="stock-status">
              {{#product.soldOut}}
                  <span class="out-of-stock">
                      {{#shop.soldout_text}}
                          {{shop.soldout_text}}
                      {{/shop.soldout_text}}
                      {{^shop.soldout_text}}
                          {{#lang}}Out of Stock{{/lang}}
                      {{/shop.soldout_text}}
                  </span>
              {{/product.soldOut}}
              {{^product.soldOut}}
                  <span class="in-stock">{{#lang}}Available{{/lang}}</span>
              {{/product.soldOut}}
          </div>
      </div>
      
      {{#product.description}}
          <div class="product-description">
              {{&product.description}}
          </div>
      {{/product.description}}
  </div>
  ```
</CodeGroup>

### User Account Information

<CodeGroup>
  ```mustache User Object Examples theme={null}
  <!-- User authentication status -->
  {{#shop.login_active}}
      {{#user.logged_in}}
          <div class="user-info">
              <p>{{#lang}}Welcome back{{/lang}}</p>
              
              <nav class="user-nav">
                  <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
              </nav>
          </div>
      {{/user.logged_in}}

      {{^user.logged_in}}
          <div class="auth-links">
              <a href="{{user.login_url}}">{{#lang}}Login{{/lang}}</a>
          </div>
      {{/user.logged_in}}
  {{/shop.login_active}}
  ```
</CodeGroup>

## Working with Context and Parent Access

When iterating through arrays or working within sections, you may need to access parent object properties:

<CodeGroup>
  ```mustache Parent Context Access theme={null}
  <!-- Access parent product while iterating variants -->
  {{#product.options}}
      <div class="product-option">
          <h4>{{option_title}}</h4>
          {{#option_values}}
              <div class="variant">
                  <span>{{name}}</span>
                  <!-- Access parent product title using ../ -->
                  <p>{{#lang}}For{{/lang}}: {{../../title}}</p>
              </div>
          {{/option_values}}
      </div>
  {{/product.options}}

  <!-- Access global shop info within product loops -->
  {{#related_products}}
      <div class="product-card">
          <h3>{{rp.title}}</h3>
          <p>{{rp.price}}</p>
          <!-- Access global shop currency -->
          <p>{{#lang}}Currency{{/lang}}: {{../shop.name}}</p>
      </div>
  {{/related_products}}
  ```
</CodeGroup>

## Object Property Debugging

When working with objects, you might need to debug what properties are available:

<CodeGroup>
  ```mustache Debug Object Properties theme={null}
  <!-- Check if property exists -->
  {{#product.description}}
      <div class="description">{{&product.description}}</div>
  {{/product.description}}

  {{^product.description}}
      <div class="no-description">{{#lang}}No description available{{/lang}}</div>
  {{/product.description}}

  <!-- Check for images -->
  {{#product.images}}
      <div class="has-images">{{#lang}}Images available{{/lang}}</div>
  {{/product.images}}

  {{^product.images}}
      <div class="no-images">{{#lang}}No images available{{/lang}}</div>
  {{/product.images}}
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Check Property Existence" icon="tag">
    Always check if a property exists before using it to avoid template errors
  </Card>

  <Card title="Understand Object Hierarchy" icon="sitemap">
    Learn the structure of objects to access nested properties efficiently
  </Card>

  <Card title="Handle Missing Data Gracefully" icon="exclamation-triangle">
    Provide fallbacks for optional properties that might not always be present
  </Card>
</CardGroup>

## Common Property Access Mistakes

<Warning>
  **Property Access Errors**: These common mistakes can break your templates:

  1. **Wrong property names**: `{{product.name}}` instead of `{{product.title}}`
  2. **Missing context**: Forgetting `../` when accessing parent properties
  3. **Array confusion**: Using `{{product.images}}` instead of iterating with `{{#product.images}}`
  4. **Case sensitivity**: `{{Product.title}}` instead of `{{product.title}}`
</Warning>

## Advanced Object Patterns

### Conditional Property Display

<CodeGroup>
  ```mustache Smart Property Display theme={null}
  <!-- Show additional info only if it exists -->
  <div class="product-specifications">
      {{#product.supplier_name}}<p><strong>{{#lang}}Supplier{{/lang}}:</strong> {{product.supplier_name}}</p>{{/product.supplier_name}}
      {{#product.supplier_sku}}<p><strong>{{#lang}}Supplier SKU{{/lang}}:</strong> {{product.supplier_sku}}</p>{{/product.supplier_sku}}
      {{#product.gtin}}<p><strong>{{#lang}}EAN{{/lang}}:</strong> {{product.gtin}}</p>{{/product.gtin}}
  </div>
  ```
</CodeGroup>

### Object Property Chaining

<CodeGroup>
  ```mustache Property Chain Examples theme={null}
  <!-- Chain through multiple levels -->
  {{settings.home_elements.element.title}}
  {{order.customer.ship_address}}
  {{product.options.option_values.name}}

  <!-- Safe chaining with existence checks -->
  {{#settings.home_elements}}
      {{#element}}
          {{#title}}
              <h2>{{title}}</h2>
          {{/title}}
          
          {{#page.content}}
              <div class="content">
                  {{&page.content}}
              </div>
          {{/page.content}}
      {{/element}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Supported Object Properties Reference

### Shop Object Properties

<CodeGroup>
  ```mustache Shop Properties theme={null}
  <!-- Basic store info -->
  {{shop.name}}
  {{shop.url}}
  {{shop.address}}
  {{shop.zipcode}}
  {{shop.city}}
  {{shop.phone}}
  {{shop.contact_text}}
  {{shop.soldout_text}}

  <!-- Feature flags -->
  {{#shop.cconverter_active}}...{{/shop.cconverter_active}}
  {{#shop.app.languages}}...{{/shop.app.languages}}
  {{#shop.taxtoggle_active}}...{{/shop.taxtoggle_active}}
  {{#shop.login_active}}...{{/shop.login_active}}

  <!-- Currency converter -->
  {{#shop.cconverter_currencies}}
      {{currency}}
      {{#current}}...{{/current}}
  {{/shop.cconverter_currencies}}

  <!-- Languages -->
  {{#shop.languages}}
      {{id}}
      {{url}}
      {{#asset_flags}}{{id}}{{/asset_flags}}
  {{/shop.languages}}

  <!-- Tax toggle -->
  {{#shop.exclude_tax}}...{{/shop.exclude_tax}}
  {{shop.incl_tax_url}}
  {{shop.excl_tax_url}}
  ```
</CodeGroup>

### Product Object Properties

<CodeGroup>
  ```mustache Product Properties theme={null}
  <!-- Basic product info -->
  {{product.title}}
  {{product.id}}
  {{product.sku}}
  {{product.gtin}}
  {{product.price}}
  {{product.price_raw}}
  {{product.before_price}}
  {{product.currency}}
  {{product.description}}

  <!-- Images -->
  {{product.firstimage}}
  {{product.secondimage}}
  {{#product.images}}
      {{image}}
      {{image_id}}
      {{alttext}}
  {{/product.images}}

  <!-- Supplier info -->
  {{product.supplier_name}}
  {{product.supplier_sku}}

  <!-- Status -->
  {{#product.soldOut}}...{{/product.soldOut}}
  {{#product.has_before_price}}...{{/product.has_before_price}}

  <!-- Variants -->
  {{#product.hasOptions}}...{{/product.hasOptions}}
  {{#product.options}}
      {{option_title}}
      {{#option_values}}
          {{id}}
          {{name}}
      {{/option_values}}
  {{/product.options}}

  <!-- Custom data fields -->
  {{product.datafield_1}}
  {{product.datafield_2}}
  <!-- etc. -->
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Conditionals" icon="code-branch" href="/theme-development/conditionals">
    Learn how to use conditional logic with object properties
  </Card>

  <Card title="Wrappers and Functions" icon="function" href="/theme-development/wrappers-and-functions">
    Discover helper functions to manipulate object data
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Explore all available global objects in detail
  </Card>

  <Card title="Page Objects" icon="file" href="/theme-development/pages/product">
    Learn about page-specific objects and their properties
  </Card>
</CardGroup>


# Blog Object
Source: https://quickbutik.dev/theme-development/pages/blog

Display blog posts and articles using the basic blog functionality

The `blog` object contains basic information about blog posts and articles. It's available on blog pages and provides access to post listings, individual posts, and basic blog functionality.

<Info>
  **Usage**: Available on blog pages - use to display blog posts and basic blog functionality
</Info>

## Blog Context Detection

Check what type of blog page is being displayed:

<CodeGroup>
  ```mustache Blog Context Detection theme={null}
  {{#is_list}}
      <!-- Blog overview/list page -->
      <div class="blog-list-page">
          <h1>{{blog.title_current}}</h1>
          
          {{#isBlogTag}}
              <p class="blog-tag-info">{{#lang}}Posts tagged with{{/lang}}: {{current_tag}}</p>
          {{/isBlogTag}}
          
          <!-- Blog posts loop -->
          {{#posts}}
              <!-- Individual post content -->
          {{/posts}}
      </div>
  {{/is_list}}

  {{#is_post}}
      <!-- Individual blog post page -->
      <article class="blog-post-single">
          <h1>{{post.title}}</h1>
          <!-- Single post content -->
      </article>
  {{/is_post}}
  ```
</CodeGroup>

## Blog Posts Listing

Display multiple blog posts using the posts loop:

<CodeGroup>
  ```mustache Blog Posts Grid theme={null}
  {{#is_list}}
  <div class="blog-page">
      <header class="blog-header">
          <h1>{{blog.title_current}}</h1>
          
          <div class="blog-meta">
              <a href="{{blog.rss}}" class="rss-link">
                  <i class="icon-rss"></i>
                  {{#lang}}RSS Feed{{/lang}}
              </a>
          </div>
      </header>
      
      {{#isBlogTag}}
          <div class="blog-tag-notice">
              <p>{{#lang}}Showing posts with selected tag{{/lang}}</p>
          </div>
      {{/isBlogTag}}
      
      <div class="blog-posts-grid">
          {{#posts}}
          <article class="blog-post-card">
              {{#hasImage}}
                  <div class="post-image">
                      <a href="{{url}}">
                          <img src="{{#img}}{{image}}_400x250{{/img}}" 
                               alt="{{title}}"
                               loading="lazy">
                      </a>
                  </div>
              {{/hasImage}}
              
              <div class="post-content">
                  <h3 class="post-title">
                      <a href="{{url}}">{{title}}</a>
                  </h3>
                  
                  <div class="post-meta">
                      <time class="post-date">{{date_pretty}}</time>
                      {{#author}}
                          <span class="post-author">{{#lang}}By{{/lang}} {{author}}</span>
                      {{/author}}
                  </div>
                  
                  {{#content_short}}
                      <div class="post-excerpt">
                          {{&content_short}}
                      </div>
                  {{/content_short}}
                  
                  <a href="{{url}}" class="read-more">
                      {{#lang}}Read More{{/lang}}
                  </a>
              </div>
          </article>
          {{/posts}}
      </div>
  </div>
  {{/is_list}}
  ```

  ```mustache Blog Posts List theme={null}
  {{#is_list}}
  <div class="blog-list-layout">
      <header class="blog-header">
          <h1>{{blog.title_current}}</h1>
          
          {{#blog.rss}}
              <a href="{{blog.rss}}" class="rss-feed">
                  {{#lang}}Subscribe to RSS{{/lang}}
              </a>
          {{/blog.rss}}
      </header>
      
      <div class="blog-posts">
          {{#posts}}
          <article class="blog-post-item">
              <header class="post-header">
                  <h2 class="post-title">
                      <a href="{{url}}">{{title}}</a>
                  </h2>
                  
                  <div class="post-meta">
                      <time datetime="{{date_pretty}}">{{date_pretty}}</time>
                      {{#author}}
                          <span class="author">{{#lang}}By{{/lang}} {{author}}</span>
                      {{/author}}
                  </div>
              </header>
              
              <div class="post-body">
                  {{#hasImage}}
                      <div class="post-thumbnail">
                          <a href="{{url}}">
                              <img src="{{#img}}{{image}}_300x200{{/img}}" alt="{{title}}">
                          </a>
                      </div>
                  {{/hasImage}}
                  
                  <div class="post-content">
                      {{#content_short}}
                          <div class="post-excerpt">
                              {{&content_short}}
                          </div>
                      {{/content_short}}
                      
                      <a href="{{url}}" class="read-more-btn">
                          {{#lang}}Read Full Article{{/lang}}
                      </a>
                  </div>
              </div>
          </article>
          {{/posts}}
      </div>
  </div>
  {{/is_list}}
  ```
</CodeGroup>

## Single Blog Post

Display individual blog post content:

<CodeGroup>
  ```mustache Single Blog Post theme={null}
  {{#is_post}}
  <article class="blog-post-single">
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <!-- Post Header -->
      <header class="post-header">
          <h1 class="post-title">{{post.title}}</h1>
          
          <div class="post-meta">
              <time class="post-date">{{post.date_pretty}}</time>
              {{#post.author}}
                  <span class="post-author">
                      {{#lang}}By{{/lang}} {{post.author}}
                  </span>
              {{/post.author}}
          </div>
      </header>
      
      <!-- Featured Image -->
      {{#post.hasImage}}
      <div class="post-featured-image">
          <img src="{{#img}}{{post.image}}_1200x600{{/img}}" 
               alt="{{post.title}}"
               loading="lazy">
      </div>
      {{/post.hasImage}}
      
      <!-- Post Content -->
      <div class="post-content">
          {{&post.content}}
      </div>
      
      <!-- Post Footer -->
      <footer class="post-footer">
          <div class="post-navigation">
              <a href="{{blog.url}}" class="back-to-blog">
                  <i class="icon-arrow-left"></i>
                  {{#lang}}Back to Blog{{/lang}}
              </a>
          </div>
      </footer>
  </article>
  {{/is_post}}
  ```
</CodeGroup>

## Blog Tags

Display available blog tags when tag filtering is active:

<CodeGroup>
  ```mustache Blog Tags theme={null}
  {{#blog.filter_tags}}
  <div class="blog-tags-section">
      <h3>{{#lang}}Browse by Tags{{/lang}}</h3>
      
      {{#available_tags}}
      <div class="blog-tags">
          {{#available_tags}}
          <a href="{{url}}" class="tag-link" rel="tag">
              {{title}}
          </a>
          {{/available_tags}}
      </div>
      {{/available_tags}}
  </div>
  {{/blog.filter_tags}}
  ```

  ```mustache Blog Tags Navigation theme={null}
  {{#blog.filter_tags}}
  <nav class="blog-tags-nav">
      <h4>{{#lang}}Filter by Tags{{/lang}}</h4>
      <ul class="tags-list">
          {{#available_tags}}
          <li class="tag-item">
              <a href="{{url}}" class="tag-link">
                  #{{title}}
              </a>
          </li>
          {{/available_tags}}
      </ul>
  </nav>
  {{/blog.filter_tags}}
  ```
</CodeGroup>

## Available Properties

### Blog Context Properties

| Property    | Type    | Description                                |
| ----------- | ------- | ------------------------------------------ |
| `is_list`   | Boolean | Check if blog overview is being shown      |
| `is_post`   | Boolean | Check if specific blog post is being shown |
| `isBlogTag` | Boolean | Is blog overview shown based on a tag      |

### Blog Properties

| Property              | Type    | Description                      |
| --------------------- | ------- | -------------------------------- |
| `blog.url`            | String  | Blog link address                |
| `blog.title_current`  | String  | Blog title                       |
| `blog.rss`            | String  | Blog RSS link address            |
| `blog.filter_tags`    | Boolean | Check if tags are active         |
| `blog.available_tags` | Array   | Object with blog tags            |
| `blog.posts`          | Array   | Object containing all blog posts |

### Available Tags Properties (within available\_tags loop)

| Property | Type   | Description     |
| -------- | ------ | --------------- |
| `title`  | String | Tag designation |
| `url`    | String | Tag URL         |

### Posts Properties (within posts loop)

| Property        | Type    | Description                     |
| --------------- | ------- | ------------------------------- |
| `hasImage`      | Boolean | Check if blog post has an image |
| `image`         | String  | Blog post image                 |
| `title`         | String  | Blog post title                 |
| `content_short` | String  | Short preview of blog post      |
| `content`       | String  | Blog post content               |
| `author`        | String  | Blog post author                |
| `date_pretty`   | String  | Blog post date                  |
| `url`           | String  | Blog post link address          |

### Post Properties (single post context)

| Property             | Type    | Description                     |
| -------------------- | ------- | ------------------------------- |
| `post.hasImage`      | Boolean | Check if blog post has an image |
| `post.image`         | String  | Blog post image                 |
| `post.title`         | String  | Blog post title                 |
| `post.content_short` | String  | Short preview of blog post      |
| `post.content`       | String  | Blog post content               |
| `post.author`        | String  | Blog post author                |
| `post.date_pretty`   | String  | Blog post date                  |
| `post.url`           | String  | Blog post link address          |

## Complete Blog Template

<CodeGroup>
  ```mustache Complete Blog Template theme={null}
  <div class="blog-container">
      {{#is_list}}
          <!-- Blog List Page -->
          <div class="blog-list-page">
              <header class="blog-header">
                  <h1>{{blog.title_current}}</h1>
                  
                  <div class="blog-actions">
                      {{#blog.rss}}
                          <a href="{{blog.rss}}" class="rss-link">
                              <i class="icon-rss"></i>
                              {{#lang}}RSS Feed{{/lang}}
                          </a>
                      {{/blog.rss}}
                  </div>
              </header>
              
              {{#isBlogTag}}
                  <div class="tag-filter-notice">
                      <p>{{#lang}}Filtered by tag{{/lang}}</p>
                  </div>
              {{/isBlogTag}}
              
              <!-- Tags Navigation -->
              {{#blog.filter_tags}}
              <nav class="blog-tags">
                  <h3>{{#lang}}Browse Tags{{/lang}}</h3>
                  <div class="tags-container">
                      {{#available_tags}}
                      <a href="{{url}}" class="tag-button">{{title}}</a>
                      {{/available_tags}}
                  </div>
              </nav>
              {{/blog.filter_tags}}
              
              <!-- Posts Grid -->
              <main class="blog-posts">
                  {{#posts}}
                  <article class="post-card">
                      {{#hasImage}}
                          <div class="post-image">
                              <a href="{{url}}">
                                  <img src="{{#img}}{{image}}_400x250{{/img}}" alt="{{title}}">
                              </a>
                          </div>
                      {{/hasImage}}
                      
                      <div class="post-info">
                          <h2 class="post-title">
                              <a href="{{url}}">{{title}}</a>
                          </h2>
                          
                          <div class="post-meta">
                              <time>{{date_pretty}}</time>
                              {{#author}}<span>{{#lang}}By{{/lang}} {{author}}</span>{{/author}}
                          </div>
                          
                          {{#content_short}}
                              <div class="post-excerpt">{{&content_short}}</div>
                          {{/content_short}}
                          
                          <a href="{{url}}" class="read-more">{{#lang}}Read More{{/lang}}</a>
                      </div>
                  </article>
                  {{/posts}}
              </main>
          </div>
      {{/is_list}}
      
      {{#is_post}}
          <!-- Single Post Page -->
          <article class="single-post">
              <header class="post-header">
                  <h1>{{post.title}}</h1>
                  <div class="post-meta">
                      <time>{{post.date_pretty}}</time>
                      {{#post.author}}<span>{{#lang}}By{{/lang}} {{post.author}}</span>{{/post.author}}
                  </div>
              </header>
              
              {{#post.hasImage}}
                  <div class="post-image">
                      <img src="{{#img}}{{post.image}}_1200x600{{/img}}" alt="{{post.title}}">
                  </div>
              {{/post.hasImage}}
              
              <div class="post-content">
                  {{&post.content}}
              </div>
              
              <footer class="post-footer">
                  <a href="{{blog.url}}" class="back-link">
                      {{#lang}}← Back to Blog{{/lang}}
                  </a>
              </footer>
          </article>
      {{/is_post}}
  </div>
  ```
</CodeGroup>

## Usage Notes

<Warning>
  **Limited Blog Object**: The blog object only provides basic functionality (post listings, individual posts, and simple tag filtering). Advanced features like categories, related posts, pagination, SEO properties, and complex metadata are not available.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Context Detection" icon="eye">
    Always use is\_list and is\_post to determine the correct template structure
  </Card>

  <Card title="Image Handling" icon="image">
    Check hasImage before displaying images and use proper image optimization
  </Card>

  <Card title="Content Display" icon="file-text">
    Use content\_short for excerpts and full content for complete posts
  </Card>

  <Card title="Tag Filtering" icon="tag">
    Implement tag filtering when blog.filter\_tags is available
  </Card>
</CardGroup>

## Common Blog Layouts

| Layout Type  | Context   | Key Elements                         |
| ------------ | --------- | ------------------------------------ |
| Blog List    | is\_list  | Posts loop, title\_current, RSS link |
| Single Post  | is\_post  | Individual post content, navigation  |
| Tagged Posts | isBlogTag | Filtered posts, tag navigation       |

## Next Steps

<CardGroup>
  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build blog navigation and breadcrumbs
  </Card>

  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Basic SEO optimization for blog pages
  </Card>

  <Card title="Static Pages" icon="file-text" href="/theme-development/pages/static">
    Learn about creating static content pages
  </Card>

  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Learn about product page implementation
  </Card>
</CardGroup>


# Category Object
Source: https://quickbutik.dev/theme-development/pages/category

Display category pages with basic category information

The `category` object contains basic information about product categories. It's available on product list pages and provides access to category name and description fields.

<Info>
  **Usage**: Available on product list pages - use to display basic category information
</Info>

## Basic Category Information

Access the core category details that are available:

<CodeGroup>
  ```mustache Basic Category Display theme={null}
  <div class="category-page">
      <header class="category-header">
          <h1 class="category-title">{{category.name}}</h1>
          
          {{#category.description1}}
              <div class="category-description">
                  {{&category.description1}}
              </div>
          {{/category.description1}}
          
          {{#category.description2}}
              <div class="category-description-secondary">
                  {{&category.description2}}
              </div>
          {{/category.description2}}
      </header>
  </div>
  ```

  ```mustache Category with Breadcrumbs theme={null}
  <div class="category-page">
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <!-- Category Header -->
      <div class="category-header">
          <h1>{{category.name}}</h1>
          
          {{#category.description1}}
              <div class="category-intro">
                  {{&category.description1}}
              </div>
          {{/category.description1}}
          
          {{#category.description2}}
              <div class="category-additional-info">
                  {{&category.description2}}
              </div>
          {{/category.description2}}
      </div>
  </div>
  ```
</CodeGroup>

## Available Properties

### Core Category Properties

| Property                | Type   | Description                  |
| ----------------------- | ------ | ---------------------------- |
| `category.name`         | String | Category name                |
| `category.description1` | String | Category description field 1 |
| `category.description2` | String | Category description field 2 |

## Product Listings

For product listings within categories, you'll need to use the product objects as they become available within product loops:

<CodeGroup>
  ```mustache Basic Product Display in Category Context theme={null}
  <div class="products-section">
      <div class="products-header">
          <h2>{{#lang}}Products in{{/lang}} {{category.name}}</h2>
      </div>
      
      <!-- Note: Product loops and properties are handled separately from the category object -->
      <!-- You would use individual product properties within product listing contexts -->
      
      <div class="category-content">
          {{#category.description1}}
              <div class="category-intro">
                  {{&category.description1}}
              </div>
          {{/category.description1}}
          
          {{#category.description2}}
              <div class="category-additional">
                  <h3>{{#lang}}Additional Information{{/lang}}</h3>
                  {{&category.description2}}
              </div>
          {{/category.description2}}
      </div>
  </div>
  ```
</CodeGroup>

## Complete Category Template Example

<CodeGroup>
  ```mustache Complete Category Template theme={null}
  <div class="category-page">
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <!-- Category Header -->
      <header class="category-header">
          <div class="category-intro">
              <h1 class="category-title">{{category.name}}</h1>
              
              {{#category.description1}}
                  <div class="category-description">
                      {{&category.description1}}
                  </div>
              {{/category.description1}}
          </div>
      </header>
      
      <!-- Main Content Area -->
      <div class="category-content">
          <!-- Products would be handled in separate product listing contexts -->
          <!-- The category object only provides basic category information -->
          
          {{#category.description2}}
          <section class="category-additional">
              <h2>{{#lang}}Additional Information{{/lang}}</h2>
              <div class="additional-content">
                  {{&category.description2}}
              </div>
          </section>
          {{/category.description2}}
      </div>
  </div>
  ```
</CodeGroup>

## Usage Notes

<Warning>
  **Limited Category Object**: The category object only provides basic information (name and two description fields). Product listings, subcategories, pagination, and filtering functionality are not part of the category object itself and would need to be implemented through other means in the theme system.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Content Organization" icon="layout">
    Use description1 for main category content and description2 for additional information
  </Card>

  <Card title="SEO Optimization" icon="search">
    Use category names and descriptions effectively for search engine optimization
  </Card>

  <Card title="HTML Content" icon="code">
    Category descriptions support HTML content, use proper markup for structure
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Use semantic HTML and proper heading hierarchy for category content
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Learn about individual product page implementation
  </Card>

  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build category navigation and breadcrumbs
  </Card>

  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Optimize category pages for search engines
  </Card>

  <Card title="Basket Object" icon="shopping-cart" href="/theme-development/global/basket">
    Integrate shopping cart functionality
  </Card>
</CardGroup>


# Order Object
Source: https://quickbutik.dev/theme-development/pages/order

Display order confirmation, thank you pages, and order details

The `order` object contains information about completed orders and is available on order confirmation pages (thank you pages). It provides access to all order details including items, totals, shipping information, and customer data.

<Info>
  **Usage**: Available on order confirmation/thank you pages - use to display order details and confirmation information
</Info>

## Basic Order Information

Access the core order details for confirmation pages:

<CodeGroup>
  ```mustache Basic Order Confirmation theme={null}
  <div class="order-confirmation">
      <header class="order-header">
          <h1>{{#lang}}Thank you for your order!{{/lang}}</h1>
          <p class="order-number">
              {{#lang}}Order number{{/lang}}: <strong>{{order.id}}</strong>
          </p>
      </header>
      
      <div class="order-status">
          <p class="status-message">
              {{#lang}}We have received your order and will process it shortly.{{/lang}}
          </p>
          <p class="email-confirmation">
              {{#lang}}A confirmation email has been sent to{{/lang}} {{order.customer.email}}
          </p>
      </div>
  </div>
  ```

  ```mustache Order Summary Card theme={null}
  <div class="order-summary-card">
      <div class="order-info">
          <h2>{{#lang}}Order Summary{{/lang}}</h2>
          
          <div class="order-details">
              <div class="detail-row">
                  <span class="label">{{#lang}}Order Number{{/lang}}:</span>
                  <span class="value">{{order.id}}</span>
              </div>
              <div class="detail-row">
                  <span class="label">{{#lang}}Total Amount{{/lang}}:</span>
                  <span class="value total">{{order.value}} {{order.currency}}</span>
              </div>
          </div>
      </div>
  </div>
  ```
</CodeGroup>

## Available Properties

### Core Order Properties

| Property                | Type   | Description                              |
| ----------------------- | ------ | ---------------------------------------- |
| `order.id`              | String | Order number                             |
| `order.value`           | String | Order total amount incl. tax (formatted) |
| `order.value_excl_tax`  | String | Order total amount excl. tax (formatted) |
| `order.tax_amount`      | String | Tax amount on order (formatted)          |
| `order.currency`        | String | Currency used for the order              |
| `order.shipping_amount` | String | Shipping cost (formatted)                |
| `order.shipping_name`   | String | Shipping method chosen during order      |
| `order.payment_method`  | String | Payment method used for the order        |

### Customer Properties

| Property                       | Type   | Description             |
| ------------------------------ | ------ | ----------------------- |
| `order.customer.email`         | String | Customer email address  |
| `order.customer.firstname`     | String | Customer first name     |
| `order.customer.lastname`      | String | Customer last name      |
| `order.customer.ship_address`  | String | Customer address Line 1 |
| `order.customer.ship_address2` | String | Customer address Line 2 |
| `order.customer.ship_zipcode`  | String | Customer postal code    |
| `order.customer.ship_city`     | String | Customer city           |
| `order.customer.ship_country`  | String | Customer country        |
| `order.customer.ship_phone`    | String | Customer phone number   |

## Order Items

Display the products that were purchased:

<CodeGroup>
  ```mustache Basic Order Items theme={null}
  <div class="order-items">
      <h3>{{#lang}}Items Ordered{{/lang}}</h3>
      
      <div class="items-list">
          {{#order.items}}
          <div class="order-item">
              <div class="item-details">
                  <h4 class="item-title">{{title}}</h4>
                  <p class="item-sku">{{#lang}}SKU{{/lang}}: {{sku}}</p>
                  
                  {{#variant}}
                      <p class="item-variant">{{variant}}</p>
                  {{/variant}}
                  
                  <div class="item-pricing">
                      <span class="item-price">{{price}}</span>
                      <span class="item-quantity">× {{qty}}</span>
                  </div>
              </div>
          </div>
          {{/order.items}}
      </div>
  </div>
  ```

  ```mustache Detailed Order Items Table theme={null}
  <div class="order-items-table">
      <h3>{{#lang}}Order Details{{/lang}}</h3>
      
      <table class="items-table">
          <thead>
              <tr>
                  <th>{{#lang}}Product{{/lang}}</th>
                  <th>{{#lang}}Price{{/lang}}</th>
                  <th>{{#lang}}Quantity{{/lang}}</th>
              </tr>
          </thead>
          <tbody>
              {{#order.items}}
              <tr class="item-row">
                  <td class="product-info">
                      <div class="product-details">
                          <div class="product-text">
                              <h4>{{title}}</h4>
                              <p class="product-sku">{{sku}}</p>
                              {{#variant}}
                                  <p class="product-variant">{{variant}}</p>
                              {{/variant}}
                          </div>
                      </div>
                  </td>
                  <td class="item-price">{{price}}</td>
                  <td class="item-quantity">{{qty}}</td>
              </tr>
              {{/order.items}}
          </tbody>
          <tfoot>
              {{#order.value_excl_tax}}
              <tr class="subtotal-row">
                  <td colspan="2">{{#lang}}Subtotal (excl. tax){{/lang}}</td>
                  <td>{{order.value_excl_tax}}</td>
              </tr>
              {{/order.value_excl_tax}}
              {{#order.shipping_amount}}
              <tr class="shipping-row">
                  <td colspan="2">{{#lang}}Shipping{{/lang}} ({{order.shipping_name}})</td>
                  <td>{{order.shipping_amount}}</td>
              </tr>
              {{/order.shipping_amount}}
              {{#order.tax_amount}}
              <tr class="tax-row">
                  <td colspan="2">{{#lang}}Tax{{/lang}}</td>
                  <td>{{order.tax_amount}}</td>
              </tr>
              {{/order.tax_amount}}
              <tr class="total-row">
                  <td colspan="2"><strong>{{#lang}}Total{{/lang}}</strong></td>
                  <td><strong>{{order.value}} {{order.currency}}</strong></td>
              </tr>
          </tfoot>
      </table>
  </div>
  ```
</CodeGroup>

### Order Item Properties

When looping through `order.items`, each item has these properties:

| Property     | Type   | Description                           |
| ------------ | ------ | ------------------------------------- |
| `product_id` | String | Product ID                            |
| `title`      | String | Product title                         |
| `sku`        | String | Product/variant article number        |
| `variant_id` | String | Variant ID                            |
| `variant`    | String | Variant designation                   |
| `price`      | String | Product unit price (formatted)        |
| `price_raw`  | String | Product unit price without formatting |
| `qty`        | Number | Quantity ordered of the product       |

## Shipping Information

Display shipping address using the available customer properties:

<CodeGroup>
  ```mustache Shipping Details theme={null}
  <div class="shipping-info">
      <h3>{{#lang}}Shipping Address{{/lang}}</h3>
      
      <div class="address-card">
          <div class="address-name">
              {{order.customer.firstname}} {{order.customer.lastname}}
          </div>
          
          <div class="address-details">
              <p>{{order.customer.ship_address}}</p>
              {{#order.customer.ship_address2}}
                  <p>{{order.customer.ship_address2}}</p>
              {{/order.customer.ship_address2}}
              <p>{{order.customer.ship_zipcode}} {{order.customer.ship_city}}</p>
              <p>{{order.customer.ship_country}}</p>
          </div>
          
          {{#order.customer.ship_phone}}
              <div class="address-phone">
                  <i class="icon-phone"></i>
                  {{order.customer.ship_phone}}
              </div>
          {{/order.customer.ship_phone}}
      </div>
  </div>
  ```

  ```mustache Customer Information theme={null}
  <div class="customer-info">
      <h4>{{#lang}}Customer Information{{/lang}}</h4>
      <div class="customer-details">
          <p class="customer-name">{{order.customer.firstname}} {{order.customer.lastname}}</p>
          <p class="customer-email">{{order.customer.email}}</p>
          {{#order.customer.ship_phone}}
              <p class="customer-phone">{{order.customer.ship_phone}}</p>
          {{/order.customer.ship_phone}}
      </div>
      
      <h4>{{#lang}}Shipping Address{{/lang}}</h4>
      <div class="shipping-address">
          <p>{{order.customer.ship_address}}</p>
          {{#order.customer.ship_address2}}<p>{{order.customer.ship_address2}}</p>{{/order.customer.ship_address2}}
          <p>{{order.customer.ship_zipcode}} {{order.customer.ship_city}}</p>
          <p>{{order.customer.ship_country}}</p>
      </div>
  </div>
  ```
</CodeGroup>

## Payment Information

Display payment method information:

<CodeGroup>
  ```mustache Payment Details theme={null}
  <div class="payment-info">
      <h3>{{#lang}}Payment Information{{/lang}}</h3>
      
      <div class="payment-method">
          <div class="method-details">
              <i class="payment-icon icon-{{order.payment_method}}"></i>
              <span class="method-name">{{order.payment_method}}</span>
          </div>
      </div>
  </div>
  ```
</CodeGroup>

## Customer Support

Provide support information and next steps:

<CodeGroup>
  ```mustache Customer Support theme={null}
  <div class="customer-support">
      <h3>{{#lang}}Need Help?{{/lang}}</h3>
      
      <div class="support-options">
          {{#shop.phone}}
          <div class="support-option">
              <i class="icon-phone"></i>
              <div class="option-content">
                  <h4>{{#lang}}Phone Support{{/lang}}</h4>
                  <p>{{#lang}}Questions about your order?{{/lang}}</p>
                  <a href="tel:{{shop.phone}}">
                      {{shop.phone}}
                  </a>
              </div>
          </div>
          {{/shop.phone}}
      </div>
      
      <div class="support-note">
          <p>{{#lang}}Please have your order number ready when contacting support{{/lang}}: <strong>{{order.id}}</strong></p>
      </div>
  </div>
  ```
</CodeGroup>

## Complete Order Confirmation Example

<CodeGroup>
  ```mustache Complete Order Confirmation Page theme={null}
  <div class="order-confirmation-page">
      <!-- Success Header -->
      <header class="confirmation-header">
          <div class="success-icon">
              <i class="icon-check-circle"></i>
          </div>
          <h1>{{#lang}}Thank you for your order!{{/lang}}</h1>
          <p class="confirmation-message">
              {{#lang}}Your order has been successfully placed and you will receive a confirmation email shortly.{{/lang}}
          </p>
      </header>
      
      <!-- Order Summary -->
      <section class="order-summary">
          <div class="summary-header">
              <h2>{{#lang}}Order Summary{{/lang}}</h2>
              <div class="order-meta">
                  <span class="order-number">{{#lang}}Order{{/lang}} #{{order.id}}</span>
              </div>
          </div>
          
          <!-- Order Items -->
          <div class="order-items">
              {{#order.items}}
              <div class="order-item">
                  <div class="item-details">
                      <h4>{{title}}</h4>
                      {{#variant}}<p class="variant">{{variant}}</p>{{/variant}}
                      <div class="item-pricing">
                          <span>{{price}} × {{qty}}</span>
                      </div>
                  </div>
              </div>
              {{/order.items}}
          </div>
          
          <!-- Order Totals -->
          <div class="order-totals">
              {{#order.value_excl_tax}}
              <div class="total-line">
                  <span>{{#lang}}Subtotal (excl. tax){{/lang}}</span>
                  <span>{{order.value_excl_tax}}</span>
              </div>
              {{/order.value_excl_tax}}
              {{#order.shipping_amount}}
              <div class="total-line">
                  <span>{{#lang}}Shipping{{/lang}} ({{order.shipping_name}})</span>
                  <span>{{order.shipping_amount}}</span>
              </div>
              {{/order.shipping_amount}}
              {{#order.tax_amount}}
              <div class="total-line">
                  <span>{{#lang}}Tax{{/lang}}</span>
                  <span>{{order.tax_amount}}</span>
              </div>
              {{/order.tax_amount}}
              <div class="total-line grand-total">
                  <span>{{#lang}}Total{{/lang}}</span>
                  <span>{{order.value}} {{order.currency}}</span>
              </div>
          </div>
      </section>
      
      <!-- Order Details Grid -->
      <section class="order-details-grid">
          <!-- Customer & Shipping Information -->
          <div class="detail-section">
              <h3>{{#lang}}Customer Information{{/lang}}</h3>
              <div class="customer-info">
                  <p><strong>{{order.customer.firstname}} {{order.customer.lastname}}</strong></p>
                  <p>{{order.customer.email}}</p>
                  {{#order.customer.ship_phone}}<p>{{order.customer.ship_phone}}</p>{{/order.customer.ship_phone}}
              </div>
              
              <h4>{{#lang}}Shipping Address{{/lang}}</h4>
              <div class="address">
                  <p>{{order.customer.ship_address}}</p>
                  {{#order.customer.ship_address2}}<p>{{order.customer.ship_address2}}</p>{{/order.customer.ship_address2}}
                  <p>{{order.customer.ship_zipcode}} {{order.customer.ship_city}}</p>
                  <p>{{order.customer.ship_country}}</p>
              </div>
          </div>
          
          <!-- Payment Information -->
          <div class="detail-section">
              <h3>{{#lang}}Payment & Shipping{{/lang}}</h3>
              <div class="payment-info">
                  <p><strong>{{#lang}}Payment Method{{/lang}}:</strong> {{order.payment_method}}</p>
                  {{#order.shipping_name}}
                      <p><strong>{{#lang}}Shipping Method{{/lang}}:</strong> {{order.shipping_name}}</p>
                  {{/order.shipping_name}}
              </div>
          </div>
      </section>
      
      <!-- Next Steps -->
      <section class="next-steps">
          <h3>{{#lang}}What happens next?{{/lang}}</h3>
          <div class="steps-list">
              <div class="step">
                  <i class="icon-mail"></i>
                  <p>{{#lang}}You'll receive an email confirmation at{{/lang}} {{order.customer.email}}</p>
              </div>
              <div class="step">
                  <i class="icon-package"></i>
                  <p>{{#lang}}We'll process and pack your order{{/lang}}</p>
              </div>
              <div class="step">
                  <i class="icon-truck"></i>
                  <p>{{#lang}}Your order will be shipped using{{/lang}} {{order.shipping_name}}</p>
              </div>
          </div>
      </section>
      
      <!-- Customer Support -->
      <section class="customer-support">
          <h3>{{#lang}}Questions about your order?{{/lang}}</h3>
          <p>{{#lang}}Contact our customer service team with your order number{{/lang}}: <strong>{{order.id}}</strong></p>
          
          <div class="support-contacts">
              {{#shop.phone}}
              <a href="tel:{{shop.phone}}" class="support-link">
                  <i class="icon-phone"></i>
                  {{shop.phone}}
              </a>
              {{/shop.phone}}
          </div>
      </section>
      
      <!-- Continue Shopping -->
      <section class="continue-shopping">
          <a href="/" class="continue-btn">
              {{#lang}}Continue Shopping{{/lang}}
          </a>
      </section>
  </div>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Clear Information" icon="eye">
    Display all essential order information prominently and clearly
  </Card>

  <Card title="Customer Support" icon="headset">
    Provide easy access to customer service with order number context
  </Card>

  <Card title="Email Integration" icon="mail">
    Include order details that match the confirmation email format
  </Card>

  <Card title="Mobile Friendly" icon="mobile">
    Ensure order confirmation works well on all devices
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Product Object" icon="box" href="/theme-development/pages/product">
    Learn about individual product page implementation
  </Card>

  <Card title="Basket Object" icon="shopping-cart" href="/theme-development/global/basket">
    Understand shopping cart and checkout integration
  </Card>

  <Card title="User Object" icon="user" href="/theme-development/global/user">
    Handle customer account and login functionality
  </Card>

  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Optimize confirmation pages for search engines
  </Card>
</CardGroup>


# Product Object
Source: https://quickbutik.dev/theme-development/pages/product

Display individual product information, images, variants, and purchase options

The `product` object contains all information about a single product. It's available on product pages and provides access to everything needed to display product details, handle variants, and enable purchasing.

<Info>
  **Usage**: Available on product pages - use to display product information, images, pricing, variants, and purchase forms
</Info>

## Basic Product Information

Access the core product details that every product page needs:

<CodeGroup>
  ```mustache Basic Product Display theme={null}
  <div class="product-page">
      <h1 class="product-title">{{product.title}}</h1>
      
      <div class="product-meta">
          <p class="product-sku">{{#lang}}SKU{{/lang}}: {{product.sku}}</p>
          {{#product.gtin}}<p class="product-gtin">{{#lang}}EAN{{/lang}}: {{product.gtin}}</p>{{/product.gtin}}
          {{#product.supplier_name}}<p class="product-supplier">{{#lang}}Supplier{{/lang}}: {{product.supplier_name}}</p>{{/product.supplier_name}}
      </div>
      
      <div class="product-price">
          {{#product.has_before_price}}
              <span class="before-price">{{product.before_price}}</span>
          {{/product.has_before_price}}
          <span class="current-price">{{product.price}} {{product.currency}}</span>
      </div>
      
      <div class="product-description">
          {{&product.description}}
      </div>
  </div>
  ```

  ```mustache Product Status theme={null}
  <div class="product-availability">
      {{#product.soldOut}}
          <span class="status sold-out">
              <i class="icon-x-circle"></i>
              {{#lang}}Out of stock{{/lang}}
          </span>
      {{/product.soldOut}}
      
      {{^product.soldOut}}
          <span class="status in-stock">
              <i class="icon-check-circle"></i>
              {{#lang}}In stock{{/lang}}
          </span>
      {{/product.soldOut}}
  </div>
  ```
</CodeGroup>

## Available Properties

### Core Properties

| Property                | Type   | Description                     |
| ----------------------- | ------ | ------------------------------- |
| `product.id`            | String | Product ID                      |
| `product.sku`           | String | Product article number          |
| `product.title`         | String | Product title                   |
| `product.description`   | String | Product description             |
| `product.gtin`          | String | Product EAN code                |
| `product.supplier_name` | String | Product supplier                |
| `product.supplier_sku`  | String | Product supplier article number |

### Pricing Properties

| Property                   | Type    | Description                             |
| -------------------------- | ------- | --------------------------------------- |
| `product.price`            | String  | Product price (formatted)               |
| `product.price_raw`        | String  | Product price without formatting        |
| `product.before_price`     | String  | Product comparison price                |
| `product.has_before_price` | Boolean | Check if product has a comparison price |
| `product.currency`         | String  | Currency                                |

### Stock Properties

| Property          | Type    | Description                      |
| ----------------- | ------- | -------------------------------- |
| `product.soldOut` | Boolean | Check if product is out of stock |

### Custom Data Fields

| Property              | Type   | Description                                                            |
| --------------------- | ------ | ---------------------------------------------------------------------- |
| `product.datafield_1` | String | Custom product information from data field 1                           |
| `product.datafield_2` | String | Custom product information from data field 2                           |
| `product.datafield_x` | String | Custom product information from data field X (replace X with field ID) |

## Product Images

Display product images with responsive optimization:

<CodeGroup>
  ```mustache Basic Image Gallery theme={null}
  <div class="product-gallery">
      {{#product.images}}
      <div class="gallery-item">
          <img src="{{#img}}{{image}}_800x800{{/img}}" 
               alt="{{alttext}}" 
               data-image-id="{{image_id}}"
               loading="lazy">
      </div>
      {{/product.images}}
      
      {{^product.images}}
      <div class="no-image-placeholder">
          <i class="icon-image"></i>
          <span>{{#lang}}No image available{{/lang}}</span>
      </div>
      {{/product.images}}
  </div>
  ```

  ```mustache Advanced Image Gallery theme={null}
  <div class="product-image-gallery">
      <!-- Main image display -->
      <div class="main-image">
          {{#product.firstimage}}
              <img src="{{#img}}{{product.firstimage}}_1000x1000{{/img}}" 
                   alt="{{product.title}}"
                   id="main-product-image">
          {{/product.firstimage}}
          
          {{^product.firstimage}}
              <div class="no-image">
                  <i class="icon-image"></i>
                  <span>{{#lang}}No image{{/lang}}</span>
              </div>
          {{/product.firstimage}}
      </div>
      
      <!-- Thumbnail navigation -->
      {{#product.images}}
      <div class="image-thumbnails">
          {{#product.images}}
          <button class="thumbnail" 
                  data-image="{{#img}}{{image}}_1000x1000{{/img}}"
                  aria-label="{{#lang}}View image{{/lang}} {{image_id}}">
              <img src="{{#img}}{{image}}_100x100{{/img}}" alt="{{alttext}}">
          </button>
          {{/product.images}}
      </div>
      {{/product.images}}
      
      <!-- Secondary image if available -->
      {{#product.secondimage}}
      <div class="secondary-image">
          <img src="{{#img}}{{product.secondimage}}_400x400{{/img}}" 
               alt="{{product.title}} - {{#lang}}Additional view{{/lang}}">
      </div>
      {{/product.secondimage}}
  </div>
  ```
</CodeGroup>

### Image Properties

When looping through `product.images`:

| Property   | Type   | Description    |
| ---------- | ------ | -------------- |
| `image`    | String | Image link     |
| `image_id` | String | Image ID       |
| `alttext`  | String | Image ALT text |

### Special Image Properties

| Property              | Type   | Description            |
| --------------------- | ------ | ---------------------- |
| `product.firstimage`  | String | Product's first image  |
| `product.secondimage` | String | Product's second image |

## Product Variants

Handle product variants (size, color, etc.) and their selection:

<CodeGroup>
  ```mustache Basic Variant Selection theme={null}
  {{#product.hasOptions}}
  <div class="product-variants">
      <h3>{{#lang}}Options{{/lang}}</h3>
      
      {{#product.options}}
      <div class="variant-group">
          <label class="variant-label">{{option_title}}</label>
          
          <select name="variant_{{option_title}}" class="variant-select">
              {{#option_values}}
              <option value="{{id}}">{{name}}</option>
              {{/option_values}}
          </select>
      </div>
      {{/product.options}}
  </div>
  {{/product.hasOptions}}
  ```

  ```mustache Advanced Variant Display theme={null}
  {{#product.hasOptions}}
  <div class="product-options">
      {{#product.options}}
      <div class="option-section">
          <h4 class="option-title">{{option_title}}</h4>
          
          <!-- Option buttons -->
          <div class="option-buttons">
              {{#option_values}}
              <label class="option-button">
                  <input type="radio" 
                         name="variant_{{option_title}}" 
                         value="{{id}}">
                  <span class="button-text">{{name}}</span>
              </label>
              {{/option_values}}
          </div>
      </div>
      {{/product.options}}
  </div>
  {{/product.hasOptions}}
  ```
</CodeGroup>

### Variant Properties

When using `product.options`:

| Property        | Type   | Description                                     |
| --------------- | ------ | ----------------------------------------------- |
| `option_title`  | String | Product option title                            |
| `option_values` | Array  | Object containing Product Option's all Variants |

When looping through `option_values`:

| Property | Type   | Description         |
| -------- | ------ | ------------------- |
| `id`     | String | Variant ID          |
| `name`   | String | Variant designation |

## Add to Cart Form

Create functional purchase forms with variant support:

<CodeGroup>
  ```mustache Basic Add to Cart theme={null}
  {{^product.soldOut}}
  <form action="/cart/add" method="post" class="add-to-cart-form">
      <input type="hidden" name="product_id" value="{{product.id}}">
      
      {{#product.hasOptions}}
          {{#product.options}}
          <input type="hidden" 
                 name="variant_{{option_title}}" 
                 class="variant-input"
                 data-option="{{option_title}}">
          {{/product.options}}
      {{/product.hasOptions}}
      
      <div class="quantity-section">
          <label for="quantity">{{#lang}}Quantity{{/lang}}</label>
          <div class="quantity-controls">
              <button type="button" class="qty-decrease" aria-label="{{#lang}}Decrease quantity{{/lang}}">-</button>
              <input type="number" 
                     name="quantity" 
                     id="quantity" 
                     value="1" 
                     min="1"
                     class="quantity-input">
              <button type="button" class="qty-increase" aria-label="{{#lang}}Increase quantity{{/lang}}">+</button>
          </div>
      </div>
      
      <button type="submit" class="add-to-cart-button">
          <i class="icon-shopping-cart"></i>
          <span>{{#lang}}Add to Cart{{/lang}}</span>
      </button>
  </form>
  {{/product.soldOut}}

  {{#product.soldOut}}
  <div class="sold-out-message">
      <button class="sold-out-button" disabled>
          <i class="icon-x-circle"></i>
          <span>{{#lang}}Out of Stock{{/lang}}</span>
      </button>
  </div>
  {{/product.soldOut}}
  ```
</CodeGroup>

## Related Products

Display related or recommended products using the related\_products object:

<CodeGroup>
  ```mustache Related Products theme={null}
  {{#has_related_products}}
  <section class="related-products">
      <h3>{{#lang}}Related Products{{/lang}}</h3>
      
      <div class="product-grid">
          {{#related_products}}
          <div class="related-product-item">
              <div class="product-link">
                  {{#rp.firstimage}}
                      <img src="{{#img}}{{rp.firstimage}}_300x300{{/img}}" 
                           alt="{{rp.title}}"
                           loading="lazy">
                  {{/rp.firstimage}}
                  
                  <div class="product-info">
                      <h4>{{rp.title}}</h4>
                      <p class="product-sku">{{rp.sku}}</p>
                      
                      {{#rp.supplier_name}}
                          <p class="supplier">{{rp.supplier_name}}</p>
                      {{/rp.supplier_name}}
                      
                      <div class="price">
                          {{#rp.has_before_price}}
                              <span class="before-price">{{rp.before_price}}</span>
                          {{/rp.has_before_price}}
                          <span class="current-price">{{rp.price}}</span>
                      </div>
                      
                      {{#rp.soldOut}}
                          <span class="sold-out-badge">{{#lang}}Out of stock{{/lang}}</span>
                      {{/rp.soldOut}}
                      
                      {{#rp.hasOptions}}
                          <span class="has-variants">{{#lang}}Multiple options{{/lang}}</span>
                      {{/rp.hasOptions}}
                  </div>
              </div>
          </div>
          {{/related_products}}
      </div>
  </section>
  {{/has_related_products}}
  ```
</CodeGroup>

### Related Product Properties

When looping through `related_products`, access properties with `rp.` prefix:

| Property              | Type    | Description                           |
| --------------------- | ------- | ------------------------------------- |
| `rp.title`            | String  | Product title                         |
| `rp.id`               | String  | Product ID                            |
| `rp.sku`              | String  | Product article number                |
| `rp.price`            | String  | Product price                         |
| `rp.before_price`     | String  | Product comparison price              |
| `rp.has_before_price` | Boolean | Check if product has comparison price |
| `rp.description`      | String  | Product description                   |
| `rp.firstimage`       | String  | Product's first image                 |
| `rp.secondimage`      | String  | Product's second image                |
| `rp.soldOut`          | Boolean | Check if product is out of stock      |
| `rp.supplier_name`    | String  | Product supplier                      |
| `rp.supplier_sku`     | String  | Product supplier article number       |
| `rp.hasOptions`       | Boolean | Check if product has variants         |

## Complete Product Page Example

<CodeGroup>
  ```mustache Complete Product Page theme={null}
  <article class="product-page">
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <div class="product-container">
          <!-- Product Images -->
          <div class="product-images">
              <div class="main-image">
                  {{#product.firstimage}}
                      <img src="{{#img}}{{product.firstimage}}_800x800{{/img}}" 
                           alt="{{product.title}}"
                           id="main-image">
                  {{/product.firstimage}}
                  
                  {{^product.firstimage}}
                      <div class="no-image">
                          <i class="icon-image"></i>
                          <span>{{#lang}}No image{{/lang}}</span>
                      </div>
                  {{/product.firstimage}}
              </div>
              
              {{#product.images}}
              <div class="image-thumbnails">
                  {{#product.images}}
                  <button class="thumbnail" data-image="{{#img}}{{image}}_800x800{{/img}}">
                      <img src="{{#img}}{{image}}_100x100{{/img}}" alt="{{alttext}}">
                  </button>
                  {{/product.images}}
              </div>
              {{/product.images}}
              
              {{#product.secondimage}}
              <div class="secondary-image">
                  <img src="{{#img}}{{product.secondimage}}_400x400{{/img}}" 
                       alt="{{product.title}} - {{#lang}}Additional view{{/lang}}">
              </div>
              {{/product.secondimage}}
          </div>
          
          <!-- Product Information -->
          <div class="product-details">
              <header class="product-header">
                  <h1>{{product.title}}</h1>
                  <p class="sku">{{#lang}}SKU{{/lang}}: {{product.sku}}</p>
                  {{#product.gtin}}<p class="gtin">{{#lang}}EAN{{/lang}}: {{product.gtin}}</p>{{/product.gtin}}
                  {{#product.supplier_name}}<p class="supplier">{{#lang}}Supplier{{/lang}}: {{product.supplier_name}}</p>{{/product.supplier_name}}
              </header>
              
              <!-- Pricing -->
              <div class="product-pricing">
                  {{#product.has_before_price}}
                      <span class="original-price">{{product.before_price}}</span>
                      <span class="sale-badge">{{#lang}}Sale{{/lang}}</span>
                  {{/product.has_before_price}}
                  <span class="current-price">{{product.price}} {{product.currency}}</span>
              </div>
              
              <!-- Stock Status -->
              <div class="stock-status">
                  {{#product.soldOut}}
                      <span class="out-of-stock">{{#lang}}Out of stock{{/lang}}</span>
                  {{/product.soldOut}}
                  {{^product.soldOut}}
                      <span class="in-stock">{{#lang}}In stock{{/lang}}</span>
                  {{/product.soldOut}}
              </div>
              
              <!-- Product Variants -->
              {{#product.hasOptions}}
              <div class="product-options">
                  {{#product.options}}
                  <div class="option-group">
                      <label>{{option_title}}</label>
                      <select name="variant_{{option_title}}">
                          {{#option_values}}
                          <option value="{{id}}">{{name}}</option>
                          {{/option_values}}
                      </select>
                  </div>
                  {{/product.options}}
              </div>
              {{/product.hasOptions}}
              
              <!-- Add to Cart Form -->
              {{^product.soldOut}}
              <form action="/cart/add" method="post" class="purchase-form">
                  <input type="hidden" name="product_id" value="{{product.id}}">
                  
                  <div class="quantity-selector">
                      <label for="quantity">{{#lang}}Quantity{{/lang}}</label>
                      <input type="number" name="quantity" id="quantity" value="1" min="1">
                  </div>
                  
                  <button type="submit" class="add-to-cart">
                      {{#lang}}Add to Cart{{/lang}}
                  </button>
              </form>
              {{/product.soldOut}}
              
              <!-- Product Description -->
              <div class="product-description">
                  <h3>{{#lang}}Description{{/lang}}</h3>
                  <div class="description-content">
                      {{&product.description}}
                  </div>
              </div>
              
              <!-- Custom Data Fields -->
              {{#product.datafield_1}}
              <div class="custom-field">
                  <h4>{{#lang}}Additional Information{{/lang}}</h4>
                  <p>{{product.datafield_1}}</p>
              </div>
              {{/product.datafield_1}}
              
              <!-- Supplier Information -->
              {{#product.supplier_name}}
              <div class="supplier-info">
                  <h4>{{#lang}}Supplier Information{{/lang}}</h4>
                  <p><strong>{{#lang}}Supplier{{/lang}}:</strong> {{product.supplier_name}}</p>
                  {{#product.supplier_sku}}
                      <p><strong>{{#lang}}Supplier SKU{{/lang}}:</strong> {{product.supplier_sku}}</p>
                  {{/product.supplier_sku}}
              </div>
              {{/product.supplier_name}}
          </div>
      </div>
      
      <!-- Related Products -->
      {{#has_related_products}}
      <section class="related-products">
          <h3>{{#lang}}You might also like{{/lang}}</h3>
          <div class="related-grid">
              {{#related_products}}
              <div class="related-item">
                  {{#rp.firstimage}}
                      <img src="{{#img}}{{rp.firstimage}}_250x250{{/img}}" alt="{{rp.title}}">
                  {{/rp.firstimage}}
                  <h4>{{rp.title}}</h4>
                  <span class="price">{{rp.price}}</span>
                  {{#rp.soldOut}}
                      <span class="sold-out">{{#lang}}Out of stock{{/lang}}</span>
                  {{/rp.soldOut}}
              </div>
              {{/related_products}}
          </div>
      </section>
      {{/has_related_products}}
  </article>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Image Optimization" icon="image">
    Always use the `{{#img}}` wrapper with appropriate sizes for responsive images
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Include proper alt text, labels, and ARIA attributes for screen readers
  </Card>

  <Card title="Variant Handling" icon="toggle-on">
    Use JavaScript to update pricing and availability when variants change
  </Card>

  <Card title="SEO Optimization" icon="search">
    Include structured data for products to enhance search results
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Category Object" icon="folder" href="/theme-development/pages/category">
    Learn about displaying product listings and category pages
  </Card>

  <Card title="Basket Object" icon="shopping-cart" href="/theme-development/global/basket">
    Understand cart functionality and integration
  </Card>

  <Card title="Order Object" icon="receipt" href="/theme-development/pages/order">
    Display order confirmation and thank you pages
  </Card>

  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Optimize product pages for search engines
  </Card>
</CardGroup>


# Static Pages
Source: https://quickbutik.dev/theme-development/pages/static

Display static content pages using the basic page object

Static pages are content pages that contain information about your store, policies, or other important details. These pages use a `page` object to access basic content.

<Info>
  **Usage**: Available on static content pages - use to display basic page content
</Info>

## Basic Page Information

Access the core page content that is available:

<CodeGroup>
  ```mustache Basic Static Page theme={null}
  <div class="static-page">
      <header class="page-header">
          <h1 class="page-title">{{page.title}}</h1>
      </header>
      
      <div class="page-content">
          {{&page.content}}
      </div>
  </div>
  ```

  ```mustache Static Page with Page Builder Check theme={null}
  <div class="page-container">
      <!-- Page Header -->
      <header class="page-hero">
          <div class="hero-content">
              <h1>{{page.title}}</h1>
          </div>
      </header>
      
      <!-- Page Content -->
      <main class="page-main">
          <div class="container">
              {{#page.qbuilder}}
                  <!-- Content created with Page Builder -->
                  <div class="qbuilder-content">
                      {{&page.content}}
                  </div>
              {{/page.qbuilder}}
              
              {{^page.qbuilder}}
                  <!-- Regular content -->
                  <div class="regular-content">
                      {{&page.content}}
                  </div>
              {{/page.qbuilder}}
          </div>
      </main>
  </div>
  ```
</CodeGroup>

## Available Properties

### Core Page Properties

| Property        | Type    | Description                                           |
| --------------- | ------- | ----------------------------------------------------- |
| `page.title`    | String  | Page title                                            |
| `page.content`  | String  | Main page content (HTML)                              |
| `page.qbuilder` | Boolean | Check if Page Builder was used to create page content |

## Basic Page Template

Create a simple static page layout:

<CodeGroup>
  ```mustache Simple Page Layout theme={null}
  <div class="static-page">
      <!-- Page Header -->
      <section class="page-header">
          <div class="container">
              <h1>{{page.title}}</h1>
          </div>
      </section>
      
      <!-- Main Content -->
      <section class="page-content">
          <div class="container">
              <div class="content-wrapper">
                  {{&page.content}}
              </div>
          </div>
      </section>
  </div>
  ```
</CodeGroup>

## Contact Page Template

Create a basic contact page using available shop information:

<CodeGroup>
  ```mustache Contact Page theme={null}
  <div class="contact-page">
      <!-- Page Header -->
      <header class="contact-header">
          <div class="container">
              <h1>{{page.title}}</h1>
          </div>
      </header>
      
      <!-- Contact Content -->
      <section class="contact-content">
          <div class="container">
              <div class="contact-grid">
                  <!-- Contact Information -->
                  <div class="contact-info">
                      <h2>{{#lang}}Get in Touch{{/lang}}</h2>
                      
                      <!-- Page content -->
                      {{&page.content}}
                      
                      <!-- Available shop contact details -->
                      <div class="contact-details">
                          {{#shop.contact_text}}
                          <div class="contact-item">
                              <div class="contact-text">
                                  {{&shop.contact_text}}
                              </div>
                          </div>
                          {{/shop.contact_text}}
                          
                          {{#shop.address}}
                          <div class="contact-item">
                              <i class="icon-map-pin"></i>
                              <div class="contact-text">
                                  <h4>{{#lang}}Address{{/lang}}</h4>
                                  <p>{{shop.address}}</p>
                                  <p>{{shop.zipcode}} {{shop.city}}</p>
                              </div>
                          </div>
                          {{/shop.address}}
                          
                          {{#shop.phone}}
                          <div class="contact-item">
                              <i class="icon-phone"></i>
                              <div class="contact-text">
                                  <h4>{{#lang}}Phone{{/lang}}</h4>
                                  <p><a href="tel:{{shop.phone}}">{{shop.phone}}</a></p>
                              </div>
                          </div>
                          {{/shop.phone}}
                      </div>
                  </div>
                  
                  <!-- Contact Form -->
                  <div class="contact-form-section">
                      <h2>{{#lang}}Send us a Message{{/lang}}</h2>
                      
                      <form class="contact-form" action="/contact" method="post">
                          <div class="form-row">
                              <div class="form-group">
                                  <label for="contact-name">{{#lang}}Name{{/lang}} *</label>
                                  <input type="text" 
                                         id="contact-name" 
                                         name="name" 
                                         required
                                         placeholder="{{#lang}}Your name{{/lang}}">
                              </div>
                              
                              <div class="form-group">
                                  <label for="contact-email">{{#lang}}Email{{/lang}} *</label>
                                  <input type="email" 
                                         id="contact-email" 
                                         name="email" 
                                         required
                                         placeholder="{{#lang}}Your email{{/lang}}">
                              </div>
                          </div>
                          
                          <div class="form-group">
                              <label for="contact-subject">{{#lang}}Subject{{/lang}}</label>
                              <input type="text" 
                                     id="contact-subject" 
                                     name="subject"
                                     placeholder="{{#lang}}What is this about?{{/lang}}">
                          </div>
                          
                          <div class="form-group">
                              <label for="contact-message">{{#lang}}Message{{/lang}} *</label>
                              <textarea id="contact-message" 
                                        name="message" 
                                        rows="6" 
                                        required
                                        placeholder="{{#lang}}Your message{{/lang}}"></textarea>
                          </div>
                          
                          <div class="form-group">
                              <button type="submit" class="submit-btn">
                                  {{#lang}}Send Message{{/lang}}
                              </button>
                          </div>
                      </form>
                  </div>
              </div>
          </div>
      </section>
  </div>
  ```
</CodeGroup>

## About Page Template

Create a basic about page:

<CodeGroup>
  ```mustache About Page theme={null}
  <div class="about-page">
      <!-- Page Header -->
      <header class="about-header">
          <div class="container">
              <h1>{{page.title}}</h1>
          </div>
      </header>
      
      <!-- Main Content -->
      <section class="about-content">
          <div class="container">
              <div class="content-wrapper">
                  {{&page.content}}
              </div>
          </div>
      </section>
      
      <!-- Call to Action -->
      <section class="about-cta">
          <div class="container">
              <div class="cta-content">
                  <h2>{{#lang}}Ready to get started?{{/lang}}</h2>
                  <p>{{#lang}}Browse our products and find what you're looking for{{/lang}}</p>
                  <a href="/products" class="cta-button">
                      {{#lang}}Shop Now{{/lang}}
                  </a>
              </div>
          </div>
      </section>
  </div>
  ```
</CodeGroup>

## Legal Pages Template

Create professional legal and policy pages:

<CodeGroup>
  ```mustache Legal Page Template theme={null}
  <div class="legal-page">
      <header class="legal-header">
          <div class="container">
              <h1>{{page.title}}</h1>
          </div>
      </header>
      
      <!-- Legal Content -->
      <main class="legal-content">
          <div class="container">
              <div class="content-wrapper">
                  {{&page.content}}
              </div>
          </div>
      </main>
      
      <!-- Contact Information -->
      <footer class="legal-footer">
          <div class="container">
              <div class="legal-contact">
                  <h3>{{#lang}}Questions about this policy?{{/lang}}</h3>
                  <p>{{#lang}}If you have any questions about this policy, please contact us.{{/lang}}</p>
                  
                  <div class="contact-info">
                      {{#shop.address}}
                          <p><strong>{{#lang}}Address{{/lang}}:</strong></p>
                          <p>{{shop.name}}</p>
                          <p>{{shop.address}}</p>
                          <p>{{shop.zipcode}} {{shop.city}}</p>
                      {{/shop.address}}
                  </div>
              </div>
          </div>
      </footer>
  </div>
  ```
</CodeGroup>

## Complete Static Page Example

<CodeGroup>
  ```mustache Generic Static Page theme={null}
  <!DOCTYPE html>
  <html lang="{{shop.language}}">
  <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      
      <!-- Basic SEO -->
      <title>{{page.title}} - {{shop.name}}</title>
      <meta name="description" content="{{page.title}}">
  </head>
  <body>
      <header class="site-header">
          <!-- Include header template -->
      </header>
      
      <main class="page-main">
          <div class="page-container">
              <!-- Breadcrumbs -->
              <nav class="breadcrumbs">
                  {{#breadcrumbs}}
                      <a href="{{url}}">{{title}}</a>
                      {{^last}} > {{/last}}
                  {{/breadcrumbs}}
              </nav>
              
              <!-- Page Content -->
              <article class="page-content">
                  <header class="page-header">
                      <h1>{{page.title}}</h1>
                  </header>
                  
                  <div class="page-body">
                      {{&page.content}}
                  </div>
              </article>
          </div>
      </main>
      
      <footer class="site-footer">
          <!-- Include footer template -->
      </footer>
  </body>
  </html>
  ```
</CodeGroup>

## Usage Notes

<Warning>
  **Limited Page Object**: The page object only provides basic information (title, content, and qbuilder status). Advanced features like SEO properties, featured images, excerpts, publishing dates, and custom settings are not available.
</Warning>

## Best Practices

<CardGroup>
  <Card title="Content Structure" icon="layout">
    Use proper HTML structure within page content for organization
  </Card>

  <Card title="Page Builder Check" icon="wand-magic">
    Use page.qbuilder to handle different content rendering approaches
  </Card>

  <Card title="HTML Content" icon="code">
    Page content supports HTML, use semantic markup for accessibility
  </Card>

  <Card title="Contact Forms" icon="envelope">
    Build contact forms using basic form elements and available shop properties
  </Card>
</CardGroup>

## Common Static Page Types

| Page Type        | Purpose                     | Available Elements               |
| ---------------- | --------------------------- | -------------------------------- |
| About            | Company information         | Basic content, shop name/address |
| Contact          | Contact information         | Contact form, shop address/phone |
| FAQ              | Frequently asked questions  | Basic content structure          |
| Privacy Policy   | Data protection information | Legal content                    |
| Terms of Service | Usage terms and conditions  | Legal content                    |
| Shipping Info    | Delivery information        | Policy content                   |
| Returns          | Return policy               | Process and contact info         |

## Next Steps

<CardGroup>
  <Card title="Navigation Object" icon="bars" href="/theme-development/global/navigation">
    Build static page navigation and breadcrumbs
  </Card>

  <Card title="Shop Object" icon="store" href="/theme-development/global/shop">
    Learn about available shop information properties
  </Card>

  <Card title="SEO Object" icon="search" href="/theme-development/global/seo">
    Basic SEO optimization for static pages
  </Card>

  <Card title="Response Data" icon="message" href="/theme-development/global/response-data">
    Handle contact form responses
  </Card>
</CardGroup>


# Quickstart Tutorial
Source: https://quickbutik.dev/theme-development/quickstart

Build your first custom Quickbutik theme template in 15 minutes

This tutorial will walk you through creating your first custom theme template. You'll learn the core concepts by building a simple product page layout with dynamic content.

<Note>
  **Prerequisites**: Basic knowledge of HTML and CSS. Access to your Quickbutik Control Panel.
</Note>

## What we'll build

By the end of this tutorial, you'll have created a custom product page that:

* ✅ Displays product information dynamically
* ✅ Shows product images in a gallery
* ✅ Handles product variants and stock status
* ✅ Includes an add-to-cart button

## Step 1: Access the Theme Editor

First, let's access your theme files:

<Steps>
  <Step title="Open Control Panel">
    Log into your Quickbutik store and navigate to **Appearance → Theme**
  </Step>

  <Step title="Access Code Editor">
    Click **"Under the hood"** to open the theme code editor
  </Step>

  <Step title="Find Product Template">
    Look for the `product.html` file in the file list - this controls how individual product pages are displayed
  </Step>
</Steps>

## Step 2: Understanding the Basic Structure

Let's start with a simple product page template:

```mustache product.html theme={null}
<!DOCTYPE html>
<html>
<head>
    <title>{{product.title}} - {{shop.name}}</title>
    <meta name="description" content="{{seo.description}}">
</head>
<body>
    <div class="product-page">
        <!-- We'll build our product content here -->
    </div>
</body>
</html>
```

<Accordion title="Understanding the template tags">
  * `{{product.title}}` - Displays the product name
  * `{{shop.name}}` - Shows your store name
  * `{{seo.description}}` - SEO-optimized description for the page
</Accordion>

## Step 3: Add Product Information

Now let's add the core product information:

<CodeGroup>
  ```mustache Basic Product Info theme={null}
  <div class="product-info">
      <h1 class="product-title">{{product.title}}</h1>
      
      <div class="product-price">
          {{#product.has_before_price}}
              <span class="before-price">{{product.before_price}}</span>
          {{/product.has_before_price}}
          <span class="current-price">{{product.price}}</span>
          <span class="currency">{{product.currency}}</span>
      </div>
      
      <div class="product-description">
          {{&product.description}}
      </div>
  </div>
  ```

  ```mustache Stock Status theme={null}
  <div class="stock-status">
      {{#product.soldOut}}
          <span class="out-of-stock">{{#lang}}Out of stock{{/lang}}</span>
      {{/product.soldOut}}
      {{^product.soldOut}}
          <span class="in-stock">{{#lang}}In stock{{/lang}}</span>
      {{/product.soldOut}}
  </div>
  ```
</CodeGroup>

### What's happening here?

<CardGroup>
  <Card title="Price Display" icon="dollar-sign">
    We show both regular and sale prices, with the `has_before_price` conditional showing sale pricing only when relevant.
  </Card>

  <Card title="Stock Status" icon="boxes-stacked">
    Using `#` and `^` operators to show different content based on whether the product is sold out.
  </Card>

  <Card title="Localization" icon="language">
    The `{{#lang}}` wrapper automatically translates text based on your store's language settings.
  </Card>

  <Card title="HTML Content" icon="code">
    The `&` symbol in `{{&product.description}}` renders HTML content without escaping it.
  </Card>
</CardGroup>

## Step 4: Product Image Gallery

Let's create a dynamic image gallery:

```mustache Image Gallery theme={null}
<div class="product-gallery">
    {{#product.images}}
        <div class="gallery-item">
            <img src="{{#img}}{{image}}_800x600{{/img}}" 
                 alt="{{alttext}}" 
                 data-id="{{image_id}}">
        </div>
    {{/product.images}}
    
    {{^product.images}}
        <!-- Fallback for products without images -->
        <div class="no-image">
            <span>{{#lang}}No image available{{/lang}}</span>
        </div>
    {{/product.images}}
</div>
```

<Tip>
  The `{{#img}}` wrapper automatically optimizes images. The `_800x600` suffix resizes the image to 800x600 pixels.
</Tip>

## Step 5: Product Variants

If your product has variants (like size or color), let's display them:

```mustache Product Variants theme={null}
{{#product.hasOptions}}
<div class="product-options">
    <h3>{{#lang}}Options{{/lang}}</h3>
    
    {{#product.options}}
    <div class="option-group">
        <label>{{option_title}}</label>
        <select name="variant_{{option_title}}">
            {{#option_values}}
            <option value="{{id}}">{{name}}</option>
            {{/option_values}}
        </select>
    </div>
    {{/product.options}}
</div>
{{/product.hasOptions}}
```

## Step 6: Add to Cart Button

Finally, let's add a functional add-to-cart button:

```mustache Add to Cart theme={null}
<div class="add-to-cart-section">
    {{^product.soldOut}}
        <form action="/cart/add" method="post">
            <input type="hidden" name="product_id" value="{{product.id}}">
            
            {{#product.hasOptions}}
                <!-- Include variant selection -->
                <div class="variant-selection">
                    <!-- Variant dropdowns will go here -->
                </div>
            {{/product.hasOptions}}
            
            <div class="quantity-selector">
                <label for="quantity">{{#lang}}Quantity{{/lang}}</label>
                <input type="number" name="quantity" value="1" min="1" id="quantity">
            </div>
            
            <button type="submit" class="btn-add-to-cart">
                {{#lang}}Add to Cart{{/lang}}
            </button>
        </form>
    {{/product.soldOut}}
    
    {{#product.soldOut}}
        <button class="btn-sold-out" disabled>
            {{#lang}}Out of Stock{{/lang}}
        </button>
    {{/product.soldOut}}
</div>
```

## Step 7: Complete Example

Here's your complete product page template:

<CodeGroup>
  ```mustache Complete Template theme={null}
  <!DOCTYPE html>
  <html>
  <head>
      <title>{{product.title}} - {{shop.name}}</title>
      <meta name="description" content="{{seo.description}}">
      <style>
          /* Basic styling */
          .product-page { max-width: 1200px; margin: 0 auto; padding: 20px; }
          .product-gallery img { max-width: 100%; height: auto; }
          .before-price { text-decoration: line-through; color: #888; }
          .current-price { font-weight: bold; font-size: 1.2em; }
          .out-of-stock { color: #e74c3c; }
          .in-stock { color: #27ae60; }
          .btn-add-to-cart { background: #3498db; color: white; padding: 12px 24px; border: none; cursor: pointer; }
          .btn-sold-out { background: #95a5a6; color: white; padding: 12px 24px; border: none; }
      </style>
  </head>
  <body>
      <div class="product-page">
          <!-- Product Gallery -->
          <div class="product-gallery">
              {{#product.images}}
                  <img src="{{#img}}{{image}}_800x600{{/img}}" alt="{{alttext}}">
              {{/product.images}}
          </div>
          
          <!-- Product Information -->
          <div class="product-info">
              <h1 class="product-title">{{product.title}}</h1>
              
              <div class="product-price">
                  {{#product.has_before_price}}
                      <span class="before-price">{{product.before_price}}</span>
                  {{/product.has_before_price}}
                  <span class="current-price">{{product.price}}</span>
                  <span class="currency">{{product.currency}}</span>
              </div>
              
              <div class="stock-status">
                  {{#product.soldOut}}
                      <span class="out-of-stock">{{#lang}}Out of stock{{/lang}}</span>
                  {{/product.soldOut}}
                  {{^product.soldOut}}
                      <span class="in-stock">{{#lang}}In stock{{/lang}}</span>
                  {{/product.soldOut}}
              </div>
              
              <div class="product-description">
                  {{&product.description}}
              </div>
              
              <!-- Product Options -->
              {{#product.hasOptions}}
              <div class="product-options">
                  {{#product.options}}
                  <div class="option-group">
                      <label>{{option_title}}</label>
                      <select name="variant_{{option_title}}">
                          {{#option_values}}
                          <option value="{{id}}">{{name}}</option>
                          {{/option_values}}
                      </select>
                  </div>
                  {{/product.options}}
              </div>
              {{/product.hasOptions}}
              
              <!-- Add to Cart -->
              <div class="add-to-cart-section">
                  {{^product.soldOut}}
                      <form action="/cart/add" method="post">
                          <input type="hidden" name="product_id" value="{{product.id}}">
                          <div class="quantity-selector">
                              <label for="quantity">{{#lang}}Quantity{{/lang}}</label>
                              <input type="number" name="quantity" value="1" min="1" id="quantity">
                          </div>
                          <button type="submit" class="btn-add-to-cart">
                              {{#lang}}Add to Cart{{/lang}}
                          </button>
                      </form>
                  {{/product.soldOut}}
                  
                  {{#product.soldOut}}
                      <button class="btn-sold-out" disabled>
                          {{#lang}}Out of Stock{{/lang}}
                      </button>
                  {{/product.soldOut}}
              </div>
          </div>
      </div>
  </body>
  </html>
  ```
</CodeGroup>

## Step 8: Test Your Template

<Steps>
  <Step title="Save your changes">
    Click **Save** in the theme editor
  </Step>

  <Step title="Preview the page">
    Use the preview function to see your changes on a test product
  </Step>

  <Step title="Test different scenarios">
    * Products with/without images
    * Products with/without variants
    * Products that are in stock vs. sold out
  </Step>

  <Step title="Publish when ready">
    When you're satisfied, publish your changes to make them live
  </Step>
</Steps>

## 🎉 Congratulations!

You've successfully created your first custom Quickbutik theme template! You now understand:

* ✅ How to display product data dynamically
* ✅ How to use conditionals for different states
* ✅ How to handle product variants and options
* ✅ How to create functional form elements

## Next Steps

<CardGroup>
  <Card title="Mustache Basics" icon="code" href="/theme-development/mustache-basics">
    Learn more about the templating language fundamentals
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Explore store-wide data like navigation, cart, and settings
  </Card>

  <Card title="Advanced Usage" icon="rocket" href="/theme-development/advanced/dynamic-elements">
    Learn about dynamic elements and complex layouts
  </Card>

  <Card title="Best Practices" icon="star" href="/theme-development/advanced/best-practices">
    Discover performance tips and coding standards
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Template not updating">
    Make sure you clicked **Save** and try clearing your browser cache. Some changes may take a few minutes to appear.
  </Accordion>

  <Accordion title="Missing product data">
    Check that you're viewing the template on a product page. Some data is only available on specific page types.
  </Accordion>

  <Accordion title="Styling issues">
    Remember that your theme's CSS file controls the visual appearance. The template only handles the HTML structure and dynamic content.
  </Accordion>
</AccordionGroup>


# Template Structure
Source: https://quickbutik.dev/theme-development/template-structure

Understanding Quickbutik theme architecture and file organization

# Template Structure

Quickbutik themes are built using the **Mustache** templating language. This guide covers the theme architecture and file organization you need to understand before building your first theme.

## Theme Architecture

### Template Files

Quickbutik themes consist of several template files, each serving a specific purpose:

| Template File     | Purpose                       | Usage                        |
| ----------------- | ----------------------------- | ---------------------------- |
| **Startpage**     | Homepage/Landing page         | Main store entry point       |
| **Produktsida**   | Product detail page           | Individual product display   |
| **Produktlista**  | Product listing/Category page | Product collection views     |
| **Innehållssida** | Static content pages          | About, Terms, Custom pages   |
| **Kontaktsida**   | Contact page                  | Contact form and information |
| **Blog**          | Blog overview                 | Blog post listings           |
| **Blog\_post**    | Individual blog post          | Single blog post display     |
| **Tack-sida**     | Thank you page                | Order confirmation           |

### Accessing Template Files

You can access and edit your theme's source code through your Quickbutik control panel:

**Utseende > Tema > Kod under huven**

<Tip>
  Always make a backup of your theme before making changes, and test thoroughly in a theme under construction before publishing to your live version!
</Tip>

## Data Availability

Understanding which data is available on which templates is crucial for effective theme development:

### Global Objects

Available on **all pages**:

* `shop` - Store settings and configuration
* `user` - Customer login/account information
* `basket` - Shopping cart data
* `seo` - Search engine optimization data
* `linklist` - Navigation menus
* `paylink` - Checkout URL

### Page-Specific Objects

Available only on **specific templates**:

| Object                  | Available On              | Purpose                           |
| ----------------------- | ------------------------- | --------------------------------- |
| `product`               | Produktsida, Produktlista | Product information               |
| `products`              | Produktlista              | Product collection for categories |
| `category`              | Produktlista              | Category information              |
| `order`                 | Tack-sida                 | Order confirmation details        |
| `blog`, `posts`, `post` | Blog pages                | Blog content and navigation       |
| `page`                  | Innehållssida             | Static page content               |
| `response_data`         | Kontaktsida               | Contact form responses            |

## File Organization Best Practices

### CSS and Assets

```
/css/
  styles.css       - Main stylesheet
  responsive.css   - Mobile/tablet styles
  
/js/
  theme.js         - Theme functionality
  
/images/
  logo.png         - Store logo
  placeholders/    - Default images
```

### Template Structure Example

```mustache theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>{{seo.title}} - {{shop.name}}</title>
  <link href="{{#assets}}css/styles.css{{/assets}}" rel="stylesheet">
</head>
<body>
  <!-- Global Header -->
  <header>
    <h1>{{shop.name}}</h1>
    <!-- Navigation available globally -->
    {{#linklist.main}}
      <a href="{{url}}">{{name}}</a>
    {{/linklist.main}}
  </header>

  <!-- Page-specific content varies by template -->
  <main>
    <!-- Content differs based on template file -->
  </main>

  <!-- Global Cart (available everywhere) -->
  <aside>
    {{^basket.isEmpty}}
      <p>{{basket.items_count}} items - {{basket.total_amount}}</p>
    {{/basket.isEmpty}}
  </aside>
</body>
</html>
```

## Template Inheritance Patterns

### Common Header/Footer

Most themes follow this pattern:

1. **Header section** - Logo, navigation, search (same across all pages)
2. **Main content** - Varies by template type
3. **Footer section** - Links, contact info (same across all pages)

### Responsive Considerations

Structure your templates with mobile-first approach:

* Use flexible grid systems
* Optimize images with `{{#img}}` wrapper
* Test on multiple screen sizes

## Next Steps

Now that you understand the theme structure, learn the templating language:

<CardGroup>
  <Card title="Mustache Basics" icon="file-code" href="/theme-development/mustache-basics">
    Learn the fundamentals of Mustache templating
  </Card>

  <Card title="Objects and Attributes" icon="brackets-curly" href="/theme-development/objects-and-attributes">
    How to access and display data in your themes
  </Card>

  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Explore shop, user, and navigation data
  </Card>

  <Card title="Development Setup" icon="tools" href="/theme-development/development-setup">
    Set up your development environment
  </Card>
</CardGroup>


# Wrappers and Functions
Source: https://quickbutik.dev/theme-development/wrappers-and-functions

Master helper functions, data wrappers, and content manipulation in Quickbutik themes

Wrappers and functions in Quickbutik's Mustache implementation provide essential tools for transforming and manipulating data. These helper functions extend Mustache's capabilities for specific use cases like image optimization, translations, and asset linking.

<Info>
  **Prerequisites**: This guide covers the available wrapper functions. Make sure you understand [basic Mustache syntax](/theme-development/mustache-basics) and [object access patterns](/theme-development/objects-and-attributes) first.
</Info>

<Note>
  **Key Concept**: Wrappers use the `{{#function}}content{{/function}}` syntax to process and transform data
</Note>

## Available Wrappers

According to the Quickbutik platform, only the following wrappers are supported:

| Wrapper            | Purpose                                | Usage                                                                     |
| ------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
| `{{#img}}`         | Image manipulation and optimization    | `{{#img}}{{product.firstimage}}_400x400{{/img}}`                          |
| `{{#lang}}`        | Text translation via Control Panel     | `{{#lang}}My text here{{/lang}}`                                          |
| `{{#assets}}`      | Link to correct path for specific file | `{{#assets}}css/style.css{{/assets}}`                                     |
| `{{#breadcrumbs}}` | Output breadcrumbs/category structure  | `{{#breadcrumbs}} {{url}} {{title}} {{^last}} {{/last}} {{/breadcrumbs}}` |
| `{{#asset_flags}}` | Return flag icon for language          | `{{#asset_flags}}{{id}}{{/asset_flags}}`                                  |

## Image Wrapper (`{{#img}}`)

The image wrapper is essential for handling product images and media optimization:

<CodeGroup>
  ```mustache Basic Image Resizing theme={null}
  <!-- Resize image to specific dimensions -->
  <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}">

  <!-- Different sizes for different uses -->
  <img src="{{#img}}{{product.firstimage}}_150x150{{/img}}" alt="{{product.title}}" class="thumbnail">
  <img src="{{#img}}{{product.firstimage}}_800x600{{/img}}" alt="{{product.title}}" class="main-image">
  ```

  ```mustache Product Image Gallery theme={null}
  {{#product.images}}
      <div class="image-item">
          <!-- Thumbnail -->
          <img src="{{#img}}{{image}}_100x100{{/img}}" 
               alt="{{alttext}}"
               class="thumbnail"
               onclick="showLarge('{{#img}}{{image}}_800x800{{/img}}')">
          
          <!-- Hidden large image URL for lightbox -->
          <data value="{{#img}}{{image}}_1200x1200{{/img}}"></data>
      </div>
  {{/product.images}}
  ```

  ```mustache Responsive Images theme={null}
  <!-- Different sizes for different screen sizes -->
  <picture>
      <source media="(max-width: 480px)" 
              srcset="{{#img}}{{product.firstimage}}_300x300{{/img}}">
      <source media="(max-width: 768px)" 
              srcset="{{#img}}{{product.firstimage}}_500x500{{/img}}">
      <source media="(max-width: 1024px)" 
              srcset="{{#img}}{{product.firstimage}}_700x700{{/img}}">
      <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" 
           alt="{{product.title}}">
  </picture>
  ```
</CodeGroup>

### Image Size Options

| Size Format | Description      | Use Case                     |
| ----------- | ---------------- | ---------------------------- |
| `_100x100`  | Square thumbnail | Product grid thumbnails      |
| `_300x200`  | Landscape card   | Product cards, lists         |
| `_400x400`  | Medium square    | Product detail thumbnails    |
| `_800x600`  | Large landscape  | Product detail main image    |
| `_1200x800` | Extra large      | Lightbox, zoom functionality |

### Settings Home Elements Images

<CodeGroup>
  ```mustache Home Elements with Images theme={null}
  {{#settings.home_elements}}
      {{#element}}
          {{#image1_link}}
              <div class="element-image">
                  <img src="{{#img}}{{image1_link}}_800x400{{/img}}" alt="{{title}}">
              </div>
          {{/image1_link}}
          
          {{#use_image2}}
              {{#image2_link}}
                  <div class="element-secondary-image">
                      <img src="{{#img}}{{image2_link}}_400x300{{/img}}" alt="{{title}}">
                  </div>
              {{/image2_link}}
          {{/use_image2}}
      {{/element}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Language Wrapper (`{{#lang}}`)

Handle multi-language content and translations via the Control Panel:

<CodeGroup>
  ```mustache Basic Translation theme={null}
  <!-- Simple text translation -->
  <h1>{{#lang}}Welcome to our store{{/lang}}</h1>
  <button>{{#lang}}Add to Cart{{/lang}}</button>
  <p>{{#lang}}Free shipping on orders over $50{{/lang}}</p>
  ```

  ```mustache Dynamic Content Translation theme={null}
  <!-- Translate dynamic content with context -->
  <div class="product-status">
      {{#product.soldOut}}
          <span class="out-of-stock">{{#lang}}Out of Stock{{/lang}}</span>
      {{/product.soldOut}}
      
      {{^product.soldOut}}
          <span class="in-stock">{{#lang}}In Stock{{/lang}}</span>
      {{/product.soldOut}}
  </div>

  <div class="basket-info">
      {{#basket.isEmpty}}
          <p>{{#lang}}Your cart is empty{{/lang}}</p>
      {{/basket.isEmpty}}
      
      {{^basket.isEmpty}}
          <p>{{basket.items_count}} {{#lang}}items in cart{{/lang}}</p>
      {{/basket.isEmpty}}
  </div>
  ```

  ```mustache Form Labels and Messages theme={null}
  <!-- Translate form elements -->
  <form class="contact-form">
      <label for="name">{{#lang}}Name{{/lang}} *</label>
      <input type="text" id="name" placeholder="{{#lang}}Enter your name{{/lang}}">
      
      <label for="email">{{#lang}}Email{{/lang}} *</label>
      <input type="email" id="email" placeholder="{{#lang}}Enter your email{{/lang}}">
      
      <label for="message">{{#lang}}Message{{/lang}}</label>
      <textarea id="message" placeholder="{{#lang}}Write your message here{{/lang}}"></textarea>
      
      <button type="submit">{{#lang}}Send Message{{/lang}}</button>
  </form>
  ```
</CodeGroup>

### Navigation and UI Translation

<CodeGroup>
  ```mustache Navigation Translation theme={null}
  <!-- Translate navigation elements -->
  <nav class="main-navigation">
      {{#linklist.main}}
          <a href="{{url}}" class="nav-link {{#current}}active{{/current}}">
              {{#lang}}{{name}}{{/lang}}
          </a>
      {{/linklist.main}}
  </nav>

  <!-- Translate common UI elements -->
  <div class="user-actions">
      {{#shop.login_active}}
          {{#user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
          {{/user.logged_in}}
          
          {{^user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
          {{/user.logged_in}}
      {{/shop.login_active}}
  </div>
  ```
</CodeGroup>

## Assets Wrapper (`{{#assets}}`)

Link to correct paths for theme files like CSS, JavaScript, and other assets:

<CodeGroup>
  ```mustache CSS and JavaScript Assets theme={null}
  <!-- Link to theme CSS files -->
  <link rel="stylesheet" href="{{#assets}}css/style.css{{/assets}}">
  <link rel="stylesheet" href="{{#assets}}css/responsive.css{{/assets}}">

  <!-- Link to theme JavaScript files -->
  <script src="{{#assets}}js/main.js{{/assets}}"></script>
  <script src="{{#assets}}js/cart.js{{/assets}}"></script>
  ```

  ```mustache Image and Font Assets theme={null}
  <!-- Link to theme images -->
  <img src="{{#assets}}images/logo.png{{/assets}}" alt="{{shop.name}}">
  <img src="{{#assets}}images/placeholder.jpg{{/assets}}" alt="{{#lang}}No image available{{/lang}}">

  <!-- Link to theme fonts -->
  <link rel="preload" href="{{#assets}}fonts/custom-font.woff2{{/assets}}" as="font" type="font/woff2" crossorigin>
  ```

  ```mustache Icon and Resource Assets theme={null}
  <!-- Link to theme icons -->
  <link rel="icon" href="{{#assets}}images/favicon.ico{{/assets}}">
  <link rel="apple-touch-icon" href="{{#assets}}images/apple-touch-icon.png{{/assets}}">

  <!-- Link to other theme resources -->
  <link rel="manifest" href="{{#assets}}manifest.json{{/assets}}">
  ```
</CodeGroup>

## Breadcrumbs Wrapper (`{{#breadcrumbs}}`)

Output breadcrumbs/category structure regardless of the current page:

<CodeGroup>
  ```mustache Basic Breadcrumbs theme={null}
  <!-- Simple breadcrumb navigation -->
  <nav class="breadcrumbs">
      {{#breadcrumbs}}
          <a href="{{url}}">{{title}}</a>
          {{^last}} > {{/last}}
      {{/breadcrumbs}}
  </nav>
  ```

  ```mustache Styled Breadcrumbs theme={null}
  <!-- Enhanced breadcrumb navigation with styling -->
  <nav class="breadcrumb-navigation" aria-label="{{#lang}}Breadcrumb{{/lang}}">
      <ol class="breadcrumb-list">
          {{#breadcrumbs}}
          <li class="breadcrumb-item {{#last}}current{{/last}}">
              {{#last}}
                  <span aria-current="page">{{title}}</span>
              {{/last}}
              {{^last}}
                  <a href="{{url}}">{{title}}</a>
              {{/last}}
          </li>
          {{/breadcrumbs}}
      </ol>
  </nav>
  ```

  ```mustache Breadcrumbs with Icons theme={null}
  <!-- Breadcrumbs with separators and icons -->
  <nav class="breadcrumbs-with-icons">
      {{#breadcrumbs}}
          <span class="breadcrumb-item">
              {{^last}}
                  <a href="{{url}}" class="breadcrumb-link">
                      <span>{{title}}</span>
                  </a>
                  <i class="breadcrumb-separator">›</i>
              {{/last}}
              {{#last}}
                  <span class="breadcrumb-current">{{title}}</span>
              {{/last}}
          </span>
      {{/breadcrumbs}}
  </nav>
  ```
</CodeGroup>

### Breadcrumb Properties

Within the `{{#breadcrumbs}}` loop:

| Property | Type    | Description                                        |
| -------- | ------- | -------------------------------------------------- |
| `url`    | String  | Link URL for the breadcrumb item                   |
| `title`  | String  | Display text for the breadcrumb item               |
| `last`   | Boolean | True if this is the last (current) breadcrumb item |

## Asset Flags Wrapper (`{{#asset_flags}}`)

Return flag icons for languages (used within the languages loop):

<CodeGroup>
  ```mustache Language Selector with Flags theme={null}
  {{#shop.app.languages}}
  <div class="language-selector">
      <h4>{{#lang}}Choose Language{{/lang}}</h4>
      {{#shop.languages}}
      <a href="{{url}}" class="language-option">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" 
               alt="{{id}}" 
               class="flag">
          {{id}}
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```

  ```mustache Compact Language Switcher theme={null}
  {{#shop.app.languages}}
  <div class="lang-switcher">
      {{#shop.languages}}
      <a href="{{url}}" class="lang-link" title="{{id}}">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```

  ```mustache Language Dropdown theme={null}
  {{#shop.app.languages}}
  <div class="language-dropdown">
      <button class="language-toggle">
          {{#shop.languages}}
              {{#current}}
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
                  {{id}}
              {{/current}}
          {{/shop.languages}}
      </button>
      
      <div class="language-options">
          {{#shop.languages}}
          <a href="{{url}}" class="language-option">
              <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
              {{id}}
          </a>
          {{/shop.languages}}
      </div>
  </div>
  {{/shop.app.languages}}
  ```
</CodeGroup>

## Combining Wrappers

### Complete Examples with Multiple Wrappers

<CodeGroup>
  ```mustache Product Card with All Wrappers theme={null}
  <div class="product-card">
      <!-- Product image with optimization -->
      <div class="product-image">
          {{#product.firstimage}}
              <img src="{{#img}}{{product.firstimage}}_300x300{{/img}}" alt="{{product.title}}">
          {{/product.firstimage}}
          {{^product.firstimage}}
              <img src="{{#assets}}images/no-image.png{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
          {{/product.firstimage}}
      </div>
      
      <!-- Product information with translations -->
      <div class="product-info">
          <h3>{{product.title}}</h3>
          <p class="price">{{product.price}}</p>
          
          {{#product.soldOut}}
              <span class="status out-of-stock">{{#lang}}Out of Stock{{/lang}}</span>
          {{/product.soldOut}}
          
          {{^product.soldOut}}
              <button class="add-to-cart">{{#lang}}Add to Cart{{/lang}}</button>
          {{/product.soldOut}}
      </div>
  </div>
  ```

  ```mustache Complete Page Template theme={null}
  <!DOCTYPE html>
  <html>
  <head>
      <title>{{seo.title}}</title>
      <meta name="description" content="{{seo.description}}">
      
      <!-- Theme assets -->
      <link rel="stylesheet" href="{{#assets}}css/style.css{{/assets}}">
      <link rel="icon" href="{{#assets}}images/favicon.ico{{/assets}}">
  </head>
  <body>
      <header class="site-header">
          <!-- Logo -->
          <div class="logo">
              <a href="{{shop.url}}">
                  <img src="{{#assets}}images/logo.png{{/assets}}" alt="{{shop.name}}">
              </a>
          </div>
          
          <!-- Language selector -->
          {{#shop.app.languages}}
          <div class="language-selector">
              {{#shop.languages}}
              <a href="{{url}}">
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
              </a>
              {{/shop.languages}}
          </div>
          {{/shop.app.languages}}
          
          <!-- User account -->
          {{#shop.login_active}}
          <div class="account-links">
              {{#user.logged_in}}
                  <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
              {{/user.logged_in}}
              {{^user.logged_in}}
                  <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
              {{/user.logged_in}}
          </div>
          {{/shop.login_active}}
      </header>
      
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <main class="main-content">
          <!-- Page content here -->
      </main>
      
      <footer class="site-footer">
          <p>&copy; {{shop.name}}. {{#lang}}All rights reserved{{/lang}}.</p>
      </footer>
      
      <!-- Theme JavaScript -->
      <script src="{{#assets}}js/main.js{{/assets}}"></script>
  </body>
  </html>
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Image Optimization" icon="image">
    Always use the `{{#img}}` wrapper with appropriate dimensions for optimal performance
  </Card>

  <Card title="Translation Consistency" icon="language">
    Wrap all user-facing text with `{{#lang}}` for proper multi-language support
  </Card>

  <Card title="Asset Management" icon="folder">
    Use `{{#assets}}` for all theme files to ensure correct paths across environments
  </Card>

  <Card title="Breadcrumb Navigation" icon="map">
    Implement breadcrumbs for better user navigation and SEO benefits
  </Card>
</CardGroup>

## Common Patterns

### Error Handling and Fallbacks

<CodeGroup>
  ```mustache Image Fallbacks theme={null}
  <!-- Product image with fallback -->
  {{#product.firstimage}}
      <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}">
  {{/product.firstimage}}
  {{^product.firstimage}}
      <img src="{{#assets}}images/placeholder.jpg{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
  {{/product.firstimage}}
  ```

  ```mustache Content Fallbacks theme={null}
  <!-- Content with translation fallback -->
  {{#shop.contact_text}}
      <div class="contact-content">
          {{&shop.contact_text}}
      </div>
  {{/shop.contact_text}}
  {{^shop.contact_text}}
      <div class="contact-content">
          <p>{{#lang}}Contact information not available{{/lang}}</p>
      </div>
  {{/shop.contact_text}}
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Learn how to use wrappers with global object data
  </Card>

  <Card title="Product Pages" icon="box" href="/theme-development/pages/product">
    Apply wrappers in product page templates
  </Card>

  <Card title="Template Structure" icon="file-code" href="/theme-development/template-structure">
    Understand how wrappers fit into overall theme architecture
  </Card>

  <Card title="Best Practices" icon="star" href="/theme-development/advanced/best-practices">
    Follow coding standards and optimization guidelines
  </Card>
</CardGroup>


# Events
Source: https://quickbutik.dev/webhooks/events



Available Events:

**order**

* event\_type: order.new

> New order (paid). Sent with parameter `order_id`.

* event\_type: order.done

> Order marked as done (sent). Sent with parameter `order_id`.

* event\_type: order.cancelled

> Order marked as cancelled. Sent with parameter `order_id`.

**product**

* event\_type: product.add

> Product added. Sent with parameter `product_id`.

* event\_type: product.update

> Product updated. Sent with parameter `product_id`.

* event\_type: product.delete

> Product deleted. Sent with parameter `product_id`.


# Webhooks
Source: https://quickbutik.dev/webhooks/introduction

Get real-time notifications when events occur in your Quickbutik store

Webhooks allow your application to receive real-time notifications when important events happen in your Quickbutik store. Instead of constantly polling the API, webhooks push data to your application immediately when events occur.

<Info>
  **Common use cases:**

  * Sync new orders to your fulfillment system instantly
  * Update inventory levels across multiple platforms
  * Send custom order confirmations or notifications
  * Trigger automated workflows and integrations
</Info>

## How Webhooks Work

When an event occurs in your store (like a new order), Quickbutik sends an HTTP GET request to your configured webhook URL with event details as query parameters.

```mermaid theme={null}
sequenceDiagram
    participant QS as Quickbutik Store
    participant QW as Quickbutik Webhooks
    participant YE as Your Endpoint
    participant YS as Your System

    QS->>QW: Order Created
    QW->>YE: GET /webhook?event_type=order.new&order_id=12345
    YE->>YE: Acknowledge (200 OK)
    YE->>YS: Process Order Async
    YS->>QS: Fetch Order Details (API)
```

## Quick Setup

<Steps>
  <Step title="Create webhook endpoint">
    Set up an endpoint in your application to receive webhook notifications

    ```javascript theme={null}
    app.get('/webhooks/quickbutik', (req, res) => {
      const { event_type, order_id, product_id } = req.query;
      
      // Always respond quickly
      res.status(200).send('OK');
      
      // Process webhook asynchronously
      processWebhook(event_type, { order_id, product_id });
    });
    ```
  </Step>

  <Step title="Configure in Quickbutik">
    Enable webhooks in your Quickbutik Control Panel under **Settings → Webhooks** and add your endpoint URL
  </Step>

  <Step title="Handle events">
    Process the webhook events in your application based on the event type
  </Step>
</Steps>

## Event Structure

All webhook requests are sent as GET requests with the following query parameters:

| Parameter    | Description                     | Example                       |
| ------------ | ------------------------------- | ----------------------------- |
| `event_type` | The type of event that occurred | `order.new`, `product.update` |
| `order_id`   | Order ID (for order events)     | `12345`                       |
| `product_id` | Product ID (for product events) | `67890`                       |

### Example Webhook Request

```
GET /your-webhook-endpoint?event_type=order.new&order_id=12345
Host: your-domain.com
User-Agent: Quickbutik-Webhooks/1.0
```

## Complete Example

Here's a complete webhook handler that processes different event types:

<CodeGroup>
  ```javascript Express.js theme={null}
  const express = require('express');
  const QuickbutikAPI = require('./quickbutik-api');

  const app = express();
  const api = new QuickbutikAPI(process.env.QUICKBUTIK_API_KEY);

  app.get('/webhooks/quickbutik', async (req, res) => {
    const { event_type, order_id, product_id } = req.query;
    
    console.log(`Received webhook: ${event_type}`, { order_id, product_id });
    
    // Acknowledge webhook immediately (important!)
    res.status(200).send('OK');
    
    try {
      // Process webhook asynchronously
      switch (event_type) {
        case 'order.new':
          await handleNewOrder(order_id);
          break;
        case 'order.done':
          await handleOrderShipped(order_id);
          break;
        case 'order.cancelled':
          await handleOrderCancelled(order_id);
          break;
        case 'product.add':
          await handleProductAdded(product_id);
          break;
        case 'product.update':
          await handleProductUpdated(product_id);
          break;
        case 'product.delete':
          await handleProductDeleted(product_id);
          break;
        default:
          console.log(`Unhandled event type: ${event_type}`);
      }
    } catch (error) {
      console.error(`Error processing webhook ${event_type}:`, error);
      
      // In production, add to retry queue or send alert
      await handleWebhookError(event_type, { order_id, product_id }, error);
    }
  });

  async function handleNewOrder(orderId) {
    console.log(`Processing new order: ${orderId}`);
    
    // Fetch complete order details
    const orders = await api.getOrders({ 
      order_id: orderId,
      include_details: true 
    });
    
    if (orders && orders.length > 0) {
      const order = orders[0];
      
      // Your business logic here
      await processNewOrder(order);
      console.log(`Successfully processed order ${orderId}`);
    }
  }

  async function handleProductUpdated(productId) {
    console.log(`Processing product update: ${productId}`);
    
    // Fetch updated product details
    const products = await api.getProducts({ 
      product_id: productId,
      include_details: true 
    });
    
    if (products && products.length > 0) {
      const product = products[0];
      
      // Your business logic here
      await syncProductToExternalSystem(product);
      console.log(`Successfully synced product ${productId}`);
    }
  }

  app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
  });
  ```

  ```python Flask theme={null}
  from flask import Flask, request, jsonify
  import asyncio
  import logging
  from quickbutik_api import QuickbutikAPI

  app = Flask(__name__)
  logging.basicConfig(level=logging.INFO)

  api = QuickbutikAPI(os.getenv('QUICKBUTIK_API_KEY'))

  @app.route('/webhooks/quickbutik', methods=['GET'])
  def quickbutik_webhook():
      event_type = request.args.get('event_type')
      order_id = request.args.get('order_id')
      product_id = request.args.get('product_id')
      
      app.logger.info(f'Received webhook: {event_type}, order_id: {order_id}, product_id: {product_id}')
      
      # Acknowledge webhook immediately (important!)
      response = jsonify({'status': 'received'})
      
      # Process webhook asynchronously
      try:
          if event_type == 'order.new':
              asyncio.create_task(handle_new_order(order_id))
          elif event_type == 'order.done':
              asyncio.create_task(handle_order_shipped(order_id))
          elif event_type == 'order.cancelled':
              asyncio.create_task(handle_order_cancelled(order_id))
          elif event_type == 'product.add':
              asyncio.create_task(handle_product_added(product_id))
          elif event_type == 'product.update':
              asyncio.create_task(handle_product_updated(product_id))
          elif event_type == 'product.delete':
              asyncio.create_task(handle_product_deleted(product_id))
          else:
              app.logger.info(f'Unhandled event type: {event_type}')
      except Exception as error:
          app.logger.error(f'Error processing webhook {event_type}: {error}')
          asyncio.create_task(handle_webhook_error(event_type, {'order_id': order_id, 'product_id': product_id}, error))
      
      return response, 200

  async def handle_new_order(order_id):
      app.logger.info(f'Processing new order: {order_id}')
      
      try:
          # Fetch complete order details
          orders = await api.get_orders(order_id=order_id, include_details=True)
          
          if orders:
              order = orders[0]
              
              # Your business logic here
              await process_new_order(order)
              app.logger.info(f'Successfully processed order {order_id}')
      except Exception as error:
          app.logger.error(f'Failed to process order {order_id}: {error}')

  async def handle_product_updated(product_id):
      app.logger.info(f'Processing product update: {product_id}')
      
      try:
          # Fetch updated product details
          products = await api.get_products(product_id=product_id, include_details=True)
          
          if products:
              product = products[0]
              
              # Your business logic here
              await sync_product_to_external_system(product)
              app.logger.info(f'Successfully synced product {product_id}')
      except Exception as error:
          app.logger.error(f'Failed to sync product {product_id}: {error}')

  if __name__ == '__main__':
      app.run(debug=True, port=3000)
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Respond Quickly" icon="clock">
    **Always respond with 200 OK within 10 seconds** to acknowledge receipt. Process the actual work asynchronously.
  </Card>

  <Card title="Handle Retries" icon="arrows-rotate">
    **Webhooks may be sent multiple times** if your endpoint doesn't respond. Make your processing idempotent.
  </Card>

  <Card title="Validate Events" icon="shield-check">
    **Verify webhook authenticity** in production environments using request validation.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    **Implement proper error handling** and retry mechanisms for failed webhook processing.
  </Card>
</CardGroup>

<Warning>
  **Important Considerations:**

  * Webhooks are sent as GET requests (not POST)
  * Always acknowledge webhooks quickly to avoid retries
  * Events may be delivered more than once - ensure idempotent processing
  * Use the API to fetch complete data when processing webhooks
</Warning>

## Testing Webhooks

Use tools like ngrok to test webhooks locally:

<CodeGroup>
  ```bash Terminal theme={null}
  # Install ngrok
  npm install -g ngrok

  # Start your webhook server
  node webhook-server.js

  # In another terminal, expose your local server
  ngrok http 3000

  # Use the ngrok URL in your Quickbutik webhook settings
  # Example: https://abc123.ngrok.io/webhooks/quickbutik
  ```

  ```javascript Testing Script theme={null}
  // Simple webhook tester
  const express = require('express');
  const app = express();

  app.get('/webhooks/quickbutik', (req, res) => {
    console.log('Webhook received:', {
      event_type: req.query.event_type,
      order_id: req.query.order_id,
      product_id: req.query.product_id,
      timestamp: new Date().toISOString()
    });
    
    res.status(200).send('Webhook received successfully');
  });

  app.listen(3000, () => {
    console.log('Webhook test server running on http://localhost:3000');
    console.log('Test URL: http://localhost:3000/webhooks/quickbutik');
  });
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Event Types" icon="list" href="/webhooks/events">
    Explore all available webhook events and their data
  </Card>

  <Card title="Setup Guide" icon="gear" href="/webhooks/setup">
    Detailed webhook configuration and troubleshooting
  </Card>
</CardGroup>


# Webhook Setup
Source: https://quickbutik.dev/webhooks/setup

Configure and troubleshoot your webhook endpoints

This guide walks you through setting up webhooks in your Quickbutik store and configuring your application to receive and process webhook events reliably.

## Configuration in Quickbutik

<Steps>
  <Step title="Access webhook settings">
    Log into your Quickbutik Control Panel and navigate to **Settings → Webhooks**
  </Step>

  <Step title="Add webhook URL">
    Enter your webhook endpoint URL where you want to receive notifications:

    ```
    https://your-domain.com/webhooks/quickbutik
    ```

    <Note>
      Your webhook URL must be publicly accessible and respond to GET requests. Use HTTPS in production for security.
    </Note>
  </Step>

  <Step title="Select events">
    Choose which events should trigger webhook notifications:

    * **Order events**: `order.new`, `order.done`, `order.cancelled`
    * **Product events**: `product.add`, `product.update`, `product.delete`
  </Step>

  <Step title="Test your webhook">
    Use the test function in the Quickbutik panel to verify your endpoint is working correctly
  </Step>
</Steps>

## Development Setup

For local development, use a tool like ngrok to expose your local server:

<CodeGroup>
  ```bash Terminal theme={null}
  # Install ngrok
  npm install -g ngrok

  # Start your local webhook server
  node webhook-server.js

  # In another terminal, expose your local server
  ngrok http 3000

  # Copy the ngrok URL to your Quickbutik webhook settings
  # Example: https://abc123.ngrok.io/webhooks/quickbutik
  ```

  ```javascript Local Server theme={null}
  const express = require('express');
  const app = express();

  app.get('/webhooks/quickbutik', (req, res) => {
    console.log('Webhook received:', {
      event_type: req.query.event_type,
      order_id: req.query.order_id,
      product_id: req.query.product_id,
      timestamp: new Date().toISOString(),
      ip: req.ip,
      headers: req.headers
    });
    
    res.status(200).send('OK');
  });

  app.listen(3000, () => {
    console.log('Webhook server listening on port 3000');
  });
  ```
</CodeGroup>

## Production Deployment

For production environments, ensure your webhook endpoint is robust and scalable:

<CodeGroup>
  ```javascript Production Webhook theme={null}
  const express = require('express');
  const rateLimit = require('express-rate-limit');
  const helmet = require('helmet');

  const app = express();

  // Security middleware
  app.use(helmet());

  // Rate limiting
  const webhookLimiter = rateLimit({
    windowMs: 1 * 60 * 1000, // 1 minute
    max: 100, // limit each IP to 100 requests per windowMs
    message: 'Too many webhook requests from this IP',
    standardHeaders: true,
    legacyHeaders: false,
  });

  app.use('/webhooks', webhookLimiter);

  // Health check endpoint
  app.get('/health', (req, res) => {
    res.status(200).json({
      status: 'healthy',
      timestamp: new Date().toISOString()
    });
  });

  // Webhook endpoint
  app.get('/webhooks/quickbutik', async (req, res) => {
    const { event_type, order_id, product_id } = req.query;
    
    // Log webhook receipt
    console.log(`Webhook received: ${event_type}`, {
      order_id,
      product_id,
      timestamp: new Date().toISOString(),
      ip: req.ip
    });
    
    // Respond immediately
    res.status(200).send('OK');
    
    try {
      // Add to processing queue
      await addToQueue({
        event_type,
        order_id,
        product_id,
        received_at: new Date().toISOString()
      });
    } catch (error) {
      console.error('Failed to queue webhook:', error);
      
      // Send alert but don't fail the webhook response
      await sendAlert({
        type: 'webhook_queue_error',
        event_type,
        error: error.message
      });
    }
  });

  async function addToQueue(webhookData) {
    // Add to Redis queue, SQS, or your preferred queue system
    // This ensures webhook processing doesn't block the response
    
    if (process.env.REDIS_URL) {
      const redis = require('redis');
      const client = redis.createClient({ url: process.env.REDIS_URL });
      await client.lPush('webhook_queue', JSON.stringify(webhookData));
    }
  }

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Webhook server running on port ${PORT}`);
  });
  ```

  ```dockerfile Dockerfile theme={null}
  FROM node:18-alpine

  WORKDIR /app

  # Install dependencies
  COPY package*.json ./
  RUN npm ci --only=production

  # Copy application
  COPY . .

  # Create non-root user
  RUN addgroup -g 1001 -S webhook
  RUN adduser -S webhook -u 1001

  # Security
  RUN chown -R webhook:webhook /app
  USER webhook

  # Health check
  HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:3000/health || exit 1

  EXPOSE 3000

  CMD ["node", "webhook-server.js"]
  ```
</CodeGroup>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Webhook not receiving events">
    **Possible causes:**

    * Webhook URL is not publicly accessible
    * Firewall blocking incoming requests
    * Server not running or crashed
    * Wrong endpoint path configured

    **Solutions:**

    * Test your endpoint with curl: `curl "https://your-domain.com/webhooks/quickbutik?event_type=test"`
    * Check server logs for errors
    * Verify webhook URL in Quickbutik settings
    * Use tools like ngrok for local testing
  </Accordion>

  <Accordion title="Getting timeout errors">
    **Possible causes:**

    * Webhook handler takes too long to respond
    * Processing heavy operations synchronously
    * Database or external API calls blocking response

    **Solutions:**

    * Always respond with 200 OK immediately
    * Process webhook data asynchronously
    * Use queue systems for heavy processing
    * Implement timeout handling
  </Accordion>

  <Accordion title="Receiving duplicate events">
    **Possible causes:**

    * Webhook endpoint responding slowly or with errors
    * Network issues causing retries
    * Processing failures triggering redelivery

    **Solutions:**

    * Implement idempotent processing
    * Store processed webhook IDs to prevent duplicates
    * Respond quickly with 200 OK
    * Use database transactions for atomic operations
  </Accordion>

  <Accordion title="Missing webhook events">
    **Possible causes:**

    * Endpoint was down during event
    * Processing errors causing webhook to be marked as failed
    * Rate limiting rejecting webhooks

    **Solutions:**

    * Implement reliable webhook processing with retries
    * Monitor webhook endpoint uptime
    * Use dead letter queues for failed webhooks
    * Regularly poll API for missed events as backup
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Event Types" icon="list" href="/webhooks/events">
    Explore all available webhook events and their data
  </Card>
</CardGroup>