ATG Commerce Programming Guide

These classes are used by the ATG Commerce item, order, tax, and shipping pricing engines to calculate prices. They can be extended according to your pricing needs.

DiscountCalculatorService

The atg.commerce.pricing.DiscountCalculatorService class is an extension of GenericService. DiscountCalculatorService computes a price based on the type of discount, the discount amount, and the current price. It holds information common to all the discount calculators, which can extend this class to eliminate redundant configuration code.

The adjust method can be used as a quick way to apply a discount. It calculates a price based on an existing price, the discount type, and the discount amount. This functionality is used by all discount calculators.

The following list describes important properties in the DiscountCalculatorService class:

ItemPriceCalculator

The abstract class atg.commerce.pricing.ItemPriceCalculator is the parent class for many item pricing calculators (for example, ItemListPriceCalculator and ItemSalePriceCalculator), consolidating the functionality that these calculators have in common. ItemPriceCalculator extends ApplicationLoggingImpl, so classes that extend it have access to Nucleus logging services.

This class determines a price for an object based on a pricesource object and the properties of that pricesource. It contains a single abstract method: priceItems. Extending classes implement this method to leverage the other item pricing functionality that this class provides.

The ItemPriceCalculator class also contains the following properties:

ItemPriceCalculator determines an item’s price based on a property value. The property value comes from a priceSource object. The priceSource object can be one of two objects, depending on the boolean value of the priceFromCatalogRef property.

The catalogRef property of items to be priced points to a SKU in the SKU catalog. The productRef property points to a product in the product catalog. For more information, see the atg.commerce.order.CommerceItem entry in the ATG API Reference.

The pricePropertyName in the ItemPriceCalculator (and therefore the ItemListPriceCalculator and ItemSalePriceCalculator, which extend ItemPriceCalculator) identifies the property on the priceSource object (the SKU or product) which contains the price for the current item. The ItemListPriceCalculator and ItemSalePriceCalculator read this value and return a price object that contains the price.

Examples of How Classes that Extend ItemPriceCalculator Determine Prices

The ItemListPriceCalculator extends ItemPriceCalculator. In this example, the ItemListPriceCalculator is set with the following properties:

In this example, the SKU catalog contains a SKU that identifies blue shorts. That SKU has the following properties:

When a CommerceItem is passed to the ItemListPriceCalculator, this particular Itemlistpricecalculator looks at the item’s catalogRef property (SKU) and retrieves the value of that object’s listPrice property (10.00). The ItemListPriceCalculator then modifies the input price to be 10.00 and returns it.

The ItemSalePriceCalculator works almost the same way. The ItemSalePriceCalculator has an additional property called onSalePropertyName, which is a boolean property on the priceSource object that indicates whether the item is on sale.

In this example, the priceFromCatalogRef property of ItemSalePriceCalculator is set to true. The pricePropertyName property is set to salePrice. A SKU in the SKU catalog has a property called onSale. If a SKU were on sale, the onSale property would be set to true. The onSalePropertyName property of ItemSalePriceCalculator is set to onSale.

When an item is passed to the ItemSalePriceCalculator, it has a catalogRef property that points to a SKU from the SKU catalog.

When the ItemSalePriceCalculator receives this item, it uses the value of the SKU’s onSale property to determine if it’s on sale. In this example, the value is true, indicating that the SKU is on sale. The calculator then gets the sale price using the SKU’s salePrice property. The price in this case is 7.00. The calculator then modifies the input price for the item to be 7.00 and registers that a change has been made to the price. This registering is done by creating a new PricingAdjustment and adding it to the adjustments property of the price object, which in this case is an ItemPriceInfo. The adjustment would be -3.00, and it would show that the ItemSalePriceCalculator was responsible for the change.

ItemDiscountCalculator

The atg.commerce.pricing.ItemDiscountCalculator class calculates the new price for an item or items based on a given pricing model. It applies the discount that the pricing model describes to the price in the ItemPriceInfo corresponding to each passed CommerceItem. The discount can be a fixed amount, a percentage, or a fixed price.

