Migrate to the JavaScript SDK

Previously, a set of Smile.* methods were bundled with Smile UI, which allowed you to fetch and interact with customer and loyalty program data using JavaScript. As of February 2026, these methods are being deprecated and replaced with a new standalone JavaScript SDK library that can be used independently of (or together with) Smile UI. This guide will walk you through what’s new and how to migrate your code.

What’s new

The new JavaScript SDK, Smile.js, is a standalone library can be used with or without Smile UI. It offers methods for fetching and interacting with customer and loyalty program data, and works with modern JavaScript tooling and frameworks. Once you’ve upgraded, you’ll be able to:

Load the SDK via a script tag or a bundler like Vite or Webpack.
Use included TypeScript type definitions for autocomplete and type checking.
Preload multiple resources in a single API call to reduce latency and load times.
Log customers in and out programmatically without a full page reload.
Access additional data such as detailed customer VIP status and program settings.

How to migrate

To migrate to the new JavaScript SDK, you need to make the following changes to your code. Each step contains instructions and examples to guide you along the way.

Tip: Throughout this guide, pay special attention to when instructions and code samples refer to the Smile vs. SmileUI class to avoid confusion.

1. Include the JavaScript SDK

Shopify
BigCommerce
Custom storefront

If you’re using a standard Shopify storefront (not Shopify Hydrogen), ensure that the JavaScript SDK setting is enabled in Smile Admin. This will automatically include the JavaScript SDK on your storefront without additional code required.

If you’re using a custom storefront and want to continue to use the rewards panel and launcher, update your code to pass an includeSdk: true parameter when initializing Smile UI.

JavaScript

SmileUI.initialize({
  publishableKey: "pub_0987654321",
  customerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  includeSdk: true
});

If you no longer wish to use the launcher and panel, replace your code for including and initializing Smile UI with code to include and initialize the JavaScript SDK instead. The values for the publishableKey and customerToken parameters do not need to change.

HTML

<script async src="https://js.smile.io/v1/smile-ui.js"></script>
<script async src="https://sdk.smile.io/smile-js/v1/smile.js"></script>

