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.

After a cart command runs, the user is redirected back to the referring page (or to a page specified with a Redirect parameter). Most content-manipulating commands set a result that you can inspect in templates to give feedback (e.g. product added, cart emptied).

Note

Once a cart can no longer be edited – for example because it has entered checkout – most cart commands are ignored. Only emptycart, createnew, and setcart (along with the ledger-related commands) are still processed on a non-editable cart.

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 appropriate data to submit, like product ids, order lines, 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
quantity An integer No How many units to add. Defaults to the product's quantity step (1 for most products) if omitted
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
EcomOrderLineFieldInput_{OrderLineFieldSystemName} Value of the orderline field No Use this to set the value of a custom order line field

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>

When adding a product of the type BOM (a bundle), the command accepts an additional set of fields for configuring the bundle content - selecting products in bundle groups, choosing variants, and setting per-item quantities. These fields are documented in Bundles (BOM).

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)

The per-product parameters must be submitted with an integer suffix, so productid becomes productid1 for the first product, productid2 for the second product, and so on. The suffix must match the value of the corresponding productloopcounter.

Parameter Value Required Comment
productid{n} A product id Yes Suffixed per product, e.g. productid1
productloopcounter{n} An integer Yes Suffixed per product; its value is the same n used to suffix the other fields
Quantity{n} An integer Yes Suffixed per product
variantid{n} A variant id No Suffixed per product. Use this to add a specific variant to cart.
unitid{n} A unit id No Suffixed per product. Use this to add a specific product unit to cart
stocklocationid{n} A stock location id No Suffixed per product. Use this to subtract stock from a specific stock location
cartid A cart id No Not suffixed. Use this to add to non-active carts on solutions with cart management.
wishlistid A wish list id No Not suffixed – a single value shared by all the submitted products. Use this to add the products 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 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="text" name="@QuantityCounter" value="0" />

    <!--wishListID is shared by all products, so it is NOT suffixed-->
    <input type="hidden" name="wishListID" value="" />

    <!--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
quantity An integer No How many units to add. Defaults to the product's quantity step (1 for most products) if omitted
stocklocationid A stock location id No Use this to subtract stock from a specific stock location
EcomOrderLineFieldInput_{OrderLineFieldSystemName} Value of the orderline field No Use this to set the value of a custom order line field

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. They take a key parameter 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>
Note

delorderline can alternatively be given a ProductID parameter instead of key – in that case all order lines for that product are removed from the cart. If both are supplied, ProductID takes precedence.

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 delete 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 – a non-positive quantity is replaced by the product's quantity step (1 for most products).

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 updates one or more properties of one or more orderlines at once. Each parameter is 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 No Sets the orderline's quantity, replacing the existing quantity. A value of 0 leaves the quantity unchanged rather than deleting the line - use delorderline to remove a line
DiscountPercentageOrderLine{ID} A percentage No Sets a discount percentage on the orderline. Only applied if the current user has cart-editing rights, e.g. impersonation
UnitPriceOrderLine{ID} A decimal amount No Overrides the orderline's unit price. Only applied if the current user has cart-editing rights, e.g. impersonation
StockLocationOrderLine{ID} A stock location id No Sets the stock location the orderline is picked from
CustomerCommentOrderLine{ID} A string No Sets a customer-facing comment on the orderline

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>
Note

Submitted QuantityOrderLine{ID} values are applied to the cart on every request that has an active cart, regardless of which CartCmd - if any - is submitted alongside them. Explicitly submitting updateorderlines is still recommended, since it is the only way to get a CartResultType.OrderLinesUpdated result to give feedback in your template. The other four parameters above are only applied when updateorderlines is submitted.

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>

By default, copy copies only the cart name, owner, custom order discounts, and the product order lines. To also copy the addresses, comments, requisition & reference, shipping date, and order context, use the copyExtended command instead – it takes the same parameters as copy:

<button type="submit" name="CartCmd" value="copyExtended">Copy cart with addresses</button>
Note

Extended copying can also be made the default for the plain copy command by enabling the /Globalsettings/Ecom/Cart/Cmd/EnableExtendedCopy configuration setting.

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.
SetActive true or false No Defines if the newly created empty cart should be set as the active cart
OrderContextId An order context id No Creates the cart in a specific order context

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 set 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 a mandatory CartName parameter, and an optional CartId.

Parameter Value Required Comment
CartName A string Yes
CartId A valid cart id No Defaults to the current cart if no cart is specified

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>

Ledger commands

A separate pair of cart commands is used to combine one or more ledger entries - such as outstanding invoices - into a single payment order, and to adjust how much of that payment order is actually paid. These are the commands behind invoice-payment flows like Truvio Payment Portal.

Combineforpayment

The combineforpayment command combines one or more ledger entries into a single payment order, covering each entry's full remaining balance. The user must be logged in, and all the given entries must be ledger entries using the same currency.

Parameter Value Required Comment
Ids Comma-separated list of ledger entry (order) IDs Yes
TargetLedgerType A ledger type name No Sets the ledger type of the resulting payment order
PaidOrderStateId An order state ID No The order state to set on each combined entry once its payment is completed in full. If omitted, the order state is not changed
PartiallyPaidOrderStateId An order state ID No The order state to set on each combined entry if its payment is completed as a partial payment - see updatecombinedpayments. If omitted, the order state is not changed

A simple link using this command could look like this:

<a href='cartcmd=combineforpayment&Ids=INVOICE001,INVOICE002&TargetLedgerType=PAYMENT&PaidOrderStateId=OS11&PartiallyPaidOrderStateId=OS12'>Pay selected invoices</a>
Note

combineforpayment always creates a payment order for the full remaining balance of each entry. To let the customer pay less than the full balance, follow up with updatecombinedpayments before the payment order is completed at checkout.

Updatecombinedpayments

The updatecombinedpayments command adjusts how much of the current payment order - created with combineforpayment - is paid for one or more of its combined entries, reducing it below the full balance to record a partial payment. It works on the active cart, so it must be run after combineforpayment and before the payment order is completed at checkout.

Parameter Value Required Comment
Ids Comma-separated list of ledger entry (order) IDs to update Yes Must match entries already combined into the current payment order
AmountWithoutVAT_{ID} A decimal amount Yes, per ID Suffixed per entry, e.g. AmountWithoutVAT_INVOICE001. The amount to pay for that entry, excluding VAT. An amount that is zero, negative, or greater than the entry's remaining balance is ignored, leaving the entry's current price unchanged

A simple link using this command could look like this:

<a href='cartcmd=updatecombinedpayments&Ids=INVOICE001,INVOICE002&AmountWithoutVAT_INVOICE001=250&AmountWithoutVAT_INVOICE002=150'>Update payment amounts</a>
Note

If the submitted amount matches an entry's full remaining balance, the entry is treated as fully paid rather than partial - the PartiallyPaidOrderStateId set in combineforpayment only applies once the paid amount is genuinely less than the balance.

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 A valid product id Yes The product to watch
VariantID A variant id No Use this to watch a specific variant
LanguageID A language id No Used to look up the product; falls back to the current context language if omitted
UnitID A unit id No Use this to watch a specific product unit
NotificationEmail An email address Yes* Required for anonymous users. For logged-in users the user's own email is used if omitted.

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 Required Comment
LoadingOrderId A valid order id Yes
LoadingOrderSecret A valid loading order secret Yes
Improve this doc
To top