Cart resource - browsing and updating a shopping cart

This resource allows you to retrieve the contents of a shopping cart, add one or more items to a shopping cart, update an entire shopping cart contents in one go (replace the cart), or empty the cart.

Retrieving cart contents

Issue a GET request to /API/V3/Cart/. You can optionally pass a cart name (by default it will use the default cart main) - e.g. /API/V3/Cart/secondary will retrieve the shopping cart called secondary.

Keep in mind you will need to pass your session token (as retrieved from the ResultSet node of your last call) as e.g. ?_session_token=5ybb8je8aM8QNRy. See the API session documentation for more information.

Retrieving list of all available countries

If you would like the result to include a list of all available countries that the merchant ships to, pass countries=1 as a querystring parameter - e.g. /API/V3/Cart?countries=1&_session_token=xyz.

The selected country (or default if none) for the current session will have the selected=1 attribute.

Expected result

The expected result will look something like this (comments added for explanation of data):

<ResultSet session="5ybb8je8aM8QNRy" totalItems="2" totalQuantity="3" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://mydomain.nz/API/V3/Cart.xsd">
    <Cart href="https://mydomain.nz/API/V3/Cart/main" id="Ecommerce::Cart::main">
        <CartItem href="https://mydomain.nz/API/V3/CartItem/NlE438vaQEOOSq4UD5tkjA" id="Ecommerce::CartItem::NlE438vaQEOOSq4UD5tkjA">
            <sku>10412</sku>
            <title>Green Tshirt</title>
            <description></description>
            <thumb>green-tshirt.png</thumb>
            <image>green-tshirt.png</image>

            <!-- prices generally have a numeric and a `*_formatted` version which includes currency symbol -->
            <price>22.00</price>
            <price_formatted>$22.00</price_formatted>
            <quantity>1</quantity>
            <subtotal>22.00</subtotal>
            <subtotal_formatted>$22.00</subtotal_formatted>
        </CartItem>
        <CartItem href="https://mydomain.nz/API/V3/CartItem/C-7f5YZ9TFWfhOMmD4oQ5Q" id="Ecommerce::CartItem::C-7f5YZ9TFWfhOMmD4oQ5Q">
            <sku>10442</sku>
            <title>Long Pants</title>

            <!--
                Additional description information where required.
                  - If this product has options are selected, a string representing the selected options.
                  - If this product has advanced options, the "subproduct" description
            -->
            <description>Size: Small, Colour: Blue</description>

            <thumb>long-pants.jpg</thumb>
            <image>long-pants.jpg</image>

            <!--
                Options for this product. Each option wrapped in <option> and contains:
                  - group - the identifier for this option
                  - group_label - the output ready name of this option
                  - value - the selected option value
                  - label - the output ready label of the selected value
            -->
            <option>
                <group>size</group>
                <group_label>Size</group>
                <value>sm</sm>
                <label>Small</label>
            </option>
            <option>
                <group>colour</group>
                <group_label>Colour</group_label>
                <value>blue</value>
                <label>Blue</label>
            </option>

            <price>15.00</price>
            <price_formatted>$15.00</price_formatted>
            <quantity>2</quantity>
            <subtotal>30.00</subtotal>
            <subtotal_formatted>$30.00</subtotal_formatted>
        </CartItem>

        <!-- name of the cart (usually main) -->
        <name>main</name>

        <!-- subtotal - total of the order lines -->
        <subtotal>52.00</subtotal>
        <subtotal_formatted>$52.00</subtotal_formatted>

        <!-- if this site has sales tax configured, the amount of tax -->
        <tax>7.80</tax>
        <tax_formatted>$7.80</tax_formatted>

        <delivery>

            <!-- numeric & formatted delivery cost for this cart -->
            <cost>22.00</cost>
            <cost_formatted>$22.00</cost_formatted>

            <!--
                valid delivery modes for the current country - including:
                  - mode - the identifier for this mode - this gets passed as `delivery=$mode` to update to this mode
                  - description - output ready name of the delivery mode
                  - cost - numeric cost if this mode was selected with the current cart
                  - cost_formatted - cost ready for output with currency symbol
            -->
            <option>
                <cost>4.00</cost>
                <cost_formatted>$4.00</cost_formatted>
                <description>North Island</description>
                <message></message>
                <mode>NZPostNorthIsland</mode>
            </option>

            <!-- selected="1" indicates the current mode -->
            <option selected="1">
                <cost>12.00</cost>
                <cost_formatted>$12.00</cost_formatted>
                <description>South Island</description>
                <message></message>
                <mode>NZPostSouthIsland</mode>
            </option>

            <!-- current selected country -->
            <country>NZ</country>

            <!-- if countries were requested -->
            <countries>
                <country code="GL" name="Greenland" />
                <country code="DJ" name="Djibouti" />
                <country code="JM" name="Jamaica" />
                <country code="PG" name="Papua New Guinea" />
                <country code="AT" name="Austria" />
                <country code="NZ" name="New Zealand" selected="1" />
                <!-- etc -->
            </countries>
        </delivery>

        <!-- total cost of the order including all costs -->
        <total>81.80</total>
        <total_formatted>$81.80</total_formatted>
    </Cart>