<script>
  SmileUI.initialize({ 
  Smile.initialize({ 
    publishableKey: "pub_0987654321",
    customerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  });
</script>

2. Update method calls

Any call sites for deprecated Smile.* methods should be updated to use the corresponding methods from the JavaScript SDK instead.

With the exception of the Smile.purchasePointsProduct() method, no parameter names or values have changed, so you can simply replace method names with the corresponding equivalent from the JavaScript SDK.

Old `Smile.*` method	New JavaScript SDK method
`Smile.createActivity()`	`Smile.activities.create()`
`Smile.customerReady()`	Listen for the `smile-js-initialized` event instead.
`Smile.fetchAllCustomerPointsProducts()`	`Smile.customerPointsProducts.get()`
`Smile.fetchAllPointsProducts()`	`Smile.pointsProducts.get()`
`Smile.fetchAllRewardFulfillments()`	`Smile.rewardFulfillments.get()`
`Smile.fetchCustomer()`	Based on the data you need, use any of: • `Smile.customer.current()` - name & referral URL • `Smile.customerPointsWallet.get()` - points balance • `Smile.customerVipStatus.get()` - VIP tier
`Smile.fetchPointsProduct()`	`Smile.pointsProducts.get()`
`Smile.purchasePointsProduct()`	`Smile.pointsProducts.purchase()` (see note) Note: The `points_to_spend` parameter has changed to `pointsToSpend`.
`Smile.ready()`	Listen for the `smile-js-initialized` event instead.

3. Update customer ready calls

The SmileUI.customerReady() method is now deprecated, and the appropriate replacement depends on what you’re trying to achieve.

To detect when it’s safe to call other SmileUI.* methods, use the SmileUI.ready() method. This would typically be for situations where you want to programmatically open the loyalty panel or launcher.
To detect when it’s safe to call other Smile.* methods, listen for the smile-js-initialized event from the JavaScript SDK. This would typically be for situations where you want to programmatically access information about the customer or loyalty program (like displaying their points balance).

Calling SmileUI.* methods
Calling Smile.* methods

JavaScript

SmileUI.customerReady().then(() => { 
SmileUI.ready().then(() => { 
  // Safe to call SmileUI.* methods
});

JavaScript

SmileUI.customerReady().then(() => { 
document.addEventListener('smile-js-initialized', () => { 
  // Safe to call Smile.* methods
});

4. Update object properties

The JavaScript SDK now returns all objects with camelCase property names (instead of snake_case) for improved compatibility with modern JavaScript frameworks and tooling. As such, you’ll need to update any code that accesses object properties to use the new camelCase names.

5. Audit for preloading

The JavaScript SDK introduces the ability to preload resources, enabling you to retrieve multiple resources on initial page load and reduce the number of roundtrip API calls being made. This helps improve performance and reduce latency, while also providing instant access to preloaded data via new .preloaded() methods on each resource class. Read our guide on preloading resources, and then audit your code for opportunities to switch from using .get() methods to the new .preloaded() methods instead. Often, it’s as simple as replacing a single .get() call with a single .preloaded() call, like so:

JavaScript

await Smile.initialize({
  publishableKey: 'pub_0987654321',
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  preload: ['pointsProducts', 'customerPointsWallet'] 
});

// Make separate API calls for each resource
const pointsProducts = await Smile.pointsProducts.get();
const pointsWallet = await Smile.customerPointsWallet.get();
// Access preloaded data instantly (no additional API calls)
const pointsProducts = Smile.pointsProducts.preloaded();
const pointsWallet = Smile.customerPointsWallet.preloaded();

6. Preload points settings

The Smile.formatPoints() method is now part of the JavaScript SDK and requires that the account’s points settings be preloaded before points values can be formatted.

Shopify
BigCommerce
Custom storefront

If you’re using the Smile.formatPoints() method, you’ll need to call Smile.preload() with pointsSettings before formatting points.

JavaScript

await Smile.preload(['pointsSettings']); 

const formattedPoints = Smile.formatPoints(1000);

If you’re using the Smile.formatPoints() method, you’ll need to call Smile.preload() with pointsSettings before formatting points.

JavaScript

await Smile.preload(['pointsSettings']); 

const formattedPoints = Smile.formatPoints(1000);

If you’re using the Smile.formatPoints() method, you’ll need to include pointsSettings in the preload array during initialization, or call Smile.preload() with pointsSettings before calling the method.

await Smile.initialize({
  publishableKey: 'pub_0987654321',
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  preload: ['pointsSettings'] 
});

const formattedPoints = Smile.formatPoints(1000);

You only need to preload the pointsSettings resource once per pageload (whether during initialization or later). Subsequent calls to Smile.formatPoints() will use the cached value from the preloaded resource.

7. Audit manual page reloads

With Smile UI
Standalone JavaScript SDK

If you’re including the JavaScript SDK alongside Smile UI (e.g. are still using the rewards panel and launcher), you’ll need to continue to trigger full page reloads after any action that would change the customer’s state or points balance (e.g. logging in or out, redeeming points, completing an activity, etc).Assuming your storefront was already using the rewards panel and launcher prior to beginning the migration process, no changes are required.

If you’re using the JavaScript SDK standalone (without the rewards panel and launcher / Smile UI), you can now programatically log customers in and out and refresh customer data without a full page reload.

To log a customer in, use Smile.customer.login().
To log a customer out, use Smile.customer.logout().
To refresh customer data, use Smile.preload() with the appropriate resource key(s).

While the old manual page reload approach will continue to work, we recommend auditing your codebase for opportunities to switch to using the new methods instead. A complete example of using the new methods in sequence might look like:

JavaScript

// Log a customer in and preload their points balance
await Smile.customer.login({
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  preload: ['customerPointsWallet', 'pointsSettings']
});

// Display the customer's current points balance
const pointsBalance = Smile.customerPointsWallet.preloaded();
console.log("You've got", Smile.formatPoints(pointsBalance), "!");

// Purchase a points product (e.g. spend points)
await Smile.pointsProducts.purchase(132456921);

// Complete an activity (e.g. earn points)
await Smile.activities.create({token: 'activity_1dDdzcKNsp84b'});

// Refresh customer points balance
await Smile.preload(['customerPointsWallet']);

// Show the updated points balance
const pointsBalance = Smile.customerPointsWallet.preloaded();
console.log("You've got", Smile.formatPoints(pointsBalance), "!");

// Log the customer out
await Smile.customer.logout();

8. Check for deprecation warnings

After the completing the migration steps above, you should no longer see any deprecation warnings in the browser console when viewing your storefront. If you do, it means that you’re still using one or more of the deprecated Smile.* methods and your code requires further updates.

Where to get help

While we aren’t able to assist with updating, debugging, or reviewing custom code, our support team can help answer questions or clarify details related to the migration process or the JavaScript SDK itself. If you need assistance updating your code, our team can help connect you with an agency partner who specializes in Smile integrations.

Getting started

Apps & integrations

Deprecated

What’s new

How to migrate

1. Include the JavaScript SDK

2. Update method calls

3. Update customer ready calls

4. Update object properties

5. Audit for preloading

6. Preload points settings

7. Audit manual page reloads

8. Check for deprecation warnings

Where to get help

Getting started

Apps & integrations

Deprecated

​What’s new

​How to migrate

​1. Include the JavaScript SDK

​2. Update method calls

​3. Update customer ready calls

​4. Update object properties

​5. Audit for preloading

​6. Preload points settings

​7. Audit manual page reloads

​8. Check for deprecation warnings

​Where to get help

What’s new

How to migrate

1. Include the JavaScript SDK

2. Update method calls

3. Update customer ready calls

4. Update object properties

5. Audit for preloading

6. Preload points settings

7. Audit manual page reloads

8. Check for deprecation warnings

Where to get help