Installation & Setup

Add the script

<script src="https://cdn.komerza.com/komerza.min.js"></script>

That’s the whole install - there’s no npm package. As soon as the script runs it defines a global komerza (also reachable as window.komerza). The URL always serves the current version, so fixes reach your storefront without you redeploying anything. Load it as a plain script tag. With async or defer, your own code can run before komerza exists.

Initialize

Call init() with your store ID straight after the script tag, in the <head>:

<head>
  <script src="https://cdn.komerza.com/komerza.min.js"></script>
  <script>
    komerza.init("your-store-id");
  </script>
</head>

Put it there rather than in your app code. A plain script in the <head> runs before anything else on the page, your framework’s bundle included, so every component can take the SDK as ready. Leaving init() until later is the usual cause of “Komerza.init must be called before using this method”. init() is synchronous. It remembers the store for this visitor, starts loading the store’s data in the background, records an affiliate ?ref= from the URL, and - once the page has loaded - starts the built-in features.

Finding your store ID

In the dashboard, open Online Store → Settings and copy the Store ID from the General tab. Or press ⌘K (Ctrl+K on Windows), search for “store ID”, and it goes straight to your clipboard. The store ID isn’t a secret. It’s fine in your page source.

When init() is optional

On your store’s Komerza URL (*.mykomerza.com) or a custom domain connected to your store, the SDK can work out the store from the hostname when the first call needs it. Call init() anyway: without it nothing - the cookie notice, analytics, affiliate tracking - starts until your first data call, and that call pays for an extra lookup.

Frameworks

With init() in index.html, your framework code only ever uses the SDK. It never initializes it. Don’t move init() into a root component’s useEffect, mounted or onMount. React, Vue and Svelte all run child components’ hooks before their parent’s, so a child that loads data when it mounts would run before init().

import { useEffect, useState } from "react";

export function StoreName() {
  const [name, setName] = useState("");

  useEffect(() => {
    komerza.getStore().then((response) => {
      if (response.success) setName(response.data.name);
    });
  }, []);

  return <h1>{name}</h1>;
}

<script setup>
import { ref, onMounted } from "vue";

const name = ref("");

onMounted(async () => {
  const response = await komerza.getStore();
  if (response.success) name.value = response.data.name;
});
</script>

<template>
  <h1>{{ name }}</h1>
</template>

<script>
  import { onMount } from "svelte";

  let name = "";

  onMount(async () => {
    const response = await komerza.getStore();
    if (response.success) name = response.data.name;
  });
</script>

<h1>{name}</h1>

The SDK talks to Komerza from the visitor’s browser, so call it from client-side code. In a framework that renders on the server as well (Next.js, Nuxt, SvelteKit), keep SDK calls inside effects and mount hooks, which only run in the browser. In TypeScript, add the declarations from TypeScript and komerza is fully typed.

Check it’s working

komerza.getStore().then((response) => {
  if (response.success) {
    console.log("Connected to", response.data.name);
  } else {
    console.error("Store failed to load:", response.message);
  }
});

Troubleshooting

komerza is not defined

The script didn’t run before your code did. Check that the script tag is there, isn’t loaded with async or defer, and isn’t blocked - by a browser extension or by your site’s Content-Security-Policy (see the origins to allow).

Komerza.init must be called before using this method

A data call ran before init(), on a host where the SDK can’t work the store out for itself - localhost, or your own domain. Move init() into the <head>, straight after the script tag.

Every call comes back with success: false

Read response.message. If it happens on every call, check the store ID: a mistyped ID fails everything. Network failures don’t throw - a call gives up after 15 seconds and resolves with success: false and the reason in message.

Checkout fails after I switched store IDs

The cart belongs to the site’s origin, not to a store. If you develop several stores on the same localhost port, the previous store’s items are still in the cart. Call komerza.clearBasket() after switching.

Store Information

The store, its products, categories and branding

Built-in features

What the script adds to your page by itself

Getting Started

Client Library

Add the script

Initialize

Finding your store ID

When init() is optional

Frameworks

Check it’s working

Troubleshooting

Next

Store Information

Built-in features

​Add the script

​Initialize

​Finding your store ID

​When init() is optional

​Frameworks

​Check it’s working

​Troubleshooting

​Next

Store Information

Built-in features

Add the script

Initialize

Finding your store ID

When init() is optional

Frameworks

Check it’s working

Troubleshooting

Next