Methods for cart management

With Checkout API, you can manage shopping cart on the storefront with JavaScript code: get cart contents, add or remove product positions, set an address for the customer, etc. These methods work from any Ecwid storefront page.

Learn about all available methods below.

Enable JS API on the storefront

The methods listed below require JS API to be loaded on the page. Read more on how to enable JS API.

Ecwid.Cart.get()

This method allows you to receive full information about the current shopping cart. The response is available in the callback cart function.

Code example:

Ecwid.Cart.get(function(cart){
  console.log(JSON.stringify(cart));
});

/* prints

{
    "id": "TJ6VG",
    "cartId": "99E7E224-5F6F-4C00-BFE9-9F72F2B5A471",
    "orderId": 506524300,
    "items": [
        {
            "quantity": 2,
            "product": {
                "id": 455570501,
                "sku": "0000077",
                "price": 500,
                "name": "Pizza #2",
                "weight": 1,
                "shortDescription": "",
                "url": "https://example.company.site/products/Example-product-p455570501"
            },
            "options": {}
        },
        {
            "quantity": 4,
            "product": {
                "id": 439710255,
                "sku": "000001",
                "price": 500,
                "name": "Pizza",
                "weight": 0.5,
                "shortDescription": "",
                "url": "https://example.company.site/products/Example-product-2-p439710255"
            },
            "options": {
                "Size": "L, R",
                "Print_number": "123"
            }
        }
    ],
    "productsQuantity": 6,
    "shippingMethod": "Pickup",
    "shippingPerson": {
        "countryCode": "GE",
        "countryName": "Georgia",
        "name": "Jhn Doe",
        "phone": "16019521325",
        "stateOrProvinceCode": "TB"
    },
    "weight": 6
}

/*

cart

items

items contains an array of objects with the details for each product added to the shopping cart.

product

shippingPerson

Ecwid.Cart.addProduct()

This method allows you to add a new product position to the shopping cart. It accepts two arguments: product and callback. The product argument accepts either product ID or a product object with extended details including product ID, quantity, selected options, or subscription product settings.

When you use this method, it first checks the product by specified ID for stock and variations. If the selected options match one of the variations, Ecwid will check its stock first. If you don't have enough stock to add a product, Ecwid adds the available quantity. If the product is out of stock, nothing is added to the shopping cart.

Code example:

var product = {
  id: 10,
  quantity: 3,
  options: {
    "Size": "L"
  },
  recurringChargeSettings: { 
    recurringInterval: "month",
    recurringIntervalCount: 1,
    },
  callback: function(success, product, cart) {
    // ...  
  }
}

Ecwid.Cart.addProduct(product);

product argument fields:

recurringChargeSettings

callback

Callback function receives 4 arguments: success, product, cart, error

Ecwid.Cart.removeProduct()

This method removes product position from the shopping cart entirely. It has one argument called index that accepts the index of the product position.

Get an index from the Ecwid.Cart.get() method. Position of the product in the items array is the index. For example, if you have two different products added to the cart, the first product has an index of 0, and the second has an index of 1.

Code example.

Ecwid.Cart.removeProduct(0);

This method can only remove the product from the cart, it cannot decrease its quantity. If you want to decrease the quantity, first make the Ecwid.Cart.get() request, save product details, then call Ecwid.Cart.removeProduct() and add the product back with decreased quantity with Ecwid.Cart.addProduct().

Ecwid.Cart.clear()

This method allows you to clear all details from the shopping cart. It has a callback function with two arguments: success (boolean) and error (string). If the method clears the cart successfully, you receive true in the success argument.

Code example:

Ecwid.Cart.clear(function(success,error) { 
  if (success == true) {
      console.log("Cart was cleared");
  } else {
      console.log("Cart clear failed. Error message: " + error);
  }
});

// prints
// Cart was cleared

Ecwid.Cart.calculateTotal()

This method calculates the cart total asynchronously and passes the result as an order callback argument with a snapshot of the generated order with essential details.

Code example:

Ecwid.Cart.calculateTotal(function(order) {
  console.log(JSON.stringify(order));
});

/* prints

{
    "subtotal": 3500,
    "subtotalWithoutTax": 3500,
    "total": 3850,
    "totalWithoutTax": 3500,
    "tax": 350,
    "couponDiscount": 0,
    "volumeDiscount": 0,
    "customerGroupDiscount": 0,
    "customerGroupVolumeDiscount": 0,
    "discount": 0,
    "shipping": 0,
    "shippingWithoutTax": 0,
    "handlingFee": 0,
    "handlingFeeWithoutTax": 0,
    "pricesIncludeTax": false,
    "cart": {
        "id": "TJ6VG",
        "cartId": "99E7E224-5F6F-4C00-BFE9-9F72F2B5A471",
        "orderId": 506524300,
        "items": [
            {
                "quantity": 3,
                "product": {
                    "id": 455570501,
                    "sku": "0000077",
                    "price": 500,
                    "name": "Pizza #2",
                    "weight": 1,
                    "shortDescription": "",
                    "url": "https://example.company.site/products/Example-product-p455570501"
                },
                "options": {}
            },
            {
                "quantity": 4,
                "product": {
                    "id": 439710255,
                    "sku": "000001",
                    "price": 500,
                    "name": "Pizza",
                    "weight": 1,
                    "shortDescription": "123 pie",
                    "url": "https://wexample.company.site/products/Example-product-2-p439710255"
                },
                "options": {
                    "Size": "L, R",
                    "djbfdmnfb": "1234"
                }
            }
        ],
        "productsQuantity": 7,
        "shippingMethod": "Pickup",
        "shippingPerson": {
            "countryCode": "GE",
            "countryName": "Georgia",
            "name": "Jon Stewart Doe",
            "phone": "16019521325",
            "stateOrProvinceCode": "TB"
        },
        "weight": 7
    }
}

*/

