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

});

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);

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

const sdk = window.ShopSDK.initialize({

apiKey: 'YOUR_CLIENT_ID',

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

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.
```
string
```
buttonLayout
Layout style for the button: `'or'` or `'standalone'`.
```
LeadCaptureButtonLayout
```
buttonType
Type of CTA button shown when a Shop user is recognized.
```
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.
```
string
```
devMode
Enable development mode for testing.
```
boolean
```
disclosureScope
Additional disclosure scopes requiring explicit consent.
```
string
```
disclosureText
Custom disclosure text shown during the consent step.
```
string
```
disclosureTitle
Custom title for the disclosure consent screen.
```
string
```
emailInputSelector
CSS selector for the email input on the page.
```
string
```
phoneCapture
Enable phone number capture.
```
boolean
```
phoneCaptureDisclosureText
Disclosure text shown when requesting the user's phone number.
```
string
```
scope
Space-separated list of OAuth scopes.
```
string
```
storefrontOrigin
Origin of the embedding storefront.
```
string
```
uxMode
UX mode for the auth flow: `'iframe'`, `'windoid'`, or `'redirect'`.
```
'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.

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

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<>) => 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_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>

<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_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

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_CLIENT_ID',
    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_CLIENT_ID',
    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?