Here's a simple example to get you started. This example assumes you're using some bundler like vite or webpack to manage your app.
Install the official npm package.
npm i @freemius/checkout
# If using yarn
yarn add @freemius/checkoutIn your app, given the HTML:
<select id="licenses">
<option value="1" selected="selected">Single Site License</option>
<option value="2">2-Site License</option>
<option value="unlimited">Unlimited Sites License</option>
</select>
<button id="purchase">Buy Button</button>We can now write the JavaScript code to handle the purchase.
import { Checkout } from '@freemius/checkout';
function getSelectedLicenses() {
return document.querySelector('#licenses').value;
}
const handler = new Checkout({
plugin_id: '311',
public_key: 'pk_a42d2ee6de0b31c389d5d11e36211',
});
document.querySelector('#purchase').addEventListener('click', (e) => {
e.preventDefault();
handler.open({
name: 'My Awesome Plugin',
licenses: getSelectedLicenses(),
purchaseCompleted: (response) => {
console.log('Purchase completed:', response);
},
success: (response) => {
console.log('Checkout closed after successful purchase:', response);
},
});
});Please find detailed guides below.
NOTE: If you're migrating from the old checkout JS, please see the migration guide.
To use the hosted CDN, simply include the script tag in your HTML.
<script
type="text/javascript"
src="https://checkout.freemius.com/js/v1/"
></script>This will add the global FS.Checkout class which you can instantiate.
You can also load the script using the async or defer attribute on the
script tag. Note, however, that with asynchronous loading any API calls will
have to be made only after the script execution has finished. For that you'll
need to hook into the load event of window or use window.onload.
<script
type="text/javascript"
src="https://checkout.freemius.com/js/v1/"
async
defer
></script>
<script type="text/javascript">
window.addEventListener('load', () => {
const handler = new FS.Checkout({
plugin_id: '1234',
public_key: 'pk_xxxx',
});
handler.open({
// plan
plan_id: 9999,
// number of sites
licenses: 1,
// billing cycles
billing_cycle: 'annual',
});
});
</script>Both the constructor and the open method accept the following set of options.
All the official options are supported here, along with some additional options.
interface AdditionalCheckoutOptions {
/**
* Optional callback to execute when the iFrame opens.
*
* @new
*/
afterOpen?: () => void;
/**
* An optional callback to execute when the iFrame closes.
*
* @new
*/
afterClose?: () => void;
/**
* Optional callback to trigger on exit intent. This is called only when the
* checkout iFrame is shown, not on global exit intent.
*
* @new
*/
onExitIntent?: () => void;
/**
* If you would like the dialog to open in sandbox mode,
*/
sandbox?: {
ctx: string;
token: string;
};
/**
* The URL of the image to display while the checkout is loading. By default a loading indicator from Freemius will be used.
*/
loadingImageUrl?: string;
/**
* The alt text for the loading image. By default 'Loading Freemius Checkout' will be used.
*/
loadingImageAlt?: string;
}For testing with the sandbox API, see the relevant section.
The main class exported by the package is Checkout. For the hosted CDN it is
available under the global FS namespace.
const handler = new FS.Checkout({
plugin_id: '1234',
public_key: 'pk_xxxx',
});If you're using the package from npm, simply import it and create an instance.
import { Checkout } from 'freemius-checkout-js';
// instantiate
const handler = new Checkout({
plugin_id: '0001',
public_key: 'pk_xxxx',
});Note that the plugin_id and public_key are required parameters and must be
supplied during instantiation.
Now you can simply call the open method to show the checkout popup.
handler.open();You can also pass additional options
handler.open({
// plan
plan_id: 9999,
// number of sites
licenses: 1,
// billing cycles
billing_cycle: 'annual',
});This is useful when you have multiple checkouts related to different plans, billing cycles, licenses, trials etc.
See the source code of the demo to learn more.
To close the popup programmatically, call the close method.
handle.close();We will make a small react hook. Here we assume the plugin_id and public_key
are available in
some environment variable.
checkout.ts
import { Checkout, CheckoutOptions } from '@freemius/checkout';
import { useState, useEffect } from 'react';
export const checkoutConfig: CheckoutOptions = {
plugin_id: import.meta.env.VITE_FS_PLUGIN_ID as string,
public_key: import.meta.env.VITE_FS_PUBLIC_KEY as string,
};
export function useFSCheckout() {
// create a Checkout instance once
const [fsCheckout] = useState<Checkout>(() => new Checkout(checkoutConfig));
useEffect(() => {
// close and destroy the DOM related stuff on unmount
return () => {
fsCheckout.destroy();
};
}, [fsCheckout]);
return fsCheckout;
}Now we use in our component.
App.tsx
import React from 'react';
import { useFSCheckout } from './checkout.ts';
export default function App() {
const fsCheckout = useFSCheckout();
return (
<button
onClick={(e) => {
e.preventDefault();
fsCheckout.open({
plan_id: 1234,
licenses: 1,
billing_cycle: 'annual',
success: (data) => {
console.log(data);
},
});
}}
>
Buy Plan
</button>
);
}To get the sandbox token and ctx, follow the steps:
- Go to the Developer Dashboard.
- Under Plans click on the "Get Checkout Code" button.
- Go to the Sandbox tab.
- Copy the
sandbox_tokenandtimestampvalues.
The value of sandbox is token and value of s_ctx_ts is ctx. So for the above
value, the configuration would look like
const config = {
// ...
sandbox: {
token: 'xxxxxxxx',
ctx: '00000000',
},
};NOTICE: Use this only during development and never publish the token and
context. In this repository we use the .env file for storing sandbox data.
-
Look for the following scripts:
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script> <script src="https://checkout.freemius.com/checkout.min.js"></script>
-
Remove the jQuery script tag if you aren't using jQuery.
-
Replace the checkout script with the new one.
<script src="https://checkout.freemius.com/js/v1/"></script>
-
Change
FS.Checkout.configure()tonew 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_ccca7be7fa43aec791448b43c6266', 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.
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();
});Note: If you need to add a checkout for a different configuration on the same page, just create a new checkout:
const anotherHandler = new FS.Checkout({
plugin_id: '4321',
plan_id: '9876',
public_key: 'pk_....nnn',
image: 'https://your-plugin-site.com/logo-100x100.png',
});Now you can 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();
});If you've been using the FS.Checkout singleton interface like
FS.Checkout.open({
plugin_id: 'x',
// ...
});Then you will need to adjust your code to call the methods on the instance instead of the singleton.
const handler = new FS.Checkout({
plugin_id: 'x',
// ...
});
handler.open({
// ...
});We also have introduced a compatibility layer which you can use as a quick path to migrate to the new checkout JS without making any changes to your checkout code.
However, please note the following limitations to this approach:
- it may stop working in a future version.
- it has a singleton pattern which can get confusing when configuring for multiple products on the same page.
- using the adapter will add extra bytes.
- 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>
- Remove the jQuery script tag if you aren't using jQuery.
- 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_ccca7be7fa43aec791448b43c6266',
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();
});We welcome contributions! Please see the contribution guide.