1. Home
  2. Documentation
  3. Selling with Freemius
  4. Freemius Checkout / Buy Button JavaScript API

Freemius Checkout / Buy Button 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>
<button id="purchase">Buy Button</button>
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="https://checkout.freemius.com/checkout.min.js"></script>
    var handler = FS.Checkout.configure({
        plugin_id:  '<productID>',
        plan_id:    '<planID>',
        public_key: '<productPublicKey>',
        image:      'https://your-plugin-site.com/logo-100x100.png'

    $('#purchase').on('click', function (e) {
            name     : '<productTitle>',
            licenses : $('#licenses').val(),
            // You can consume the response for after purchase logic.
            success  : function (response) {
                // alert(response.user.email);

You can find more advanced multi-plan + multi-site licenses example via this Gist.


Required product ID (whether it’s a plugin, theme, add-on, bundle, or SaaS).

Require product public key.

An optional ID to set the id attribute of the checkout’s <body> HTML element. This argument is particularly useful if you have multiple checkout instances that need to have a slightly different design or visibility of UI components. You can assign a unique ID for each instance and customize it differently using the CSS stylesheet that you can attach through the PLANS -> CUSTOMIZATION in the Developer Dashboard.
namestringoptional Defaults to the product’s title set within the Freemius dashboard.

An optional string to override the product’s title.
titlestringoptional Defaults to “Great selection, {{ firstName }}!”

An optional string to override the checkout’s title when buying a new license.
subtitlestringoptional Defaults to “You’re one step closer to our {{ planTitle }} features”

An optional string to override the checkout’s subtitle.
imagestringoptional Defaults to the product’s title set within the Freemius dashboard.

An optional icon that loads at the checkout and will override the product’s icon uploaded to the Freemius Dashboard. Use a secure path to the image over HTTPS. While the checkout will remain PCI compliant, credit-card automatic prefill by the browser will not work.
plan_idnumberoptional Defaults to the 1st paid plan.

The ID of the plan that will load with the checkout. When selling multiple plans you can set the param when calling the open() method.
licensesnumberoptional Default is 1

A multi-site licenses prices that will load immediately with the checkout. A developer-friendly param that can be used instead of the pricing_id. To specify unlimited licenses prices, use one of the following values: 0, null, or 'unlimited'.
disable_licenses_selectorbooleanoptionalnew Default is false

Set this param to true if you like to disable the licenses selector when the product is sold with multiple license activation options.
pricing_idnumberoptional Defaults to the plan’s single-site prices ID.

Use the licenses param instead. An optional ID of the exact multi-site license prices that will load once the checkout opened.
billing_cyclestringoptional Defaults is 'annual'

An optional billing cycle that will be auto selected when the checkout is opened. Can be one of the following values: 'monthly', 'annual', 'lifetime'.
hide_billing_cyclesbooleanoptionalnew Defaults is false

Set this param to true if you like to hide the billing cycles selector when the product is sold in multiple billing frequencies.
currencystringoptional Defaults is 'usd'

One of the following 3-chars currency codes (ISO 4217): 'usd', 'eur', 'gbp'.
If you configure prices in all three supported currencies, you could also set the parameter to 'auto' to let the checkout automatically choose the currency based on the geolocation of the user. If you decide to choose the 'auto' option, you may also want to dynamically show the prices on your pricing page according to the user’s geo. Therefore, we created checkout.freemius.com/geo.json to allow you to identify the browser’s geo and currency that the checkout will use by default.

To set the default currency of the pricing page and checkout within the WP Admin dashboard, use the 'default_currency' filter:
						function my_default_currency( $currency ) {
						    return 'eur';
						my_fs()->add_filter( 'default_currency', 'my_default_currency' );

An optional coupon code to be automatically applied on the checkout immediately when opened.
hide_couponbooleanoptional Defaults is false

Set this param to true if you pre-populate a coupon and like to hide the coupon code and coupon input field from the user.
maximize_discountsbooleanoptional Defaults is true

Set this param to false when selling a bundle and you want the discounts to be based on the closest licenses quota and billing cycle from the child products. Unlike the default discounts calculation which is maximized by basing the discounts on the child products single-site prices.
trialboolean or 'free' or 'paid'optional Defaults is false

When set to true, it will open the checkout in a trial mode and the trial type (free vs. paid) will be based on the plan’s configuration. This will only work if you’ve activated the Free Trial functionality in the plan configuration. If you configured the plan to support a trial that doesn’t require a payment method, you can also open the checkout in a trial mode that requires a payment method by setting the value to 'paid'.

A callback handler that will execute once a user closes the checkout by clicking the close icon. This handler only executes when the checkout is running in a dialog mode.
purchaseCompletedcallable(data: Object)optional

An after successful purchase/subscription completion callback handler.
Notice: When the user subscribes to a recurring billing plan, this method will execute upon a successful subscription creation. It doesn’t guarantee that the subscription’s initial payment was processed successfully as well. 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.
successcallable(data: Object)optional

An optional callback handler, similar to purchaseCompleted. The main difference is that this callback will only execute after the user clicks the “Got It”” button that appears in the after purchase screen as a declaration that they successfully received the after purchase email. This callback is obsolete when the checkout is running in a dashboard mode.”
trackcallable(event: String, data: Object)optionalnew

An optional callback handler for advanced tracking, which will be called on multiple checkout events such as updates in the currency, billing cycle, licenses #, etc.

An optional param to pre-populate a license key for license renewal, license extension and more.
is_payment_method_updatebooleanoptional Defaults is false

An optional param to load the checkout for a payment method update. When set to `true`, the license_key param must be set and associated with a non-canceled subscription.

An optional string to prefill the buyer’s email address.

An optional string to prefill the buyer’s first name.

An optional string to prefill the buyer’s last name.

An optional user ID to associate purchases generated through the checkout with their affiliate account.

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.

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:

  purchaseCompleted: function( response ) {
          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';

      if ( typeof fbq !== "undefined" ) {
          fbq( 'track', 'Purchase', { 
              currency: response.purchase.currency.toUpperCase(), 
              value: total
          } );

      if ( typeof ga !== "undefined" ) {
          ga( 'send', 'event', 'plugin', 'purchase', productName );

          ga( 'require', 'ecommerce' );

          ga( 'ecommerce:addTransaction', {
              'id': response.purchase.id.toString(), // Transaction ID. Required.
              'affiliation': storeName,              // Affiliation or store name.
              'revenue': total,                      // Grand Total.
              'shipping': '0',                       // Shipping.
              'tax': '0'                             // Tax.
          } );

          ga( 'ecommerce:addItem', {
              'id': response.purchase.id.toString(),                // Transaction ID. Required.
              'name': productName,                                  // Product name. Required.
              'sku': response.purchase.plan_id.toString(),          // SKU/code.
              'category': 'Plugin',                                 // Category or variation.
              'price': response.purchase.initial_amount.toString(), // Unit price.
              'quantity': '1' // Quantity.
          } );

          ga( 'ecommerce:send' );

          ga( 'send', {
              hitType: 'pageview',
              page: '/purchase-completed/',
              location: storeUrl + '/purchase-completed/'
          } );

This snippet was kindly contributed by James Kemp from IconicWP 🙌

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:

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

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