Handling Checkout form instance

"Checkout instance" is a Javascript object created when Checkout 3 Form is initialised in a page. It contains various functions for interacting with Checkout 3 Form. More information about embedding the form can be found in the article "Embed Checkout Form".

Checkout Instance type

export type CheckoutInstance = {
  refreshForm: (payload?: RefreshFormPayload) => void;
  unmount: () => void;
  beforeSubmitAbort: () => void;
  beforeSubmitContinue: () => void;
  deliveryAddressChangedContinue: () => void;
  clearCustomerToken: () => void;
  changeLanguage: (language: string) => void;
  purchaseId: string;
};

Accessing the checkout instance

1. Storing Checkout instance returned from window.avardaCheckoutInit
2. Using Checkout instance attached to window object
3. Using Checkout instance from callbacks payload

1. Storing Checkout instance returned from window.avardaCheckoutInit

After calling window.avardaCheckoutInit with required payload the function will return checkout instance as it’s return value.

You can store a reference to this CheckoutInstance object while user is on the page where the Checkout Form is displayed to interact with it.

2. Using Checkout instance attached to window object

After calling window.avardaCheckoutInit with required payload the function will attach the CheckoutInstance to the window object allowing you to access the Checkout instance directly by calling window.avardaCheckout.

Example:

// Refresh Checkout Form
window.avardaCheckout.refreshForm();
 
// Change language of the Checkout Form to "Swedish"
window.avardaCheckout.changeLanguage('Swedish');

3. Using Checkout instance from callbacks payload

All callbacks registered in Checkout Form initialisation will receive CheckoutInstance as last argument. In the following example we can see two different callbacks, in deliveryAddressChangedCallback the registered callback will receive the data payload as a first argument and Checkout instance as a second argument – the instance can be used to handle the callback correctly either by refreshing the form or confirming with the deliveryAddressChangedContinue. In completedPurchaseCallback there is no data payload so only the Checkout instance is received and can be used to remove the Checkout Form from the page.

Example:

<script>
  var deliveryAddressChangedCallback = function(callbackDataPayload, checkoutInstance) {
    ...
    // If Delivery address has changed
    // Handle Update items
    // Refresh form to display the new updated data
    checkoutInstance.refreshForm();
 
    // Delivery address is the same as stored
    // Shipping price is the same as was before
    // Continue
    checkoutInstance.deliveryAddressChangedContinue();
  };
 
  // Completed callback provides checkout instance
  // that can be used to remove checkout from the current page
  var completedPurchaseCallback = function(checkoutInstance) {
    // Un-mount Checkout Form from the page
    checkoutInstance.unmount();
    // Display success message instead of the  Checkout Form
  };
</script>

Make sure to check each of the callbacks documentation to confirm the data contract.

refreshForm additional options

Anytime you want to call avardaCheckout.refreshForm() you can decide to pass in a reason for calling refreshForm. This is completely optional and should only be used if your specific integration requires it (e.g. using Partner shipping module, using external shipping module, synchronizing multiple windows with the same purchase, etc.).

avardaCheckout.refreshForm({reason: "Default"});

You can use one of the following reasons:

Removing Checkout3 Form from the page

When it comes to removing the application from your web page, it’s crucial to follow the correct procedure to ensure proper cleanup and prevent potential issues. This ensures that the application is properly deleted from memory, the instance is removed from the window, and the associated <div> element is also removed from the DOM.

window.avardaCheckout.unmount();