Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.komerza.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Access your store’s public information including name, description, logo, banner, and currency settings.

​
Get Store Details

Retrieve complete information about your store. 
const response = await komerza.getStore();

​
Returns

Returns ApiResponse<Store>: 
interface Store {
  id: string; // Store identifier
  name: string; // Store name
  description: string; // Store description (supports markdown)
  url: string; // Store subdomain
  customDomain?: string; // Custom domain if set
  currencyCode: string; // ISO 4217 currency code (e.g., "USD")
  domain: string; // Full domain
  rating: number; // Average store rating
  maintenanceReason?: string; // If store is in maintenance mode
  branding?: {
    iconFileName?: string; // Logo filename
    bannerFileName?: string; // Banner filename
    accentColor?: string; // Store accent color
    isAutomaticCurrencyConversionEnabled?: boolean;
  };
  products: ProductReference[]; // List of products
  categories: Category[]; // List of store categories
  affiliateOptions?: {
    isEnabled: boolean;
    defaultReturnPercentage: number;
    defaultPercentageOff: number;
    canConvertAffiliateBalance: boolean;
    isPublicRegistrationEnabled: boolean;
    isLinkEditingEnabled: boolean;
  };
  dateCreated: string; // ISO 8601 timestamp
}

interface Category {
  id: string;
  name: string;
  slug: string;
  visibility: number;
  order: number;
  storeId: string;
  productCount: number;
  products: string[]; // List of product IDs
  dateCreated: string;
}

​
Example

// Display store information
async function displayStoreInfo() {
  const response = await komerza.getStore();

  if (response.success) {
    const store = response.data;

    document.getElementById("store-name").textContent = store.name;
    document.getElementById("store-description").textContent =
      store.description;
    document.getElementById(
      "product-count"
    ).textContent = `${store.products.length} products`;

    console.log(`Store uses ${store.currencyCode} currency`);
  }
}
Get the URL to your store’s logo image. 
const logoUrl = await komerza.getStoreLogoUrl();

​
Returns

Returns a string containing the full URL to the logo image.

​
Example

// Display store logo
async function displayLogo() {
  const logoUrl = await komerza.getStoreLogoUrl();

  const img = document.createElement("img");
  img.src = logoUrl;
  img.alt = "Store Logo";
  document.getElementById("logo-container").appendChild(img);
}

​
Get Store Banner

Get the URL to your store’s banner image. 
const bannerUrl = await komerza.getStoreBannerUrl();

​
Returns

Returns a string containing the full URL to the banner image.

​
Example

// Display store banner
async function displayBanner() {
  const bannerUrl = await komerza.getStoreBannerUrl();

  document.getElementById(
    "hero-banner"
  ).style.backgroundImage = `url('${bannerUrl}')`;
}

​
Currency Formatter

Create a number formatter for displaying prices in your store’s currency. 
const formatter = await komerza.createFormatter();

​
Returns

Returns an Intl.NumberFormat instance configured for your store’s currency.

​
Example

// Format prices consistently
async function displayProduct(product) {
  const formatter = await komerza.createFormatter();

  product.variants.forEach((variant) => {
    const priceFormatted = formatter.format(variant.cost);
    console.log(`${variant.name}: ${priceFormatted}`);
  });
}

​
Advanced Formatting

const formatter = await komerza.createFormatter();

// Format different amounts
console.log(formatter.format(29.99)); // "$29.99" (USD)
console.log(formatter.format(100)); // "$100.00"
console.log(formatter.format(0.99)); // "$0.99"

// Use in templates
const price = formatter.format(product.price);
element.innerHTML = `<span class="price">${price}</span>`;

​
Complete Example

Here’s a complete storefront header with store branding: 
<!DOCTYPE html>
<html>
  <head>
    <title>Store</title>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
    <style>
      .header {
        text-align: center;
        padding: 20px;
      }
      .logo {
        max-width: 200px;
        height: auto;
      }
      .banner {
        width: 100%;
        height: 300px;
        background-size: cover;
        background-position: center;
      }
      .store-info {
        margin: 20px 0;
      }
    </style>
  </head>
  <body>
    <div class="header">
      <img id="logo" class="logo" alt="Store Logo" />
      <h1 id="store-name"></h1>
      <p id="store-description"></p>
      <p id="store-stats"></p>
    </div>

    <div id="banner" class="banner"></div>

    <div id="products"></div>

    <script>
      // Initialize
      komerza.init("your-store-id");

      // Load store information
      async function loadStore() {
        try {
          // Get all store data in parallel
          const [storeResponse, logoUrl, bannerUrl, formatter] =
            await Promise.all([
              komerza.getStore(),
              komerza.getStoreLogoUrl(),
              komerza.getStoreBannerUrl(),
              komerza.createFormatter(),
            ]);

          if (!storeResponse.success) {
            console.error("Failed to load store:", storeResponse.message);
            return;
          }

          const store = storeResponse.data;

          // Display branding
          document.getElementById("logo").src = logoUrl;
          document.getElementById(
            "banner"
          ).style.backgroundImage = `url('${bannerUrl}')`;

          // Display store info
          document.getElementById("store-name").textContent = store.name;
          document.getElementById("store-description").textContent =
            store.description;
          document.getElementById(
            "store-stats"
          ).textContent = `${store.products.length} products • ${store.rating}★ rating`;

          // Display products with formatted prices
          const productsHtml = store.products
            .map((product) => {
              const minPrice = Math.min(...product.variants.map((v) => v.cost));
              const priceFormatted = formatter.format(minPrice);

              return `
            <div class="product">
              <h3>${product.name}</h3>
              <p>${product.description}</p>
              <p class="price">From ${priceFormatted}</p>
            </div>
          `;
            })
            .join("");

          document.getElementById("products").innerHTML = productsHtml;
        } catch (error) {
          console.error("Error loading store:", error);
        }
      }

      // Load on page load
      loadStore();
    </script>
  </body>
</html>

​
Caching

Store data is automatically cached by the library for performance: Cached data:
  • Store details (getStore)
  • Logo URL (getStoreLogoUrl)
  • Banner URL (getStoreBannerUrl)
  • Currency formatter (createFormatter)
The library handles cache invalidation automatically. You don’t need to worry about stale data.

​
Error Handling

// Handle store loading errors
async function loadStoreInfo() {
  const response = await komerza.getStore();

  if (!response.success) {
    console.error("Failed to load store:", response.message);

    // Show user-friendly error
    document.getElementById("error").textContent =
      "Unable to load store information. Please try again later.";
    return;
  }

  // Handle maintenance mode
  if (response.data.maintenanceReason) {
    document.getElementById("maintenance").textContent =
      response.data.maintenanceReason;
    document.getElementById("maintenance").style.display = "block";
  }

  // Process store data
  displayStore(response.data);
}

​
Best Practices

Load in parallel - Use Promise.all() to fetch store data, logo, and banner simultaneously for faster loading Cache the formatter - Create the currency formatter once and reuse it throughout your page Handle maintenance mode - Check maintenanceReason and display appropriate messages to customers Fallback for images - Provide fallback images if logo/banner URLs fail to load Markdown support - Store descriptions support markdown - use a markdown parser if needed

​
Next Steps

Products

Learn how to display and fetch products

Basket Management

Handle shopping cart operations