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:
Obtain a coupon code.
Try to claim the coupon from the
ClaimableRepository
.Note that coupon codes are case-sensitive. For example,
COUP100
andcoup100
are two different coupon codes.Add the resulting promotion to the
activePromotions
list in the user profile.
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="http://www.atg.com/dsp.tld" prefix="dsp" %> <dsp:page> <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" type="text"/> <dsp:input bean="CouponFormHandler.claimCoupon" type="submit"/> </dsp:form> </dsp:page>
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:
The order meets the requirements of the promotion
The promotion has not expired
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" sub-type-value="PromotionClaimable"> <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"/> </table> </item-descriptor>
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 coupon.id
. 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="coupon.id">no value</dsp:valueof> </dsp:oparam> <dsp:oparam name="error"> </dsp:oparam> </dsp:droplet>
You could include the CouponDroplet
in a targeted e-mail JSP, thereby creating a coupon code that is ready to send to a customer.