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 which manipulate cart content, e.g. by adding or removing products from cart
  • Those which manipulate the cart object, e.g. creating carts, setting a cart as active, archiving a cart, etc.

Both types – and some special cart commands which fall outside these categories – are described below.

One group 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 cart
  • Increase or decrease the quantity of an order line
  • Empty the cart
  • Ertc.

These commands are typically submitted to the system from either the product catalog app or the shopping cart app but they can be submitted from pretty much anywhere, provided that you can access the data you need to submit to cart, like product ids, orderline ids, etc.

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
RAZOR
<!-- Add--> <form method="post" class="col-md-12"> <input type="hidden" name="ProductId" value="@product.Id" /> <input type="hidden" name="VariantId" value="@product.VariantId" /> <button class="btn btn-primary pull-right" type="submit" name="CartCmd" value="Add">Add</button> </form>

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
RAZOR
<!—Addmulti & Setmulti--> @{ 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>

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
RAZOR
<!--Add with points--> <form method="post" class="col-md-12"> <input type="hidden" name="ProductId" value="@product.Id" /> <input type="hidden" name="VariantId" value="@product.VariantId" /> <button class="btn btn-primary pull-right" type="submit" name="CartCmd" value="addwithpoints">Addwithpoints</button> </form>

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

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

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 checkbox checked under Settings > Ecommerce > Advanced configuration > Shopping Cart.

Parameter

Value

Required

Comment

cartid

A valid cart id

No

Use this to delete all orderlines from a cart other than the current cart
RAZOR
<!--Delete all orderlines--> <form method="post"> <button type="submit" name="CartCmd" value="deleteallorderlines">Delete all order lines</button> </form>

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 - and make sure the solutions does not have the Do not delete carts with 0 orderlines checkbox checked under Settings > Ecommerce > Advanced configuration > Shopping Cart.

Parameter

Value

Required

Comment

cartid

A valid cart id

No

Use this to empty and deleta a cart other than the current cart
RAZOR
<!--Emptycart--> <form method="post"> <button type="submit" name="CartCmd" value="emptycart">Emptycart</button> </form>

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

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

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

 
RAZOR
<!--Updayeorderlines--> <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 class="btn btn-default" type="submit" name="CartCmd" value="Updateorderlines">Updateorderlines</button> </form>

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 order drafts over time before finalizing an order.

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.

RAZOR
<!--Archive>--> <form method="post"> <button type="submit" name="CartCmd" value="archive"></button> </form> <a href='@baseurl&cartcmd=archive'>Archive Cart</a>

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.
RAZOR
<!--Copy--> <form method="post" class="col-md-12"> <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 class="btn btn-primary" type="submit" name="CartCmd" value="copy">Copy Cart</button> </form>

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.
RAZOR
<!--Createnew--> <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 class="btn btn-success pull-right" href='@baseurl&cartcmd=createnew&CartUserId=@userID&CartName=NewCart'>Create new cart</a>

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

Parameter

Value

Required

Comment

Cartid

A cart id

Yes

 
RAZOR
<!--Setcart--> <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>

The setdiscount cart command is used to assign custom order discounts to a cart, either a fixed amount or a percentage discount. In order for this cart command to work:

Once these conditions are fulfilled you can add variable discounts to an order:

  • 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 parameters to assign to a specific cart – if left out 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
RAZOR
<!--Fixed discount--> <form method="post"> <input type="hidden" name="CartID" id="CartID" value="@currentcart.Id" /> <input type="number" name="OrderDiscount" id="OrderDiscount" value="0" /> <span>@currentcart.CurrencyCode </span> <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" /> <span>% </span> <button type="submit" name="CartCmd" value="setdiscount">Apply percentage discount</button> </form>

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

 
RAZOR
<!--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>

In addition to the cart commands described above, a number of more specialized cart commands exist – they are described below.

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

Parameter

Value

Required

Comment

ProductID

 

Yes

 

VariantID

 

Yes

 

LanguageID

 

Yes

 

NotificationEmail

 

Yes*

 

* For anonymous users – but not logged in users. You should probably  make sure they have an email on their profile too, though.
RAZOR
<!-- 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' /> <label for="NotificationEmail">Email</label> <input type="email" required="required" id="NotificationEmail" name="NotificationEmail" value=""> <button class="btn btn-primary btn-xs" type="submit" name="CartCmd" value="createnotificationforthisproduct">Create back in stock notification</button> </form> }

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 cart management.

Parameter

Value

Required

Comment

ProductID

A valid product id

Yes

 

The load order 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

 
RAZOR
<a href="/Default.aspx?CartCmd=loadorder&LoadingOrderId=<!--@Ecom:Order.ID-->&LoadingOrderSecret=<!--@Ecom:Order.LoadingOrderSecret-->">Load order</a>

Order contexts are used to create multiple shopping carts on a solution - to add products to a specific context cart you generally only need to add an OrderContext parameter to the cart command and set an order context as the value.

Read more about order contexts.

Please note that order contexts & cart management can't be used at the same time.