Migrate to the JavaScript SDK - Smile.io Developer Documentation

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

The Smile.* methods bundled with Smile UI will be removed on August 1, 2026. Please migrate to the new JavaScript SDK as soon as possible to avoid any potential issues.

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.

FAQ

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

No. The deprecation 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 deprecated 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 deprecated 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 deprecation warnings related to the Smile.* methods 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 deprecation warnings, try searching through your codebase for any remaining references to the deprecated methods.If you’ve done both and haven’t found any references to the deprecated methods in your codebase or seen any deprecation warnings in the browser console, no migration is required.

What is the full list of methods that are being deprecated?

The full list of methods that are being deprecated 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 deprecated method?

If you’re using a deprecated method, you’ll need to follow the instructions in the migration 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 don't migrate by August 1, 2026?

On August 1, 2026, the deprecated Smile.* methods will be removed entirely. Any custom code still calling them will throw errors and stop working — for example, custom points balance displays, referral URL displays, or any custom loyalty pages built using the deprecated methods would break.Standard Smile UI functionality (the rewards panel and launcher) is not affected and will continue 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?

No downtime is required if you complete the migration before August 1, 2026. The new JavaScript SDK can be loaded alongside your existing Smile UI integration, and the deprecated Smile.* methods will continue to work (with deprecation warnings in the browser console) up until that date. This means you can migrate incrementally and test thoroughly before the deadline.After August 1, 2026, any custom code still using the deprecated methods will stop working, which could affect custom-built parts of your storefront.

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

Forward them this migration guide. It contains the full list of deprecated 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?

Yes. Until August 1, 2026, the deprecated Smile.* methods will continue to work (with deprecation warnings in the browser console) alongside their new JavaScript SDK equivalents. This means you can migrate one method call at a time, test as you go, and ship changes incrementally rather than all at once.

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 deprecation warnings in the browser console, custom features functioning correctly), deploy the changes to production.

Why are the Smile.* methods being deprecated?

The deprecated 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.

Documentation Index

​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

​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 deprecation warnings

Where to get help

FAQ