---
title: Shop SDK
description: >-
  The Shop SDK is a JavaScript module that wraps Shop JS web components behind a
  unified, imperative API.
source_url:
  html: 'https://shopify.dev/docs/api/shop-sdk/reference/shop-sdk'
  md: 'https://shopify.dev/docs/api/shop-sdk/reference/shop-sdk.md'
api_name: shop-sdk
---

# Shop SDK

The Shop SDK is a JavaScript module that wraps Shop JS web components behind a unified, imperative API. Instead of dropping custom-element tags into HTML, consumers call `initialize` to create a `ShopInstance` and then `create` to instantiate individual features.

***

## Why use the SDK

* **Unified config**: API key, locale, appearance, and scopes are set once at `initialize` time and inherited by every feature.
* **Explicit lifecycle**: `create()` returns a promise that resolves after the feature is ready; `destroy()` tears down all resources.
* **No DOM races**: the SDK manages script loading and element creation internally, avoiding the timing issues that arise with `customElements.whenDefined`.
* **Typed surface**: full TypeScript definitions for every config option, event handler, and instance method.

***

## Adding the loader script

Load the SDK from Shopify's CDN. Unlike per-feature loaders, this script is locale-agnostic; locale is passed at runtime:

```html
<script type="module" src="https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js"></script>
```

Or import dynamically:

```js
const { initialize } = await import(
  'https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js'
);
```

***

## Available features

| Feature key | Description |
| - | - |
| `lead-capture` | Capture leads by recognizing returning Shop users and collecting email addresses. Supports discount and button flows. |
| `login` | Add Shop account authentication to a storefront. Supports standalone button and inline email input flows. |

#### InitializeOptions

Config object accepted by `initialize()`. Sets the API key, locale, appearance, event handlers, and eager-load hints shared by all features.

* **api​Key**

  **string**

  Secondary client ID. If supplied, the client ID will receive a delegated consent token on behalf of the primary client ID.

* **appearance**

  **AppearanceConfig**

  Appearance configuration for styling Shop SDK components. Set at the instance level in `initialize()` or per-feature in `create()`.

* **client​Id**

  **string**

  Primary Client ID. This client will be shown to the buyer in the sign in flow and is the Relying Party of the OAuth flow. If omitted, defaults to the Shopify Merchant.

* **features**

  **EagerLoadFeatureConfig**

  Eager-load hints: `{ 'lead-capture': true }` preloads that loader script.

* **locale**

  **string**

  BCP-47 locale tag, e.g. `'en'`, `'fr'`, `'ro-RO'`. Default: `'en'`.

* **on​Error**

  **(event: SDKErrorEvent) => void**

  Fires when an SDK or feature-level error occurs.

* **on​Ready**

  **(event: ReadyEvent) => void**

  Fires when a feature element finishes loading and is ready.

* **on​Recognized**

  **(event: RecognizedEvent) => void**

  Fires when the Shop user-recognition signal changes.

* **scope**

  **string**

### AppearanceConfig