The ItemDiscountCalculator class performs this discounting by consulting the Qualifier service for a list of items that should receive the input discount. It calls Qualifier.findQualifyingItems to get this list.

The ItemDiscountCalculator inherits all the properties of DiscountCalculatorService. For more information on the default implementation of this class, refer to the Default Item Discount Calculator section.

ItemDiscountMultiplierCalculator

The atg.commerce.pricing.ItemDiscountMultiplierCalculator class adjusts the amount of a discount by factor N, where N is the adjuster amount defined in a PricingModel. For example, if an item originally costs $20, and $5 is taken off the price, the new price is $15. The ItemDiscountMultiplierCalculator takes this discount amount and multiplies it by the number N. If the number N is 2, the new discount amount would be $10 and the new price would also be $10. This calculator could be used to create promotions such as “Double Coupon Days.”

The parent class, ItemDiscountCalculator, is used to determine which items qualify for getting a double discount. Then the overridden adjust method defined in this class determines the new adjustment.

For more information on the default implementation of this class, refer to the Default Item Discount Multiplier Calculator section.

ItemListPriceCalculator

The atg.commerce.pricing.ItemListPriceCalculator class is a calculator that determines the list price of an item and sets the itemPriceInfo to that amount. This class extends the ItemPriceCalculator. The list price is determined based on the value returned from the getPriceSource property. This is typically the first in a series of calculations, with this calculator providing a starting price for other calculators. The ItemListPriceCalculator sets the listPrice property of the input price object to the input Price.

The ItemPriceCalculator section includes an example of how the ItemListPriceCalculator determines a price.

ItemSalePriceCalculator

The atg.commerce.pricing.ItemSalePriceCalculator class extends the ItemPriceCalculator. It determines the sale price of an item and discounts the itemPriceInfo to that amount. This class also maintains the audit trail of the ItemPriceInfo. There is no rule associated with this calculator. If one of the pricing methods of ItemSalePriceCalculator is invoked, all input items are discounted to the sale price.

The ItemSalePriceCalculator class also contains the following property:

The ItemPriceCalculator section includes an example of how the ItemSalePriceCalculator determines a price.

ConfigurableItemPriceCalculator

The atg.commerce.pricing.ConfigurableItemPriceCalculator class extends the ItemPriceCalculator. It calculates the list price of a configurable item and sets the itemPriceInfo to that amount. It computes the price of the configurable item by adding up the price of all the individual subSKUs and the price of the configurable SKU. This sets the list price with the prices of the subSKUs that are configured in the configurable item. If the configurable item is on sale then the sale price will also be modified.

OrderDiscountCalculator

The atg.commerce.pricing.OrderDiscountCalculator class implements the OrderPricingCalculator. It calculates OrderPriceInfo values for orders when the calculator is invoked. This calculator consults the Qualifer service, looking for the order to be priced by calling Qualifier.findQualifyingOrder. If it gets back an order, an OrderPriceInfo is computed based on the input PricingModel (RepositoryItem).

For more information on the default implementation of this class, refer to the Default Order Discount Calculator section.

OrderSubtotalCalculator

The atg.commerce.pricing.OrderSubtotalCalculator class computes the rawSubtotal and amount of an OrderPriceInfo that corresponds to the input order. Unlike in the case of discount calculators, there is no rule that determines whether the subtotal should be calculated. The order’s subtotal is always calculated by summing the prices of the items in the order. If a pricing model is passed in, it is ignored.

ShippingCalculatorImpl

The atg.commerce.pricing.ShippingCalculatorImpl class is an abstract class that acts as a starting point for general price calculation in shipping groups. The implementation of priceShippingGroup checks that there are items in the shipping group. If there are no items, the price quote is reset to zero. If there are items to price for shipping, the performPricing method confirms that the items in the group should be priced. For example, soft goods, such as gift certificates, should not be priced for shipping.

