Freemius Overlay Checkout JavaScript API

Selling with Freemius from any website takes just a few minutes to configure. Once you have your product’s plans and pricing set up within the Freemius Dashboard, simply go to the Plans section and click the Get Checkout Code button.

You’ll get a ready-to-use simple JavaScript snippet that you can embed on any website.

Here’s a simple example of the checkout code will look like for a plan that offers 3 multi-site prices:

<select id="licenses">
    <option value="1" selected="selected">Single Site License</option>
    <option value="5">5-Site License</option>
    <option value="25">25-Site License</option>
</select>

<button id="purchase">Buy Button</button>

<script src="https://checkout.freemius.com/js/v1/"></script>
<script>
    const handler = new FS.Checkout({
        product_id: '<productID>',
        plan_id: '<planID>',
        public_key: '<productPublicKey>',
        image: 'https://your-plugin-site.com/logo-100x100.png',
    });

    document.querySelector('#purchase').addEventListener('click', function (e) {
        handler.open({
            title: '<productTitle>',
            licenses: document.querySelector('#licenses').value,
            // You can consume the response for after purchase logic.
            success: function (response) {
                // alert(response.user.email);
            },
        });
        e.preventDefault();
    });
</script>

You can find more advanced multi-plan + multi-site licenses example via this Gist. For more information about the JS SDK, and to use it with NPM, please refer to our official GitHub repository.

Freemius will attempt to recover the sale when a checkout is abandoned using an out-of-the-box Cart Abandonment Recovery mechanism. For this mechanism to properly work, make sure that new FS.Checkout() is called right with the page loading. Otherwise, the links in the cart recovery email campaign won’t automatically open the checkout in its saved state.

Arguments

                function my_default_currency( $currency ) {
                     return 'eur';
                }

                my_fs()->add_filter( 'default_currency', 'my_default_currency' );
                

All the parameters can be preset when configuring the checkout using FS.Checkout.configure(). If you need to set different param values based on the user’s selection, you can set all the params except plugin_id and public_key when executing the handler.open() method.

To add a coupon to a URL, so your customers automatically arrive to the Freemius Checkout page with a coupon activated, all you need to do is add ?coupon=12345 to the end of the URL. 12345 should be replaced with the coupon code.

User & Purchase Data in Callbacks

If you’re hooking into the success or purchaseCompleted callbacks for advanced integrations, you can retrieve purchase and user information from the first argument passed to your callback. For example:

handler.open({
  success(data) {
    // Get the user
    console.log(data.user);
    // Get the purchase
    console.log(data.purchase);
  }
});

The user Object

Contains details about the user who completed the purchase:

• email: Buyer’s email address
• first: First name
• last: Last name
• id: Freemius user ID

The purchase Object

The purchase object differs depending on whether the transaction is a subscription or a one-off payment. Key properties include:

• plan_id: ID of the purchased plan
• license_id: ID of the license created or updated
• subscription_id: ID of the subscription (only present for subscriptions)
• billing_cycle: Subscription billing frequency (only present for subscriptions)

The full structure is documented in our repository. If you’re using the @freemius/checkout package, you’ll get full IDE type intellisense support.

Tracking purchases with Google Analytics and Facebook

The easiest way to track purchase conversions with external analytics and conversion tracking tools like Google Analytics is by leveraging the purchaseCompleted callback.

Here is an implementation example:

handler.open({
    // ...
    purchaseCompleted: function (response) {
        var isTrial = null != response.purchase.trial_ends,
            isSubscription = null != response.purchase.initial_amount,
            total = isTrial
                ? 0
                : (isSubscription
                        ? response.purchase.initial_amount
                        : response.purchase.gross
                  ).toString(),
            productName = 'Product Name',
            storeUrl = 'https://your-site.com',
            storeName = 'Store Name';

        // Facebook Pixel tracking code.
        if (typeof fbq !== 'undefined') {
            fbq('track', 'Purchase', {
                currency: response.purchase.currency.toUpperCase(),
                value: total,
            });
        }

        // The new GA4 gtag based tracking code.
        if (typeof gtag !== 'undefined') {
            gtag('event', 'purchase', {
                transaction_id: response.purchase.id.toString(), // Transaction ID. Required.
                affiliation: storeName, // Affiliation or store name.
                value: total, // Grand Total.
                shipping: 0, // Shipping.
                tax: 0, // Tax.
                currency: response.purchase.currency.toUpperCase(), // Currency.
                items: [
                    {
                        item_id: response.purchase.plugin_id.toString(), // SKU/code.
                        item_variant: response.purchase.plan_id.toString(), // SKU/code.
                        item_name: productName, // Product name. Required.
                        item_category: 'Plugin', // Category or variation.
                        price: total, // Unit price.
                        quantity: 1, // Quantity
                        currency: response.purchase.currency.toUpperCase(), // Currency.
                    },
                ],
            });

            gtag('event', 'page_view', {
                page_title: '/purchase-completed/',
                page_location: storeUrl + '/purchase-completed/',
            });
        }
    },
    // ...
});

