Manage customer cart

Manage cart on customer’s behalf.

Ecwid.Cart.addProduct

This function allows to add a product to shopping cart, modifying the cart on behalf of customer.

There are 2 possible ways to call this function: adding products by product ID or adding products with extended options.

Adding by product ID

Add product function

Ecwid.Cart.addProduct(productID, callback);

addProduct() can accept 2 arguments: productId and callback.

Add product to cart using ID

var productId = 10;
Ecwid.Cart.addProduct(productId); 

The most simple call to Ecwid.Cart.addProduct only requires to pass the numeric product ID. See example code on the right. This code adds 1 item of the given product ID to cart.

If this product contains variations and the base product is out of stock, the first variation that is in stock will be added to cart instead. If the product is out of stock (and there are no variations in stock for this product), nothing is added to cart.

Adding with extended options

Add product to cart with extended options

var product = {
  id: 10,
  quantity: 3,
  options: {
    someTextOption: "Your name",
    someDateOption: new Date().getTime().toString(),
    someRadioOption: "Use default color",
    someDropDownOption: "I want custom engraving",
    someCheckboxOption: ["It's a gift", "Gold engraving"]
  },
  callback: function(success, product, cart) {
    // ...  
  }
}

Ecwid.Cart.addProduct(product);

If it is necessary to specify options or quantity of product to be added to cart, the product parameter needs to be passed as an object.

Since this method allows to specify the exact options to be added to cart, only the base product or variation matching those options will be added to cart. So, if the base product or matching variation is out of stock, the addProduct call will not add anything to cart, even if there are other variations in stock.

Callback

Adding to cart is done asynchronously, so if it is important to know the result of this function. The callback function can be passed as the second agrument of the function.

Add product to cart with callback function, example 1

Ecwid.Cart.addProduct(productID, function(success, product, cart){
  console.log(success); // true or false
  console.log(product.name);
});

Add product to cart with callback function, example 2

Ecwid.Cart.addProduct({
  id: 10, 
  quantity: 3, 
  callback: function(success, product, cart){
    console.log(success); // true or false
    console.log(product.name);
  }
});

Callback receives 3 arguments: success, product, cart

Product

OptionsInfo

Ecwid.Cart.removeProduct

Remove specific product from cart

Ecwid.Cart.removeProduct(index);

Example

// returns cart details with items' details. Use 'items' array to get the index

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

// remove first product from customer's cart

Ecwid.Cart.removeProduct(0);

Removes a product with specified index from customer’s cart. Ecwid.Cart.removeProduct() receives one argument: index

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

Ecwid.Cart.clear

Clear cart contents

Ecwid.Cart.clear();

Clears the cart contents.

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

Ecwid.Cart.get

Get total number of products in cart code example

Ecwid.Cart.get(function(cart) {
  alert(cart.productsQuantity + " products in cart now");
});

Retrieves the cart contents asynchronously and passes it as an argument of type Cart to the callback.

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

Ecwid.Cart.calculateTotal

Calculate cart total example

Ecwid.Cart.calculateTotal(function(order) {
  if (!order)
    alert('An error occurred while calculating the order!')
  else    
    alert('Order total: ' + order.total);    
}); 

Calculates the cart asynchronously and passes the result as an argument of type Order to the callback.

Cart calculation involves a request to server, so this method should be called only occasionally. Calling it frequently, e.g. from loops or by timer, is not acceptable.

Since the calculation needs a server connection, it might fail due to network conditions. In this case, null is passed into the callback instead of Order object.

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

Ecwid.Cart.gotoCheckout

Send customer to checkout

Ecwid.Cart.gotoCheckout();

Ecwid.Cart.gotoCheckout() function allows you to send customer to the first step of the checkout process in a store. Customer will be sent there only if agreeing to terms and conditions is not required in the store. You can find this setting in Ecwid Control Panel > Settings > General > Legal Pages > “Show “I agree with Terms & Conditions” checkbox during checkout” or check it using Ecwid.Cart.canGotoCheckout() function.

Callback function after sending to checkout

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

You can also execute a callback function if a customer was successfully sent to the first step of the checkout process in a store. See example code on the right.

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

Ecwid.Cart.canGotoCheckout

Check if possible to send customer to checkout

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

Using Ecwid.Cart.canGotoCheckout() function you can check whether you can send customers to the first step of checkout process in a store.

Fields:

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

Ecwid.Cart.setCustomerEmail

Function description