When extending this class, implement the getAmount method as the base shipping cost in this calculator.

The amount returned is set into the ShippingPriceInfo. If the addAmount property is true, the amount returned is added to the current ShippingPriceInfo amount. This behavior allows for the addition of surcharges.

Set the shippingMethod property to the name of a particular delivery process that your site offers, for example UPS Ground, UPS 2-day or UPS Next Day. If the ignoreShippingMethod property is true, then the calculator does not expose a shipping method name (through getAvailableMethods). In addition, this calculator always attempts to perform pricing. This option is useful for situations in which you do not want to give customers a choice of different shipping methods.

ShippingDiscountCalculator

The atg.commerce.pricing.ShippingDiscountCalculator class calculates ShippingPriceInfos for specified ShippingGroups. This calculator consults the Qualifer service for the ShippingGroup to be priced. It calls Qualifier.findQualifyingShipping. If it gets back a ShippingGroup, it computes a ShippingPriceInfo based on the input PricingModel (RepositoryItem).

For more information on the default implementation of this class, refer to the Default Shipping Discount Calculator section.

PriceRangeShippingCalculator

The atg.commerce.pricing.PriceRangeShippingCalculator class determines the shipping price based on the subtotal of all the items in the shipping group. The service is configured through the ranges property. With the given array of price range configurations (format: low:high:price) the service parses the values into their double format for calculating shipping costs. For example:

ranges=00.00:15.99:4.50,\
        16.00:30.99:6.00,\
        31.00:40.99:7.25,\
        41.00:MAX_VALUE:10.00

Note: The keyword MAX_VALUE indicates the maximum possible value in the range.

The PriceRangeShippingCalculator also contains the following properties:

DoubleRangeShippingCalculator

This atg.commerce.pricing.DoubleRangeShippingCalculator class is an abstract shipping calculator that determines the shipping price by comparing a value from the ShippingGroup to a series of ranges. The service is configured through the ranges property. It is extended by the PriceRangeShippingCalculator, PropertyRangeShippingCalculator, and WeightRangeShippngCalculator classes.

With the given array of price range configurations (format: low:high:price), the service parses the values into their double format for calculating shipping costs. For example:

ranges=00.00:15.99:4.50,\
        16.00:30.99:6.00,\
        31.00:40.99:7.25,\
        41.00:MAX_VALUE:10.00

Note: The keyword MAX_VALUE indicates the maximum possible value in the range.

The DoubleRangeShippingCalculator also contains the following properties:

FixedPriceShippingCalculator

The atg.commerce.pricing.FixedPriceShippingCalculator class is a shipping calculator that sets the shipping amount to a fixed price.

The FixedPriceShippingCalculator also contains the following properties:

PropertyRangeShippingCalculator

The atg.commerce.pricing.PropertyRangeShippingCalculator class is a highly-flexible shipping calculator that identifies some item property and adds the value provided to each item in the shipping group together to create a shipping group total. The total falls into one of the ranges specified in the ranges property, which provides a shipping cost for each range.

For example, all items may have a property called weight that correlates to the weight of the item in pounds. To base shipping cost on the cumulative weight total, you set the PropertyRangeShippingCalculatorpropertyName property to weight. If your shipping group has 3 items, each of which has a weight of 1, ATG Commerce calculates a total of 3 and uses the ranges property to determine how much to charge. The range property takes the format of low:high:price and holds these options:

ranges=00.00:15.99:4.50,\
        16.00:30.99:6.00,\
        31.00:40.99:7.25,\
        41.00:MAX_VALUE:10.00

In this example, shipping charges total $4.50. Note that keyword MAX_VALUE indicates the maximum possible value in the range.

The PropertyRangeShippingCalculator also contains the following properties:

WeightRangeShippingCalculator

The atg.commerce.pricing.WeightRangeShippingCalculator class is a shipping calculator that determines the shipping price based on the sum of the weights of each item in a shipping group.