Appearance configuration for styling Shop SDK components. Set at the instance level in \`initialize()\` or per-feature in \`create()\`.

* preferredLoginExperience

  Preferred UX for the login experience: \`'redirect'\`, \`'popup'\`, or \`null\` for the default.

  ```ts
  'redirect' | 'popup' | null
  ```

* variables

  CSS custom property overrides.

  ```ts
  AppearanceVariables
  ```

### AppearanceVariables

CSS custom properties that control styling of Shop SDK components. All properties are optional — only set ones will be applied.

* \--buttons-radius

  Border radius for buttons (e.g. \`'12px'\`).

  ```ts
  string
  ```

* \--font-paragraph--line-height

  Line height for paragraph text (e.g. \`'22px'\`).

  ```ts
  string
  ```

* \--font-paragraph--size

  Font size for paragraph text (e.g. \`'16px'\`).

  ```ts
  string
  ```

* \--shop-pay-button-border-radius

  Border radius of the Shop Pay button (e.g. \`'4px'\`, \`'999px'\`).

  ```ts
  string
  ```

* \--shop-pay-button-height

  Height of the Shop Pay button (e.g. \`'48px'\`).

  ```ts
  string
  ```

* \--shop-pay-button-width

  Width of the Shop Pay button (e.g. \`'260px'\`, \`'100%'\`).

  ```ts
  string
  ```

* \--x-spacing-base

  Base spacing unit (e.g. \`'14px'\`).

  ```ts
  string
  ```

* \[variable: \`--${string}\`]

  ```ts
  string | undefined
  ```

### EagerLoadFeatureConfig



### AvailableFeatures

```ts
keyof FeatureConfigMap
```

### FeatureConfigMap

Per-feature config interfaces. Add new features by extending this map.

* lead-capture

  Config accepted by \`sdk.create('lead-capture', config)\`. Derived from \`LeadCaptureRegistrationSpec\`: includes all component attributes, all event handlers, plus SDK-specific fields like \`appearance\`.

  ```ts
  LeadCaptureConfig
  ```

* listener

  Config accepted by \`sdk.create('listener', config)\`. The \`listener\` feature is a lightweight, headless observer that monitors an email input for returning Shop users. It renders no UI — it only watches and reports — making it ideal for custom flows where the merchant controls the entire visual experience.

  ```ts
  ListenerConfig
  ```

* login

  Config accepted by \`sdk.create('login', config)\`. Includes component attributes, appearance overrides, and event handlers. The \`login\` feature provides Shop account authentication.

  ```ts
  LoginConfig
  ```

### LeadCaptureConfig

Config accepted by \`sdk.create('lead-capture', config)\`. Derived from \`LeadCaptureRegistrationSpec\`: includes all component attributes, all event handlers, plus SDK-specific fields like \`appearance\`.

* appearance

  Component-level appearance overrides. Variables set here take precedence over those set in \`initialize\` or \`update()\`.

  ```ts
  AppearanceConfig
  ```

* attributes

  Component attributes. These map to HTML attributes on the underlying \`\<shop-lead-capture>\` element.

  ```ts
  LeadCaptureAttributes
  ```

* onAuthenticate

  Fired during the discount flow to retrieve the discount to offer.

  ```ts
  () => Promise<{ discount: LeadCaptureDiscount; }>
  ```

* onBeforeAuthenticate

  Fired before authentication begins. Can be async.

  ```ts
  () => void | Promise<void>
  ```

* onComplete

  Fired when the lead capture flow completes successfully.

  ```ts
  (event: LeadCaptureCompleteEvent) => void
  ```

* onConfirmSuccess

  Fired after the user confirms a successful action.

  ```ts
  () => void
  ```

* onError

  Fired when an error occurs during the flow.

  ```ts
  (event: LeadCaptureErrorEvent) => void
  ```

* onGetEmailInput

  Fired to retrieve the email input element (alternative to emailInputSelector).

  ```ts
  () => HTMLInputElement
  ```

* onLoad

  Fired when the component loads and user recognition completes.

  ```ts
  (event: LeadCaptureLoadEvent) => void
  ```

* onReady

  SDK-level ready handler (fires when the element's loader resolves).

  ```ts
  (event: ReadyEvent) => void
  ```

* onRestart

  Fired when the user restarts the flow.

  ```ts
  () => void
  ```

### LeadCaptureAttributes

Attributes accepted by the \`lead-capture\` feature.

* apiKey

  Secondary client ID. If supplied, the client ID will receive a delegated consent token on behalf of the primary client ID.

  ```ts
  string
  ```

* authorizationDetails

  RAR \`authorization\_details\` (a JSON string) requesting data sharing at the consent step. Each entry carries a \`type\`; for Lead Capture that is \`urn:shopify:shop\_app:data-sharing:v1\`, whose \`datatypes\` name the fields requested — \`given\_name\`, \`family\_name\`, \`phone\_number\`, \`birthdate\`. Forwarded verbatim on every authorization request. If it is not well-formed JSON, or the resulting authorization request would exceed the maximum URL length, authentication is aborted with an error rather than sent with the value dropped.

  ```ts
  string
  ```

* buttonLayout

  Layout style for the button: \`'or'\` or \`'standalone'\`.

  ```ts
  LeadCaptureButtonLayout
  ```

* buttonType

  Type of CTA button shown when a Shop user is recognized.

  ```ts
  LeadCaptureButtonType
  ```

* clientId

  Primary Client ID. This client will be shown to the buyer in the sign in flow and is the Relying Party of the OAuth flow. If omitted, defaults to the Shopify Merchant.

  ```ts
  string
  ```

* devMode

  Enable development mode for testing.

  ```ts
  boolean
  ```

* disclosureScope

  Additional disclosure scopes requiring explicit consent.

  ```ts
  string
  ```

* disclosureText

  Custom disclosure text shown during the consent step.

  ```ts
  string
  ```

* disclosureTitle

  Custom title for the disclosure consent screen.

  ```ts
  string
  ```

* emailInputSelector

  CSS selector for the email input on the page.

  ```ts
  string
  ```

* phoneCapture

  Enable phone number capture.

  ```ts
  boolean
  ```

* phoneCaptureDisclosureText

  Disclosure text shown when requesting the user's phone number.

  ```ts
  string
  ```

* presentationMode

  Control the presentation mode where relevant, such for recognised users.

  ```ts
  PresentationMode
  ```

* scope

  Space-separated list of OAuth scopes.

  ```ts
  string
  ```

* storefrontOrigin

  Origin of the embedding storefront.

  ```ts
  string
  ```

* uxMode

  UX mode for the auth flow: \`'iframe'\`, \`'windoid'\`, or \`'redirect'\`.

  ```ts
  'iframe' | 'windoid' | 'redirect'
  ```

### LeadCaptureButtonLayout

Layout style for the lead capture button. - \`'or'\` — Shows an “or” separator between the button and the form. - \`'standalone'\` — Shows the button without any separator.

```ts
'or' | 'standalone'
```

### LeadCaptureButtonType

The type of call-to-action button shown when a Shop user is recognized. - \`'none'\` — No button; uses inline email-based flow instead. - \`'claim'\` — Shows “Claim with Shop” button. - \`'continue'\` — Shows “Continue with Shop” button. - \`'notify'\` — Shows “Notify me with Shop” button. - \`'save'\` — Shows “Save with Shop” button.

```ts
'none' | 'claim' | 'continue' | 'notify' | 'save'
```

### LeadCaptureDiscount

A discount to apply after successful lead capture.

* code

  The discount code string.

  ```ts
  string
  ```

* gid

  The Shopify global ID of the discount, if available.

  ```ts
  string
  ```

### LeadCaptureCompleteEvent

Event payload dispatched when the lead capture flow completes successfully.

* consentedScopes

  A space-separated list of OAuth scopes the user consented to.

  ```ts
  string
  ```

* customerAccessToken

  A customer access token issued after authentication, if available.

  ```ts
  string
  ```

* customerAccessTokenExpiresAt

  ISO 8601 timestamp of when the customer access token expires.

  ```ts
  string
  ```

* customerUpdateErrors

  Error messages from the customer update mutation, if any.

  ```ts
  string
  ```

* disclosureAgreed

  Whether the user agreed to the disclosure presented during the flow.

  ```ts
  boolean
  ```

* email

  The email address captured from the user.

  ```ts
  string
  ```

* emailVerified

  Whether the user's email has been verified.

  ```ts
  boolean
  ```

* phoneShareConsent

  Whether the user consented to share their phone number.

  ```ts
  boolean
  ```

* shopConsentToken

  A token that can be exchanged in the Shop Partners API to receive access for a user in the Shop Users API

  ```ts
  string
  ```

* signedIn

  Whether the user signed in during the flow (as opposed to only providing their email).

  ```ts
  boolean
  ```

### LeadCaptureErrorEvent

Event payload dispatched when an error occurs during lead capture.

* code

  A machine-readable error code.

  ```ts
  string
  ```

* email

  The email address associated with the error, if available.

  ```ts
  string
  ```

* message

  A human-readable error message.

  ```ts
  string
  ```

### LeadCaptureLoadEvent

Event payload dispatched when the lead capture component finishes loading.

* userFound

  Whether a recognized Shop user was detected for the current browser session.

  ```ts
  boolean
  ```

### ReadyEvent

Event payload passed to the \`onReady\` handler when a feature element finishes loading.

* detail

  Underlying \`CustomEvent.detail\` from the element's \`'loaded'\` event, when available. Shape is feature-specific — e.g. for lead-capture this includes fields like \`userFound\`, \`loginTitle\`, etc. emitted by \`useAuthorizeEventListener\`.

  ```ts
  unknown
  ```

* elementTagName

  Tag name of the element that became ready, e.g. \`shop-lead-capture\`.

  ```ts
  string
  ```

### ListenerConfig

Config accepted by \`sdk.create('listener', config)\`. The \`listener\` feature is a lightweight, headless observer that monitors an email input for returning Shop users. It renders no UI — it only watches and reports — making it ideal for custom flows where the merchant controls the entire visual experience.

* inputElement

  The DOM element to observe for email input.

  ```ts
  HTMLElement
  ```

* inputSelector

  CSS selector for the email input on the page (alternative to \`inputElement\`).

  ```ts
  string
  ```

* onMatched

  Fired when a returning Shop user is detected for the entered email.

  ```ts
  () => void
  ```

* onReady

  SDK-level ready handler (fires when the element's loader resolves).

  ```ts
  (event: ReadyEvent) => void
  ```

### LoginConfig

Config accepted by \`sdk.create('login', config)\`. Includes component attributes, appearance overrides, and event handlers. The \`login\` feature provides Shop account authentication.

* appearance

  Component-level appearance overrides.

  ```ts
  AppearanceConfig
  ```

* attributes

  Component attributes.

  ```ts
  LoginAttributes
  ```

* onBeforeAuthenticate

  Fired before authentication begins. Can be async.

  ```ts
  () => void | Promise<void>
  ```

* onComplete

  Fired when the login flow completes successfully.

  ```ts
  (event: LoginCompleteEvent) => void
  ```

* onConfirmSuccess

  Fired after the user confirms a successful action.

  ```ts
  () => void
  ```

* onError

  Fired when an error occurs during the flow.

  ```ts
  (event: LoginErrorEvent) => void
  ```

* onGetEmailInput

  Fired to retrieve the email input element (alternative to \`emailInputSelector\`).

  ```ts
  () => HTMLInputElement
  ```

* onLoad

  Fired when the component loads and user recognition completes.

  ```ts
  (event: LoginLoadEvent) => void
  ```

* onReady

  SDK-level ready handler (fires when the element's loader resolves).

  ```ts
  (event: ReadyEvent) => void
  ```

* onRestart

  Fired when the user restarts the flow.

  ```ts
  () => void
  ```

### LoginAttributes

Attributes accepted by the \`login\` feature.

* apiKey

  Secondary client ID. If supplied, the client ID will receive a delegated consent token on behalf of the primary client ID.

  ```ts
  string
  ```

* buttonLayout

  Layout style for the button: \`'or'\` or \`'standalone'\`.

  ```ts
  LeadCaptureButtonLayout
  ```

* buttonType

  Type of CTA button shown when a Shop user is recognized.

  ```ts
  LeadCaptureButtonType
  ```

* clientId

  Primary Client ID. This client will be shown to the buyer in the sign in flow and is the Relying Party of the OAuth flow. If omitted, defaults to the Shopify Merchant.

  ```ts
  string
  ```

* devMode

  Enable development mode for testing.

  ```ts
  boolean
  ```

* emailInputSelector

  CSS selector for the email input on the page.

  ```ts
  string
  ```

* scope

  Space-separated list of OAuth scopes.

  ```ts
  string
  ```

* storefrontOrigin

  Origin of the embedding storefront.

  ```ts
  string
  ```

* uxMode

  UX mode for the auth flow: \`'iframe'\`, \`'windoid'\`, or \`'redirect'\`.

  ```ts
  'iframe' | 'windoid' | 'redirect'
  ```

### LoginCompleteEvent

Event payload dispatched when the login flow completes successfully.

* consentedScopes

  A space-separated list of OAuth scopes the user consented to.

  ```ts
  string
  ```

* customerAccessToken

  A customer access token issued after authentication, if available.

  ```ts
  string
  ```

* customerAccessTokenExpiresAt

  ISO 8601 timestamp of when the customer access token expires.

  ```ts
  string
  ```

* email

  The email address captured from the user.

  ```ts
  string
  ```

* emailVerified

  Whether the user's email has been verified.

  ```ts
  boolean
  ```

* shopConsentToken

  A token that can be exchanged in the Shop Partners API to receive access for a user in the Shop Users API

  ```ts
  string
  ```

* signedIn

  Whether the user signed in during the flow (as opposed to only providing their email).

  ```ts
  boolean
  ```

### LoginErrorEvent

Event payload dispatched when an error occurs during login.

* code

  A machine-readable error code.

  ```ts
  string
  ```

* email

  The email address associated with the error, if available.

  ```ts
  string
  ```

* message

  A human-readable error message.

  ```ts
  string
  ```

### LoginLoadEvent

Event payload dispatched when the login component finishes loading.

* userFound

  Whether a recognized Shop user was detected for the current browser session.

  ```ts
  boolean
  ```

### SDKErrorEvent

Event payload passed to the \`onError\` handler when an SDK or feature-level error occurs.

* cause

  Underlying error if one was captured.

  ```ts
  unknown
  ```

* feature

  Feature key the error originated from, if applicable.

  ```ts
  AvailableFeatures
  ```

* message

  Human-readable message.

  ```ts
  string
  ```

### RecognizedEvent

Event payload passed to the \`onRecognized\` handler when the Shop user-recognition signal changes.

* recognized

  Whether the current visitor was recognized as a Shop user.

  ```ts
  boolean
  ```

#### ShopInstance

The runtime object returned by `initialize()`. Use `create()` to instantiate features, `update()` to change config, and `destroy()` to tear down.

* **create**

  **\<T extends AvailableFeatures>(feature: T, config?: FeatureConfigMap\[T]) => Promise\<ShopFeatureInstanceMap\[T]>**

  **required**

  Load (if needed) and create a feature instance. Resolves once the per-feature loader script has loaded and the underlying custom element has been created. Rejects on load failure; failures are also surfaced via `onError`.

  The returned wrapper exposes the element via `.element` — the consumer is responsible for inserting it into the DOM.

* **destroy**

  **() => void**

  **required**

  Destroy all feature instances created from this `ShopInstance`.

* **update**

  **(config: UpdatableOptions) => ShopInstance**

  **required**

  Merge new top-level config into the instance. `locale` is stripped if present (see file header). Returns `this` for chaining.

### ShopFeatureInstanceMap

Per-feature instance wrapper interfaces.

* lead-capture

  Runtime instance returned by \`sdk.create('lead-capture')\`. Exposes: - All component methods from the registration spec - \`setAttribute\` for updating attributes after creation - Event subscription methods for each event handler - \`onReady\` with late-subscriber semantics - \`element\` for DOM insertion - \`destroy\` for cleanup

  ```ts
  LeadCaptureInstance
  ```

* listener

  Runtime instance returned by \`sdk.create('listener')\`. The listener is headless — \`element\` is always \`null\` and the SDK appends the underlying element to \`document.body\` automatically. Exposes \`onReady\`, \`onMatched\`, and \`destroy\`.

  ```ts
  ListenerInstance
  ```

* login

  Runtime instance returned by \`sdk.create('login')\`. Exposes methods, attribute setters, and event subscriptions for the login flow.

  ```ts
  LoginInstance
  ```

### LeadCaptureInstance

Runtime instance returned by \`sdk.create('lead-capture')\`. Exposes: - All component methods from the registration spec - \`setAttribute\` for updating attributes after creation - Event subscription methods for each event handler - \`onReady\` with late-subscriber semantics - \`element\` for DOM insertion - \`destroy\` for cleanup

* destroy

  Tear down listeners and remove the element from the DOM if attached.

  ```ts
  () => void
  ```

* element

  The underlying custom element. The consumer is responsible for inserting it into the DOM.

  ```ts
  HTMLElement
  ```

* notifyEmailFieldShown

  Notify the component that the email field has been shown.

  ```ts
  () => void
  ```

* onAuthenticate

  Register an \`onAuthenticate\` handler.

  ```ts
  (handler: () => Promise<{ discount: LeadCaptureDiscount; }>) => void
  ```

* onBeforeAuthenticate

  Register an \`onBeforeAuthenticate\` handler.

  ```ts
  (handler: () => void | Promise<void>) => void
  ```

* onComplete

  Register an \`onComplete\` handler.

  ```ts
  (handler: (event: LeadCaptureCompleteEvent) => void) => void
  ```

* onConfirmSuccess

  Register an \`onConfirmSuccess\` handler.

  ```ts
  (handler: () => void) => void
  ```

* onError

  Register an \`onError\` handler.

  ```ts
  (handler: (event: LeadCaptureErrorEvent) => void) => void
  ```

* onLoad

  Register an \`onLoad\` handler.

  ```ts
  (handler: (event: LeadCaptureLoadEvent) => void) => void
  ```

* onReady

  Register an \`onReady\` handler. Fires immediately if already ready.

  ```ts
  (handler: (event: ReadyEvent) => void) => void
  ```

* onRestart

  Register an \`onRestart\` handler.

  ```ts
  (handler: () => void) => void
  ```

* setAttribute

  Update one or more attributes on the underlying element. Accepts the same attribute keys as \`config.attributes\`.

  ```ts
  (attrs: Partial<LeadCaptureAttributes>) => void
  ```

* start

  Trigger the lead-capture flow, optionally with a pre-filled email.

  ```ts
  (email?: string) => void
  ```

### ListenerInstance

Runtime instance returned by \`sdk.create('listener')\`. The listener is headless — \`element\` is always \`null\` and the SDK appends the underlying element to \`document.body\` automatically. Exposes \`onReady\`, \`onMatched\`, and \`destroy\`.

* destroy

  Tear down listeners and remove the element from the DOM if attached.

  ```ts
  () => void
  ```

* element

  Always \`null\` — the listener is headless and manages its own DOM.

  ```ts
  null
  ```

* onMatched

  Register an \`onMatched\` handler. Fires whenever a returning Shop user is detected.

  ```ts
  (handler: () => void) => void
  ```

* onReady

  Register an \`onReady\` handler. Fires immediately if already ready.

  ```ts
  (handler: (event: ReadyEvent) => void) => void
  ```

### LoginInstance

Runtime instance returned by \`sdk.create('login')\`. Exposes methods, attribute setters, and event subscriptions for the login flow.

* destroy

  Tear down listeners and remove the element from the DOM if attached.

  ```ts
  () => void
  ```

* element

  The underlying custom element. The consumer is responsible for inserting it into the DOM.

  ```ts
  HTMLElement
  ```

* notifyEmailFieldShown

  Notify the component that the email field has been shown.

  ```ts
  () => void
  ```

* onBeforeAuthenticate

  Register an \`onBeforeAuthenticate\` handler.

  ```ts
  (handler: () => void | Promise<void>) => void
  ```

* onComplete

  Register an \`onComplete\` handler.

  ```ts
  (handler: (event: LoginCompleteEvent) => void) => void
  ```

* onConfirmSuccess

  Register an \`onConfirmSuccess\` handler.

  ```ts
  (handler: () => void) => void
  ```

* onError

  Register an \`onError\` handler.

  ```ts
  (handler: (event: LoginErrorEvent) => void) => void
  ```

* onLoad

  Register an \`onLoad\` handler.

  ```ts
  (handler: (event: LoginLoadEvent) => void) => void
  ```

* onReady

  Register an \`onReady\` handler. Fires immediately if already ready.

  ```ts
  (handler: (event: ReadyEvent) => void) => void
  ```

* onRestart

  Register an \`onRestart\` handler.

  ```ts
  (handler: () => void) => void
  ```

* setAttribute

  Update one or more attributes on the underlying element.

  ```ts
  (attrs: Partial<LoginAttributes>) => void
  ```

* start

  Trigger the login flow, optionally with a pre-filled email.

  ```ts
  (email?: string) => void
  ```

### UpdatableOptions

Subset of \`InitializeOptions\` accepted by \`instance.update(...)\`. \`locale\` is intentionally excluded — see file header.

* apiKey

  Secondary client ID. If supplied, the client ID will receive a delegated consent token on behalf of the primary client ID.

  ```ts
  string
  ```

* appearance

  Appearance configuration for styling Shop SDK components. Set at the instance level in \`initialize()\` or per-feature in \`create()\`.

  ```ts
  AppearanceConfig
  ```

* clientId

  Primary Client ID. This client will be shown to the buyer in the sign in flow and is the Relying Party of the OAuth flow. If omitted, defaults to the Shopify Merchant.

  ```ts
  string
  ```

* features

  Eager-load hints: \`{ 'lead-capture': true }\` preloads that loader script.

  ```ts
  EagerLoadFeatureConfig
  ```

* onError

  Fires when an SDK or feature-level error occurs.

  ```ts
  (event: SDKErrorEvent) => void
  ```

* onReady

  Fires when a feature element finishes loading and is ready.

  ```ts
  (event: ReadyEvent) => void
  ```

* onRecognized

  Fires when the Shop user-recognition signal changes.

  ```ts
  (event: RecognizedEvent) => void
  ```

* scope

  ```ts
  string
  ```

#### AppearanceConfig

Appearance configuration for styling Shop SDK components. Set at the instance level in `initialize()` or per-feature in `create()`.

* **variables**

  **AppearanceVariables**

  CSS custom property overrides.

#### AppearanceVariables

CSS custom properties that control styling of Shop SDK components. All properties are optional — only set ones will be applied.

* **\[variable: \`--${string}\`]**

  **string | undefined**

  **required**

* **--buttons-radius**

  **string**

  Border radius for buttons (e.g. `'12px'`).

* **--font-paragraph--line-height**

  **string**

  Line height for paragraph text (e.g. `'22px'`).

* **--font-paragraph--size**

  **string**

  Font size for paragraph text (e.g. `'16px'`).

* **--shop-pay-button-border-radius**

  **string**

  Border radius of the Shop Pay button (e.g. `'4px'`, `'999px'`).

* **--shop-pay-button-height**

  **string**

  Height of the Shop Pay button (e.g. `'48px'`).

* **--shop-pay-button-width**

  **string**

  Width of the Shop Pay button (e.g. `'260px'`, `'100%'`).

* **--x-spacing-base**

  **string**

  Base spacing unit (e.g. `'14px'`).

#### ReadyEvent

Event payload passed to the `onReady` handler when a feature element finishes loading.

* **element​Tag​Name**

  **string**

  **required**

  Tag name of the element that became ready, e.g. `shop-lead-capture`.

* **detail**

  **unknown**

  Underlying `CustomEvent.detail` from the element's `'loaded'` event, when available. Shape is feature-specific — e.g. for lead-capture this includes fields like `userFound`, `loginTitle`, etc. emitted by `useAuthorizeEventListener`.

#### RecognizedEvent

Event payload passed to the `onRecognized` handler when the Shop user-recognition signal changes.

* **recognized**

  **boolean**

  **required**

  Whether the current visitor was recognized as a Shop user.

#### SDKErrorEvent

Event payload passed to the `onError` handler when an SDK or feature-level error occurs.

* **message**

  **string**

  **required**

  Human-readable message.

* **cause**

  **unknown**

  Underlying error if one was captured.

* **feature**

  **AvailableFeatures**

  Feature key the error originated from, if applicable.

Examples

### Examples

* ####

  ##### Description

  Initialize the SDK and create a lead-capture instance with an email input.

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

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

    document.querySelector('#lead-capture-mount').appendChild(leadCapture.element);
  </script>

  <form id="lead-capture-form">
    <label for="email">Email address</label>
    <input type="email" id="email" name="email" placeholder="Enter your email" />
  </form>

  <div id="lead-capture-mount"></div>
  ```