Ecwid.Cart.setCustomerEmail(email, successCallback, errorCallback);

Set customer email example

Ecwid.Cart.setCustomerEmail('james@coolstore.com');

Ecwid.Cart.setCustomerEmail() allows you to set customer’s email in checkout process. Make sure to use it on pages, where the email is not shown so that it is always up-to-date.

If a customer is logged in, your set email will overwrite the email for that customer’s account (if possible).

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

Fields:

errorCallback structure is: errorCallback(errCode, errMsg)

Errors

Ecwid.Cart.setOrderComments

Function

Ecwid.Cart.setOrderComments(orderComments, successCallback, errorCallback);

Set order comments example

Ecwid.Cart.setOrderComments('Leave order at the door.');

Full function call example

Ecwid.Cart.setOrderComments('Leave order at the door.',
  function(){
    console.log('Successfully set order comments.')
  },
  function(){
    console.log('Error setting order comments.');
});

Ecwid.Cart.setOrderComments allows you to set the order comments field on the fly. It’s quite useful to pass some additional information for an order, which will be provided in email notifications to customer and store admin as well as the order details in Ecwid Control Panel and Ecwid API.

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

Fields:

errorCallback structure is: errorCallback(errCode, errMsg)

Errors

Ecwid.Cart.setAddress

Function

Ecwid.Cart.setAddress(address, successCallback, errorCallback);

Set shipping address example

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"
  }
);

Full function call example

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(){
    console.log('Address successfully set')
  },
  function(){
    console.log('Error setting the address');
  }
);

Ecwid.Cart.setAddress() allows you to set shipping address for customer in storefront. You can use it to prefill and hide fields in checkout process to simplify it.

If you specify some fields only (name, for example), then Ecwid will reset all other fields and they will become empty. So if you need to update only some fields, make sure to send them in your function call as well as the updated values.

When function is called, Ecwid will set the 'My shipping address is the same as the billing address’ flag to true automatically.

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

Fields:

Person fields:

errorCallback structure is: errorCallback(errCode, errMsg)

Errors

Ecwid.Cart.setBillingAddress

Function

Ecwid.Cart.setBillingAddress(address, successCallback, errorCallback);

Set billing address example

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"
  }
);

Full function call example

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(){
   console.log('Address successfully set')
  },
  function(){
   console.log('Error setting the address');
  }
);

Ecwid.Cart.setBillingAddress() allows you to set billing address for customer in storefront. You can use it to specify some address from your custom form on your website.

If you specify some fields only (name, for example), then Ecwid will apply the changed fields only, leaving preset ones as they were before.

When function is called, Ecwid will set the 'My shipping address is the same as the billing address’ flag to false automatically.

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

Fields:

Person fields:

errorCallback structure is: errorCallback(errCode, errMsg)

Errors

Generate cart with products

Ecwid JavaScript API allows you to add items to customer’s cart automatically. This can be useful when you are using custom storefront to provide any type of button to add products to cart.

Using the following steps you will be able to create links to your storefront with products in cart for your customers. So all they have to do is just clikc that promo link to go to your store and have products added to cart automatically.

Let’s check out how this can be achieved:

Step 1: Add external files to your website

Script and CSS to load on your storefront page

<link rel="stylesheet" type="text/css" href="https://djqizrxa6f10j.cloudfront.net/apps/ecwid-cart-app/cartapp.css">
<script src="https://djqizrxa6f10j.cloudfront.net/apps/ecwid-cart-app/1.0.0/cart.js"></script>

Add this code to the source code of the page, where your Ecwid storefront is displayed.

Step 2: Generate your cart

Generate items in cart example

var cartItems = [{
    "id": 66821181, // ID of the product in Ecwid
    "quantity": 3, // Quantity of products to add
    "options": { // Specify product options
        "Color": "White",
        "Size":"11oz"
    }
}, {
    "id": 66722581,
    "quantity": 5
}];

var cart = {
     "gotoCheckout": true, // go to next checkout step right away (after 'Cart' page)
     "products": cartItems, // products to add to cart
     "profile": {
         "address": { // Shipping address details
             "name": "john smith",
             "companyName": "general motors",
             "street": "5th Ave",
             "city": "New York",
             "countryCode": "US",
             "postalCode": "10002",
             "stateOrProvinceCode": "NY",
             "phone": "+1 234 235 22 12"
         },
         "billingAddress": { // Billing address details
             "countryCode": "US",
             "stateOrProvinceCode": "AL",
         },
         "email": "test@test.com", // Customer email
         "orderComments": "Comments!" // Order comments
     }
 }

