Sign in with Shop

Use the Shop SDK login feature to add Sign in with Shop to your self-hosted login page. The SDK loads the sign-in code, creates a login instance, and returns an element that you can mount where the sign-in experience should appear.

Anchor to What you'll learnWhat you'll learn

In this guide, you'll learn how to:

• Initialize the Shop SDK.
• Create a login feature instance and add it to your page.
• Handle authentication events after the user signs in.

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. If you want to preload the login code before calling sdk.create(), set features.login to true.

The script registers window.ShopSDK when it loads. initialize returns an SDK instance that you use to create the login feature.

Anchor to Step 2: Create a login instanceStep 2: Create a login instance

Call sdk.create('login', config) to create a login instance. The method returns a Promise that resolves after the feature is loaded and the element is ready.

Use the builder to customize the generated SDK code for your login button:

Add a container to your page, such as <div id="login-container"></div>. The SDK creates the underlying HTML element for you. You're responsible for inserting login.element into the DOM wherever you want the sign-in experience to appear.

Anchor to Login attributesLogin attributes

The following attributes are common for the login feature. Pass them as JavaScript configuration in sdk.create(), not as markup on the page.

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

Anchor to Step 3: Handle authentication resultsStep 3: Handle authentication results

The onComplete handler runs after the sign-in flow completes. Use it to update your UI or send the authentication result to your backend. If the event includes user-scoped credentials, then handle them like other authentication tokens:

• Send them only over HTTPS.
• If your app needs them after the page session, then store them server-side.
• Don't log them in analytics or error reports.

The onError handler runs when the login flow can't complete. Use it to show a fallback login path or ask the user to try again.

Anchor to LocalizationLocalization

Sign in with Shop supports multiple languages so users can sign in in their preferred language. This improves accessibility and helps you accommodate a diverse user base.

Anchor to Set the localeSet the locale

Set the language with the locale option when you initialize the SDK. Pass a BCP-47 locale tag, such as 'en', 'fr', or 'ro-RO'. The locale defaults to 'en' and is inherited by every feature you create, including login.

Anchor to Supported localesSupported locales

The button text adapts to the buttonType you choose. For example, buttonType: 'continue' renders a Continue with Shop button. Regardless of the buttonType, the button text is translated according to the configured locale. With locale: 'fr', a 'continue' button renders as Continuer avec Shop.

The SDK supports the following locales for the login button text:

Anchor to Next stepsNext steps

• Review the full login feature reference.
• If your sign-in flow returns a shopConsentToken, then exchange it for a user access token to read and write Shop User data. See Store metafields on Shop users.
• Use the lead capture feature to collect email addresses from users who aren't yet signed in.