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. These methods have been removed and replaced with a new standalone JavaScript SDK library that can be used independently of (or together with) Smile UI. This guide walks you through what’s new and how to migrate your code.

The Smile.* methods bundled with Smile UI have been removed. Any code still calling them throws standard JavaScript errors (e.g. TypeError: Smile.fetchCustomer is not a function) until it’s migrated to the new JavaScript SDK.

What’s new

The new JavaScript SDK, Smile.js, is a standalone library that 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 the removed 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.getById()`
`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 has been removed, 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);

await Smile.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 continues 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 remaining errors

After completing the migration steps above, you should no longer see any errors related to the removed Smile.* methods (e.g. TypeError: Smile.fetchCustomer is not a function) in the browser console when viewing your storefront. If you do, it means that you’re still calling one or more of the removed 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.

FAQ

Does this affect me if I only use the standard rewards panel and launcher?

No. The removal only affects custom JavaScript code that uses the bundled Smile.* methods (like Smile.fetchCustomer() or Smile.createActivity()). If your storefront only uses the out-of-the-box rewards panel and launcher and hasn’t been customized with code that calls these methods, no action is required.This migration only applies if you (or your developer) wrote custom code using the removed methods — typically to embed loyalty information directly into your storefront (e.g. a customer’s points balance in the site header) or to build custom loyalty pages and experiences.

How do I know if I'm using a removed method?

The easiest way to check is to open the browser console and visit every page on your website that includes loyalty information or functionality. While browsing each page, look for any errors related to the Smile.* methods (e.g. TypeError: Smile.fetchCustomer is not a function) in the browser console. If you see any, you’ll need to update your code to use the corresponding methods from the JavaScript SDK instead.If you’ve visited every page on your website and don’t see any of these errors, try searching through your codebase for any remaining references to the removed methods.If you’ve done both and haven’t found any references to the removed methods in your codebase or seen any related errors in the browser console, no migration is required.

What is the full list of methods that were removed?

The full list of methods that were removed is as follows:

Smile.createActivity()
Smile.customerReady()
Smile.fetchAllCustomerPointsProducts()
Smile.fetchAllPointsProducts()
Smile.fetchAllRewardFulfillments()
Smile.fetchCustomer()
Smile.fetchPointsProduct()
Smile.formatPoints()
Smile.purchasePointsProduct()
Smile.ready()

What should I do if I'm using a removed method?

If you’re using a removed method, you’ll need to follow the migration steps in this guide to update your code. If you need help, our team can help connect you with an agency partner who specializes in Smile integrations.

Can Smile do the migration for me?

Unfortunately, no. Smile doesn’t have access to your storefront’s code, so we aren’t able to update, debug, or review custom code on your behalf. Our support team is happy to answer questions about the migration process or the JavaScript SDK itself, but the code changes need to be made by you or your developer.If you don’t have a developer or agency on hand, our team can connect you with an agency partner who specializes in Smile integrations.

What happens if I haven't migrated yet?

The removed Smile.* methods now throw standard JavaScript errors (e.g. TypeError: Smile.fetchCustomer is not a function). Any custom code still calling them doesn’t work — for example, custom points balance displays, referral URL displays, or any custom loyalty pages built using the removed methods. Following the migration steps in this guide restores that functionality.Standard Smile UI functionality (the rewards panel and launcher) is not affected and continues to work as expected.

Will my customers' points balances or other loyalty data be affected by the migration?

No. This migration is a change to frontend JavaScript code only. Customer points balances, VIP statuses, redemption history, and all other loyalty data are stored on Smile’s servers and are completely unaffected by the migration.

Will my customers experience any downtime during the migration?

The standard rewards panel and launcher are unaffected and continue to work throughout the migration.However, any custom functionality built with the removed Smile.* methods stopped working when the methods were removed, and remains unavailable until you migrate that code to the JavaScript SDK. Each call site starts working again as soon as its migrated code is deployed, so you can migrate and ship incrementally.

My developer or agency built our custom integration — what should I send them?

Forward them this migration guide. It contains the full list of removed methods, their replacements, and step-by-step migration instructions.If you don’t currently have a developer or agency on hand, our support team can help connect you with an agency partner who specializes in Smile integrations.

Can I run both the old Smile.* methods and the new JavaScript SDK side-by-side during migration?

No. The old Smile.* methods have been removed and no longer work, so they can’t run alongside their JavaScript SDK equivalents. You can still migrate one method call at a time, test as you go, and ship changes incrementally rather than all at once — each migrated call starts working as soon as it’s deployed.

How can I test the migration before deploying to production?

We recommend testing the migration in a staging or development environment before deploying to your live storefront:

Shopify: Use a development store or a duplicate of your live theme to test changes before publishing.
BigCommerce: Use a staging or preview store.
Custom storefront: Use whatever staging or preview environment you typically deploy to before production.

Once you’ve verified everything works as expected (no errors related to Smile.* methods in the browser console, custom features functioning correctly), deploy the changes to production.

Why were the Smile.* methods removed?

The removed Smile.* methods were bundled with Smile UI and were difficult to use in modern JavaScript projects. The new JavaScript SDK is a standalone library that brings several improvements:

Works with modern frameworks and bundlers (e.g. Vite, Webpack)
Includes TypeScript type definitions for autocomplete and type checking
Supports preloading multiple resources in a single API call to reduce latency
Allows logging customers in and out programmatically without a full page reload
Provides access to additional data such as detailed VIP status and program settings

See the What’s new section above for more details.

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 remaining errors

Where to get help

FAQ

​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 remaining errors

​Where to get help

​FAQ

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 remaining errors

Where to get help

FAQ