ATG Commerce treats coupons as a type of promotion that customers can claim. The customer types in a specific code, and the system adds the corresponding promotion to the customer’s profile. Most of the code for handling coupons is included in the ClaimableManager component and the standard promotion architecture, with a FormHandler to connect these two systems. The process for handling a coupon is as follows:

Use the /atg/commerce/promotion/CouponFormHandler component to obtain a coupon code and add it to a customer’s list of promotions in the customer’s activePromotions profile property. Create an input field on an appropriate site page (for example, a Checkout page) and hook it up to the couponClaimCode property of the CouponFormHandler component. Then, have the form submit to the handleClaimCoupon method of the form handler. This method uses the ClaimableManager component to attempt to get a coupon from the Claimable repository. Then it extracts the promotion from the coupon and uses the PromotionTools component to place the promotion into the customer’s user profile.

The following example shows the JSP code for using the CouponFormHandler component:

<%@ taglib uri="" prefix="dsp" %>

<dsp:form method="post">
<!-- Where to go to on success or failure -->
<dsp:input bean="CouponFormHandler.claimCouponSuccessURL"
value="CouponClaim.jsp" type="hidden"/>
<dsp:input bean="CouponFormHandler.claimCouponSuccessURL"
value="CouponClaim.jsp" type="hidden"/>

<!-- Get the coupon claim code -->
Coupon code: <dsp:input bean="CouponFormHandler.couponClaimCode"
<dsp:input bean="CouponFormHandler.claimCoupon" type="submit"/>


When a user enters a coupon code on a Checkout page, ATG Commerce checks that the coupon is active and the promotion associated with it is not expired. If both conditions are met, the user “claims” the coupon, which means that the promotion is added to the user’s activePromotions profile property. During order pricing, ATG Commerce determines whether the order qualifies for the coupon’s promotion by checking that:

This double-checking capability ensures that if a user claims a coupon as part of one order, discontinues that order, then creates a second one, the promotion applies to the second order, as long as the promotion is active and applicable.

A promotion given by a coupon persists on the user profile, not as part of the order. A claimed coupon is automatically applied to any order to which it qualifies; there’s no need to claim a coupon twice. You can persist a coupon code with an order by adding a new property to the Order object and storing the coupon code in the new property. For information on how to extend the commerce object hierarchy to include a new property, refer to Extending the Purchase Process in the Customizing Purchase Process Externals chapter.

The other step to consider when you set up coupons is to make sure that there are coupons in the Claimable repository for a customer to claim. The following example shows the default item-descriptor for coupons:

<!-- Promotion Claimable object -->
<item-descriptor name="PromotionClaimable" super-type="claimable"
 <table name="dcspp_coupon" type="auxiliary" id-column-name="coupon_id">
    <property name="promotion" column-name="promotion_id"
item-type="promotion" repository="/atg/commerce/pricing/Promotions"/>

The coupon item-descriptor is defined in /atg/commerce/claimable/claimableRepository.xml, which is located in a .jar file at <ATG9dir>/DCS/config/config.jar. The item-descriptor defines a claim code ID and a link to a promotion object in the Promotions repository. If your Web site requires multiple types of coupons, you can define additional item-descriptor types by editing the claimableRepository.xml file and then specifying the valid coupon types in the validCouponItemTypes property in the CouponFormHandler properties file. When a coupon is claimed, the CouponFormHandler.checkPromotionType method checks the item type of the coupon corresponding to the given claim code against the array of acceptable item types in the CouponFormHandler.validCouponItemTypes property.

You can populate the Claimable repository through either the ATG Control Center or the atg.commerce.promotion.CouponDroplet. The CouponDroplet servlet bean takes either a promotion or promotion ID and then generates a coupon for it in the repository. The value of the output parameter in the CouponDroplet is the coupon object. You can obtain the claim code for the coupon using The following example shows the JSP code for the CouponDroplet:

<dsp:importbean bean="/atg/commerce/promotion/CouponDroplet"/>
<h2>here is a coupon that was created: </h2>
<dsp:droplet name="CouponDroplet">
<dsp:param value="promo60001" name="promoId"/>
<dsp:oparam name="output">
  <dsp:valueof param="">no value</dsp:valueof>
<dsp:oparam name="error">

You could include the CouponDroplet in a targeted e-mail JSP, thereby creating a coupon code that is ready to send to a customer.

loading table of contents...