cart = encodeURIComponent(btoa(encodeURIComponent(JSON.stringify(cart))));

console.log(cart);

// prints the resulting string you need to use in step 3
//
// JTdCJTIyZ290b0NoZWNrb3V0JTIyJTNBdHJ1ZSUyQyUyMnByb2R1Y3RzJTIyJTNBJTVCJTdCJTIyaWQlMjIlM0E2NjgyMTE4MSUyQyUyMnF1YW50aXR5JTIyJTNBMyUyQyUyMm9wdGlvbnMlMjIlM0ElN0IlMjJDb2xvciUyMiUzQSUyMldoaXRlJTIyJTJDJTIyU2l6ZSUyMiUzQSUyMjExb3olMjIlN0QlN0QlMkMlN0IlMjJpZCUyMiUzQTY2NzIyNTgxJTJDJTIycXVhbnRpdHklMjIlM0E1JTdEJTVEJTJDJTIycHJvZmlsZSUyMiUzQSU3QiUyMmFkZHJlc3MlMjIlM0ElN0IlMjJuYW1lJTIyJTNBJTIyam9obiUyMHNtaXRoJTIyJTJDJTIyY29tcGFueU5hbWUlMjIlM0ElMjJnZW5lcmFsJTIwbW90b3JzJTIyJTJDJTIyc3RyZWV0JTIyJTNBJTIyNXRoJTIwQXZlJTIyJTJDJTIyY2l0eSUyMiUzQSUyMk5ldyUyMFlvcmslMjIlMkMlMjJjb3VudHJ5Q29kZSUyMiUzQSUyMlVTJTIyJTJDJTIycG9zdGFsQ29kZSUyMiUzQSUyMjEwMDAyJTIyJTJDJTIyc3RhdGVPclByb3ZpbmNlQ29kZSUyMiUzQSUyMk5ZJTIyJTJDJTIycGhvbmUlMjIlM0ElMjIlMkIxJTIwMjM0JTIwMjM1JTIwMjIlMjAxMiUyMiU3RCUyQyUyMmJpbGxpbmdBZGRyZXNzJTIyJTNBJTdCJTIyY291bnRyeUNvZGUlMjIlM0ElMjJVUyUyMiUyQyUyMnN0YXRlT3JQcm92aW5jZUNvZGUlMjIlM0ElMjJBTCUyMiU3RCUyQyUyMmVtYWlsJTIyJTNBJTIydGVzdCU0MHRlc3QuY29tJTIyJTJDJTIyb3JkZXJDb21tZW50cyUyMiUzQSUyMkNvbW1lbnRzISUyMiU3RCU3RA%3D%3D
//

In order for the script to add items to cart, we need to 'tell’ it what items to add. Check the example on the right on how to do this. The cart variable will have the generated cart content in it.

The syntax is very similar to adding products to cart via Ecwid JavaScript API.

Step 3: Create a link for customers

Final link structure

http://example.com/store#!/~/cart/create={generatedCartCode}

Final link to generated cart example

https://www.ecwid.com/demo#!/~/cart/create=JTdCJTIyZ290b0NoZWNrb3V0JTIyJTNBdHJ1ZSUyQyUyMnByb2R1Y3RzJTIyJTNBJTVCJTdCJTIyaWQlMjIlM0E2NjgyMTE4MSUyQyUyMnF1YW50aXR5JTIyJTNBMyUyQyUyMm9wdGlvbnMlMjIlM0ElN0IlMjJDb2xvciUyMiUzQSUyMldoaXRlJTIyJTJDJTIyU2l6ZSUyMiUzQSUyMjExb3olMjIlN0QlN0QlMkMlN0IlMjJpZCUyMiUzQTY2NzIyNTgxJTJDJTIycXVhbnRpdHklMjIlM0E1JTdEJTVEJTJDJTIycHJvZmlsZSUyMiUzQSU3QiUyMmFkZHJlc3MlMjIlM0ElN0IlMjJuYW1lJTIyJTNBJTIyam9obiUyMHNtaXRoJTIyJTJDJTIyY29tcGFueU5hbWUlMjIlM0ElMjJnZW5lcmFsJTIwbW90b3JzJTIyJTJDJTIyc3RyZWV0JTIyJTNBJTIyNXRoJTIwQXZlJTIyJTJDJTIyY2l0eSUyMiUzQSUyMk5ldyUyMFlvcmslMjIlMkMlMjJjb3VudHJ5Q29kZSUyMiUzQSUyMlVTJTIyJTJDJTIycG9zdGFsQ29kZSUyMiUzQSUyMjEwMDAyJTIyJTJDJTIyc3RhdGVPclByb3ZpbmNlQ29kZSUyMiUzQSUyMk5ZJTIyJTJDJTIycGhvbmUlMjIlM0ElMjIlMkIxJTIwMjM0JTIwMjM1JTIwMjIlMjAxMiUyMiU3RCUyQyUyMmJpbGxpbmdBZGRyZXNzJTIyJTNBJTdCJTIyY291bnRyeUNvZGUlMjIlM0ElMjJVUyUyMiUyQyUyMnN0YXRlT3JQcm92aW5jZUNvZGUlMjIlM0ElMjJBTCUyMiU3RCUyQyUyMmVtYWlsJTIyJTNBJTIydGVzdCU0MHRlc3QuY29tJTIyJTJDJTIyb3JkZXJDb21tZW50cyUyMiUzQSUyMkNvbW1lbnRzISUyMiU3RCU3RA%3D%3D

