Wix eCommerce (Checkout & Orders): Checkout Page

The following slots and APIs are available when building a site plugin for the Checkout Page.

Slots

The following image shows slots in the checkout page, into which users can add plugins.

Each slot is identified by a unique placement slot ID. Declare the slots your plugin can be added to by listing their IDs in the placementsSlotIds array in your plugin's configuration:

The following table lists the placement slot ID for each slot in the Slots diagram:

For example, to allow your plugin to be placed before the totals breakdown in a checkout page:

Checkout plugin API

Use the Checkout plugin API to integrate with the plugin's host.

The API provides data about the current checkout process, and a function that refreshes the checkout after your plugin changes it.

Properties

Functions

Receive the API in a custom element

When you build a checkout plugin as a custom element, whether with the CLI or in a self-managed app, Wix passes it the checkout plugin API as follows:

• Properties and functions: Wix sets each one on the element as a JavaScript property with the same name, such as checkoutId and onRefreshCheckout. Receive them with setters. A setter is a method declared with set that runs each time Wix sets the property it's named after.
• Attributes: Wix also sets each property as a kebab-case attribute, such as checkout-id, so code that reads attributes also works.
• The refresh function: onRefreshCheckout holds the function that refreshes the checkout. Call it with no arguments after your plugin changes the checkout.
• Values set before your code loads: Wix can set a property before your element's code loads. When that happens, the value hides your setter, and the setter never runs. To handle this, pass any such value to its setter in connectedCallback(), as the following example does.
• Registration: The CLI registers your element's exported class for you. In a self-managed plugin, register it with customElements.define().

Code example: custom element

The following example stores and displays the checkout ID and the current step. It also stores the refresh function for its refreshCheckout() method, which you call after your plugin changes the checkout:

If you write the element in React, wrap the component with react-to-webcomponent and declare onRefreshCheckout as a method prop. The method prop type requires @r2wc/core 1.3.0 or later, which react-to-webcomponent depends on. The React example requires React 18. You don't need the connectedCallback() step, because react-to-webcomponent picks up values that Wix set early.

The following example displays the checkout ID and refreshes the checkout when a site visitor clicks Refresh checkout:

Code example: Velo

In Velo, read the properties from $widget.props, and export an onRefreshCheckout() function. The checkout calls it with the refresh callback, which you call after your plugin changes the checkout:

Brand styling

Merchants can theme their checkout (colors and corner radius). Checkout can't style your slot for you, so it passes the resolved design to your plugin as data in the slotBrand property, for you to apply in your own markup.

The values are:

• Per-slot: your slot receives the colors of the section it renders in — a form slot gets the form section's background, a summary slot gets the summary section's background, and a header slot gets the header's. In the single-column layout used on narrow screens, summary slots receive the form section's colors.
• Always defined: checkout supplies sensible defaults when the merchant hasn't customized their checkout.
• Contrast-safe: textColor and buttonTextColor are pre-resolved for contrast against their section's background.

The slotBrand object has the following properties:

In both a custom element and Velo, slotBrand reaches you as a ready-to-use object. Read it, apply the values, and reapply them on every change. How you apply them depends on the framework.

In a custom element, receive slotBrand with a setter, which runs again on every change. As in Receive the API in a custom element, connectedCallback() passes a value that Wix set early to the setter:

In Velo, slotBrand is on $widget.props. Apply the same values to your elements through their style APIs when the widget loads, and again on every change with $widget.onPropsChanged():

Dashboard page example

Checkout plugins require a dashboard page so users can add the plugin to their checkout page. Use addSitePlugin() to trigger the addition flow. The pluginId is the ID of your site plugin extension, which you can find in your app's dashboard under Extensions.

Delivery step options slot API

The checkout:delivery-step:options:after slot uses a different API than the other checkout slots.

Properties

Functions

Permissions and webhooks

The following permissions are relevant for most checkout plugins:

• Wix Developers > Manage Your App: Added automatically.
• Stores > Read Stores: Required for accessing product and store data.

The following webhooks are relevant to most checkout plugins:

• App Installed
• App Removed

Design guidelines

The Checkout page is the final step in the customer's purchase process. Its layout is closed and can't be changed by users or third parties, and all Wix eCommerce sites share the same checkout structure. Merchants can customize the checkout's colors and corner radius, and your plugin can match those choices — see Brand styling.

Testing checkout plugins

To test a checkout plugin:

1. Create a Premium development site. Select Wix Stores as the business solution.
2. Install your app on the development site.
3. If your plugin requires dashboard-based installation, go to your dashboard page and add the plugin to the checkout page.
4. Initiate a checkout flow on the live site to verify your plugin appears and functions correctly.

Related Wix backend APIs

Checkout plugins usually need to integrate with Wix eCommerce's Checkout APIs, as well as other backend APIs.

In your site plugin or in your app's server code, you may want to perform actions or implement logic that's dependent on the state of the current checkout or related data.

The following Wix APIs may be useful:

• eCommerce APIs (JavaScript SDK, REST, Velo)
• Stores APIs (JavaScript SDK, REST, Velo)