Site Theme SDK Reference

A lightweight, open source JavaScript SDK that wraps basic asynchronous functionality of client APIs as well as additional helper functionality.

The Site Theme SDK is available at https://github.com/square/site-theme-sdk. Autogenerated docs are available in the typedocs folder.

Typescript type information can be found in the types folder of the released tarball package.

The Site Theme SDK is intended to simplify actions on a Square Online site, such as validating item resources and manipulating the cart.

Please note that during this Alpha phase, the Site Theme SDK is not yet available on any public registries.

Usage

SDK Init Config

The SDK needs to be initialized via its constructor with an InitConfig object:

interface InitConfig {
    userId: number;
    siteId: string;
    cmsSiteId: string;
    cdnDomain: string;
    merchantId: string;
}

These line up to the following objects on the square.site namespace

  • square.site.user_id
  • square.site.site_id
  • square.site.cdn_domain

To make it easier, we’ve also provided a sdk_init_config function that will create this entire config object for you.

The constructor will throw an error if not initialized with the correct InitConfig properties.

UMD

Embed from a script tag and then initialize:

<script src="{{ 'site-theme-sdk/lib/index.umd.cjs?cachebuster=10102023' | asset_url }}"></script>

Note we recommend using a cachebuster query param on every upgrade of the script to ensure the old version is not cached by the browser.

It will then be available on the window object as SiteThemeSDK to initialize:

<script>
try {
    window.sdk = new SiteThemeSDK({{ sdk_init_config() }});
} catch (error) {
    // if the InitConfig is invalid/missing, an exception will be thrown
}
</script>

ESM

Embed from a module script tag:

<script type="module">
    import SiteThemeSDK from "{{ 'site-theme-sdk/lib/index.js?cachebuster=10102023' | asset_url }}";
    try {
        window.sdk = new SiteThemeSDK({{ sdk_init_config() }});
    } catch (error) {
        // if the InitConfig is invalid/missing, an exception will be thrown
    }
</script>

Note we recommend using a cachebuster query param on every upgrade of the script to ensure the old version is not cached by the browser.

Or in a Typescript environment:

import SiteThemeSDK from "./site-theme-sdk/lib/";
import { AddItemRequest } from "./site-theme-sdk/lib/types";

SDK guides

The following topics show how you can call SDK functions from your pages for dynamic site actions:

For full reference documentation, see the typedocs folder in the SDK.