> ## Documentation Index > Fetch the complete documentation index at: https://dev.smile.io/llms.txt > Use this file to discover all available pages before exploring further. # Migrate to the JavaScript SDK > Migrate to using the new JavaScript SDK instead of the old `Smile.*` methods bundled with Smile UI. Previously, a set of `Smile.*` methods were bundled with [Smile UI](/ui/introduction), 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](/js/introduction) 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 If you're using a standard Shopify storefront (not Shopify Hydrogen), ensure that the [JavaScript SDK setting](https://help.smile.io/en/articles/4891875-javascript-sdk) is enabled in Smile Admin. This will automatically include the JavaScript SDK on your storefront without additional code required. If you're using a standard BigCommerce storefront, ensure that the [JavaScript SDK setting](https://help.smile.io/en/articles/4891875-javascript-sdk) 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 JavaScript lines theme={null} SmileUI.initialize({ publishableKey: "pub_0987654321", customerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", includeSdk: true // [!code ++] }); ``` 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 HTML lines theme={null} // [!code --] // [!code ++] ``` ### 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()`](/js/resources/activities/create)

| | `Smile.customerReady()` | Listen for the [`smile-js-initialized`](/js/concepts/initialized-event) event instead.

| | `Smile.fetchAllCustomerPointsProducts()` | [`Smile.customerPointsProducts.get()`](/js/resources/customer-points-products/get)


| | `Smile.fetchAllPointsProducts()` | [`Smile.pointsProducts.get()`](/js/resources/points-products/get)

| | `Smile.fetchAllRewardFulfillments()` | [`Smile.rewardFulfillments.get()`](/js/resources/reward-fulfillments/get)

| | `Smile.fetchCustomer()` | Based on the data you need, use any of:
• [`Smile.customer.current()`](/js/resources/customer/current) - name & referral URL
• [`Smile.customerPointsWallet.get()`](/js/resources/customer-points-wallet/get) - points balance
• [`Smile.customerVipStatus.get()`](/js/resources/customer-vip-status/get) - VIP tier

| | `Smile.fetchPointsProduct()` | [`Smile.pointsProducts.get()`](/js/resources/points-products/get)

| | `Smile.purchasePointsProduct()` | [`Smile.pointsProducts.purchase()`](/js/resources/points-products/purchase) *(see note)*

**Note:** The `points_to_spend` parameter has changed to `pointsToSpend`.

| | `Smile.ready()` | Listen for the [`smile-js-initialized`](/js/concepts/initialized-event) 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()`](/ui/smile/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`](/js/concepts/initialized-event) 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). ```javascript JavaScript lines theme={null} SmileUI.customerReady().then(() => { // [!code --] SmileUI.ready().then(() => { // [!code ++] // Safe to call SmileUI.* methods }); ``` ```javascript JavaScript lines theme={null} SmileUI.customerReady().then(() => { // [!code --] document.addEventListener('smile-js-initialized', () => { // [!code ++] // 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](/js/concepts/preloading), 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](/js/concepts/preloading), 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 JavaScript lines theme={null} await Smile.initialize({ publishableKey: 'pub_0987654321', customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', preload: ['pointsProducts', 'customerPointsWallet'] // [!code ++] }); // Make separate API calls for each resource // [!code --:3] const pointsProducts = await Smile.pointsProducts.get(); const pointsWallet = await Smile.customerPointsWallet.get(); // Access preloaded data instantly (no additional API calls) // [!code ++:3] 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. If you're using the `Smile.formatPoints()` method, you'll need to call [`Smile.preload()`](/js/smile/preload) with `pointsSettings` before formatting points. ```javascript JavaScript lines theme={null} await Smile.preload(['pointsSettings']); // [!code ++] const formattedPoints = Smile.formatPoints(1000); ``` If you're using the `Smile.formatPoints()` method, you'll need to call [`Smile.preload()`](/js/smile/preload) with `pointsSettings` before formatting points. ```javascript JavaScript lines theme={null} await Smile.preload(['pointsSettings']); // [!code ++] 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](/js/smile/initialize), or call [`Smile.preload()`](/js/smile/preload) with `pointsSettings` before calling the method. ```javascript Preload during initialization lines theme={null} await Smile.initialize({ publishableKey: 'pub_0987654321', customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', preload: ['pointsSettings'] // [!code ++] }); const formattedPoints = Smile.formatPoints(1000); ``` ```javascript Preload later lines theme={null} await Smile.preload(['pointsSettings']); // [!code ++] 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 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()`](/js/resources/customer/login). * To log a customer out, use [`Smile.customer.logout()`](/js/resources/customer/logout). * To refresh customer data, use [`Smile.preload()`](/js/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 JavaScript lines theme={null} // 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](https://help.smile.io/en/articles/4495476-how-to-get-help-with-smile) 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 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. 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. 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()` If you're using a deprecated method, you'll need to follow the instructions in the [migration guide](/guides/use-cases/custom-frontend/js-sdk-migration) to update your code. If you need help, our team can help connect you with an agency partner who specializes in Smile integrations. 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. 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. 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. 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. 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. 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. 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. 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](#whats-new) section above for more details.