lead-capture

The lead-capture feature enables merchants to capture leads on their storefront by recognizing returning Shop users and facilitating email collection.

It supports two main flows:

Discount flow — Offer a discount code in exchange for an email, using the onAuthenticate callback.
Default flow — Standard email capture without a discount incentive.

The feature detects whether the current visitor is a known Shop user and can display a call-to-action button (for example, "Continue with Shop") or integrate inline with an existing email input field.

Anchor to UsageUsage

Create a lead-capture instance via the SDK:

const sdk = window.ShopSDK.initialize({

apiKey: 'YOUR_STOREFRONT_API_KEY',

});

const leadCapture = await sdk.create('lead-capture', {

attributes: {

emailInputSelector: '#email',

onComplete(event) {

console.log('Lead captured:', event.email);

});

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

You can also eagerly preload the feature loader before calling create:

const sdk = window.ShopSDK.initialize({

apiKey: 'YOUR_STOREFRONT_API_KEY',

features: { 'lead-capture': true },

});

Anchor to leadcaptureconfigLeadCaptureConfig

Config accepted by sdk.create('lead-capture', config).

Derived from LeadCaptureRegistrationSpec: includes all component attributes, all event handlers, plus SDK-specific fields like appearance.

Anchor to appearance appearance: Component-level appearance overrides. Variables set here take precedence over those set in initialize or update().
Anchor to attributes attributes { apiKey?: string; clientId?: string; devMode?: boolean; emailInputSelector?: string; buttonType?: ; buttonLayout?: ; storefrontOrigin?: string; uxMode?: "redirect" | "iframe" | "windoid"; scope?: string; disclosureScope?: string; disclosureText?: string; disclosureTitle?: string; phoneCapture?: boolean; phoneCaptureDisclosureText?: string; }: Component attributes. These map to HTML attributes on the underlying <shop-lead-capture> element.
Anchor to onAuthenticate onAuthenticate () => Promise<{ discount: ; }>: Fired during the discount flow to retrieve the discount to offer.
Anchor to onBeforeAuthenticate onBeforeAuthenticate () => void | Promise<void>: Fired before authentication begins. Can be async.
Anchor to onComplete onComplete (event: ) => void: Fired when the lead capture flow completes successfully.
Anchor to onConfirmSuccess onConfirmSuccess () => void: Fired after the user confirms a successful action.
Anchor to onError onError (event: ) => void: Fired when an error occurs during the flow.
Anchor to onGetEmailInput onGetEmailInput () => HTMLInputElement: Fired to retrieve the email input element (alternative to emailInputSelector).
Anchor to onLoad onLoad (event: ) => void: Fired when the component loads and user recognition completes.
Anchor to onReady onReady (event: ) => void: SDK-level ready handler (fires when the element's loader resolves).
Anchor to onRestart onRestart () => void: Fired when the user restarts the flow.

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.
```
'redirect' | 'popup' | null
```
variables
CSS custom property overrides.
```
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'`).
```
string
```
--font-paragraph--line-height
Line height for paragraph text (e.g. `'22px'`).
```
string
```
--font-paragraph--size
Font size for paragraph text (e.g. `'16px'`).
```
string
```
--shop-pay-button-border-radius
Border radius of the Shop Pay button (e.g. `'4px'`, `'999px'`).
```
string
```
--shop-pay-button-height
Height of the Shop Pay button (e.g. `'48px'`).
```
string
```
--shop-pay-button-width
Width of the Shop Pay button (e.g. `'260px'`, `'100%'`).
```
string
```
--x-spacing-base
Base spacing unit (e.g. `'14px'`).
```
string
```
[variable: `--${string}`]
```
string | undefined
```

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. - `'favorite'` — Shows “Favorite with Shop” button. - `'notify'` — Shows “Notify me with Shop” button. - `'save'` — Shows “Save with Shop” button.

'none' | 'claim' | 'continue' | 'favorite' | 'notify' | 'save'

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.

'or' | 'standalone'

LeadCaptureDiscount

A discount to apply after successful lead capture.

code
The discount code string.
```
string
```
gid
The Shopify global ID of the discount, if available.
```
string
```

LeadCaptureCompleteEvent

Event payload dispatched when the lead capture flow completes successfully.

consentedScopes
A space-separated list of OAuth scopes the user consented to.
```
string
```
customerAccessToken
A customer access token issued after authentication, if available.
```
string
```
customerAccessTokenExpiresAt
ISO 8601 timestamp of when the customer access token expires.
```
string
```
customerUpdateErrors
Error messages from the customer update mutation, if any.
```
string
```
disclosureAgreed
Whether the user agreed to the disclosure presented during the flow.
```
boolean
```
email
The email address captured from the user.
```
string
```
emailVerified
Whether the user's email has been verified.
```
boolean
```
phoneShareConsent
Whether the user consented to share their phone number.
```
boolean
```
shopConsentToken
A token that can be exchanged in the Shop Partners API to receive access for a user in the Shop Users API
```
string
```
signedIn
Whether the user signed in during the flow (as opposed to only providing their email).
```
boolean
```

LeadCaptureErrorEvent

Event payload dispatched when an error occurs during lead capture.

code
A machine-readable error code.
```
string
```
email
The email address associated with the error, if available.
```
string
```
message
A human-readable error message.
```
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.
```
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`.
```
unknown
```
elementTagName
Tag name of the element that became ready, e.g. `shop-lead-capture`.
```
string
```

Anchor to leadcaptureinstanceLeadCaptureInstance

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

Anchor to destroy destroy () => void required: Tear down listeners and remove the element from the DOM if attached.
Anchor to element element HTMLElement required: The underlying custom element. The consumer is responsible for inserting it into the DOM.
Anchor to notifyEmailFieldShown notifyEmailFieldShown () => void required: Notify the component that the email field has been shown.
Anchor to onAuthenticate onAuthenticate (handler: () => Promise<{ discount: ; }>) => void required: Register an onAuthenticate handler.
Anchor to onBeforeAuthenticate onBeforeAuthenticate (handler: () => void | Promise<void>) => void required: Register an onBeforeAuthenticate handler.
Anchor to onComplete onComplete (handler: (event: ) => void) => void required: Register an onComplete handler.
Anchor to onConfirmSuccess onConfirmSuccess (handler: () => void) => void required: Register an onConfirmSuccess handler.
Anchor to onError onError (handler: (event: ) => void) => void required: Register an onError handler.
Anchor to onLoad onLoad (handler: (event: ) => void) => void required: Register an onLoad handler.
Anchor to onReady onReady (handler: (event: ) => void) => void required: Register an onReady handler. Fires immediately if already ready.
Anchor to onRestart onRestart (handler: () => void) => void required: Register an onRestart handler.
Anchor to setAttribute setAttribute (attrs: Partial<{ apiKey?: string; clientId?: string; devMode?: boolean; emailInputSelector?: string; buttonType?: ; buttonLayout?: ; storefrontOrigin?: string; uxMode?: "redirect" | "iframe" | "windoid"; scope?: string; disclosureScope?: string; disclosureText?: string; disclosureTitle?: string; phoneCapture?: boolean; phoneCaptureDisclosureText?: string; }>) => void required: Update one or more attributes on the underlying element. Accepts the same attribute keys as config.attributes.
Anchor to start start (email?: string) => void required: Trigger the lead-capture flow, optionally with a pre-filled email.

Anchor to leadcapturecompleteeventLeadCaptureCompleteEvent

Event payload dispatched when the lead capture flow completes successfully.

Anchor to email email string required: The email address captured from the user.
Anchor to signedIn signedIn boolean required: Whether the user signed in during the flow (as opposed to only providing their email).
Anchor to consentedScopes consentedScopes string: A space-separated list of OAuth scopes the user consented to.
Anchor to customerAccessToken customerAccessToken string: A customer access token issued after authentication, if available.
Anchor to customerAccessTokenExpiresAt customerAccessTokenExpiresAt string: ISO 8601 timestamp of when the customer access token expires.
Anchor to customerUpdateErrors customerUpdateErrors string: Error messages from the customer update mutation, if any.
Anchor to disclosureAgreed disclosureAgreed boolean: Whether the user agreed to the disclosure presented during the flow.
Anchor to emailVerified emailVerified boolean: Whether the user's email has been verified.
Anchor to phoneShareConsent phoneShareConsent boolean: Whether the user consented to share their phone number.
Anchor to shopConsentToken shopConsentToken string: A token that can be exchanged in the Shop Partners API to receive access for a user in the Shop Users API

Anchor to leadcaptureerroreventLeadCaptureErrorEvent

Event payload dispatched when an error occurs during lead capture.

Anchor to code code string required: A machine-readable error code.
Anchor to message message string required: A human-readable error message.
Anchor to email email string: The email address associated with the error, if available.

Anchor to leadcaptureloadeventLeadCaptureLoadEvent

Event payload dispatched when the lead capture component finishes loading.

Anchor to userFound userFound boolean required: Whether a recognized Shop user was detected for the current browser session.

Examples

HTML

import 'https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js';

const sdk = window.ShopSDK.initialize({

apiKey: 'YOUR_STOREFRONT_API_KEY',

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>

<label for="email">Email address</label>

</form>

Examples

Description

Create a lead-capture instance with an email input and handle the complete event.

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_STOREFRONT_API_KEY',
    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

Offer a discount code to users who provide their email via the `onAuthenticate` callback.

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_STOREFRONT_API_KEY',
    locale: 'en',
    onError(event) {
      console.error('[ShopSDK]', event.message, event.cause);
    },
  });

  const leadCapture = await sdk.create('lead-capture', {
    attributes: {
      emailInputSelector: '#newsletter-email',
      flow: 'discount',
    },
    onAuthenticate: async () => {
      return { discount: { code: 'WELCOME10' } };
    },
    onComplete(event) {
      console.log('Lead captured:', event.email);
      console.log('Signed in:', event.signedIn);
    },
    onLoad(event) {
      if (event.userFound) {
        console.log('Recognized Shop user detected');
      }
    },
  });

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

<form id="newsletter-form">
  <label for="newsletter-email">Get 10% off your first order</label>
  <input
    type="email"
    id="newsletter-email"
    name="email"
    placeholder="Enter your email"
  />
  <button type="submit">Subscribe</button>
</form>

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

Description

Show a "Continue with Shop" button for recognized users instead of an inline email input.

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_STOREFRONT_API_KEY',
    locale: 'en',
  });

  const leadCapture = await sdk.create('lead-capture', {
    attributes: {
      buttonType: 'continue',
      buttonLayout: 'or',
    },
    onComplete(event) {
      console.log('Lead captured:', event.email);
    },
    onLoad(event) {
      console.log('User found:', event.userFound);
    },
    onError(event) {
      console.error('Error:', event.code, event.message);
    },
  });

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

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

Anchor to RelatedRelated

OverviewShop SDK

Was this page helpful?