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, and create feature instances programmatically.
Anchor to Getting startedGetting started
Load the SDK loader script and call initialize with your client ID. The apiKey is the client ID from your Dev Dashboard app.
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.
Anchor to ConfigurationConfiguration
Anchor to [object Object], optionsinitialize options
initialize optionsapiKey: Your client ID from the Dev Dashboard.appearance: Styling overrides. See 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.scope: Space-separated list of OAuth scopes to request.
Anchor to AppearanceAppearance
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. |
Anchor to Event handlersEvent 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.