If you’d like to leverage this method for the in-dashboard/WP-Admin checkout, you’ll need to utilize a special filter named checkout/purchaseCompleted as in this example.

Advanced Event Tracking new

You can leverage the track callback handler to act upon different checkout actions taken by the user. Here’s how you can use it including the list of the currently supported events:

handler.open({
  ...
  
  track: function( event, data ) {
	  const product = data.product;
	  const user = data.user;

    switch (event) {
      case 'load':
        // Checkout loaded.
        break;
      case 'currency-changed':
        // Currency changed.
        break;
      case 'licenses-inc':
        // Licenses # increased.
        break;
      case 'licenses-dec':
        // Licenses # decreased.
        break;
      case 'billing-cycle-updated':
        // Billing cycle update.
        break;
      case 'email-updated':
        // Email address set or updated.
        break;
      case 'coupon-updated':
        // Coupon set or updated.
        break;
      case 'paypal-express-checkout':
        // PayPal express checkout started.
        break;
      case 'review-order':
        // User moved to review mode, i.e., they already filled up their payment method details and ready to confirm the purchase.
        break;
      case 'cooling-off-waiver-toggled':
        // Cooling-off waiver toggled (only relevant for EU buyers).
        break;
      case 'complete':
        // Purchase completed.
        break;
      case 'exit-intent-shown':
        // Exit intent shown.
        break;
      case 'exit-intent-promotion-ended':
        // Exit intent promotion ended.
        break;
      case 'exit-intent-discount-applied':
        // Exit intent discount applied.
        break;
      case 'exit-intent-discount-canceled':
        // Exit intent discount denied.
        break;
    }
  },
  
  ...
});

User Token in Checkout new

This feature lets you load the Freemius Checkout app where the user’s name, email, VAT, country, Zip Code/Postal Code etc are already prepopulated, in a safe and secure way.

The pre-requisites are:

1. You must know the Freemius User ID of the user going through the checkout.
2. You must make a Freemius API call in the context of the same plugin/product for which you are loading the checkout.
3. The token must be used immediately while loading the checkout. The lifespan of the token is 1 minutes.

High-level process

1. When the user clicks on the purchase button, make a call to YOUR backend.
2. Your backend will figure out the ID of the user and the ID of the product they are trying to purchase.
3. The backend will call Freemius API to generate a token.
4. The token would be given back to the JavaScript application which intercepted the “click”.
5. The JavaScript application will then open the Freemius checkout while passing in the generated token as user_token in the configuration.

Code example is given for both your backend (using PHP and Freemius PHP SDK) and JavaScript app.

checkout-app.js
This is a sample JavaScript code that you can use to initialize the checkout on your website.

<!-- Init the Freemius Checkout JS SDK. -->
<script>
    const fsCheckout = FS.Checkout.configure({
        plugin_id:  '9889',
        plan_id:    '16645',
        public_key: 'pk_6405fe361ba0a6e68d14fb480d98b',
        image:      'https://your-plugin-site.com/logo-100x100.png'
    });

    // Assume the purchase button has an ID `#purchase`
    const purchaseButton = document.querySelector('#purchase');

    purchaseButton.addEventListener('click', async (e) => {
        e.preventDefault();

        // First make an API call to YOUR backend to generate the user token.
        const userToken = await fetch('https://yoursite.com/generate-user-token.php', { method: 'POST' })
                                  .then(response => response.json())
                                  .then(data => data.token);

        // Now load the Freemius Checkout with the freshly generated token.
        fsCheckout.open({
            // Add the user Token as `user_token` parameter.
            user_token: userToken,
            // ....other configuration option
        });
    });
</script>

generate-user-token.php
This is a sample backend code to which the JS code would make a request to get the token.

<?php

// Use the Freemius PHP SDK
define( 'FS__API_SCOPE', 'developer' );
define( 'FS__API_DEV_ID', 1234 );
define( 'FS__API_PUBLIC_KEY', 'pk_YOUR_PUBLIC_KEY' );
define( 'FS__API_SECRET_KEY', 'sk_YOUR_SECRET_KEY' );

// Init SDK.
$api = new Freemius_Api(FS__API_SCOPE, FS__API_DEV_ID, FS__API_PUBLIC_KEY, FS__API_SECRET_KEY);

// Figure out the product ID and the user ID.
$plugin_id = '...';
$user_id   = '...';

// Make an API call to the token generator.
$result = $api->Api("plugins/{$plugin_id}/users/{$user_id}/tokens/checkout.json");

// Send the token back to your JS application.
echo json_encode(array(
  'token' => $result['token'],
));

Please generate the user_token right before opening the checkout and open the checkout as soon as the token is generated. The token has a short life-span and you must not generate it before hand.