/cart/update.json

Cart object returned as JSON.

For familiarity we have tried to ensure consistency in terminology with the Cart object.

Example using JQuery


    $.ajax({
        url: "/cart/update.json",
        type: "POST",
        dataType: "json",
        data: "line[1][quantity]=2",
        success : function(returnValue) {
            console.log(returnValue);
        },
        error: function(xhr, resp, text) {
            console.log(xhr, resp, text);
        }
    });

Internationalisation

If your website has multiple languages you will want to ensure results are returned in the language, country and currency of your locales. To achieve this you can localise the URL as follows.

In your EVML view file:


<div id="myDiv" data-url="@/cart/update.json"></div>

Within your view's JavaScript file:


    var myDiv = jQuery('#myDiv');
    $.ajax({
        url: myDiv.attr('data-url'),
        type: "POST",
        dataType: "json",
        data: "line[1][quantity]=2"
        success : function(returnValue) {
            console.log(returnValue);
        },
        error: function(xhr, resp, text) {
            console.log(xhr, resp, text);
        }
    });

With the code above it won't matter which locale you visit the URL and results will be correct.

Accepted Parameters

The update script allows you to define the following optional parameters.

cart[postageId]

If a valid postage id is supplied, the cart is updated.

couponName

If a valid coupon code is supplied, the cart is updated.

fragment

An EVML include/partial to render per result. You may supply one fragment to render only. The fragment path should be supplied in the format controller/filename. For example in many themes the file cart/mini.partial.evml is available. This may be supplied as /cart.json?fragment=cart/mini.partial

line[id][quantity]

You can update the quantity of a cart line by supplying the line id and the new quantity.

taxNumber

If a valid tax number is supplied, the cart is updated.



Returned Object

The update script returns an object with the following properties.

availablePostage

Returns an Array of available Postage options.

channelCurrency

The ISO code of currency of the channel at the point of instantiation e.g. GBP or USD.

code

200 if the request was successful, or 400 if the request was bad.

coupon

If the cart contains a discount coupon, the Discount object is returned.
else Null.

created

The date the cart was created on.

currency

The currency ISO code for the Cart object.

discount

The total discount applied to the cart, either net or gross depending on the taxRule.

errors

If you send your request with one or more of the accepted parameters and the value passed through is invalid, then an array of errors will be returned.

fragment

If you specify a fragment parameter a fragment property will be available containing the rendered partial. This is an ideal way of quickly building HTML from your Ajax queries using the Theme engine rather than through JavaScript. Note that the fragment parameter supplied must be a legitimate cart partial/include. The cart is supplied to the fragment file as a fully qualified Cart Object within a cart variable.

hasCutOff

Returns true if the cart's postage option has a cut off time less than the current time. This allows us to show the postage's cut-off message to the visitor.

hasDiscount

Returns true if the cart has any discounts applied.

id

The system ID for the cart.

includesTax

Returns true if the cart's taxRule is set to includingTax, else false.

isCustomShipping

Returns true if an administrator has applied custom shipping costs to a cart or order.

isPurchasable

Returns true if a customer/visitor is able to purchase the Cart contents online, else false - the user may enquire online if the facility is available.

isRecurring

Returns true if the cart contains a product which is of type 'Subscription'.

isTaxExempt

Returns true if the cart has a valid taxNumber.

isTaxExemptable

Returns true if a customer may enter a VAT number for tax exemption.

lines

An array item for each cart line is built up containing the properties of the CartLine object.

postageMethod

The name of the postage method.

shipping

The total cost of shipping either net or gross depending on the taxRule.

source

The original source of where the cart was instantiated. This property is important in segmenting order activity by:

  • website
  • telesales
subtotal

The subtotal of all lines in the cart excluding shipping and before discount. The subtotal will be either net or gross depending on the taxRule.

tax

The total tax levied on the cart.

taxNumber

Goods shipped within the EC, but outside the European merchant's own country may allow their customer to provide a valid VAT number. The tax registration number is stored with the order.

taxNumberVerified

Returns true if the VAT number provided by the customer was verified.
False if not.

taxRule

The tax rule for the cart may be:

  • includingTax
  • excludingTax

European based consumer sites generally have a taxRule of includingTax, whilst trade or US websites prefer excludingTax rules.

Note: the taxRule is independent of whether the merchant charges tax on sales. So a merchant in the United Kingdom who is not yet VAT registered may still have a tax rule of includingTax, despite no levy.

total

The gross total for the cart.

weight

The gross shipping weight of the cart in kg.