Skip to main content

Set up the Shop SDK

The Shop SDK is a JavaScript library for integrating Shop functionality into any storefront. Load a single script from Shopify's CDN, initialize the SDK with your configuration, then create feature instances programmatically.

Developer preview

The Shop platform is in early access. Features and APIs may change before general availability.

Anchor to Step 1: Load and initialize the SDKStep 1: Load and initialize the SDK

Add the SDK loader script to your page and call initialize with your configuration. The apiKey is the client ID from your Dev Dashboard app.

HTML

<script type="module">
import 'https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js';

const sdk = window.ShopSDK.initialize({
apiKey: 'YOUR_CLIENT_ID',
locale: 'en',
});
</script>

The script registers window.ShopSDK when it loads. initialize returns an SDK instance that you use to create features.

Anchor to Step 2: Create a feature instanceStep 2: Create a feature instance

Call sdk.create() with a feature name and configuration. The method returns a Promise that resolves once the feature's code has loaded.

JavaScript

const leadCapture = await sdk.create('lead-capture', {
attributes: {
flow: 'discount',
buttonType: 'save',
},
onComplete(event) {
console.log('Lead captured:', event.email);
},
});

// Insert the element into the DOM
document.querySelector('#shop-container').appendChild(leadCapture.element);

The SDK creates the underlying HTML element for you. You're responsible for inserting instance.element into the DOM wherever you want it to appear.

Anchor to ConfigurationConfiguration

Anchor to [object Object], optionsinitialize options

OptionTypeDescription
apiKeystringYour client ID from the Dev Dashboard.
appearanceobjectStyling overrides. See Appearance.
featuresobjectEagerly preload feature scripts. For example, { 'lead-capture': true } starts loading the lead capture code immediately.
localestringBCP-47 locale tag (for example, 'en', 'fr', 'ro-RO'). Defaults to 'en'.
onErrorfunctionSDK-level error handler. See Event handlers.
onReadyfunctionFires when a feature instance finishes loading. See Event handlers.
onRecognizedfunctionFires when a Shop user is detected (or not). See Event handlers.
scopestringSpace-separated list of OAuth scopes to request.

Anchor to AppearanceAppearance

Control the look of SDK components with CSS custom properties:

JavaScript

const sdk = window.ShopSDK.initialize({
apiKey: 'YOUR_CLIENT_ID',
appearance: {
variables: {
'--buttons-radius': '8px',
'--font-paragraph--size': '16px',
},
},
});
VariableDescription
--buttons-radiusBorder radius for buttons.
--font-paragraph--sizeFont size for paragraph text.
--font-paragraph--line-heightLine height for paragraph text.
--x-spacing-baseBase spacing unit.

Anchor to Event handlersEvent handlers

SDK-level event handlers fire for all feature instances. Pass them as top-level properties on the initialize config:

JavaScript

const sdk = window.ShopSDK.initialize({
apiKey: 'YOUR_CLIENT_ID',
onReady(event) {
console.log(`${event.elementTagName} is ready`);
},
onRecognized(state) {
if (state.recognized) {
// Show a personalized experience
}
},
onError(event) {
console.error('SDK error:', event.message);
},
});
HandlerPayloadDescription
onReady{ elementTagName, detail }Fires when a feature instance finishes loading.
onRecognized{ recognized }Fires when a Shop user is detected (or not) in the current session.
onError{ message, cause, feature }Fires when an error occurs in any feature instance.

Anchor to Updating and destroyingUpdating and destroying

Call sdk.update() to merge new configuration into the SDK instance:

JavaScript

sdk.update({
appearance: {
variables: { '--buttons-radius': '0' },
},
});

Call sdk.destroy() to tear down all feature instances and clean up event listeners. You can also destroy individual feature instances with instance.destroy().

Anchor to Next stepsNext steps

  • See the full Shop SDK reference for all configuration options and feature APIs.
  • Use the lead capture feature to collect email addresses from Shop users on your storefront.
  • Use onRecognized to silently detect returning Shop users.
Was this page helpful?