Now we need to fill in customer’s cart when your custom link is opened.

First things first, let’s determine where your Ecwid store is displayed and get a direct link to that page. For example, our demo store is located in: https://www.ecwid.com/demo

And to fill in customer’s cart with items that you seleted earlier, we need to create a link to your storefront with the generated cart part.

Example link

Generated link with products added automatically to cart for Ecwid demo store will be:

https://www.ecwid.com/demo#!/~/cart/create=JTdCJTIyZ290b0NoZWNrb3V0JTIyJTNBdHJ1ZSUyQyUyMnByb2R1Y3RzJTIyJTNBJTVCJTdCJTIyaWQlMjIlM0E2NjgyMTE4MSUyQyUyMnF1YW50aXR5JTIyJTNBMyUyQyUyMm9wdGlvbnMlMjIlM0ElN0IlMjJDb2xvciUyMiUzQSUyMldoaXRlJTIyJTJDJTIyU2l6ZSUyMiUzQSUyMjExb3olMjIlN0QlN0QlMkMlN0IlMjJpZCUyMiUzQTY2NzIyNTgxJTJDJTIycXVhbnRpdHklMjIlM0E1JTdEJTVEJTJDJTIycHJvZmlsZSUyMiUzQSU3QiUyMmFkZHJlc3MlMjIlM0ElN0IlMjJuYW1lJTIyJTNBJTIyam9obiUyMHNtaXRoJTIyJTJDJTIyY29tcGFueU5hbWUlMjIlM0ElMjJnZW5lcmFsJTIwbW90b3JzJTIyJTJDJTIyc3RyZWV0JTIyJTNBJTIyNXRoJTIwQXZlJTIyJTJDJTIyY2l0eSUyMiUzQSUyMk5ldyUyMFlvcmslMjIlMkMlMjJjb3VudHJ5Q29kZSUyMiUzQSUyMlVTJTIyJTJDJTIycG9zdGFsQ29kZSUyMiUzQSUyMjEwMDAyJTIyJTJDJTIyc3RhdGVPclByb3ZpbmNlQ29kZSUyMiUzQSUyMk5ZJTIyJTJDJTIycGhvbmUlMjIlM0ElMjIlMkIxJTIwMjM0JTIwMjM1JTIwMjIlMjAxMiUyMiU3RCUyQyUyMmJpbGxpbmdBZGRyZXNzJTIyJTNBJTdCJTIyY291bnRyeUNvZGUlMjIlM0ElMjJVUyUyMiUyQyUyMnN0YXRlT3JQcm92aW5jZUNvZGUlMjIlM0ElMjJBTCUyMiU3RCUyQyUyMmVtYWlsJTIyJTNBJTIydGVzdCU0MHRlc3QuY29tJTIyJTJDJTIyb3JkZXJDb21tZW50cyUyMiUzQSUyMkNvbW1lbnRzISUyMiU3RCU3RA%3D%3D

Set order referrer

Set order referrer to 'Amazon’

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

You can set a custom referrer for an order in storefront – use the ec.order.referrer_id field for your custom value.

Afterwards, this field will appear in order export via CSV, invoices and email notifications as a variable, and in the Ecwid REST API for orders.