Gift certificates allow a customer to pay for all or part of a purchase using a prepaid amount. Processing a gift certificate involves the following steps:

The Purchase and Fulfillment Process for Gift Certificates

Set up gift certificates as items in your product catalog, adding separate SKUs for different amounts. For example, you could have two SKUs, one for a $50 dollar certificate and another for a $100 certificate. The value of the gift certificate is stored in the listPrice property of each gift certificate SKU in the product catalog.

Each SKU has a fulfiller property that defines an ElectronicFulfiller. When Customer A adds a gift certificate to his or her shopping cart, the fulfiller property tells the OrderFulfiller to route the purchase to the specified ElectronicFulfiller. The ElectronicFulfiller then creates the gift certificate in the Claimable repository (by means of the ClaimableManager component) and sends an e-mail to the recipient notifying him or her that a gift certificate has been purchased on his or her behalf and including the code to use for claiming it. Refer to the Configuring the Order Fulfillment Framework chapter for more information on the ElectronicFulfiller.

The following properties can be set when the gift certificate is created. The gift certificate is not functional unless the three required properties (identified below) are set.

Note: By default, the stock level of a gift certificate is set to -1 indicating that an infinite number of the item is available. Setting the stock level of a gift certificate to 0 (out of stock) does not affect the gift certificate’s availability because the ElectronicFulfiller does not check a gift certificate’s stock level.

Sending an e-mail to the recipient of the gift certificate requires knowing his or her e-mail address. Core Commerce does this through an ElectronicShippingGroup, which designates the necessary information for delivering electronic goods, in this case an e-mail address. So, when Customer A adds the gift certificate to his or her cart, you add an ElectronicShippingGroup to the order as well, and define the relationship between the two. Use the handleAddSoftGoodToOrder method in the /atg/commerce/order/ShoppingCartModifier component to do this. The following example shows the JSP code you would add to the page on which the gift certificate product is displayed. It adds the gift certificate to the customer’s order and prompts him or her to specify the e-mail address of the recipient:

<%@ taglib uri="http://www.atg.com/dsp.tld" prefix="dsp" %>
<dsp:page>

<dsp:form action="<%=request.getServletPath()%>" method="post">
<!-- Store this Product's ID in the Form Handler: -->
 <dsp:input bean="ShoppingCartModifier.ProductId"
paramvalue="Product.repositoryId" type="hidden"/>
<!--set id param so that the Navigator won't get messed up
     in case of an error that makes us return to this page.-->
 <input value='<dsp:valueof param="Product.repositoryId"/>' type="hidden"
name="id">
    Give
    <dsp:input bean="ShoppingCartModifier.quantity" size="4" value="1"
type="text"/>

<!-----------DropDownList format (default) ----------- -->
<!--Create a dropdown list will all Sku in the Product.
           Store the selected SKU's id in the Form Handler: -->
       <dsp:select bean="ShoppingCartModifier.catalogRefIds">
<!--For each of the SKUs in this Product, add the SKU to the
            dropdown list:-->
  <dsp:droplet name="/atg/dynamo/droplet/ForEach">
         <dsp:param param="Product.childSKUs" name="array"/>
         <dsp:param value="Sku" name="elementName"/>
         <dsp:param value="skuIndex" name="indexName"/>
         <dsp:oparam name="output">
<!--This is the ID to store, if this SKU is selected in
             dropdown:-->
          <dsp:getvalueof id="option48" param="Sku.repositoryID"
idtype="java.lang.String">
<dsp:option value="<%=option48%>"/>
</dsp:getvalueof>
<!--Display the SKU's display name in the dropdown
              list:-->
          <dsp:valueof param="Sku.displayName"/>
         </dsp:oparam>
        </dsp:droplet>
<!--ForEach SKU droplet-->
       </dsp:select> to
       <br>
    Recipient's e-mail address
    <dsp:input bean="ShoppingCartModifier.softGoodRecipientEmailAddress"
