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

 With the frontend eCom 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](fallback::https://support.wix.com/en/article/customizing-the-cart-page).
 + Navigate to the [Checkout Page](fallback::https://support.wix.com/en/article/customizing-the-checkout-page).

 ## Before you begin

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

 + You need to [add eCommerce functionality to your site](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/wix-e-commerce-platform-handbook/get-started/sites/add-e-com-to-a-site).

 + Upgrade your site to a premium business plan in order to [accept payments](fallback::https://support.wix.com/en/article/accepting-payments-an-overview).

 ## 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.

# Setup

@package_metadata:@wix/site-ecom

To use the Contacts API, install the `@wix/site-ecom` package.

## Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/site-ecom` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/site-ecom` or `yarn add @wix/site-ecom`. |

## Import the package

To import the package in your code:

```js
import * as wixSiteEcom from "@wix/site-ecom";
```

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

SiteEcom

Returns the currency selected by the customer.

The `getCustomerSelectedCurrency()` method returns a Promise that resolves with the currency selected by the customer.

For more site currency and conversion functionality:
+ To retrieve the site's currency, use the [`site.currency()`](https://dev.wix.com/docs/sdk/frontend-modules/site/currency) method.
+ To get conversion rates, and convert between currencies, use the [`ecom.currencies`](https://dev.wix.com/docs/sdk/backend-modules/ecom/currencies/introduction) module.

Learn more about [changing the currency of your store](https://support.wix.com/en/article/changing-your-currency-in-wix-stores).

import { ecom } from "@wix/site-ecom";
import { site } from "@wix/site-site";
import { currencies } from "@wix/ecom";

$w('#myGetCurrencyButton').onClick(async () => {
  try {
    // Set the product price in the site's default currency
    const productPrice = 7.5;

    // Get the site's default currency. For example, "USD"
    const siteCurrency = await site.currency();

    // Get the currency selected by the customer. For example, "EUR"
    const customerSelectedCurrency = await ecom.getCustomerSelectedCurrency();

    // Get the conversion rate from the site currency to the customer's selected currency
    const conversionRate = await currencies.getConversionRate({ from: siteCurrency, to: customerSelectedCurrency });

    // Extract the decimal places and value from the conversion rate object
    const { rate: { decimalPlaces, value } } = conversionRate;

    // Calculate the actual conversion rate as a number
    const conversionRateNumber = Number(value) / 10 ** decimalPlaces;

    // Convert the product price to the customer's selected currency
    const convertedProductPrice = productPrice * conversionRateNumber;

    // Log the converted product price to the console
    console.log(convertedProductPrice);
  } catch (error) {
    console.error("Error getting conversion currency:", error);
    // Handle the error
  }
});


Get the customer's selected currency; convert product price with real-time exchange rates

getCustomerSelectedCurrency

string

Fulfilled - The currency selected by the customer, in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format.
For example, `"USD"`, `"EUR"`, `"GBP"`, and so on.

Default: Returns the site's default currency. If the site currency cannot be determined, returns `"USD"`.

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

The `navigateToCartPage()` method returns a Promise that resolves when the browser successfully navigates to the [Cart Page](https://support.wix.com/en/article/customizing-the-cart-page).

import { ecom } from "@wix/site-ecom";
import { addToCart } from 'backend/addToCart';

$w('#myNavigateToCartPageButton').onClick(async () => {

  // 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
    }]
  };

  try {
    // addToCart() is defined by you in a backend file
    // that calls currentCard.addToCurrentCart from the
    // backend ecom SDK module.
    await addToCart(options);
    console.log('Item added to cart');
    // Navigate to cart page after adding item
    await ecom.navigateToCartPage();
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

Navigate to the cart page

navigateToCartPage

void

Fulfilled - When the navigation is complete.

checkoutId

Additional parameters for customizing the checkout flow.

options

CheckoutPageOptions

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

The `navigateToCheckoutPage()` method returns a Promise that resolves when the browser successfully navigates to the [Checkout Page](https://support.wix.com/en/article/customizing-the-checkout-page).

> **Note:** The `checkoutId` parameter is **required**. To get a `checkoutId`, use one of the following backend methods:
> + [`currentCart.createCheckoutFromCurrentCart()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/create-checkout-from-current-cart)
> + [`cart.createCheckout()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/cart/create-checkout)
> + [`checkout.createCheckout()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/create-checkout)

import { ecom } from "@wix/site-ecom";

$w('#myNavigateToCheckoutPageButton').onClick(async () => {

  // 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}'
  };

  try {
    await ecom.navigateToCheckoutPage(checkoutId, options);
    console.log('Navigated successfully');
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

Navigate to the checkout page

navigateToCheckoutPage

handler

onCartChangeHandler

Triggered when a cart changes.

Triggered when:
+ A 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()` method is called.

> **Note:** Actions performed by any method other than `refreshCart()` don't trigger `onCartChange()`.

import { ecom } from "@wix/site-ecom";
import { retrieveCartDetails } from 'backend/cartDetails';

// Handler function that gets the ID of the current cart on cart change
const handler = async () => {
    // retrieveCartDetails() is defined by you in a backend file
    // that calls currentCart.getCurrentCart from the
    // backend ecom SDK module.
    try {
        const cart = await retrieveCartDetails();
        let cartId = cart._id;
        console.log('Cart ID: ', cartId);
    } catch (error) {
        console.error(error);
        // Handle the error
    }
};

ecom.onCartChange(handler);

Add an event handler for cart changes

onCartChange

Opens the side cart panel.

The `openSideCart()` method opens the side cart panel on the current page.

import { ecom } from "@wix/site-ecom";

$w('#myOpenSideCartButton').onClick(async () => {
  // Open the side cart when the button is clicked
  ecom.openSideCart();
});

Open the Side Cart

openSideCart

Updates cart UI elements, like the [cart icon](https://support.wix.com/en/article/customizing-the-cart-icon) and side cart with the most recent cart data.

The `refreshCart()` method returns a Promise that resolves when the latest cart data is retrieved and the cart UI elements are refreshed.

Call `refreshCart()` after modifying a cart with the Cart or Current Cart APIs to trigger the `onCartChange()` event and update UI elements.

import { ecom } from "@wix/site-ecom";
import { addToCart } from 'backend/addToCart';

$w('#myAddAndRefreshCartButton').onClick(async () => {

  // 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
    }]
  };

  try {
    // addToCart() is defined by you in a backend file
    // that calls currentCard.addToCurrentCart from the
    // backend ecom SDK module.
    await addToCart(options);
    console.log('Item added to cart');
    // Refresh the cart after adding item
    await ecom.refreshCart();
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

Refresh the cart

refreshCart

Fulfilled - When the cart refresh is complete.

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

 With the frontend eCom 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](https://support.wix.com/en/article/customizing-the-cart-page).
 + Navigate to the [Checkout Page](https://support.wix.com/en/article/customizing-the-checkout-page).

 ## Before you begin

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

 + You need to [add eCommerce functionality to your site](https://dev.wix.com/docs/rest/business-solutions/e-commerce/wix-e-commerce-platform-handbook/get-started/sites/add-e-com-to-a-site).

 + Upgrade your site to a premium business plan in order to [accept payments](https://support.wix.com/en/article/accepting-payments-an-overview).

 ## 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.


# Setup

@package_metadata:@wix/site-ecom

To use the Contacts API, install the `@wix/site-ecom` package.

## Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/site-ecom` using the [Wix CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/site-ecom` or `yarn add @wix/site-ecom`. |

## Import the package

To import the package in your code:

```js
import * as wixSiteEcom from "@wix/site-ecom";
```


site-ecom

Whether to hide the ["Continue Browsing"](https://support.wix.com/en/article/customizing-links-on-your-cart-page#customizing-the-continue-browsing-links) button from top-right-hand corner of the Checkout Page.

Default: `false`

hideContinueBrowsingButton

boolean

URL to replace the default "Continue Browsing" URL. For example, if you'd like to redirect a customer to a custom page.

overrideContinueBrowsingUrl

URL to replace the default [Thank You Page](https://support.wix.com/en/article/customizing-the-thank-you-page) URL.

Pass `{orderId}` (not the order ID itself) as a parameter to the URL to dynamically insert the order ID. See the example on the right for more information.

overrideThankYouPageUrl

Whether to skip the delivery details step in checkout. For example, if the product is for pick-up only.

Default: `false`

getCustomerSelectedCurrency( )