JavaScript SDK

Use our JavaScript SDK to use the Koalafi UI in your checkout flow.


Make sure to review Key Concepts and Getting Started first.


Import the SDK using a <script> tag:
<script src=""></script>

After the script tag, you may now access the SDK by calling koalafiSdk.<function name>



Opens a modal containing an iframe with the Koalafi UI. Requires a valid orderId.

openModal returns a promise. Depending on the outcome of the modal UI session, the promise will be resolved or rejected. The promise will be resolved when the UI session was successful and rejected if there was an error during the session, or if the user exited out of the modal prematurely.

Sample Code Snippets

   .then((res) => {
      // Success
   .catch((err) => {
      // Error

// using async/await syntax within a custom function
const = yourCustomFunction = async () => {
    const koalafiResponse = await koalafiSdk.openModal(orderId)
        //handle error
  // use koalafiResponse here.

Resolved Promise

A "successful" UI session occurs in the following situations:

  • Lease application is approved (promise is not resolved in Shop First flow)
  • Lease is signed

The resolved promise will be in the following formats (with sample values):

// Application is approved 
   approvalStatus: "preApproved",
   approvalAmount: "2500",

// Lease is signed successfully
   orderId: "2c5975d7-32e5-4072-8abf-8d17dade322a"

Rejected Promise

The following are reasons why the promise will be rejected:

  • Lease application was declined
  • User is ineligible for an appliation
  • User has added too many or too little items to their cart
  • There was a general error during the flow
  • User has closed the modal from within the application with no error
  • User has closed the modal with the X button

The rejected promise will be in the following format:

   orderId: "2c5975d7-32e5-4072-8abf-8d17dade322a",
   reasonCode: 2,
   reason: 'hardDecline',

The reasonCode property will be one of the following values:

genericError = 1,
  hardDecline = 2,
  ineligible = 3,
  cartAmtNotMet = 4,
  noCartItems = 5,
  cartAmtTooHigh = 6,
  generalCloseModal = 7