* ####

  ##### Description

  Customize component styling with CSS custom properties at the instance and component level, and update at runtime.

  ##### 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',
      appearance: {
        variables: {
          '--buttons-radius': '8px',
          '--shop-pay-button-width': '300px',
        },
      },
      onReady(event) {
        console.log(`${event.elementTagName} is ready`);
      },
      onRecognized(state) {
        if (state.recognized) {
          console.log('Returning Shop user recognized');
        }
      },
    });

    const leadCapture = await sdk.create('lead-capture', {
      attributes: {
        emailInputSelector: '#email',
      },
      appearance: {
        // Component-level variables override instance-level ones
        variables: { '--buttons-radius': '4px' },
      },
      onComplete(event) {
        console.log('Lead captured:', event.email);
      },
    });

    document.querySelector('#lead-capture-mount').appendChild(leadCapture.element);

    // Update appearance at runtime (e.g. after a theme change)
    sdk.update({
      appearance: {
        variables: { '--buttons-radius': '0px' },
      },
    });
  </script>

  <form>
    <label for="email">Email address</label>
    <input type="email" id="email" name="email" placeholder="Enter your email" />
  </form>

  <div id="lead-capture-mount"></div>
  ```

***

## Related

[Feature - login](https://shopify.dev/docs/api/shop-sdk/reference/login)

[Feature - lead-capture](https://shopify.dev/docs/api/shop-sdk/reference/lead-capture)

***