Subscribe to the Ecwid.OnAPILoaded JS API event to ensure availability of this function.

order argument fields

Ecwid.Cart.canGotoCheckout()

This method checks whether you can send customers to the first step of the checkout. It has one callback argument containing the boolean response. If true, you can send customers to the checkout, for example, with the Ecwid.Cart.gotoCheckout() method.

Ecwid.Cart.canGotoCheckout(function(callback){
  console.log(callback);
});

// prints
// true

Ecwid.Cart.gotoCheckout();

This method sends a customer to the first checkout step. This method only works if your checkout doesn't require legal terms checkboxes. Find legal terms setting in Ecwid admin > Settings > General > Legal Pages > "Show “I agree with Terms & Conditions”. Or check the availability of this method with the Ecwid.Cart.canGotoCheckout().

Code example:

Ecwid.Cart.gotoCheckout(function(){
  console.log("Checkout process started");
});

// prints
// Checkout process started

Ecwid.Cart.setCustomerEmail()

This method allows you to pre-define customer email with JavaScript. Combined with the Ecwid.Cart.gotoCheckout() you can skip the first checkout step. The method has three callback arguments: email, successCallback and errorCallback.

The email argument defines the customer email, and callback arguments are functions called if the method works successfully or fails.

Code example:

Ecwid.Cart.setCustomerEmail(
    "[email protected]",
    function (successCallback) { console.log("Success") },
    function (errorCallback) { console.log("Fail") }
);

// prints
// Success

Ecwid.Cart.setOrderComments()

This method allows you to pre-define customer comments for order with JavaScript. The method has three callback arguments: orderComments, successCallback and errorCallback.

The orderComments argument defines the customer email, and callback arguments are functions called if the method works successfully or fails.

Code example:

Ecwid.Cart.setOrderComments(
    "Please ask courier to call  1-800 on the door",
    function (successCallback) { console.log("Success") },
    function (errorCallback) { console.log("Fail") }
);

// prints
// Success

Ecwid.Cart.setAddress()

This method allows you to prefill the shipping address before customers get to the checkout. It is useful when you want to remove some address fields, like country or state. Prefill address fields with this method and then hide them with CSS {display: none;} style.

The method has three arguments: address with the address details and two function callbacks, successCallback called if the method works successfully, and errorCallback called if it fails.

Ecwid.Cart.setAddress(
	{
		"name": "John Carmichael",
  	"companyName": "Cool Slippers",
  	"street": "5th Ave",
  	"city": "New York",
  	"countryName": "United States",
  	"postalCode": "10002",
  	"stateOrProvinceCode": "NY",
  	"phone": "+1 234 523 11 42"
  },
  function(successCallback){ console.log('Success') },
  function(errorCallback){ console.log('Fail') }
);

// prints
// Success

Address fields in this method match the shippingPerson object.

Ecwid.Cart.setBillingAddress()

This method allows you to prefill the customer billing address before customers get to the checkout. It accepts three arguments: address with the address details and two function callbacks, successCallback called if the method works successfully, and errorCallback called if it fails.

Ecwid.Cart.setBillingAddress(
	{
		"name": "John Carmichael",
  	"companyName": "Cool Slippers",
  	"street": "5th Ave",
  	"city": "New York",
  	"countryName": "United States",
  	"postalCode": "10002",
  	"stateOrProvinceCode": "NY",
  	"phone": "+1 234 523 11 42"
  },
  function(successCallback){ console.log('Success') },
  function(errorCallback){ console.log('Fail') }
);

// prints
// Success

Address fields in this method match the shippingPerson object.

Set order referer

This method allows you to declare the ec.order.referer_id variable in your JavaScript code to set the order referer.

Code example:

ec.order = ec.order || {};
ec.order.referer_id = 'Amazon'

The field appears in exported order CSVs, invoices, email notifications, and REST API as refererId field.