</ResultSet>

Adding item(s) to the cart

If you POST xml containing CartItem nodes to this resource, they will be added to the specified cart (default main).

The only required node within each CartItem is sku - the item sku to be added. Other supported nodes include:

  • quantity - how many to add. Defaults to 1.

Aside from the options specific nodes below, the rest of the data received from a GET request is read only.

After adding an item to the cart, the new cart data will be returned.

Simple options

If the product supports simple options, you can pass:

  • options - one or more option settings each node should contain option settings e.g. <size>s</size> will assume this product has an option set up with a code of size with a value code available for s.

Advanced options / Subproducts

If the product supports advanced options or subproducts, set:

  • code - set this to the variant / subproduct code

Example

If you POST xml to this resource, the specified items will be added to the cart. If the contents match any item already in the cart, the existing item will have its quantity increased instead of adding a whole new line.

Note the Cart node is optional. You can optionally have your CartItem nodes directly within the root node.

<ResultSet xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://mydomain.nz/API/V3/Cart.xsd">
    <Cart>
        <CartItem>
            <sku>10412</sku>
        </CartItem>
        <CartItem>
            <sku>10442</sku>
            <options>
                <size>s</size>
                <colour>blue</colour>
            </options>
            <quantity>2</quantity>
        </CartItem>
        <CartItem>
            <sku>11122</sku>
            <code>11122-41</code>
        </CartItem>
    </Cart>
</ResultSet>

Changing selected delivery method

You can update the selected delivery method as a part of any POST or PUT request by adding delivery=$mode arguments to the querystring.

If changing the delivery method, posting an xml payload to add items / override the cart at the same is optional.

After changing delivery method, the new cart data will be returned, including updated delivery costs and totals.

Changing selected delivery country

You can update the selected delivery country as a part of any POST or PUT request by adding country=$code (where $code is the country code) arguments to the querystring.

If changing the country, posting an xml payload to add items / override the cart at the same is optional. You can also pass any other supported querystring parameters to update multiple areas at once.

If you do not specify a delivery mode at the same time, if the currently selected delivery mode is no longer valid for the new country, the default mode for that country will be returned / used.

After changing delivery country, the new cart data will be returned, including updated delivery costs and totals.

Updating the cart

If you PUT xml to this resource, the entire contents of the cart will be replaced with the passed XML. The same nodes as adding items to the cart are supported.

After updating the cart contents, the API will return the new cart contents - same structure as a GET. Take note that the ids of any CartItem nodes will have updated.

Example

PUT to https://mydomain.nz/API/V3/Cart/ will replace the contents of the main cart with the items outlined in the POSTed XML:

<ResultSet xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://mydomain.nz/API/V3/Cart.xsd">
    <Cart>
        <CartItem>
            <sku>10412</sku>
        </CartItem>
        <CartItem>
            <sku>10442</sku>
            <options>
                <size>s</size>
                <colour>blue</colour>
            </options>
            <quantity>2</quantity>
        </CartItem>
        <CartItem>
            <sku>11122</sku>
            <code>11122-41</code>
        </CartItem>
    </Cart>
</ResultSet>

Clearing the cart

Issuing a DELETE to the resource will empty the entire cart. For example: - DELETE https://mydomain.nz/API/V3/Cart/?_session_token=$token will empty the primary cart. - DELETE https://mydomain.nz/API/V3/Cart/foo?_session_token=$token will empty a cart called foo.