This section describes DetailedItemPriceInfo
objects, including how DetailedItemPriceInfo
objects relate to each other and to their ItemPriceInfo
.
It is easiest to understand DetailedItemPriceInfo
by comparing it to ItemPriceInfo
. The ItemPriceInfo
object describes the price for an entire CommerceItem
in an order. The amount
property of the ItemPriceInfo
is the final price for the given CommerceItem
. If part of the quantity of the CommerceItem
was discounted due to a promotion, this information is reflected in the ItemPriceInfo
. For example, if the order contains 10 shirts at $10.00 each, and there was a promotion “Buy 9 shirts, get 1 free” then the amount
property of the ItemPriceInfo
would be $90.00. The PricingAdjustments
in the ItemPriceInfo
would contain one PricingAdjustment
for the list price, and one for the promotion. For more information on the ItemPriceInfo
object, see the ItemPriceInfo section.
The DetailedItemPriceInfo
objects provide a much more detailed view of the price of an item. In the example above, there would be two DetailedItemPriceInfo
objects:
DetailedItemPriceInfo
object #1:quantity
: 9amount
: $90.00PricingAdjustment
: set to the list price.
DetailedItemPriceInfo
object #2:quantity
: 1amount
: $0.00PricingAdjustment
: There would be twoPricingAdjustments
. One with the list price, and one with the promotion that caused the item to be free.
Another feature of DetailedItemPriceInfo
is the range
property. Instead of a detail referring to “5 items” it is more specific and refers to “the first 5 items” or “items 2-6”. This is used for two reasons:
To split the details of items in different shipping groups. There is a
range
property inShippingGroupCommerceItemRelationship
.DetailedItemPriceInfo
objects cannot refer to items in more than one shipping group.During qualification of a promotion (the process of determining if a particular promotion applies to the order) we need to know which items have been looked at and which items have already qualified a promotion. For more information, see the Qualifier Class section.
The following statements are true for all CommerceItem
objects:
Each
CommerceItem
has exactly oneItemPriceInfo
.The price of a particular item (if there are 10 shirts, the first shirt, or the second shirt, etc.) is described by exactly one detail.
Each
DetailedItemPriceInfo
in theItemPriceInfo
describes the price of a quantity of items that are all priced in exactly the same way. (The same list price, the same sale price, and the same promotions.)All the items described by a
DetailedItemPriceInfo
are in the same shipping group.
To make sure all of the above statements are true, each ItemPricingCalculator
has the responsibility of manipulating the DetailedItemPriceInfos
correctly.
The following sections describe how the three different types of item calculators interact with DetailedItemPriceInfos
:
Using List Price Calculators with DetailedItemPriceInfo Objects
The list price calculators are responsible for calculating the price based on the list price. They can usually look up a list price and multiply it by the quantity. If the entire quantity of the item is being shipped to the same place, there will only need to be one DetailedItemPriceInfo
. The logic for making sure that each detail only refers to items in one shipping group is contained in this method: pricingTools.detailedItemPriceTools.createInitialDetailedItemPriceInfos
.
This method takes the following parameters:
TotalPrice
- The total price for which the newDetailedItemPriceInfo
objects must account.TotalPrice
is the price of the entireCommerceItem
(listPrice
*quantity
).PriceQuote
- The current working price of theItem
.PriceQuote
is theItemPriceInfo
to which the newly created details will be added.Item - The
CommerceItem
being priced. This is needed to get to theShippingGroupCommerceItemRelationships
.PricingModel
- The discount that will be set in thePricingAdjustment
(usually null).Profile
- The person for whom the items are to be discounted (currently ignored).Locale
- The locale in which the items are to be discounted (currently ignored).ExtraParameters
- Any extra information that this method might need to set the number of the qualifying item (currently ignored).AdjustmentDescription
- The adjustment description used when creating all newPricingAdjustments
that is added to each new detail.
These parameters are the only parameters required to perform list pricing and bulk pricing. The entire quantity gets the same price. To facilitate tiered pricing, there is another version of this method that also takes a Range
argument. This means that new details will only be created for the given range. In this case, the TotalPrice
is the price for the range as opposed to the entire CommerceItem
. The ItemTieredPriceCalculator
will call this method once per tier.
This method will only modify the DetailedItemPriceInfo
objects. It is the responsibility of the caller to update the ItemPriceInfo
.
Using Sale Price Calculators with DetailedItemPriceInfo Objects
The calculators responsible for calculating the sale price usually change the price of the entire quantity. The calculator retrieves the sale price, subtracts the list price, and then modifies the amount accordingly.
This functionality is contained in a centralized method: pricingTools.detailedItemPriceTools.assignSalePriceToDetails
. The assignSalePriceToDetails
method takes the following parameters:
DetailedItemPriceInfos
- The list ofDetailedItemPriceInfo
objects that should be adjusted. This will usually be the entire list of details.UnitSalePrice
- The sale price for a single givenCommerceItem
. The total adjustment for each detail is this amount times the quantity of the detail.PriceQuote
- The current working price ofItem
. This is taken from theItemPriceInfo
to which the newly created details will be added. This is also ignored.Item
-CommerceItem
being priced. This is ignored in the default implementation.PricingModel
- The discount that will be set in thePricingAdjustment
(usually null).Profile
- The person for whom the items are to be discounted (currently ignored).Locale
- The locale in which the items are to be discounted (currently ignored).ExtraParameters
- Any extra information that this method might need to set the prices of a number of the qualifying item(currently ignored).AdjustmentDescription
- This is the adjustment description used when creating all newPricingAdjustments
.
The assignSalePriceToDetails
method walks through each detail and adjusts the amount accordingly. There is no reason to create any new details. This method will only modify the DetailedItemPriceInfo
objects. It is the responsibility of the caller to update the ItemPriceInfo
objects.
One sale calculator that does not use this method is the ItemSalesTieredPriceCalculator
. This calculator splits the details since each quantity of the item will not necessarily get the same unit sale price. Therefore it usually splits each detail to maintain the property that each item in a detail was priced in exactly the same way (this includes having the same unit sale price).
Using Item Discount Calculators with DetailedItemPriceInfo Objects
The calculators that are responsible for discounting the price based on a promotion usually only adjust the price for some subset of the quantity. Therefore, the ItemDiscountCalculator
frequently splits details. The ItemDiscountCalculator
determines the range that is undiscounted vs. the range that is discounted. It creates a new DetailedItemPriceInfo
for the undiscounted portion and set its quantity to the number of undiscounted items. It modifies the current detail to be discounted and changes its price. Then, with each detail, it calls pricingTools.detailedItemPriceTools.splitDetailsAccordingtoRanges
.
This method takes the following parameters:
Detail
—TheDetailedItemPriceInfo
to split apart.Ranges
—The list of Ranges that should have aDetailedItemPriceInfo
. The size of these must equal the quantity ofDetail
.
This method takes the current detail and creates enough new details so that there is one per Range that is passed in. All the details are returned.