Skip to content
Docs
Get playground access

Adding Elements to your site

Install the Kustom Elements script from the Portal, register the domains it may run on and drop element tags into your pages — the low-effort way to put Kustom features into a storefront you already built.

Installing Elements takes one script tag and a domain allowlist, after which each element is a single HTML tag. If you’re deciding whether you need them at all, start with What Elements are. You need a Kustom merchant account and Portal access.

Before you start

Section titled “Before you start”

You need access to the Kustom Portal for the environment you’re integrating. Playground and Production scripts aren’t interchangeable — each carries a data-public-api-key bound to one Merchant ID in one environment, so log in to the environment you actually want before copying anything.

If you have more than one Merchant ID, you get one script per MID. They aren’t substitutes for each other.

Step by step

Section titled “Step by step”

1. Register your domains. In the Portal, go to Elements and add every domain the elements will run on — www.my-shop.com, checkout.my-shop.com, and so on. Elements won’t render on a domain that isn’t on the list.

In Playground only, you may use a wildcard such as *.my-shop.com. Production requires each domain in full.

2. Copy the installation script from the same Portal screen, and place it as high in your page <head> as you can. It registers the web components and connects them to your account, so it must load before any element tag on the page. In practice that means the layout or template that wraps every page using elements.

<head>
  <!-- Kustom Elements Snippet start -->
  <script
    async
    id="kustom-elements-script"
    type="text/javascript"
    src="https://js.live.kustom.co/kustom-elements/v1/pre-load.js"
    data-public-api-key="{{Your public API key}}"
  ></script>
  <script>
    (function (w) {
      ((window.kustomElements =
        window.kustomElements ||
        function (w, ...n) {
          return new Promise((o, i) => {
            window.kustomElements._internal.q.push({ method: w, args: n, resolve: o, reject: i });
          });
        }),
        (window.kustomElements._internal = window.kustomElements._internal || {
          q: [],
          snippetVersion: '1.0.0',
        }),
        window.kustomElements.load ||
          (window.kustomElements.load = new Promise((w, n) => {
            ((window.kustomElements._internal.loadResolve = w),
              (window.kustomElements._internal.loadReject = n));
          })));
    })(window);
  </script>
  <!-- Kustom Elements Snippet end -->
</head>

Treat that as a shape, not as code to copy — take the real script from the Portal, because the API key in it is yours.

Load it from the Kustom CDN URL the Portal gives you. Don’t download and re-host it, and don’t proxy it through your own domain. Both break the integration.

3. Add an element tag where you want it to appear. The installation script detects the tag and renders it:

<kustom-payment-method-display locale="en-SE"></kustom-payment-method-display>

Most elements need nothing more. Express buttons additionally need a JavaScript call that tells them which order to pay for — see Add express buttons.

To check it, load a page carrying the tag on one of your registered domains. The element should render its own content — a list of payment methods, for instance — rather than staying empty.

An element that renders nothing is almost always one of three things, in this order: the domain isn’t registered, the script is loading from somewhere other than the Kustom CDN, or the script tag sits below the element tag on the page.

Section titled “Related”

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.