Guidelines for Checkout Page Plugins

Wix eCommerce's Checkout page is the final step in the customer's purchase process. It serves different business solutions: online stores, online bookings sites and businesses that sells both of them (services and products).

As an application developing a business solution for Wix eCommerce' checkout, you can use all Wix eCommerce Platform checkout tools to find your market fit, solve users needs. For example, you can offer cross-sell, add package protection, or show a disclaimer.

Checkout APIs and SPIs provide a simple way to create your app's logic in the Checkout page. When a checkout plugin is added inside the Checkout page, customer interactions trigger APIs and SPI calls. For apps that need an interface for defining app settings (for example, letting the User set the items and discounts for a cross-sell offer), you also need to add a Dashboard extension with the relevant UI and logic.

As a developer, you can target your checkout widget for a specific slot or multiple slots - eventually the business owner chooses where to inject you plugin widget according to the use case.

Learn more about the slots available on the Checkout page.

Dev Center setup

In addition to the standard app setup in the Dev Center for all plugins, following are additional guidelines for checkout plugins.

Permissions

The following permissions are relevant for most checkout apps:

• Wix Developers > Manage Your App - this is added automatically

• Stores > Read Stores - all read permissions

Webhooks

The following webhooks are relevant to most checkout apps:

• Wix Developers > App Installed
• Wix Developers > App Removed

Design guidelines

The Checkout page is the place where buyers take the final step in the purchase process. They provide details about themself, a shipping address, payment details and additional relevant information to complete the purchase. It is a very sensitive step and we strive to help our users keep their page performance high by providing a clean and safe checkout experience for any Wix eCommerce site.

Currently the checkout page design is closed and can't be changed by users or third parties such as apps or partners. All Wix eCommerce websites have the same checkout page experience and design. Wix keeps them up to date according to best practices to make sure our users can offer the best experience to their customers.

The following resources provide information about the styles and components that your plugin should use to seamlessly fit into Wix's checkout system:

• Design specs and guidelines for the Wix Checkout page, especially the guidelines for building plugins.

• Checkout UI kit and guidelines (Figma)

Available eCommerce Platform and Catalog APIs

The eCommerce Checkout APIs provide functionality for creating, retrieving, and managing a checkout flow. A checkout holds information about items to be purchased, price and tax summaries, shipping and billing info, any applied discounts, and more.

In your Blocks widget, you can use the eCommerce Checkout Velo APIs.

Learn more about related Wix Backend APIs

CHECKOUT API

To enable plugins to communicate with the Checkout page, each slot supports an API that provides data about the checkout context (for example the current checkoutId). Use it when you code your plugin's logic in Wix Blocks.

Explore the CHECKOUT API

Refresh Checkout (optional)

Users may apply changes between the checkout steps such as editing the contact details or changing the delivery method. At this stage we do not notify the plugin.

In the future, we plan to add a solution to listen for changes, but for now, you may want to reload the checkout to make sure you have the latest version before performing actions based on it. In some cases, listening to changes to steps can update when checkout is updated, but in others, like adding coupons, it can occur at any time.

Example usage in a Blocks app:

1
// global variable to use to refresh checkout
2
let refreshCheckoutCallback;
3
$w.onReady(async function () {
4
    // get props passed in by checkout page
5
    const {checkoutId} = $widget.props;
6
   
7
    // prop usage
8
    const checkout = fetchCheckout(checkoutId);
9
    ...
10
});
11
// exported function to get refresh checkout callback
12
export function onRefreshCheckout(callback){
13
        refreshCheckoutCallback = callback;
14
}

Get the app instance

To use the getDecodedAppInstance() function, import the wix-application module.

1
import {getDecodedAppInstance} from 'wix-application'
2

3
const instance = getDecodedAppInstance();

Set up your Dashboard-based plugin installation flow

Unlike most plugins, which are added in the editor directly to the host widget, Checkout plugins are added through the Dashboard. This is because the Checkout page is not available in the editors.

Populating a slot is a critical action, and the user must approve it. The approval is requested by opening the a Consent modal, in which the user has to click Add to continue and add your widget to the checkout slot.

To install your checkout plugin using the Dashboard SDK:

1. Install the Wix Dashboard SDK.

2. Call openModal() with the following parameters:

Set componentId to: 346cce63-b26e-4846-b5df-00425e299caa

componentParams:

1
{
2
  "appDefinitionId": "YOUR_APP_ID",
3
  "widgetId": "YOUR_PLUGIN_EXTENSION_ID",
4
  "slotName": "SLOT_ID (for example, checkout:summary:after)"
5
}

The resolved promise can be one of the following:

1
enum CloseStatus {
2
  Success = 'success',
3
  Failure = 'failure',
4
}
5

6
interface CloseModalResponse {
7
  status: CloseStatus;
8
  description: string;
9
}

Example:

1
import { openModal } from '@wix/dashboard';
2

3
const SLOT_CONSENT_MODAL_ID = '346cce63-b26e-4846-b5df-00425e299caa';
4

5
const {modalClosed} = await openModal(SLOT_CONSENT_MODAL_ID, {
6
  appDefinitionId: 'YOUR_APP_DEF_ID',
7
  widgetId: 'YOUR_WIDGET_ID',
8
  slotName: 'checkout:summary:after',
9
});
10

11
modalClosed.then((result) => {
12
  console.log('The modal was closed and returned the value:', result);
13
});

Test your checkout plugin

Unlike most Wix app pages, the checkout page is not available within the Wix editors; it is only accessible on live sites. The only way to install it is via the site's Dashboard.

To test your checkout plugin:

1. Create a Premium development site. Select Wix Stores as the business solution.
2. From the Test Your App menu, install your plugin app on the development site. You'll be prompted to add the plugin to the checkout page.
3. Initiate a checkout flow on the live site.