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.

📘

Subscribe to the 'Ecwid.OnAPILoaded' to ensure availability of this function.

Adding by product ID

Add product by ID function:
Ecwid.Cart.addProduct(productID, callback);

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

NameTypeDescription
productIDintegerthe 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)
callbackfunctionthe 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 the example code on the above. This code adds 1 item of the given product ID to the 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.

If this product has "nameYourPriceEnabled": true, the product will be added with the minimum price set by the merchant or defined by priceDefaultTier.

Adding with extended options

Add product with extended options function: Ecwid.Cart.addProduct(Product);

addProduct() can accept an argument: Product.

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

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"]
    },
  recurringChargeSettings: { 
    recurringInterval: "month",
    recurringIntervalCount: 1,
    },
  callback: function(success, product, cart) {
    // ...  
  }
}

Ecwid.Cart.addProduct(product);

Product

NameTypeDescription
idintegerProduct ID
quantityintegerAmount of products to add to cart
options<OptionsInfo>Selected product options for product
selectedPriceintegerSelected price for the product with the parameter "nameYourPriceEnabled": true. If specified for a product with "nameYourPriceEnabled": false, the product will be added with the default price.
recurringChargeSettings<RecurringChargeSettings>Recurring charge settings info.
callbackfunctionFunction to run after the function is performed

OptionsInfo

NameTypeDescription
optionNamestring or array of stringReplace 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

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.

RecurringChargeSettings

FieldTypeDescription
recurringIntervalstringCharge recurring interval. Supported values: DAY, WEEK, MONTH, YEAR.
recurringIntervalCountnumberCharge recurring interval. Supported values: for DAY - 1 (daily), for WEEK - 1 (weekly), 2 (biweekly), for MONTH - 1 (monthly), 3 (quarterly), for YEAR - 1 (annually).

This method allows adding subscription products to cart. Read more about Recurring subscriptions.
If you specify and pass recurringChargeSettings - a product will be added to cart as a subscription product. If you don't specify and pass recurringChargeSettings (or if the specified data is incorrect) - a product will be added to cart as a one-time-purchase product.

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 argument of the function when you add a product by ID or as the Product object method when you add a product with extended options.

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

NameTypeDescription
successBooleanindicates the overall status of addition (succeeded or failed)
product<Product>contains 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)
errorStringReturns an error message when adding a product with the parameter "nameYourPriceEnabled": true (e.g. The price in the “selectedPrice” field must be 5 or more)

Examples:

Ecwid.Cart.addProduct(productID, function(success, product, cart){
  console.log(success); // true or false
  console.log(product.name);
});
Ecwid.Cart.addProduct({
  id: 10,
  quantity: 3,
  selectedPrice: 12, // for the product with the parameter "nameYourPriceEnabled": true
  options: {
    "Size": "L"
  }, 
  callback: function(success, product, cart, error){
    console.log(success); // true or false
    console.log(product.name);
    console.log(error) // error message or null
  }
});
var id = 10;

Ecwid.Cart.addProduct(id);

// Adds a subscription product to cart as a one-time-purchase product
var product = {
  id: 10,
  quantity: 3,
  recurringChargeSettings: { 
    recurringInterval: "month",
    recurringIntervalCount: 1,
    },
  callback: function(success, product, cart) {
    // ...  
  }
}

Ecwid.Cart.addProduct(product);

// Adds a subscription product to cart as a subscription product
{
  id: 149325324
  name: "Test"
  price: 30
  shortDescription: "Description"
  sku: "00002"
  url: "https://test.ecwid.com/Test-p149325324?~~mode=product&~~id=149325324"
  weight: 2
}