CartItem

This object represents a an item currently in the shopping cart.

Why two items? Item and CartItem are mostly the same, but CartItem contains pricing information relative to the cart. For example, coupons added to the cart could affect the price of an item, etc. So you want to an Item object to display an item on a product page or list, and use the CartItem when displaying an item contained in a cart. This shouldn't be a real issue, as the CartItem objects are only found with the items array property of the Cart itself.

currency fields, such as unitCost, will have two other fields, a Localized and LocalizedFormatted field. The Localized Field is the amount in the cart currency, which may differ from the base currency of the item. The LocalizedFormatted field is the amount in the cart currency, and formatted for that currency with proper symbols, commas, and decimal places. *You should almost always be using the Localized and LocalizedFormatted fields so that your shopping cart can handle multiple currencies.

All "Localized" and "LocalizedFormatted" fields are available to the REST API only. They are not present in the older APIs.

Field	Type	Description	Comments
itemId	string	Item ID

arbitraryUnitCost arbitraryUnitCostLocalized arbitraryUnitCostLocalizedFormatted	number number string	Arbitrary unit cost (~~not functional at this time~~) (works with the REST API)
attributes	CartItemAttribute	Attributes configured on the item
autoOrderSchedule	string	Schedule to put this auto orderable item on (only applicable if the item is configured for customer selected auto order)
defaultImageUrl	string	The full url for the item's default image.	Added June 2011, available to versions 1.1+
defaultImageSsl	string	The full url for hte item's default image with an https:// protocol
defaultThumbnailUrl	string	The full url for the item's default thumbnail.	Added June 2011, available to versions 1.1+
defaultThumbnailSsl	string	The full url for the item's default thumbnail with an https:// protocol
description	string	Description
discount discountLocalized discountLocalizedFormatted	number number string	The discount this item is receiving, be it from a combination of products purchased, coupons, whatever.
extendedDescription	string	Extended description
height	Distance	Height of the item
itemOid	integer	A unique item object identifier. This is provided to easy debugging with UltraCart premium support. Note, this uniquely identifies an item, but a single item may appear more than once in a cart. So it is NOT guaranteed to be unique within a cart.
kit	boolean	True if this item is a kit
kitComponentOptions	CartKitComponentOption	Kit component options that the customer needs to provide
length	Distance	Length of the item
manufacturerSuggestedRetailPrice manufacturerSuggestedRetailPriceLocalized manufacturerSuggestedRetailPriceLocalizedFormatted	number number string	The MSRP of the item.
maximumQuantity	number	The maximum quantity of this item a customer can purchase.
minimumQuantity	number	The minimum quantity of this item the customer must purchase.
multimedias	CartItemMultimedia	Multimedia objects available for this item.
options	CartItemOption[ ]	Options on the item that customer needs to provide
position	number	A zero based counter that is simply a number associated with each item in the cart. It feigns uniqueness.	Only available to REST API
preorder	boolean	True if the item is on pre-order. If any of your items are on pre-order your checkout should not allow PayPal or Amazon Payments as a payment option.
quantity	number	Quantity
schedules	string[ ]	If the cart item is configured for auto orders, this array will contain all of the possible re-order frequencies the customer may choose. These should be displayed to the customer in a select box allowing them to decide.
totalCost totalCostLocalized totalCostLocalizedFormatted	number number string	unit cost * quantity the main purpose this field was added was to allow multi-currency carts to display the total cost in a formatted manner without having to do currency conversions.
totalCostWithDiscount totalCostWithDiscountLocalized totalCostWithDiscountLocalizedFormatted	number number string	unit cost * quantity with discounts figured into the price. the main purpose this field was added was to allow multi-currency carts to display the discounted total cost in a formatted manner without having to do currency conversions.
unitCost unitCostLocalized unitCostLocalizedFormatted	number number number	Unit cost of item
unitCostWithDiscount unitCostWithDiscountLocalized unitCostWithDiscountLocalizedFormatted	number number string	Unit cost of item after discounts (because of a coupon or mix and match groups)
upsell	boolean	True if this item was added to the cart as part of an upsell
variations	Associative Array (Hash) key=string, value=string	A hashmap of variations. This is only populated when passing a CartItem to addItems or updateItems. It is never populated on cart.items. See discussion below.	Added Oct 2011, available to versions 2.0.9+
weight	Weight	Weight of the item
width	Distance	Width of the item

A note about variations. The variations property above is not an array of ItemVariations. It is a simple hash map of name=value for each variation. It is only populated by the client and passed to addItems or updateItems (legacy) or when the cart is passed to the REST POST to /rest/cart. Here's why: When a item is passed in with variations(s), ultracart uses the variations to look up the child item, and that item id is used in place of the provided item id. For example, in the online variations example, The item 'SHIRT' is passed in with variations (Size=Large,Color=Black). The actual item added to the cart is 'SHIRT_BLACK_LARGE'. That item doesn't have any variations attached to it, only it's parent item. So if I example the cart.items array and look at the newly added object, item.variations will be empty.

For the rest, a new item with variations will look like this (h/t to russel at augimo):

cart.items.push({itemId:'example',quantity:1,variations:{color:'Blue',flavor:'Vanilla'}});

The reason why a simple hash map is used instead of a list of ItemVariation objects is because a CartItem contains choices made, while an Item object contains available choices. The former represents a selected product, the latter is made for product displays.