ART#307 - What is CommerceItem in ATG? Why is it used?



On a very abstract level, a commerceItem is an item-descriptor in OrderRepository [backed by a Java Bean], which is used to represent a live item in the cart.
This seems confusing! If we have Products and SKUs already on a website, why do we need a commerceItem to represent a live item? Also, what is live-item?

Let us discuss these in detail?

What is the need of a CommerceItem?

1. For each product we intend to add to cart, we define inventory of a SKU in InventoryRepository, we define Price of a SKU in 
PriceLists repository, and then we add the item to cart. 

2. Now, what happens behind the scenes, is that ATG creates an item of type "commerceItem" [which is an item-descriptor of OrderRepository].

3. This repository-item is put into a Java Object of type atg.commerce.order.CommerceItem. (We can typecast the "commerceItem" repository-item into "CommerceItem")

4. Now, this repository-item contains all the information about the Product and SKU you added to cart, including the references to the Product and Sku item respectively.

ATG takes all of this pain because of many reasons. There are many logical and technical reasons for this, but for the sake of simplicity, here is an example.

When a commerceItem is created, some important properties like quantity, skuId, productId etc. are put into this repository-item.

Now, if there are any item-level discounts, those are also stored in a commerceItem [discounts will apply ONLY when an item is present in cart].

Also, there might be many cases where a customer adds an item to cart and places an order, and later the price of that SKU changes. When the user comes back to your site and sees his order history, he will see the price at which HE PURCHASED the product, and not the new price of the SKU. These old prices are also stored in a commerceItem.
Hence, in a slang perspective, i call the commerceItem a live-item, because it is added in cart.
This is the main difference between a SKU/Product and a CommerceItem. A commerce-item is used to store live-data of a product/SKU combination at a particular time.

Structure of a CommerceItem?

Here is a basic structure of commerceItem. Below diagram shows some important properties of commerceItem. Please note that not ALL properties as specified because of simplicity (nobody mugs up or asks about these properties anyway).

Lets briefly have a look at these properties and methods:


1. catalogRefId: This stores the SKU-ID of the sku you have added to cart.

2. productId: This stores the parent product id of the sku you have added to cart.

3. quantity: Quantity of above SKU you have added to cart.

4. type: This would be the string "default" as we specified while we were adding the item to cart.

5. priceInfo: This contains an object of type "ItemPriceInfo" which is backed by the Repository Item "itemPriceInfo" present in the OrderRepository. This stores the prices (sale price, list price etc.) at which the item was added to cart. This also contains details of any promotions that you might've applied on this item.

6. order: Contains the reference to the repository-item "order" from the OrderRepository.


1. getAuxiliaryData(): This method is usually an important one. This method contains an object of type AuxiliaryData() which contains the reference to product and sku items you added to cart.

This method can be used somewhat like: 

String productId = commerceItem.getAuxiliaryData().getProductId();


RepositoryItem product = (RepositoryItem)commerceItem.getAuxiliaryData().getProductRef();


RepositoryItem sku= (RepositoryItem)commerceItem.getAuxiliaryData().getCatalogRef();

Once you get these items, you can do other operations or find more data (if required) from the SKU/PRODUCT item.

2. getRepositoryItem(): Returns the repository-item corresponding to this class.

3. getPropertyValue(): If the class CommerceItemImpl, does not have a method for a property you want to fetch, you can use the getPropertyValue() method and pass the property-name to get the value. This will return the value as an "Object", therefore you might have to typecast the returned object to use.

4. setPropertyValue(): You can also set the properties of commerceItem using this method. Pass the property-name and the property-value to set any property of commerceItem.

5. getPriceInfo(): Returns the object of type ItemPriceInfo, which contains various details corresponding to the pricing and promotions applied to this item.

Now that we know, what is a commerceItem and why we use it, let us understand HOW AND WHY to customize commerceItems.




  1. How can i get a Repository Item of ItemPriceInfo for an order that is not Submitted

  2. Very Nice post to Understand ATG
    Ca you please update regarding Pipelines



Get All The Latest Updates Delivered Straight Into Your Inbox For Free!