Introduction

Using the eCommerce frontend API, you can interact with the native cart and checkout components on your site.

With the eCommerce frontend API, you can:

  • Refresh the cart to display its latest state.
  • Listen to changes in the native cart components.
  • Open the Side Cart panel.
  • Navigate to the Cart Page.
  • Navigate to the Checkout Page.

To use the eCommerce frontend API, import wixEcomFrontend from the wix-ecom-frontend module:

Copy
import wixEcomFrontend from "wix-ecom-frontend";

Before you begin

It's important to note the following points before starting to code:

Terminology

  • Cart: Holds information about a potential transaction, including details about selected items, prices, and discounts, as well as the potential buyer.
  • Side Cart: A preview of the cart page, which opens as a panel on the side of a page.
  • Cart Page: A page where a buyer can view and manage the items in their cart.
  • Checkout Page: A page where a buyer finalizes a purchase. Each checkout holds information about the items to be purchased, price and tax summaries, shipping and billing information, any applied discounts, and more.
Did this help?

navigateToCartPage( )

Directs the browser to navigate to the site visitor's Cart Page.

The navigateToCartPage() function returns a Promise that resolves when the browser successfully navigates to the Cart Page.

Method Declaration
Copy
function navigateToCartPage(): Promise<void>;
Request
This method does not take any parameters
Navigate to the cart page
JavaScript
import wixEcomFrontend from "wix-ecom-frontend";
import wixEcomBackend from "wix-ecom-backend";

$w("#myNavigateToCartPageButton").onClick(() => {
  // example values for the options object
  const options = {
    lineItems: [
      {
        catalogReference: {
          // Wix Stores appId
          appId: "215238eb-22a5-4c36-9e7b-e7c08025e04e",
          // Wix Stores productId
          catalogItemId: "3fb6a3c8-988b-8755-04bd-5c59ae0b18ea",
        },
        quantity: 1,
      },
    ],
  };

  // The wixEcomBackend.currentCart module is universal.
  // You can call its methods in frontend and backend code.
  wixEcomBackend.currentCart
    .addToCurrentCart(options)
    .then(() => {
      console.log("item added to cart");
      // navigate to cart page after adding item
      wixEcomFrontend.navigateToCartPage();
    })
    .catch((error) => {
      console.error(error);
      // Handle the error
    });
});
Did this help?

navigateToCheckoutPage( )

Directs the browser to navigate to the site visitor's Checkout Page.

The navigateToCheckoutPage() function returns a Promise that resolves when the browser successfully navigates to the Checkout Page.

Note: The checkoutId parameter is required. To get a checkoutId, use one of the following wix-ecom-backend functions:

Method Declaration
Copy
function navigateToCheckoutPage(
  checkoutId: string,
  options: CheckoutPageOptions,
): Promise<void>;
Method Parameters
checkoutIdstringRequired

ID of the checkout to navigate to.

optionsCheckoutPageOptions

Additional parameters for customizing the checkout flow.

Navigate to the checkout page
JavaScript
import wixEcomFrontend from "wix-ecom-frontend";

$w("#myNavigateToCheckoutPageButton").onClick(() => {
  // Example checkoutId and options values
  const checkoutId = "12345678-1234-1234-1234-1234567890ab";
  const options = {
    skipDeliveryStep: true,
    hideContinueBrowsingButton: false,
    overrideContinueBrowsingUrl: "https://www.myExampleSite.com/upsellPage",
    // override ThankYouPage URL with dynamic orderId parameter
    overrideThankYouPageUrl:
      "https://www.myExampleSite.com/customThankYouPage/{orderId}",
  };

  wixEcomFrontend
    .navigateToCheckoutPage(checkoutId, options)
    .then(() => {
      console.log("Navigated successfully");
    })
    .catch((error) => {
      console.error(error);
      // Handle the error
    });
});
Did this help?

onCartChange( )

Adds an event handler that runs when the cart changes.

The event handler set by the onCartChange() function runs when the cart changes.

The onCartChange() event handler is triggered when:

  • The cart is modified by native UI elements such as the 'Add to Cart' button, increase (+) and decrease (-) item quantity buttons, remove line item button (x), etc.
  • The refreshCart() function is called.

Important: Actions performed by Velo functions other than the refreshCart() function do not trigger the onCartChange() event handler.

Method Declaration
Copy
function onCartChange(handler: function): void;
Method Parameters
handlerfunctionRequired

handler(): void The name of the function or the function expression to run when the cart is changed.

Add an event handler for cart changes
JavaScript
import wixEcomFrontend from "wix-ecom-frontend";
import wixEcomBackend from "wix-ecom-backend";

$w.onReady(function () {
  // handler function that gets the current cart on cart change
  const handler = () => {
    // The wixEcomBackend.currentCart module is universal.
    // You can call its methods in frontend and backend code.
    wixEcomBackend.currentCart
      .getCurrentCart()
      .then((cart) => {
        let cartId = cart._id;
        console.log("cart ID: ", cartId);
      })
      .catch((error) => {
        console.error(error);
        // Handle the error
      });
  };

  wixEcomFrontend.onCartChange(handler);
});
Did this help?

openSideCart( )

Opens the Side Cart panel.

The openSideCart() function opens the Side Cart panel on the current page.

Notes:

  • We are gradually replacing the existing Mini Cart with the new Side Cart panel.
  • This function will fail when viewing the site on mobile because there is no Mini Cart on the mobile site.
  • The new Side Cart works on mobile sites. When Side Cart functionality becomes available for your site, openSideCart() will work on mobile.
Method Declaration
Copy
function openSideCart(): void;
Request
This method does not take any parameters
Open the Side Cart
JavaScript
import wixEcomFrontend from "wix-ecom-frontend";

$w("#myOpenSideCartButton").onClick(() => {
  // on button click - open the side cart
  wixEcomFrontend.openSideCart();
});
Did this help?