The service is configured through the ranges property. With the given array of price range configurations (format: low:high:price), the service parses the values into their double format for calculating shipping costs. For example:

ranges=00.00:15.99:4.50,\
       16.00:30.99:6.00,\
       31.00:40.99:7.25,\
       41.00:MAX_VALUE:10.00

Note: The keyword MAX_VALUE indicates the maximum possible value in the range.

The WeightRangeShippingCalculator also contains the following properties:

NoTaxCalculator

The atg.commerce.pricing.NoTaxCalculator class creates a new TaxPriceInfo object that specifies a tax price of zero for an order.

Price List ConfigurableItemPriceListCalculator

The ConfigurableItemPriceListCalculator calculator assumes the ItemListPriceCalculator has already run. ItemListPriceCalculator calculator sets the list price and the amount of the ItemPriceInfo based on the price of the ConfigurableSku. The ConfigurableItemPriceListCalculator calculator then iterates through the subSKUs and modifies the list price and amount accordingly.

For example, consider a situation when a parentSKU is $5, subSKU A is $2 and subSKU B is $1. If we buy two of this configurable SKU, then coming into this calculator the listPrice will be $5 and the amount will be $10. After the ConfigurableItemPriceListCalculator calculator runs the listPrice will be $8 and the amount will be $16.

The ConfigurableItemPriceListCalculator component is located in the ACC at atg/commerce/pricing/calculators/ConfigurableItemPriceListCalculator. For more information on this calculator. See the Price List Calculators section of the Using Price Lists section of this chapter.

Price List ItemListPriceCalculator

A calculator that determines the list price of an item and sets the itemPriceInfo to that amount. The pricing scheme for that item is list pricing.

The ItemListPriceCalculator component is located in the ACC at atg/commerce/pricing/calculators/ ItemListPriceCalculator. For more information on this calculator. See the Price List Calculators section of the Using Price Lists section of this chapter.

Price List ItemPriceCalculator

The ItemPriceCalculator class can either price a single commerce item or price a list of commerce items. It first selects the priceList to use based on the profilePriceListPropertyName property. The ItemPriceCalculator then delegates the pricing to different ItemSchemePriceCalculators based on the item’s pricing scheme by the pricingSchemePropertyName property.

The ItemPriceListCalculator component is located in the ACC at atg/commerce/pricing/calculators/ItemPriceListCalculator. It has the following properties:

For more information on this calculator. See the Price List Calculators section of the Using Price Lists section of this chapter.

Price List ItemSalesPriceCalculator

The ItemSalesPriceCalculator sets the sales price for a commerce item. The ItemSalesPriceCalculator implements the SalePriceListsListCalculator component, which is located in the ACC at atg/commerce/pricing/calculators/SalePriceListsListCalculator.

For more information on this calculator. See the Price List Calculators section of the Using Price Lists section of this chapter.

Price List ItemSalesTieredPriceCalculator

A calculator which determines the sales tiered price of an item and sets the itemPriceInfo to be that amount. The definition of tiered pricing can be referenced in ItemTieredPriceCalculator.

The ItemSalesTieredPriceCalculator implements the SalePriceListsTieredCalculator component, which is located in the ACC at atg/commerce/pricing/calculators/SalePriceListsTieredCalculator.

For more information on this calculator, see the Price List Calculators section of the Using Price Lists section of this chapter.

Price List ItemTieredPriceCalculator

The ItemTieredPriceCalculator determines the tiered price of an item and sets the itemPriceInfo to that amount. The pricing scheme for that item is tier pricing. For more information on tiered pricing, see the Using Price Lists section of this chapter.

The ItemTieredPriceCalculator implements the PriceListsTieredCalculator component, which is located in the ACC at atg/commerce/pricing/calculators/PriceListsTieredCalculator.

For more information on this calculator. See the Price List Calculators section of the Using Price Lists section of this chapter.