Wix eCommerce (Checkout & Orders): Checkout Page
The following slots and APIs are available when building a site plugin for the Checkout Page.
Important: Some plugins may not support automatic addition upon installation, even with autoAddToSite enabled. In that case, you must:
- Create a dashboard page to manage your site plugin that calls
addSitePlugin()to let users add the plugin to the checkout slot. - Release at least 1 version of your app so the site plugin extension is registered with Wix for
addSitePlugin()to work properly.
Slots
The following image shows slots in the checkout page, into which users can add plugins.
The slots are represented by the following placement object:
Provide the following values for each property:
| Key | Value |
|---|---|
appDefinitionId | "1380b703-ce81-ff05-f115-39571d94dfcd" |
widgetId | "14fd5970-8072-c276-1246-058b79e70c1a" |
slotId | ID of the slot you want as displayed in the image above. Supported values:
|
For example, for your widget to appear before the totals breakdown in a checkout page use the following object in your configuration:
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 lets you define a callback function that's invoked whenever changes are made in the checkout.
Note: The checkout:delivery-step:options:after slot uses a different API.
Properties
| Name | Type | Description |
|---|---|---|
checkoutId | String | The ID of the current checkout process. |
stepId | String | The ID of the step currently rendered in the checkout page, which can be one of the following:
|
checkoutUpdatedDate | String | Date and time the checkout was updated. |
Functions
| Name | Type | Description |
|---|---|---|
onRefreshCheckout() | (refreshCheckoutCallback: () => void) => void | An event handler that accepts a callback function that's invoked by a widget. The widget should call the function whenever the checkout needs to be refreshed. |
Code exampleL CLI custom element
When building a checkout plugin with the CLI, the checkout API properties are passed as custom element attributes in kebab-case (for example, checkoutId becomes checkout-id).
Code example: Velo
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.
Important: Some plugins may not support automatic addition upon installation, even with autoAddToSite enabled. In that case, you must:
- Create a dashboard page to manage your site plugin that calls
addSitePlugin()to let users add the plugin to the checkout slot. - Release at least 1 version of your app so the site plugin extension is registered with Wix for
addSitePlugin()to work properly.
Delivery step options slot API
The checkout:delivery-step:options:after slot uses a different API than the other checkout slots.
Properties
| Name | Type | Description |
|---|---|---|
checkoutId | String | The ID of the current checkout process. |
checkoutUpdatedDate | String | Date and time the checkout was updated. |
selectedDeliveryOptionCarrierId | String | The ID of the carrier for the selected delivery option. |
selectedDeliveryOptionId | String | The ID of the selected delivery option. |
deliveryStepState | String | The current state of the delivery step. Possible values: 'open' or 'summary'. |
Functions
| Name | Type | Description |
|---|---|---|
onRefreshCheckout() | (callback: () => Promise<void>) => void | An event handler that accepts a callback function that's invoked by a widget. The widget should call the function whenever the checkout needs to be refreshed. |
disableContinueButton() | (callback: (isDisabled: boolean) => void) => void | An event handler that accepts a callback function to control the checkout's continue button. Call the callback with true to disable the button, or false to enable it. |
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:
Design guidelines
The Checkout page is the final step in the customer's purchase process. Its design is closed and can't be changed by users or third parties. All Wix eCommerce sites share the same checkout experience.
To ensure your plugin fits seamlessly into the checkout:
- Follow the design specs and guidelines for the Wix Checkout page, especially the guidelines for building plugins.
- Use the Checkout UI kit and guidelines (Figma) for reference styles and components.
Testing checkout plugins
To test a checkout plugin:
- Create a Premium development site. Select Wix Stores as the business solution.
- Install your app on the development site.
- If your plugin requires dashboard-based installation, go to your dashboard page and add the plugin to the checkout page.
- 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)