Skip to main content
Start selling

Migration Guide

This guide applies to you only if you're using the legacy version of the Checkout JS SDK, using the following script to include it:

<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="https://checkout.freemius.com/checkout.min.js"></script>

There are two ways to migrate your existing code to the new version:

This approach requires some code changes, but it is the recommended way to migrate to the new version.

Instructions:​

  1. In your existing code, locate the following scripts that might be used to include the Checkout SDK:
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="https://checkout.freemius.com/checkout.min.js"></script>

  1. Remove the jQuery script tag if you are not using jQuery.

  2. Replace the checkout script with the new one.

<script src="https://checkout.freemius.com/js/v1/"></script>
  1. Change FS.Checkout.configure() to new FS.Checkout():
- // Legacy checkout code
- const handler = FS.Checkout.configure({
+ // New checkout code
+ const handler = new FS.Checkout({
    plugin_id: '1234',
    plan_id: '5678',
    public_key: 'pk_xxxxxxxxxxxxxxxxx',
    image: 'https://your-plugin-site.com/logo-100x100.png',
});

The rest of the code will continue to work exactly as it is, with no changes.

Optionally, you can also change plugin_id to product_id. Both are supported (with preference given to product_id if both are set), and we do not plan to remove plugin_id in the near future.

Your event listener code will remain the same:

document.querySelector('#purchase').addEventListener('click', (e) => {
  handler.open({
    name: 'My Awesome Plugin',
    licenses: getSelectedLicenses(),
    // You can consume the response for after purchase logic.
    purchaseCompleted: function (response) {
      // The logic here will be executed immediately after the purchase confirmation.
      // alert(response.user.email);
    },
    success: function (response) {
      // The logic here will be executed after the customer closes the checkout, after a successful purchase.
      // alert(response.user.email);
    },
  });

  e.preventDefault();
});

Adding Multiple Checkouts​

If you need to add a checkout for a different configuration on the same page, create a new checkout instance:

const anotherHandler = new FS.Checkout({
  product_id: '4321',
  plan_id: '9876',
  public_key: 'pk_xxxxxxxxxxxxxxxxx',
  image: 'https://your-plugin-site.com/logo-100x100.png',
});

Now, add another event listener that opens the new checkout:

document
  .querySelector('#another-purchase-button')
  .addEventListener('click', (e) => {
    anotherHandler.open({
      name: 'My Awesome Plugin',
      licenses: getSelectedLicenses(),
      purchaseCompleted: function (response) {
        //...
      },
      success: function (response) {
        //...
      },
    });

    e.preventDefault();
  });

Upgrading from the Singleton Interface​

If you have been using the FS.Checkout singleton interface like

FS.Checkout.open({
  plugin_id: '1234',
  // ...
});

Adjust your code to call the methods on the instance instead of the singleton.

const handler = new FS.Checkout({
  plugin_id: '1234',
  // ...
});

handler.open({
  // ...
});

We have also introduced a compatibility layer that you can use as a quick path to migrate to the new Checkout JS without making changes to your checkout code.

However, this approach has the following limitations:

  • It may stop working in a future version.
  • It uses a singleton pattern, which can be confusing when configuring multiple products on the same page.
  • Using the adapter will add extra bytes.

Instructions:​

  1. Look for the checkout script: 
    <script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
    <script src="https://checkout.freemius.com/checkout.min.js"></script>
  2. Remove the jQuery script tag if you are not using jQuery.
  3. Replace the checkout script with the new one. 
    <script src="https://checkout.freemius.com/js/v1/legacy/"></script>

Now all your existing code should work as is.

const handler = FS.Checkout.configure({
  plugin_id: '1234',
  plan_id: '5678',
  public_key: 'pk_xxxxxxxxxxxxxxxxx',
  image: 'https://your-plugin-site.com/logo-100x100.png',
});

document.querySelector('#purchase').addEventListener('click', (e) => {
  handler.open({
    name: 'My Awesome Plugin',
    licenses: getSelectedLicenses(),
    // You can consume the response for after purchase logic.
    purchaseCompleted: function (response) {
      // The logic here will be executed immediately after the purchase confirmation.
      // alert(response.user.email);
    },
    success: function (response) {
      // The logic here will be executed after the customer closes the checkout, after a successful purchase.
      // alert(response.user.email);
    },
  });

  e.preventDefault();
});
On this page: