11 Promotions
This chapter provides developers with formats for promotion maintenance requests sent to the Customer Engagement application. The following types of requests are supported:
Rules and Limitations
Promotion requests have the following rules and limitations:
-
These requests will not validate a serialized coupon against multiple use. Their purpose is to update coupon redemptions off-line after a coupon redemption has already been approved and redeemed.
-
Optional customer information may be provided in the request; but if the customer cannot be found in Customer Engagement, the redemption will still process—it will not be rejected.
-
In a redemption, the coupon code will be validated against the Customer Engagement CRC checks. If the coupon serial number does not pass the CRC checks, the coupon redemption will be rejected.
-
Void coupon redemption is used to unredeem a coupon. Once a redemption is voided, a coupon is available for redemption again; it is NOT marked as void or invalid.
-
Void coupon will not change any of the existing data, such as the customer who originally redeemed the coupon.
Redeem Serialized Coupon
The purpose of this action is to redeem one or more serialized coupons in a transaction.
Requirements/Restrictions
The only data item required to create a valid coupon redemption request is the CouponCode.
Fields
The elements in the table below are the elements/attributes that may be used in a Redeem Serialized Coupon request. The sample request shows the placement of these elements/attributes. Not all of these elements/attributes need to be used in any one request.
| XML Tag | Comments |
|---|---|
|
< |
|
|
|
ID for the serialized coupon used in the transaction. |
|
|
The StoreID, RegisterID, BusinessDate, and SequenceNumber make up the Retail Transaction ID. This information, along with the UserID, is recorded for the coupon redemption. |
|
|
ID of person making request. |
|
|
Location where request is being made. |
|
|
Register where request is being made. |
|
|
Business date when request is made. |
|
|
Transaction sequence number on register. |
|
|
Indicates whether the redemption was performed normally (false), or was forced (true). |
|
|
[optional] |
|
|
Customer’s Card Number |
|
|
Customer Engagement Customer ID |
|
|
TypeCode - Type of alternate ID |
|
|
Customer’s alternate ID |
Example
A CouponRedeem request should appear similar to the example below. The coupon redemption data included will vary according to each particular request.If you are processing more than one serialized coupon redemption transaction, the batch file should include multiple <CouponRedeem> sections.
<?xml version="1.0" encoding="UTF-8"?><PromotionMaintenance> <CouponRedeem VoidFlag="false"> <CouponCode><COUPON_CODE></CouponCode> <CouponCode><COUPON_CODE></CouponCode> <TransactionID> <UserID>TestPromo <USERID></UserID> <StoreID><ID></StoreID> <RegisterID><ID></RegisterID> <SequenceNumber>600001</SequenceNumber> <BusinessDate>2011-01-25T10:11:53.845</BusinessDate> <ForceFlag>true</ForceFlag> </TransactionID> <Customer> <CardNumber></CardNumber> <RelateCustomerId></RelateCustomerId> <AlternateKey TypeCode="XSTORE_ID"> <AlternateID><ID></AlternateID> </AlternateKey> </Customer> </CouponRedeem></PromotionMaintenance>
Batch File Response
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Each <CouponRedeem> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
You may be able to determine the reason for the failure by using the Batch Import Review pages (see Introduction).
Void Coupon Redemption
The purpose of this action is to void the redemption of one or more serialized coupons. After voiding a coupon redemption, the coupon is once again available for redemption.
Requirements/Restrictions
The only data items required to void a valid coupon redemption request are the VoidFlag="true" setting and the CouponCode element.
Fields
The elements in the table below are the elements/attributes that may be used in a Void Serialized Coupon Redemption request. The sample request shows the placement of these elements/attributes. Not all of these elements/attributes need to be used in any one request.
| XML Tag | Comments |
|---|---|
|
|
|
|
|
ID for the serialized coupon. |
|
|
(optional) The StoreID, RegisterID, BusinessDate, and SequenceNumber make up the Retail Transaction ID. This information, along with the UserID, is recorded in an activity record for the redemption void. |
|
|
ID of person making request. |
|
|
Location where request is being made. |
|
|
Register where request is being made. |
|
|
Business date when request is made. |
|
|
Transaction sequence number on register. |
|
|
Indicates whether the void was performed normally (false), or was forced (true). |
|
|
(optional) |
|
|
Customer’s Card Number |
|
|
Customer Engagement Customer ID |
|
|
TypeCode - Type of alternate ID |
|
|
Customer’s alternate ID |
Example
A void coupon redemption request should appear similar to the example below. The void coupon redemption data included will vary according to each particular request.
If you are processing more than one serialized coupon void redemption transaction in a batch file, multiple <CouponRedeem> sections should be used.
<?xml version="1.0" encoding="UTF-8"?><PromotionMaintenance> <CouponRedeem VoidFlag="true"> <CouponCode><COUPON_CODE></CouponCode> <CouponCode><COUPON_CODE></CouponCode> <TransactionID> <UserID>TestPromo <USER_ID></UserID> <StoreID><ID></StoreID> <RegisterID><ID></RegisterID> <SequenceNumber>1234567</SequenceNumber> <BusinessDate>2011-01-25T16:21:03.425</BusinessDate> <ForceFlag>true</ForceFlag> </TransactionID> <Customer> <CardNumber></CardNumber> <RelateCustomerId></RelateCustomerId> <AlternateKey TypeCode="XSTORE_ID"> <AlternateID><ID></AlternateID> </AlternateKey> </Customer> </CouponRedeem></PromotionMaintenance>
Batch File Response
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Each <CouponRedeem> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
You may be able to determine the reason for the failure by using the Batch Import Review pages (see Introduction).