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.
Name | Type | Description |
---|---|---|
productID | integer | the Ecwid’s internal product ID to be added to cart (can be retrieved from product export, seen in the URL of the product page or via REST API) |
callback | function | the callback function to be called once the operation is complete (either succeeded or failed). See below for details. |
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
Name | Type | Description |
---|---|---|
success | Boolean | indicates the overall status of addition (succeeded or failed) |
product | <Product> | conatins the object representation of the product added to cart, or null if adding to cart failed (wrong product ID or product is out of stock). |
cart | <Cart> | contains the object representation of the shopping cart after addition (same as in Ecwid.OnCartChanged event) |
Product
Name | Type | Description |
---|---|---|
id | integer | Product ID |
quantity | integer | Amount of products to add to cart |
options | <OptionsInfo> | Selected product options for product |
callback | function | Function to run after the function is performed |
OptionsInfo
Name | Type | Description |
---|---|---|
optionName | string or array of string | Replace optionName with the real exact product option name you want to specify. Available values depend on the product option type: for checkbox options the value is array of strings , for all other options the value is a string |
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
Name | Type | Description |
---|---|---|
index | integer | index of a product in cart object you need to remove from customer’s cart |
Ecwid.Cart.clear
Clear cart contents
Ecwid.Cart.clear()
Clears the cart contents.
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.
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.
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.
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:
Name | Type | Description |
---|---|---|
callback | boolean | true if you can send customer to the checkout process, false otherwise |
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).
Fields:
Name | Type | Description |
---|---|---|
string | Customer email address to be set | |
successCallback | function | Success callback function |
errorCallback | function | Error callback function |
errorCallback
structure is: errorCallback(errCode, errMsg)
Name | Type | Description |
---|---|---|
errCode | number | Error code |
errMsg | string | Error message |
Errors
Error code | Error message |
---|---|
0 | Missing argument |
100 | Incorrect data passed |
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.
Fields:
Name | Type | Description |
---|---|---|
orderComments | string | Order comments string to be set for an order |
successCallback | function | Success callback function |
errorCallback | function | Error callback function |
errorCallback
structure is: errorCallback(errCode, errMsg)
Name | Type | Description |
---|---|---|
errCode | number | Error code |
errMsg | string | Error message |
Errors
Error code | Error message |
---|---|
1000 | Store owner disabled this functionality |
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.
Fields:
Name | Type | Description |
---|---|---|
address | <Person> | Customer’s shipping address details |
successCallback | function | Success callback function |
errorCallback | function | Error callback function |
Person fields:
Name | Type | Description |
---|---|---|
name | string | Customer’s name |
companyName | string | Customer’s company name |
street | string | Customer’s street address. Use \n to place text in Address Line 2 |
city | string | Customer’s city |
countryName | string | Customer’s country name. countryCode can be used instead |
countryCode | string | Customer’s country code. countryName can be used instead |
postalCode | string | Customer’s zip code |
stateOrProvinceCode | string | Customer’s state or provice code |
phone | string | Customer’s phone number |
errorCallback
structure is: errorCallback(errCode, errMsg)
Name | Type | Description |
---|---|---|
errCode | number | Error code |
errMsg | string | Error message |
Errors
Error code | Error message |
---|---|
0 | Missing argument |
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.
Fields:
Name | Type | Description |
---|---|---|
address | <Person> | Customer’s billing address details |
successCallback | function | Success callback function |
errorCallback | function | Error callback function |
Person fields:
Name | Type | Description |
---|---|---|
name | string | Customer’s name |
companyName | string | Customer’s company name |
street | string | Customer’s street address. Use \n to place text in Address Line 2 |
city | string | Customer’s city |
countryName | string | Customer’s country name. countryCode can be used instead |
countryCode | string | Customer’s country code. countryName can be used instead |
postalCode | string | Customer’s zip code |
stateOrProvinceCode | string | Customer’s state or provice code |
phone | string | Customer’s phone number |
errorCallback
structure is: errorCallback(errCode, errMsg)
Name | Type | Description |
---|---|---|
errCode | number | Error code |
errMsg | string | Error message |
Errors
Error code | Error message |
---|---|
0 | Missing argument |
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://s3.amazonaws.com/ecwid-addons/apps/ecwid-cart-app/cartapp.css">
<script src="https://s3.amazonaws.com/ecwid-addons/apps/ecwid-cart-app/cart.js"></script>
Add this code to the source code of the page, where your Ecwid storefront is displayed. Add the script after or below Ecwid integration code.
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 = JSON.stringify(cart);
cart = encodeURIComponent(cart);
console.log(cart);
// prints the resulting string you need to use in step 3
//
// %7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D
//
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=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D
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=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D