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.
Field | Type | Description | Comments |
|---|---|---|---|
itemId | string | Item ID |
|
arbitraryUnitCost | number | Arbitrary unit cost ( |
|
attributes | 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+ |
defaultThumbnailUrl | string | The full url for the item's default thumbnail. | Added June 2011, available to versions 1.1+ |
description | string | Description |
|
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. | Local currency fields only available to REST API |
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 Google Checkout as a payment option. | |
quantity | number | Quantity |
|
unitCost unitCostLocalized unitCostLocalizedFormatted | number number number | Unit cost of item | Localized currency fields only available to REST API |
unitCostWithDiscount | number | 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.