Table of Contents

Cart commands

Manipulating shopping cart content using cart commands

Cart Commands are commands for manipulating shopping carts, for instance when adding or removing a product from cart. There are two ways to execute a cart command:

  • By submitting an URL with the cartcmd parameter and a set of other parameters and values appropriate for the cart command
  • By submitting a Form using a button with the name CartCmd and a set of input fields with names and values appropriate for the cart command

Generally speaking, there are two types of cart commands:

  • Those that manipulate cart content by e.g. adding product to or removing products from a shopping cart
  • Those that manipulate the cart object e.g. by creating new carts, setting a cart as active, archiving a cart, etc.

Both types - and a couple of odd cart commands which fall outside these categories - are described below.

Cart content

The most commonly used groups of cart commands are used to manipulate cart content - which is a fancy way of saying that you use them to:

  • Add or remove products from a cart
  • Increase or decrease the quantity of an order line
  • Empty the cart
  • Etc.

These commands are typically used in either a product catalog app template like a product list or in a shopping cart app template to e.g. let the user increase or decrease quantities in the cart, but they can technically be submitted from pretty much anywhere as long as you can access the approproate data to submit, like product ids, orderlines, etc.

Add

The add command adds a single product to cart - or, if the product is already in cart, increases the quantity by one.

Parameter Value Required Comment
productid A product id Yes
variantid A variant id No Use this to add a specific variant to cart.
cartid A cart ID No Use this parameter to add to non-active carts on solutions with cart management.
unitid A unit id No Use this to add a specific product unit to cart
stocklocationid A stock location id No Use this to subtract stock from a specific stock location
wishlistid A wish list id No Use this to add a product to a specific wish list

A simple form for this command could look like:

<!-- Add-->
<form method="post">
    <input type="hidden" name="ProductId" value="@product.Id" />
    <input type="hidden" name="VariantId" value="@product.VariantId" />
    <button type="submit" name="CartCmd" value="Add">Add</button>
</form>

Addmulti & setmulti

The addmulti and setmulti commands add multiple products to cart – both many of the same product and many different products. When using this command you typically nest the whole products loop inside a form, and then submit everything to cart using a single button.

The difference between the two commands is:

  • Addmulti adds the submitted quantity to the existing quantity (if any)
  • Setmulti sets the quantity to the submitted quantity, replacing the existing quantity (if any)

All parameters must be submitted with an integer added, so productid becomes productid1 for the first product, productid2 for the second product, and so on.

Parameter Value Required Comment
productid A product id Yes
productloopcounter An integer Yes
Quantity An integer Yes
variantid A variant id No Use this to add a specific variant to cart.
cartid A cart id No Use this parameter to add to non-active carts on solutions with cart management.
unitid A unit id No Use this to add a specific product unit to cart
stocklocationid A stock location id No Use this to subtract stock from a specific stock location
wishlistid A wish list id No Use this to add a product to a specific wish list

A simple mock-example for using this command could look like:

@{
    int Count = 0;
}
<form method="post" class="col-md-12">

    <!--Foreach product-->
    Count = Count +1;

    string ProductLoopCounter = "ProductLoopCounter" + Count;
    string ProductIDCounter = "ProductID" + Count;
    string VariantIDCounter = "VariantID" + Count;
    string UnitIDCounter = "UnitID" + Count;
    string wishListIDCounter = "wishListID" + Count;
    string QuantityCounter = "Quantity" + Count;

    <input type="hidden" name="@ProductLoopCounter" id="@ProductLoopCounter" value="@Count" />
    <input type="hidden" name="@ProductIDCounter" id="@ProductIDCounter" value="@product.Id" />
    <input type="hidden" name="@VariantIDCounter" id="@VariantIDCounter" value="@product.VariantId" />
    <input type="hidden" name="@UnitIDCounter" id="@UnitIDCounter" value="" />
    <input type="hidden" name="@wishListIDCounter" id="@wishListIDCounter" value="" />
    <input type="text" name="@QuantityCounter" value="0" />

    <!--One button to add to cart-->
    <button class="btn btn-primary pull-right" type="submit" name="CartCmd" value="addmulti">Addmulti</button>
    <button class="btn btn-primary pull-right" type="submit" name="CartCmd" value="setmulti">Setmulti</button>

</form>

Addwithpoints

The addwithpoints command is used to buy a product with loyalty points. There’s no automatic check in place to ensure that the user has enough points available to buy the product, this must be handled in the template.

Parameter Value Required Comment
productid A product id Yes
variantid A variant id No Use this to add a specific variant to cart.
cartid A cart id No Use this parameter to add to non-active carts on solutions with cart management.
unitid A unit id No Use this to add a specific product unit to cart
stocklocationid A stock location id No Use this to subtract stock from a specific stock location

A simple form using this could look like this:

<form method="post">
    <input type="hidden" name="ProductId" value="@product.Id" />
    <input type="hidden" name="VariantId" value="@product.VariantId" />
    <button type="submit" name="CartCmd" value="addwithpoints">Addwithpoints</button>