size="30"/>
    <p>
 <!-- ADD TO CART BUTTON: Adds this SKU to the Order-->
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrder"
value=" Add Gift Certificate to Cart " type="submit"/>
 <!-- Goto this URL if NO errors are found during the ADD TO CART
          button processing:-->
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrderSuccessURL"
value="../checkout/cart.jsp" type="hidden"/>
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrderErrorURL"
value="product_gift_certificate.jsp" type="hidden"/>
   </td>
  </tr>
 </table>
</dsp:form>

</dsp:page>

In this example, note the code that handles the recipient’s e-mail address. The customer enters the recipient’s e-mail address into a form field set to the property ShoppingCartModifier.softGoodRecipientEmailAddress. Thus, the e-mail address is set in the ElectronicShippingGroup through the handleAddSoftGoodToOrder method, and then the ElectronicFulfiller examines it to determine where to send the message.

Note that electronic goods require special processing, so the submit method of the form is set to addSoftGoodOrder and not addItemToOrder.

For more information on the ShoppingCartModifier component, please refer to the Setting Up Gift Lists and Wish Lists section.

Using a Gift Certificate

On your Checkout page (or an equivalent page on your sites), include a text field where customers can enter the claim codes for any gift certificates they may have (you send the codes in the gift certificate notification e-mail). Hook the text field up to the giftCertificateNumbers property of the ShoppingCartModifier component. During the handleMoveToConfirmation process, the ShoppingCartModifier parses any values it finds in this field into tokens, using white space as the delimiter. This behavior allows customers to enter multiple gift certificate codes into a single text field.

After the system tokenizes the giftCertificateNumbers property, it hands each token string to the ClaimableManager component. The ClaimableManager attempts to match each string to a corresponding gift certificate in the Claimable repository. If it cannot find a corresponding item, it adds an error to the FormHandler. If the system does find an item that corresponds to the token string, it creates a new GiftCertificate payment group and adds it to the order.

You must initialize the properties of the payment group to the correct values. The properties to initialize include the claim code ID, the user profile ID, and the amount of the gift certificate. Finally, create a relationship between the order and the new payment group indicating that the gift certificate payment group can account for any amount up to the value of the gift certificate.

Please refer to the Configuring Purchase Process Services chapter for more information on payment groups.

Settling a Gift Certificate

Gift certificate settlement is handled similar to the way that settlement for credit cards is handled. (For more information, see the Processing Payment of Orders section.)

When an order is submitted, each PaymentGroup in the order is authorized using the PaymentManager. The PaymentManager has different processors for gift certificates and credit cards. The processor used for gift certificates handles the authorization, debit, and credit of gift certificates. When a gift certificate is authorized, the amountRemaining is reduced by the amount being authorized. This prevents the same gift certificate from being used for more than it is worth.

During fulfillment, the PaymentGroup containing the gift certificate is debited through the PaymentManager (and ultimately the GiftCertificateProcessor). When this happens, the amount that was authorized is checked against the amount that is being debited. If the amount authorized was the same as the amount being debited, the PaymentManager.debit returns successfully. If there are any differences, they are corrected now. To make sure that the gift certificate is valid if an order is removed before the debit occurs (and after authorization), any amount that was authorized will be credited back to the gift certificate before the PaymentGroup is removed.

Core 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 or promotions 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="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, Core Commerce checks that:

If these conditions are met, the user “claims” the coupon, which means that the promotions are added to the user’s activePromotions profile property. Note that promotions cannot be granted independently while claiming a coupon; either all are granted or none.

During order pricing, Core Commerce determines whether the order qualifies for the coupon’s promotions by checking that:

This double-checking ensures that if a user claims a coupon as part of one order, discontinues that order, then creates a second one, any promotions apply to the second order, as long as the promotions are active and applicable.

Promotions given by a coupon persist 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 <ATG11dir>/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 sites require 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 the following methods: