Skip to main content

Lead capture

Use the Shop SDK to capture leads on your storefront. The lead capture component recognizes returning Shop users by their email address and pre-fills their details, reducing friction at sign-up or checkout.

Developer preview

The Shop platform is in early access. Features and APIs may change before general availability.

Anchor to What you'll learnWhat you'll learn

In this guide, you'll learn how to do the following tasks:

  • Initialize the Shop SDK on your storefront.
  • Create a lead capture instance and add it to your page.
  • Handle events when a lead is captured or an error occurs.

Anchor to RequirementsRequirements

  • A Shop app with a client ID.
  • A storefront where you can add HTML and JavaScript.

Anchor to Step 1: Load and initialize the SDKStep 1: Load and initialize the SDK

Add the SDK loader script to your page and initialize it with your client ID:

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',
features: {
'lead-capture': true, // Preload the lead capture code
},
});
</script>

Setting 'lead-capture': true in features starts loading the lead capture code as soon as the SDK initializes, so it's ready when you call sdk.create().

Anchor to Step 2: Create a lead capture instanceStep 2: Create a lead capture instance

Call sdk.create('lead-capture', config) to create an instance. The method returns a Promise that resolves once the feature is loaded and the element is ready.

JavaScript

const leadCapture = await sdk.create('lead-capture', {
attributes: {
flow: 'discount',
buttonType: 'save',
buttonLayout: 'standalone',
},
onComplete(event) {
console.log('Lead captured:', event.email, 'Signed in:', event.signedIn);
},
onError(event) {
console.error('Lead capture error:', event.code, event.message);
},
onLoad(event) {
console.log('Loaded, user found:', event.userFound);
},
});

// Insert the element where you want it on the page
document.querySelector('#lead-capture-container').appendChild(leadCapture.element);

To apply a discount after capture, add an optional onAuthenticate handler that returns a discount object with a code. If you don't provide onAuthenticate, the flow completes without applying a discount.

JavaScript

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

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

For the full list of attributes and event handlers, see the lead capture reference.

Anchor to Step 3: (Optional) Start the flow programmaticallyStep 3: (Optional) Start the flow programmatically

If you want to trigger the lead capture flow with a pre-filled email (for example, after the user types into your own email input), call start():

JavaScript

leadCapture.start('user@example.com');

Anchor to CleanupCleanup

When you no longer need the lead capture instance, call destroy() to remove the element from the DOM and clean up event listeners:

JavaScript

leadCapture.destroy();

Anchor to Next stepsNext steps

Was this page helpful?