</form>

Incorderline, decorderline & delorderline

The commands incorderline, decorderline, and delorderline are used to increase, decrease and delete an orderline. The only parameter is key which must have a valid orderline id as its value.

Parameter Value Required Comment
key An orderline id Yes

A simple form using this could look like this:

<form method="post">
    <input type="hidden" name="key" value='@line.GetValue("Ecom:Order:OrderLine.Id")' />
    <button type="submit" name="CartCmd" value="IncOrderLine"><span class="glyphicon glyphicon-plus"></span></button>
    <button type="submit" name="CartCmd" value='DecOrderline'><span class="glyphicon glyphicon-minus"></span></button>
    <button type="submit" name="CartCmd" value="DelOrderLine"><span class="glyphicon glyphicon-trash"></span></button>
</form>

Deleteallorderlines

The deleteallorderlines command is used to delete all orderlines in a cart – the cart object will then be either deleted or not, depending on whether or not the solution has the Do not delete carts with 0 orderlines setting enabled.

Parameter Value Required Comment
cartid A valid cart id No Use this to delete all orderlines from a cart other than the current cart

A simple form using this could look like this:

<form method="post">
    <button type="submit" name="CartCmd" value="deleteallorderlines">Delete all order lines</button>
</form>

Emptycart

The emptycart command is used to empty a cart – it also explicitly deletes the cart object. To delete all orderlines but not the cart object use the deleteallorderlines command.

Parameter Value Required Comment
cartid A valid cart id No Use this to empty and deleta a cart other than the current cart

Orderline

The orderline command is used to add to the quantity of a specific orderline directly – it does not support adding zero or negative amounts, both of which default to 1.

Parameter Value Required Comment
key An orderline ID Yes
quantity An integer Yes

A simple form using this command could look like this:

<form method="post">
    <input type="hidden" name="key" value='@line.GetValue("Ecom:Order:OrderLine.Id")' />
    <input type="number" name="quantity" value="1" />
    <button type="submit" name="CartCmd" value="Orderline">Add quantity</button>
</form>

Updateorderlines

The updateorderlines command is used to set the quanity of all included orderlines to a specific amount, replacing the existing quantity. The QuantityOrderLine parameter must be suffixed with a valid orderline id, e.g. QuantityOrderLineOL23 for the order line with the id OL23.

Parameter Value Required Comment
QuantityOrderLine{ID} An integer Yes

A simple mock-form using this command could look like this:

<form>
    <!--For each orderline-->
    <input type="number" name='QuantityOrderLine@(line.GetValue("Ecom:Order:OrderLine.Id"))' value='@line.GetValue("Ecom:Order:OrderLine.Quantity")' />
    <!--Use one button to submit-->
    <button type="submit" name="CartCmd" value="Updateorderlines">Updateorderlines</button>
</form>

Cart management

The other group of cart commands are used to manipulate cart objects – which means:

  • Creating carts
  • Copying carts
  • Archiving or activating a cart
  • Applying custom discounts to a cart
  • Etc.

Combined, these cart commands make it possible to create a wide range of self-service solutions where customers or staff can work with multiple open carts or order drafts over time before finalizing an order. You can read about this type of solutions here.

Archive

The archive cart command is used to archive the current cart, which means that it is removed as the current cart. The archived cart can be set as the active cart again using the setcart command. Since it affects only the currently active cart, this command does not take any parameters.

To use this cartcommand submit a form or use the parameter on an url:

<form method="post">
     <button type="submit" name="CartCmd" value="archive"></button>
</form>

<a href='cartcmd=archive'>Archive Cart</a>

Copy

The copy cart command copies a cart and all contents – it requires a cart id, and you can also name the new cart and specify which user it should belong to. The user must be either the current user (default option) or a user who can be impersonated by the current user.

Parameter Value Required Comment
CartId A cart ID Yes
CartName Any string No
CartUserId A valid user ID No Must be either the id of the current user, or a user which can be impersonated by the current user. Defaults to current user.

A simple form using this command could look like this:

<form method="post">
    <input type="text" name="CartName" id="CartName" value='Copy_of_@cart.GetString("Ecom:Order.ID")' />
    <input type="hidden" name="CartID" id="CartID" value='@cart.GetString("Ecom:Order.ID")' />
    <input type="hidden" name="CartUserId" id="CartUserID" value="@userID" />
    <button type="submit" name="CartCmd" value="copy">Copy Cart</button>
</form>

Createnew

The createnew command is used to a create a new, empty cart. It takes two optional paramaters – CartUserId and CartName – which are used to specify the owner and the name of the new cart. The user must be the current user or a user who can be impersonated by the current user.

Parameter Value Required Comment
CartName Any string No
CartUserId A valid user ID No Must be either the id of the current user, or a user which can be impersonated by the current user. Defaults to current user.

A simple form/link using this cart command could look like this:

<form method="post">
    <input type="hidden" id="CartUserId" name="CartUserId" value="@userID" />
    <input type="text" id="CartName" name="CartName" value="" />
    <button type="submit" name="CartCmd" value="createnew">Create new cart</button>
</form>

<a href='@baseurl&cartcmd=createnew&CartUserId=@userID&CartName=NewCart'>Create new cart</a>

Setcart

The setcart command is used to set a cart as the active cart. It takes a single, required argument namely a cartid.

Parameter Value Required Comment
Cartid A cart id Yes

A simple form/link using this cart command could look like this:

<form method="post">
    <input type="hidden" name="CartID" id="CartID" value='@cart.GetString("Ecom:Order.ID")' />
    <button type="submit" name="CartCmd" value="setcart">Set cart</button>
</form>

<a href='@baseurl&cartcmd=setcart&CartID=@cart.GetString("Ecom:Order.ID")'>Set Cart</a>

Setdiscount

The setdiscount cart command is used to assign custom order discounts to a cart, either a fixed amount or a percentage discount. It is intended to be used as a part of a cart management from frontend setup, where a sales rep or equivalent can login to frontend and work with open customer carts.

In order for this cart command to work:

  • You must have discounts of the types custom amount discount and custom percentage discount created
  • The user assigning the discount must have impersonation rights

Once these conditions are fulfilled, you can add variable discounts to a cart:

  • To assign a fixed amount discount submit the property OrderDiscount with an integer value
  • To assign a percentage discount submit the property OrderDiscountPercentage with an integer value

You can use a cartid parameter to assign the discount to a specific cart - if you don't, we default to the current cart.

Parameter Value Required Comment
OrderDiscount An integer Yes*
OrderDiscountPercentage An integer Yes*
CartID A valid cart id No Defaults to current cart if no cart is specified
*Only one of these is required

A simple form using setdiscount could look like this:

<!--Fixed discount-->
<form method="post">
    <input type="hidden" name="CartID" id="CartID" value="@currentcart.Id" />
    <input type="number" name="OrderDiscount" id="OrderDiscount" value="0" />
    <button type="submit" name="CartCmd" value="setdiscount">Apply fixed discount</button>
</form>

<!--Percentage discount-->
<form method="post">
    <input type="hidden" name="CartID" id="CartID" value="@currentcart.Id" />
    <input type="number" name="OrderDiscountPercentage" id="OrderDiscountPercentage" value="0" />
    <button type="submit" name="CartCmd" value="setdiscount">Apply percentage discount</button>
</form>

Setname

The setname command is used to det the display name of a cart – a name which can be given a meaningful value and shown in frontend instead of e.g. the CartId. It takes two parameters – CartId and CartName – both of which are mandatory.

Parameter Value Required Comment
CartId A valid cart id Yes
CartName A string Yes

A simple form using setname could look like this:

<!--Setname-->
<form method="post">
    <input type="text" name="CartName" id="CartName" value="" />
    <input type="hidden" name="CartID" id="CartID" value='@cart.GetString("Ecom:Order.ID")' />
    <button type="submit" name="CartCmd" value="setname">Set name</button>
</form>

Other cart commands

A couple of more specialized cart commands exist - they are described below:

Createnotificationforthisproduct

The createnotificationforthisproduct cart command is used to create a back-in-stock notification for a given user or email related to a product.

Parameter Value Required Comment
ProductID Yes
VariantID Yes
LanguageID Yes
NotificationEmail Yes* Required for anonymous users

A simple example using this cart command:

<!-- Back in stock notifications-->
@if (isLoggedIn == true)
{
    <a href="/default.aspx?id=@Pageview.Page.ID&@productLink&VariantID=@product.VariantId&LanguageID=@product.LanguageId&cartcmd=createnotificationforthisproduct">Create notification</a>
}
else if (isLoggedIn == false)
{
    <form name='@product.Id' id='NotificationForm_@product.Id' method='post' action='/Default.aspx?ID=@Pageview.Page.ID'>
        <input type="hidden" name="ProductID" id="ProductID" value='@product.Id' />
        <input type="hidden" name="VariantID" id="VariantID" value='@product.VariantId' />
        <input type="hidden" name="LanguageID" id="LanguageID" value='@product.LanguageId' />
        <input type="email" required="required" id="NotificationEmail" name="NotificationEmail" value="">
        <button type="submit" name="CartCmd" value="createnotificationforthisproduct">Create back in stock notification</button>
    </form>
}

Delsavedforlater

The delsavedforlater cart command is used to remove a product from a Saved for later-list, a distant ancestor to favorite lists. Instead of using this cart command, we recommend you use one of our more recent features like favorite lists or the cart management commands described in this article.

Parameter Value Required Comment
ProductID A valid product id Yes

Loadorder

The loadorder cart command is used to retrieve an abandoned cart – it is typically used in abandoned cart emails to link people to a cart where their abandoned order will be shown.

Parameter Value Comment
LoadingOrderId A valid order id
LoadingOrderSecret A valid loading order secret
Improve this doc
To top