---
title: Set up the Shop SDK
description: Load and initialize the Shop SDK to embed Shop functionality into any storefront.
source_url:
  html: https://shopify.dev/docs/api/shop/guides/shop-sdk
  md: https://shopify.dev/docs/api/shop/guides/shop-sdk.md
---

# 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.

***

## Step 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](https://shopify.dev/docs/api/shop/guides/creating-a-client).

## HTML

```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.

***

## Step 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

```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.

***

## Configuration

### `initialize` options

| Option | Type | Description |
| - | - | - |
| `apiKey` | `string` | Your client ID from the [Dev Dashboard](https://shopify.dev/docs/api/shop/guides/creating-a-client). |
| `appearance` | `object` | Styling overrides. See [Appearance](#appearance). |
| `features` | `object` | Eagerly preload feature scripts. For example, `{ 'lead-capture': true }` starts loading the lead capture code immediately. |
| `locale` | `string` | BCP-47 locale tag (for example, `'en'`, `'fr'`, `'ro-RO'`). Defaults to `'en'`. |
| `onError` | `function` | SDK-level error handler. See [Event handlers](#event-handlers). |
| `onReady` | `function` | Fires when a feature instance finishes loading. See [Event handlers](#event-handlers). |
| `onRecognized` | `function` | Fires when a Shop user is detected (or not). See [Event handlers](#event-handlers). |
| `scope` | `string` | Space-separated list of OAuth scopes to request. |

### Appearance

Control the look of SDK components with CSS custom properties:

## JavaScript

```javascript
const sdk = window.ShopSDK.initialize({
  apiKey: 'YOUR_CLIENT_ID',
  appearance: {
    variables: {
      '--buttons-radius': '8px',
      '--font-paragraph--size': '16px',
    },
  },
});
```

| Variable | Description |
| - | - |
| `--buttons-radius` | Border radius for buttons. |
| `--font-paragraph--size` | Font size for paragraph text. |
| `--font-paragraph--line-height` | Line height for paragraph text. |
| `--x-spacing-base` | Base spacing unit. |

### Event handlers

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

## JavaScript

```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);
  },
});
```

| Handler | Payload | Description |
| - | - | - |
| `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. |

***

## Updating and destroying

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

## JavaScript

```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()`.

***

## Next steps

* See the full [Shop SDK reference](https://shopify.dev/docs/api/shop-sdk) for all configuration options and feature APIs.
* Use the [lead capture](https://shopify.dev/docs/api/shop/guides/use-cases/lead-capture) feature to collect email addresses from Shop users on your storefront.
* Use [`onRecognized`](https://shopify.dev/docs/api/shop/guides/use-cases/recognition) to silently detect returning Shop users.

***