---
title: Shop SDK
description: |
  The Shop SDK is a JavaScript library for integrating Shop functionality into any storefront.
source_url:
  html: https://shopify.dev/docs/api/shop-sdk
  md: https://shopify.dev/docs/api/shop-sdk.md
---

# Shop SDK

The Shop SDK is a JavaScript library for integrating [Shop](https://shop.app) functionality into any storefront. Load a single script from Shopify's CDN, initialize the SDK with your configuration, and create feature instances programmatically.

## Getting started

Load the SDK loader script and call `initialize` with your client ID. The `apiKey` is the client ID from your [Dev Dashboard app](https://shopify.dev/docs/api/shop/guides/creating-a-client).

[Get started - Set up the Shop SDK](https://shopify.dev/docs/api/shop/guides/shop-sdk)

## 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. Call `sdk.create()` with a feature name to create a feature instance. The method returns a Promise that resolves once the feature's code has loaded.

The SDK creates the underlying HTML element. You're responsible for inserting `instance.element` into the DOM.

## JavaScript

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


document.querySelector('#shop-container').appendChild(leadCapture.element);
```

***

## Configuration

### `initialize` options

* `apiKey`: Your client ID from the [Dev Dashboard](https://shopify.dev/docs/api/shop/guides/creating-a-client).
* `appearance`: Styling overrides. See [Appearance](#appearance).
* `features`: Eagerly preload feature scripts. For example, `{ 'lead-capture': true }` starts loading the lead capture code immediately.
* `locale`: BCP-47 locale tag (for example, `'en'`, `'fr'`, `'ro-RO'`). Defaults to `'en'`.
* `onError` / `onReady` / `onRecognized`: SDK-level event handlers. See [Event handlers](#event-handlers).
* `scope`: Space-separated list of OAuth scopes to request.

## JavaScript

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

### Appearance

Control the look of SDK components with CSS custom properties on `appearance.variables`. Component-level variables set when calling `sdk.create()` take precedence over SDK-level ones.

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

## JavaScript

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

### Event handlers

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

| Handler | Payload | Description |
| - | - | - |
| `onError` | `{ message, cause, feature }` | Fires when an error occurs in any feature instance. |
| `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. |

Call `sdk.update()` to merge new configuration into a live SDK instance, or `sdk.destroy()` to tear down all feature instances. The `locale` option is fixed at initialization and can't be updated.

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

***

## Next steps

### Get started

[Create an app\
\
](https://shopify.dev/docs/api/shop/guides/creating-a-client)

[Set up an app in the Dev Dashboard to get the credentials you need for Shop APIs and SDKs.](https://shopify.dev/docs/api/shop/guides/creating-a-client)

[Set up the Shop SDK\
\
](https://shopify.dev/docs/api/shop/guides/shop-sdk)

[Full walkthrough for loading, initializing, and configuring the SDK on your storefront.](https://shopify.dev/docs/api/shop/guides/shop-sdk)

### Use cases

[Sign in with Shop\
\
](https://shopify.dev/docs/api/shop/guides/use-cases/sign-in)

[Add a Sign in with Shop button to your self-hosted login page using the `<shop-login-button>` web component and OpenID Connect.](https://shopify.dev/docs/api/shop/guides/use-cases/sign-in)

[Recognize returning users\
\
](https://shopify.dev/docs/api/shop/guides/use-cases/recognition)

[Use the Shop SDK's `onRecognized` event to silently detect returning Shop users and personalize your storefront.](https://shopify.dev/docs/api/shop/guides/use-cases/recognition)

[Lead capture\
\
](https://shopify.dev/docs/api/shop/guides/use-cases/lead-capture)

[Capture leads on your storefront by recognizing returning Shop users and collecting email addresses.](https://shopify.dev/docs/api/shop/guides/use-cases/lead-capture)

***