Relate Loyalty Integration

Relate Loyalty Integration

Relate Loyalty Integration allows you to register customers in Relate’s loyalty program. Once a customer is registered in the loyalty program, you can retrieve the customer’s loyalty points and awards balances, accrue points from completed purchases, and redeem awards as a pro-rated merchandise discount on an order.

About loyalty programs: Loyalty programs define the rules used for tracking the purchases of customers belonging to store loyalty programs, usually through a system of points. The loyalty points can then be redeemed for discounts of a fixed amount (though the points alone have no intrinsic value). The discounts can be distributed through the mail as paper coupons, or made available to customers as an award coupon created by the award program associated with the customer’s loyalty card.

The Relate Loyalty integration retrieves a customer’s loyalty information from Relate at specific points in CWSerenade so users can view a customer’s loyalty card information, current loyalty points, and current award coupons. Communication with Relate uses Relate’s API Interface; the loyalty information is not stored in CWSerenade. Certain activities in CWSerenade update the customer’s loyalty account information in Relate:

• the Customer Loyalty Registration Window allows you to ask a customer to join the loyalty program; when a customer joins, Relate generates a card for the customer and creates the customer’s loyalty account.

• the Issue Loyalty Points Window allows you to issue points to the customer’s loyalty account; Relate increases the points in the customer’s loyalty program.

• the Issue Loyalty Coupon Window allows you to issue an award coupon to the customer’s loyalty account; Relate creates the award coupon in the customer’s awards program.

• during order entry (interactive and using the generic order interface), you can apply an award amount to an order. When you accept the order, Relate subtracts the award amount from the customer’s awards program.

• the Relate Sales Feed sends sales and return information to Relate in the Relate Post POSlog Transaction Message; Relate increases or decreases the loyalty points from the customer’s loyalty program based on the program rules defined for the customer’s loyalty card in Relate.

Note: Other applications, such as XStore and the web storefront, communicate with Relate to retrieve and update loyalty account information for the customer. This section explains the Relate Loyalty integration between Relate and CWSerenade only.

In this topic:

• Relate Loyalty Integration Setup

• Setup in CWSerenade for the Relate Loyalty Integration

• Setup in Relate for the Relate Loyalty Integration

• Registering a Customer in the Relate Loyalty Program

• Reviewing Relate Loyalty Account Information

• Applying Points to a Customer’s Loyalty Card

• Applying Coupons to a Customer’s Loyalty Card

• Accruing Loyalty Points during Order Processing

• Applying and Redeeming Relate Awards during Order Processing

• Relate APIs used in the Relate Loyalty Integration

For more information: See:

• Relate Customer Integration for more information on interactively communicating with Relate to keep customer information in CWSerenade in sync with Relate when Relate is the system of record for customer information.

• Relate Batch Customer and Sales Integration for more information on sending merchandise hierarchy, item, customer, sales and return information from CWSerenade to Relate using a batch process. This section also includes Relate Integration Setup (Sales and Customer).

• Relate Purchase History Integration for more information on reviewing a customer’s purchase history from Relate on the Display Purchase History Screen in CWSerenade.

• Relate Customer Wish List Integration for more information on how to review and modify a customer’s wish list from Relate using the Display Wish List Screen in CWSerenade.

• The Relate Implementation Guide (Installer Version) for more information on the procedures and instructions required to install and configure the Relate application and database.

• The Relate Configuration Guide for more information on configuration settings for Relate that are defined using the Conflate tool.

• The Relate Batch Processing and Web Services Guide for more information on the Relate API interface.

• The Relate Database Dictionary for more information on the tables in the Relate database.

• The Relate User Guide for more information on using the Relate application.

Relate Loyalty Integration Setup

Before you can use the Relate Loyalty Integration, you must complete the required setup.

Required versions: To use the Loyalty Integration with Relate, you must be on these versions:

• CWSerenade version 4.5 or higher.

• Relate version 10.5 or higher.

In addition:

• the Relate Customer Integration and Relate Purchase History Integration uses version 2.3 of the Relate Customer API.

• generating a new loyalty card and assigning it to a customer uses version 1.1 of the Relate Stored Value Card Transaction Services API.

• retrieving loyalty and award summary information for all accounts attached to a specified loyalty card uses version 2.1 of the Relate Card Services API.

• issuing loyalty points to a specified loyalty card and retrieving all of the loyalty points account activity for a specified loyalty account uses version 1.2 of the Relate Loyalty Account Services API.

• issuing an award coupon to a specified loyalty card, retrieving all of the award account activity for a specified loyalty account, and automatically redeeming an award coupon for a specified amount uses version 1.2 of the Relate Award Account Services API.

Setup is required in both CWSerenade and Relate.

• Setup in CWSerenade for the Relate Loyalty Integration

• Setup in Relate for the Relate Loyalty Integration

For more information: See Relate Integration Setup (Sales and Customer) for more information on the setup required to use the Relate Item Feed, Relate Sales Feed, and Relate Customer Integration.

Setup in CWSerenade for the Relate Loyalty Integration

• System Control Values for the Relate Loyalty Integration

• Secured Feature for the Relate Loyalty Integration

• Relate Properties File

• Menu Options Related to the Relate Loyalty Integration

System Control Values for the Relate Loyalty Integration

System Control Value	Description
Prorate Dollar Discounts and Coupons (D90)	Select this system control value to automatically display the Enter Loyalty Award Discount Window when you select the Reprice option in order entry.
Use the Relate Integration Values (L52) umbrella screen to set the following values:
Relate Organization Descriptor (L50)	Use this field to identify the Relate organization that maps to your CWSerenade company.
Default Location for Sales Download (K69)	Use this field to define the Relate location to associate with the Relate loyalty program.
Use Relate Loyalty (M06)	Select this system control value if you want to use the Relate Loyalty integration. Important: If you select this system control value: • The Relate Customer Integration (L37) system control value must be set to INTERACT, indicating you communicate with Relate interactively. • You must define a card prefix in the Relate Loyalty Card Prefix (M08) system control value. • You must define a card series sequence number in the Relate Loyalty Card Series Sequence Number (M09) system control value. • The Use Rewards Integration (K86) system control value must be unselected. • The Rewards Certificates Pay Type (L54) system control value must be blank.
Prompt to Join Loyalty (M07)	Select this system control value if you want the system to automatically display the Customer Loyalty Registration Window during order entry and Work with Customers when the sold to customer is not already registered in the Loyalty program. Note: If you select this system control value, the Relate Customer Integration (L37) system control value must be set to INTERACT, indicating you communicate with Relate interactively.
Relate Loyalty Card Prefix (M08)	Defines the 5 digit prefix assigned to the Card Definition in Relate that is used to assign new loyalty cards to sold to customers that join the loyalty program. Note: This setting must match the setting in Relate; for example, if the card prefix in Relate is 00905, you must enter 00905 in this system control value.
Relate Loyalty Card Series Sequence Number (M09)	Defines the 2 digit card series number assigned to the Card Definition in Relate that is used to assign new loyalty cards to sold to customers that join the loyalty program. Note: This setting must match the setting in Relate; for example, if the card series sequence number in Relate is 02, you must enter 02 in this system control value.
Relate Loyalty Registration Notification Email Program (M10)	Defines the program used to generate a Loyalty Registration Notification email when a sold to customer joins the loyalty program and is assigned a loyalty card in Relate. LoyRegNotf is the base program that generates the Loyalty Registration Notification email in HTML format. In this situation, the XML Only flag for the Loyalty Registration Notification email template must be unselected.

Secured Feature for the Relate Loyalty Integration

Secured Feature

Description

Relate Loyalty Issue Awards/Points (J07)

This feature controls whether the Issue Points and Issue Awards options display on the Display Loyalty Account Screen.

• Allow (default) = The Issue Points and Issue Awards options display on the Display Loyalty Account Screen.

• Exclude = The Issue Points and Issue Awards options do not display on the Display Loyalty Account Screen.

Relate Properties File

The cwdirectcp_relate.properties file contains settings required for integration with Relate.

Where is the file located? This file is located in the same folder as the other CWSerenade properties files, where C: represents the root drive where CWSerenade is installed:

C:\Serenade\server\conf\cwdirectcpproperties\cwdirectcp_relate.properties

How to edit the file: MICROS recommends that you first make a backup copy of the configuration file. Then use a text editor, being careful not to change any of the settings except those indicated below.

Your changes take effect the next time you stop and restart the Serenade service (or the application server).

Setting	Description	Setting
RELATE_CUSTOMER_SERVICE_PREFIX	The system uses this property to build the URL for communication with Relate during the Relate Customer Integration, Relate Purchase History Integration, and Relate Loyalty Integration.	http://relateserver:8084/ soap where: relateserver = the name of your Relate server 8084 = the port to use on the Relate server
RELATE_CUSTOMER_SERVICE_SUFFIX	The system uses this property, along with the RELATE_CUSTOMER_SERVICE_PREFIX, to build the URL for communication with Relate using the Customer Services API.	/v2_3/CustomerServices?wsdl where 2_3 is the version of the Customer Services API
RELATE_SVC_SERVICE_SUFFIX	The system uses this property, along with the RELATE_CUSTOMER_SERVICE_PREFIX, to build the URL for communication with Relate using the Relate Stored Value Card Transaction Services API.	/v1_1/SvcTransactionServices?wsdl where 1_1 is the version of the Stored Value Card Transaction Services API
RELATE_CARD_SERVICE_SUFFIX	The system uses this property, along with the RELATE_CUSTOMER_SERVICE_PREFIX, to build the URL for communication with Relate using the Relate Card Services API.	/v2_1/CardServices?wsdl where 2_1 is the version of the Card Services API
RELATE_LOYALTY_SERVICE_SUFFIX	The system uses this property, along with the RELATE_CUSTOMER_SERVICE_PREFIX, to build the URL for communication with Relate using the Relate Loyalty Account Services API.	/v1_2/LoyaltyAccountServices?wsdl where 1_2 is the version of the Loyalty Account Services API
RELATE_LOYALTY_AWARD_SERVICE_SUFFIX	The system uses this property, along with the RELATE_CUSTOMER_SERVICE_PREFIX, to build the URL for communication with Relate using the Relate Award Account Services API.	/v1_2/AwardAccountServices?wsdl where 1_2 is the version of the Award Account Services API
RELATE_LOYALTY_PROMPT_ATTRIBUTE	Defines the corresponding Relate custom attribute to identify whether Serenade should automatically display the Customer Loyalty Registration Window for a customer that is not already assigned to a loyalty card. See Relate PROMPT_TO_JOIN_LOYALTY Attribute Definition for setup instructions.	PROMPT_TO_JOIN_LOYALTY
RELATE_SECURITY_ USER_ID	The Relate user ID with Security Group permission included in Relate’s API messages.	Must be a valid user ID in Relate that has Security Group permission
RELATE_LOYALTY_REG_MESSAGE	The text to display on the Customer Loyalty Registration Window, up to 55 positions.	Does the customer want to join the loyalty program?

Menu Options Related to the Relate Loyalty Integration

Menu Option	Description
Working with E-Mail Notification Templates (WEMT)	Define default text to include in Relate Loyalty Registration Notifications.
Establishing Order Hold Reason Codes (WOHR)	Create the RL (Relate Communication Failure) order hold reason code.

Setup in Relate for the Relate Loyalty Integration

• CWSerenade Company > Relate Organization

• Relate PROMPT_TO_JOIN_LOYALTY Attribute Definition

• Card Definition

• Card Series Distribution for Card Definition

• Generate and Activate Cards for Card Definition

• Programs for Card Definition

CWSerenade Company > Relate Organization

An organization in Relate corresponds to a company in CWSerenade. You associate a Relate organization with a CWSerenade company through the Relate Organization Descriptor (L50) system control value.

Use Conflate to define configuration settings for the Relate organization that integrates with CWSerenade. See the Relate Configuration Guide for more information on how to define configuration settings for Relate using the Conflate tool.

Configuration Settings Required for the CWSerenade Loyalty Integration with Relate

Select Edit Configs in Conflate to define these settings for the organization that integrates with CWSerenade.

Organization Descriptor	The organization descriptor must match the setting in the Relate Organization Descriptor (L50) system control value. This setting identifies the Relate organization that maps to your CWSerenade company.
Default Location ID	Enter a default location ID of up to 12 positions.
Account Activity Lookup Limit	Enter the maximum number of account activity records that can be returned when making any type of account activity lookup request to the Relate Services server. The default value is 400. If the number of loyalty account transactions returned to CWSerenade exceeds this setting, CWSerenade does not display any activity on the Display Loyalty Account History Screen and instead displays an error message: Max results value defined in Relate has been exceeded.
Card Number Length	Controls the number of digits in a card number. Must be between 10 and 16.
Process Loyalty Returns	Select Yes to process returns to a loyalty account.

Note: Whenever you makes changes to an organization’s configuration settings, you must stop the Relate service, deploy the configuration settings to Relate, and restart the Relate service. See:

• Shut Down Services in the Add New Organization section of the Relate Implementation Guide (Installer Version) for more information on how to stop the Relate service.

• the Relate Configuration Guide for more information on deploying configuration settings to Relate.

• Restart Services in the Add New Organization section of the Relate Implementation Guide (Installer Version) for more information on how to restart t he Relate service.

Relate PROMPT_TO_JOIN_LOYALTY Attribute Definition

In Relate, use the Attribute Definition screen to create an attribute definition that identifies whether Serenade should automatically display the Customer Loyalty Registration Window for a customer that is not already assigned to a loyalty card.

Note: The attribute you create must match the entry for the RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in the Relate Properties File.

See the Attribute Definition section of the Relate User Guide for detailed instructions.

Required settings: When creating the attribute definition, define the fields as follows:

Field	Description
Intended Use	Select Customer.
Attribute Name	Enter the value defined for the RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in the Relate Properties File, such as PROMPT_TO_JOIN_LOYALTY.
Unique	Leave this check box unselected.
Description	Enter a description for the attribute definition. Example: TRUE if the system should prompt this customer to join a loyalty program.
Data Type	Select Character.

Card Definition

Create a card definition in Relate to use when assigning new loyalty cards to customers that join the loyalty program.

When creating the card definition:

• the 5 digit card prefix you define must also be entered in the CWSerenade Relate Loyalty Card Prefix (M08) system control value.

• the 2 digit sequence number you define must also be entered in the CWSerenade Relate Loyalty Card Series Sequence Number (M09) system control value.

• make sure you assign the Relate organization that integrates with CWSerenade to the card definition.

For more information: See Card Definitions in the Relate User Guide for instructions on creating and updating a card definition in Relate.

Card Series Distribution for Card Definition

Create a card series distribution for the card definition you created. The card series distribution contains one or more batches of cards to be generated and then distributed to customers.

For more information: See Card Series Distribution under Card Definitions in the Relate User Guide for instructions on creating and updating a card series distribution in Relate.

Generate and Activate Cards for Card Definition

Generate and activate a set of cards within the card definition.

For more information: See Generate Cards and Activate Cards under Card Definitions in the Relate User Guide for instructions on generating and activating a set of cards within a card definition.

Programs for Card Definition

Create the following programs for the card definition you created:

• Loyalty program: The loyalty program defines the rules used to track the purchases of customers belonging to the program through a system of points that can then be redeemed for discounts on an order. Example: Create a rule to earn 1 point for each purchase dollar.

• Award program: The award program defines the coupons, or e-wards, that are distributed to the customers belonging to the program. These awards are typically distributed as part of promotions such as birthday or anniversary awards, or they can be made available to customers who have accumulated a certain number of points as part of the loyalty program. Example: Create a rule to issue a $25.00 award coupon each time the customer spends $100.00.

For more information: See Programs in the Relate User Guide for more information on creating and updating programs for a card definition in Relate.

Registering a Customer in the Relate Loyalty Program

The system registers a sold to customer in the Relate loyalty program when you select Yes on the Customer Loyalty Registration Window.

When you select to register the customer in the Relate loyalty program:

1. CWSerenade sends a Relate Loyalty Generate Card Request to Relate.

2. Relate uses the information in the Loyalty Generate Card Request to associate and activate a new loyalty card for the customer.

3. Relate returns the Relate Loyalty Generate Card Response to CWSerenade, containing the customer’s loyalty card number.

4. CWSerenade :

• generates a Relate Loyalty Registration Notifications email to send to the customer. This email contains the loyalty card number assigned to the customer; see Relate Loyalty Registration Notifications for the setup required to generate the notice and see Relate Loyalty Registration Notification Sample and Contents for a sample email.

• creates a record in the Customer Note table indicating a Relate Loyalty Registration Notice has been sent to the customer: Loyalty Reg Notice to sflye@EXAMPLE.com. You can review customer notes on the Edit Customer Notes Screen. The note is written even if the system generates the Outbound Email XML Message (CWEmailOut) rather than an actual email, or if the email cannot be relayed if, for example, there is a problem with the destination email address.

5. CWSerenade sends a Relate Update Customer Request to:

• update the RELATE_LOYALTY_PROMPT_ATTRIBUTE setting for the customer to FALSE so that CWSerenade will not prompt the customer again to join the Loyalty program.

• update the customer’s birth month and day if it was entered on the Customer Loyalty Registration Window.

6. Relate returns the Update Customer Response indicating whether the update was successful.

7. If you advanced to the Customer Loyalty Registration window from the Customer Selection Screen:

• CWSerenade sends a Relate Loyalty Card Request to Relate, requesting the details of the loyalty card.

• Relate returns the details of the loyalty card in the Relate Loyalty Card Response.

• CWSerenade uses the information in the Loyalty Card Response to display the loyalty card number and its associated points and awards on the Customer Selection screen.

Communication failure:

• If you select Yes on the Customer Loyalty Registration window and a connection could not be made to Relate, the system displays an error message similar to the following: No response from Relate-card not generated.

• If the value in the Relate Loyalty Card Prefix (M08) or Relate Loyalty Card Series Sequence Number (M09) system control value is not valid in Relate, the system displays an error message similar to the following: No response from Relate-card not generated.

Customer Loyalty Registration Window

Use this window to ask a sold to customer to join the Relate loyalty program.

How to display this screen: This window is available when the Use Relate Loyalty (M06) system control value is selected, the Relate Customer Integration (L37) system control value is set to INTERACT, and you:

• Select Loyalty from the Action drop-down menu on the Customer Scan Screen in Work with Customers (WCST) or Order Entry (OEOM).

• Select Loyalty on the Customer Selection Screen after selecting a sold to customer.

• Select Loyalty Account on the Display More Options Screen.

• Select Loyalty Account on the More Customer Sold To Options Screen.

• Select Loyalty on the Third Streamlined Order Inquiry Screen (Order Summary) in Streamlined Order Inquiry (DORI).

When you select the Loyalty option, the system retrieves the sold to customer’s information from Relate. If Relate does not find a loyalty card for the customer, the system advances you to the Customer Loyalty Registration Window, where you can select to enroll the customer in the Relate Loyalty program.

Note:

• If Relate finds a loyalty card assigned to the customer, the system advances you to the Display Loyalty Account Screen. If Relate finds more than one loyalty card assigned to the customer, the loyalty account information for the first card displays on the screen.

• If a Relate ID is not defined for the customer in the Customer Sold To table, the system displays an error message similar to the following: This customer does not have a Relate ID. Note: If a Relate ID is not defined for the sold to customer, the Loyalty option does not display on the Third Streamlined Order Inquiry Screen (Order Summary) in Streamlined Order Inquiry (DORI).

• If a connection could not be made to Relate, the system displays an error message similar to the following: Unable to connect to Relate.

When this window displays automatically: If the Prompt to Join Loyalty (M07) system control value is selected, this window displays automatically when you:

• Select a sold to customer on the CTI Customer Selection Screen if Relate does not find a loyalty card for the customer and the customer’s RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in Relate is TRUE or blank.

• Change a sold to customer in Creating and Updating Sold-to Customers (WCST) if Relate does not find a loyalty card for the customer and the customer’s RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in Relate is TRUE or blank.

• Create a sold to customer in Creating and Updating Sold-to Customers (WCST) or Order Entry (OEOM) after the customer is created in Relate.

• In Work with Customers, this window automatically displays after the final Accept to create the customer.

• In Order Entry, this window automatically displays after the system validates the customer information and source code on the order and you click Accept.

• Create an order in Order Entry (OEOM) if you do not use the CTI Customer Selection Screen and Relate does not find a loyalty card for the customer and the customer’s RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in Relate is TRUE or blank. This window automatically displays after the system validates the customer information and source code on the order and you click Accept.

Field	Description
Loyalty Registration Message (unlabeled field above customer)	The text defined for the RELATE_LOYALTY_REG_MESSAGE setting in the Relate Properties File.
Customer	The number, company name, last name, and first name of the sold to customer being asked to join the Relate loyalty program.
Birth month/day	The sold to customer’s birth month and birth day. Valid birth months are: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. Enter 000 if you do not wish to define a birth month. Valid birth days are 1-31. The system validates the birth day against the selected birth month. Note: If you enter a birth month and day on this window, regardless of whether the customer joins the Relate loyalty program or not, the system updates the birth month and day in the Customer Sold To table. The birth year does not display on the screen; however, it defaults to 1900 in the Customer Sold To table unless it has been updated through the Relate Customer Integration. Birth Month: Numeric, 2 positions (01-12 in table); required if you define a birth day. Birth Day: Numeric, 2 positions; required if you define a birth month. Birth Year (in table only): Numeric, 4 positions; optional.

Screen Option	Procedure
Register the customer in the Relate loyalty program	Select Yes. See Registering a Customer in the Relate Loyalty Program.
Do not register the customer in the Relate loyalty program, but ask the customer again at a later time	Select Not Now.
Do not register the customer in the Relate loyalty program and do not ask the customer again	Select Never. The system sends an Add or Update Customer Request to Relate to update the RELATE_LOYALTY_PROMPT_ATTRIBUTE setting in Relate to FALSE.

Reviewing Relate Loyalty Account Information

Use the following screens to review loyalty account information for a customer that is registered in the Relate Loyalty program:

• Display Loyalty Account Screen: allows you to review the current points accrued and the awards available to the customer.

• Display Loyalty Account History Screen: allows you to review the points activity and award activity associated with the customer’s loyalty card.

• Customer Selection Screen: allows you to review the loyalty card number, current earned points, and current awards balance assigned to the customer’s loyalty account.

Important: If the customer is assigned to more than one loyalty card in Relate, CWSerenade displays loyalty card information for the first card returned from Relate.

You can also review the loyalty account information in Relate; see Reviewing the Customer’s Loyalty Card in Relate.

Display Loyalty Account Screen

Use this screen to review the current points accrued and the awards available for the loyalty program and award program associated with the customer’s loyalty card.

When you advance to the Display Loyalty Account screen:

1. CWSerenade sends a Get Customer Request to Relate containing the customer’s Relate ID from the Customer Sold To table.

2. Relate uses the Relate ID in the Get Customer Request to find the customer and returns the Get Customer Response containing the customer’s information, including the customer’s cards.

3. CWSerenade sends a Relate Loyalty Card Request to Relate containing the customer’s card number.

4. Relate uses the customer’s card number in the Loyalty Card Request to retrieve the loyalty points and awards for the loyalty program and award program associated with the customer’s loyalty card.

5. Relate returns the Relate Loyalty Card Response to CWSerenade, containing the customer’s loyalty account information.

6. CWSerenade displays the loyalty account information returned from Relate on the Display Loyalty Account screen.

How to display this screen: This screen is available when the Use Relate Loyalty (M06) system control value is selected and you:

• Select Loyalty from the Action drop-down menu on the Customer Scan Screen in Work with Customers (WCST) or Order Entry (OEOM).

• Select Loyalty on the Customer Selection Screen after selecting a sold to customer.

• Select Loyalty Account on the Display More Options Screen.

• Select Loyalty Account on the More Customer Sold To Options Screen.

• Select Loyalty on the Third Streamlined Order Inquiry Screen (Order Summary) in Streamlined Order Inquiry (DORI).

When you select the Loyalty option, the system retrieves the sold to customer’s information from Relate. If Relate finds a loyalty card assigned to the customer, the system advances you to the Display Loyalty Account Screen. If Relate finds more than one loyalty card assigned to the customer, the loyalty account information for the first card returned displays on the screen.

Note:

• If Relate does not find a loyalty card for the customer, the system advances you to the Customer Loyalty Registration Window, where you can select to enroll the customer in the Relate Loyalty program.

• If a connection could not be made to Relate, the system displays an error message similar to the following: Unable to connect to Relate.

Column sort: You can sort on the Coupon ID, Coupon Amount, and Expiration Date columns on this screen by clicking on the column name. An arrow pointing up displays next to the field when the values for the field display in ascending sequence; an arrow pointing down displays next to the field when the values for the field display in descending sequence.

The information that displays on this screen is from Relate and is not stored in CWSerenade.

Field	Description
Customer #	The number, company name, last name, and first name of the sold to customer registered in the Relate Loyalty program. Customer number: Numeric, 9 positions; display-only. Customer name: Alphanumeric, 40 positions; display-only.
Loyalty Card #	The loyalty card number assigned to the customer in Relate. The points and awards associated with this card display on the screen. From cardNumber in the Relate Loyalty Card Response.
Loyalty Points The loyalty points for the loyalty program associated with the customer’s loyalty card. Only loyalty points from Relate display on this screen; escrow and bonus points from Relate do not display.
Current Points	The total current earned points balance for the customer loyalty account. From EARNED points value in the Relate Loyalty Card Response.
Points Earned This Year	The total earned points balance for the current year for the customer’s loyalty account. From YTD points value in the Relate Loyalty Card Response.
Total Points Earned	The total lifetime earned points balance for the customer’s loyalty account. From LTD points value in the Relate Loyalty Card Response.
Program Level	A description of the current level of the loyalty program to which the customer’s loyalty account is assigned. From loyaltyProgramLevel value in the Relate Loyalty Card Response.
Current Awards
Coupon ID	The ID number for the coupon created or redeemed by the award activity. From coupon id in the Relate Loyalty Card Response.
Amount	The amount of the coupon applied to the customer’s award account by the activity. From coupon amount in the Relate Loyalty Card Response.
Expiration Date	The date when the coupon expires, in MM/DD/YYYY format. No Expiration displays if an expiration date is not defined for the coupon. From coupon ExpirationDate in the Relate Loyalty Card Response.

Screen Option	Procedure
Review loyalty account history	Select Loyalty History to advance to the Display Loyalty Account History Screen.
Issue points	Select Issue Points to advance to the Issue Loyalty Points Window. Note: This option is available only if you have authority to the Relate Loyalty Issue Awards/Points (J07) secured feature.
Issue awards	Select Issue Awards to advance to the Issue Loyalty Coupon Window. Note: This option is available only if you have authority to the Relate Loyalty Issue Awards/Points (J07) secured feature.

Display Loyalty Account History Screen

Use this screen to review points activity and award activity for the loyalty program and award program associated with the customer’s loyalty card.

When you advance to the Display Loyalty Account History screen:

1. CWSerenade sends a Relate Get Customer Request to Relate containing the customer’s Relate ID from the Customer Sold To table.

2. Relate uses the Relate ID in the Get Customer Request to find the customer.

3. Relate returns the Relate Get Customer Response to CWSerenade, containing the customer’s information, along with the customer’s loyalty card information.

4. CWSerenade sends a Relate Loyalty Card Request to Relate containing the customer’s card number.

5. Relate uses the customer’s card number in the Loyalty Card Request to retrieve the loyalty account and award account associated with the customer’s loyalty card.

6. Relate returns the Relate Loyalty Card Response to CWSerenade, containing the customer’s loyalty account and award account information.

7. CWSerenade sends a Relate Loyalty Account History Request and Relate Award Account History Request to Relate.

8. Relate uses the information in the Loyalty Account History Request and Award Account History Request to retrieve the customer’s loyalty account and award account activity.

9. Relate returns the Relate Loyalty Account History Response and Relate Award Account History Response to CWSerenade, containing the customer’s loyalty account and award account activity.

10. CWSerenade displays the loyalty account and award account activity returned from Relate on the Display Loyalty Account History screen.

Note:

• If Relate finds more than one loyalty card assigned to the customer, the loyalty account information for the first card returned displays on the screen.

• CWSerenade does not display Inquiry type transactions on the screen.

• If the number of loyalty account transactions returned exceeds the Account Activity Lookup Limit setting in Relate, the system does not display any activity on the Display Loyalty Account History screen and instead displays an error message: Max results value defined in Relate has been exceeded.

How to display this screen: Select Loyalty History on the Display Loyalty Account Screen.

The information that displays on this screen in from Relate. Activity transactions display in descending activity date sequence.

Field	Description
Customer #	The number, company name, last name, and first name of the sold to customer registered in the Relate Loyalty program. Customer number: Numeric, 9 positions; display-only. Customer name: Alphanumeric, 40 positions; display-only.
Loyalty Card #	The loyalty card number assigned to the customer in Relate. The points and awards associated with this card display on the screen. From cardNumber in the Relate Loyalty Card Response.
Loyalty Account History
Activity Date	The date and time when the loyalty points or award coupon activity occurred, in MM/DD/YY HH:MM:SS format. Note: The time for loyalty points activity always displays as 12:00:00. Loyalty account: From businessDate in the Relate Loyalty Account History Response. Award account: From activityDateTime in the Relate Award Account History Response.
Activity	The type of activity that occurred against the card. Points Activity • Issue Points • Return Points • Issue Award • Void Points • Activated • Deactivated • Points Recovery • Earn Points • Expire Points • Points Balance Transfer • Change Level • Account Merge • Change Earn Date • Sustain Extension Awards Activity • Account Merge • Activate • Automatic Redeem • Deactivate • Issue Birthday Coupon • Issue Coupon • Issue Signup Coupon • Notify Coupon Expire • Redeem • Reset Expiration Date • Void Award Loyalty account: From transactionType in the Relate Loyalty Account History Response. Award account: From transactionType in the Relate Award Account History Response.
Award Effect	The effect of the awards activity. 0.00 displays if the transaction did not have a positive or negative effect on the awards amount or Relate returns 0 or no value for the awards activity. Positive Awards Activity A positive amount displays if the awards activity increased the awards amount on the loyalty card. • Activate • Issue Birthday Coupon • Issue Coupon • Issue Signup Coupon Negative Awards Activity Automatic Redeem A negative amount displays if the awards activity decreased the awards amount on the loyalty card. • Deactivate • Notify Coupon Expire • Redeem • Void Award No Effect (Positive or Negative) Awards Activity • Account Merge • Reset Expiration Date Note: This field is blank for loyalty account activity. From activityAmount in the Relate Award Account History Response.
Point Effect	The effect of the points activity. 0.00 displays if the transaction did not have a positive or negative effect on the number of points or Relate returns 0 or no value for the points activity. Activities that Add Points to the Loyalty Card • Issue Points • Activated • Deactivated (frozen balance) • Points Recovery • Earn Points • Points Balance Transfer Activities that Subtract Points from the Loyalty Card • Return Points • Issue Award • Void Points • Expire Points • Change Level Activities that have No Effect on Loyalty Points • Account Merge • Change Earn Date • Sustain Extension Note: This field is blank for award account activity. From numPoints in the Relate Loyalty Account History Response.
Pending	Yes displays if the points are pending being issued; otherwise this field is blank. Note: This field is blank for award account activity. From pendingFlag in the Relate Loyalty Account History Response.
Location ID	The location ID associated with the transaction. Loyalty account: From locationId in the Relate Loyalty Account History Response. Award account: From locationId in the Relate Award Account History Response.
Activity ID	The activity transaction ID assigned to the transaction in Relate. You can use this value as a reference for voiding a transaction in Relate or when writing a customer or order note. Loyalty account: From accountActivityId in the Relate Loyalty Account History Response. Award account: From awardTranId in the Relate Award Account History Response.

Reviewing the Customer’s Loyalty Card in Relate

Use the following screens in Relate to review the loyalty card assigned to the customer.

Customer Dashboard: The Card / Accounts section of the Customer Dashboard displays the card number generated for the customer and information about the loyalty program and award program associated with the customer’s card.

Card / Account Administration Screen: The Card / Account Association screen displays information about the card assigned to the customer.

• Selecting the Award account on the Card / Account Association screen displays basic information and activity for the award program associated with the card. You can click on a transaction to display additional information about the activity.

• Selecting the Loyalty account on the Card / Account Association screen displays basic information and activity for the loyalty program associated with the card. You can click on a transaction to display additional information about the activity.

Applying Points to a Customer’s Loyalty Card

Use the Issue Loyalty Points window to issue points to the loyalty program assigned to the customer’s card.

Issue Loyalty Points Window

How to display this screen: Select Issue Points on the Display Loyalty Account Screen. You must have authority to the Relate Loyalty Issue Awards/Points (J07) secured feature to advance to this window.

Field	Description
Loyalty Card #	The loyalty card number assigned to the customer in Relate to which you wish to issue points. This is the card number that displays on the Display Loyalty Account Screen. Display-only.
Points Amount	The number of points to issue. Updates the earned points balance for the customer’s loyalty account in Relate. Numeric, 7 positions with a 2-place decimal; Required.
Comments	An informational field to describe the points being issued. Alphanumeric, 1000 positions; Required.

To issue points:

1. Enter a Points Amount and Comments.

2. Click OK.

When you click OK:

1. CWSerenade generates a Relate Issue Points Request to Relate containing the loyalty card information and the loyalty points to issue.

2. Relate receives the request and adds the loyalty points to the customer’s loyalty account.

3. Relate generates a Relate Issue Points Response to CWSerenade.

4. CWSerenade generates a Relate Loyalty Card Request containing the customer’s card number.

5. Relate receives the Loyalty Card Request and returns a Relate Loyalty Card Response containing information on the customer’s card, current points balances and current award coupons.

6. CWSerenade returns you to the Display Loyalty Account Screen. The Current Points, Points Earned This Year, and Total Points Earned fields will include the new points issued.

Note: If a connection could not be made to Relate, the system displays an error message: Unable to connect to Relate.

Reviewing the issue points transaction in Relate: You can review the issue points transaction in Relate by selecting the Loyalty account on the Card / Account Association screen; activity for the loyalty program associated with the card displays at the bottom of the screen.

Click on the issue points transaction to advance to the Activity Detail window where you can review the details of the transaction.

Applying Coupons to a Customer’s Loyalty Card

Use the Issue Loyalty Coupon window to issue an award coupon to the award program assigned to the customer’s card.

Issue Loyalty Coupon Window

How to display this screen: Select Issue Awards on the Display Loyalty Account Screen. You must have authority to the Relate Loyalty Issue Awards/Points (J07) secured feature to advance to this window.

Field	Description
Loyalty Card #	The loyalty card number assigned to the customer in Relate. This is the card number that displays on the Display Loyalty Account Screen. Display-only.
Award Amount	The amount to assign to the award coupon. Updates the award balance for the customer’s award account in Relate. Numeric, 7 positions with a 2-place decimal; Required.
Expiration Date	The date when the award coupon expires. The expiration date you enter must be greater than the current date. If you do not define an expiration date, the award coupon uses the award program rules defined in Relate. Optional.
Comments	An informational field to describe the award coupon being issued. Alphanumeric, 1000 positions; Required.

To issue an award coupon:

1. Enter an Award Amount and Comments.

2. Optionally, enter an Expiration Date.

3. Click OK.

When you click OK:

1. CWSerenade generates a Relate Issue Coupon Request to Relate containing the loyalty card information and the award coupon amount to issue.

2. Relate receives the request and adds the award coupon for the specified amount to the customer’s award account.

3. Relate generates a Relate Issue Coupon Response to CWSerenade.

4. CWSerenade generates a Relate Loyalty Card Request containing the customer’s card number.

5. Relate receives the Loyalty Card Request and returns a Relate Loyalty Card Response containing information on the customer’s card, current points balances and current award coupons.

6. CWSerenade returns you to the Display Loyalty Account Screen. The Current Awards section of the screen will include the new award coupon issued.

Note: If a connection could not be made to Relate, the system displays an error message: Unable to connect to Relate.

Reviewing the issue coupon transaction in Relate: You can review the issue coupon transaction in Relate by selecting the Award account on the Card / Account Association screen; activity for the award program associated with the card displays at the bottom of the screen.

Click on the issue coupon transaction to advance to the Activity Detail window where you can review the details of the transaction.

Accruing Loyalty Points during Order Processing

Customers enrolled in the Relate loyalty program accrue points from completed purchases based on the program rules defined for the loyalty account in Relate.

When you send sales and return information to Relate in the Relate Post POSlog Transaction Message during the Relate Sales Feed, Relate:

• determines the loyalty account to accrue points against based on the customer passed in the Relate Post POSlog Transaction message.

• for sales transactions, increases the loyalty points on the customer’s loyalty account based on the program rules defined for the loyalty account in Relate.

• for return transactions, decreases the loyalty points on the customer’s loyalty account based on the program rules defined for the loyalty account in Relate.

Example: The issue rule defined for the customer’s loyalty program in Relate is to issue 1 point for each purchase dollar.

The customer has 155 earned points in Relate.

The customer places an order for $80.00.

When you run the Relate Sales Feed to update Relate with the sales and return information in the Relate Post POSlog Transaction Message, Relate increases the customer’s earned loyalty points to $235.00 (155 earned points + 80 points associated with sales).

The customer returns an item for $30.00.

When you run the Relate Sales Feed to update Relate with the sales and return information in the Relate Post POSlog Transaction Message, Relate decreases the customer’s earned loyalty points to $205.00 (235 earned points - 30 points associated with returns).

For more information: See Issue Rule in the Relate User Guide for more information on defining rules for a loyalty program.

Applying and Redeeming Relate Awards during Order Processing

You can apply an award amount to an order as a pro-rated merchandise discount and redeem the award amount applied to the order in Relate.

• Applying Awards during Interactive Order Entry

• Applying Awards during the Generic Order Interface (Order API)

• Combining the Loyalty Award Amount with Other Discounts

• Loyalty Award Discount Calculations

• Redeeming Awards during Order Processing

• If Communication Fails during Coupon Redemption

Note:

• You can apply an award amount to an order during order creation only; you cannot apply an award amount to an order in order maintenance.

• You can apply an award amount to a pre-order quote; however, the award amount is not redeemed until you convert the quote to an order. When you convert the quote to an order, the system allows you to change the award amount for the order before you accept the order and redeem the award amount. See Entering Pre-Order Quotes and Converting Quotes to Orders for more information about quote processing.

• Canceling an order or order line associated with a redeemed award amount does not increase a customer’s award balance. You must issue points or awards to the customer’s loyalty card manually; see Applying Points to a Customer’s Loyalty Card and Applying Coupons to a Customer’s Loyalty Card.

Applying Awards during Interactive Order Entry

Use the following steps to apply an award amount to an order during interactive Order Entry.

To apply an award amount to the order: On the Enter Loyalty Award Discount Window, enter the award amount to apply to the order and click OK. The system applies the award amount as a pro-rated merchandise discount. The discount is applied to all discountable order lines, including order lines that contain a price override reason code.

Note:

• The award amount does not apply to order lines that contain a non-discountable item or to sale items if the Exclude Sale Item When Prorating Discounts (I65) system control value is selected.

• If the entered award amount is greater than the discountable merchandise amount on the order, the system displays a message similar to the following: Award amount cannot exceed discountable merchandise.

• If the entered award amount is greater than the current awards balance for the loyalty card, the system displays a message similar to the following: Award amount cannot exceed remaining balance.

• If more than one order ship to exists on the order, the system applies the award amount to the selected order ship to only.

• The system updates the Relate Award Amount in the Order Ship To table with the award amount applied to the order.

• The system includes the award amount in the Discount field on the order.

Enter Loyalty Award Discount Window

Use this window to apply a coupon award amount as a pro-rated merchandise discount during order repricing.

Note: This window is available during order entry only; this window is not available during order maintenance.

How to display this screen: Select Reprice during order entry. The system displays the Enter Loyalty Award Discount Window if:

• the Use Relate Loyalty (M06) system control value is selected, and

• the Prorate Dollar Discounts and Coupons (D90) system control value is selected, and

• the Price Method for the source code on the order header is set to Reg Plus Reprice, and

• the sold to customer on the order is assigned to a loyalty card in Relate, and

• there are current awards associated with the customer’s loyalty account that are available for redemption.

Field	Description
Loyalty Card #	The loyalty card number assigned to the customer that is associated with the awards balance. Note: If the customer is assigned to more than one loyalty card in Relate, CWSerenade displays loyalty card information for the first card returned from Relate. Display-only.
Available awards balance	The total current awards balance for the loyalty card. Display-only.
Max award amount allowed	The maximum award amount that can be applied to the order. 0.00 displays if the order is not eligible for an award amount. Display-only.
Enter award amount to apply	The award amount to apply to the order as a pro-rated merchandise discount. A message similar to the following displays if you enter an award amount that is greater than the Available awards balance: Award amount cannot exceed remaining balance. A message similar to the following displays if you enter an award amount that is greater than the merchandise amount: Award amount cannot exceed discountable merchandise. Numeric, 7 positions with a 2-place decimal; Optional.

For more information: See Combining the Loyalty Award Amount with Other Discounts and Loyalty Award Discount Calculations for more information on how the award amount is applied to the order.

Applying Awards during the Generic Order Interface (Order API)

Use the following steps to apply a coupon award amount to a web order.

To apply an award amount to the order: Enter the award amount to apply to the order in the relate_award_amount tag included in the ShipTo element of the Inbound Order XML Message (CWORDERIN).

When CWSerenade processes the CWOrderIn message, the system determines if the order is eligible for the relate award amount.

Does the sold to customer have a loyalty card? The system verifies that the customer in Relate has a loyalty card.

If the Relate customer does not have a loyalty card, the system does not apply the award amount to the order and creates a record in the Order Transaction History table for the order indicating the award amount was not redeemed on the order. For example:

Date	Type	Transaction Note	Amount	User
3/06	SYSTEM UPDATE	Award amt not redeemed-card# not found	10.00	your default user

Is prorating dollar discounts and coupons enabled? The system applies the award amount defined in the relate_award_amount tag to the order only if the Prorate Dollar Discounts and Coupons (D90) system control value is selected.

Does the customer’s award balance cover the relate_award_amount? If the Relate customer has a loyalty card, the system determines if the award balance for the loyalty card is equal to or greater than the relate_award_amount entered on the order.

• If the award balance is 0.00 or less, the system does not apply the award amount to the order and creates a record in the Order Transaction History table for the order indicating the award amount was not redeemed on the order. For example:

Date	Type	Transaction Note	Amount	User
3/06	SYSTEM UPDATE	Award amt not redeemed-award balance=0	25.00	your default user

• If the award balance is less than the relate_award_amount, the system applies the available award balance to the order as a pro-rated merchandise discount. For example, if the relate_award_amount on the order is 25.00, but the award balance is $5.00, the system applies 5.00 to the order. The system creates a record in the Order Transaction History table for the order indicating the award amount that was redeemed on the order. For example:

Date	Type	Transaction Note	Amount	User
3/06	UPSELL PROMO	Total Prorated Order Level Discount	5.00	SFLYE
3/06	UPSELL PROMO	Award Redeemed-ID: S444399	5.00	SFLYE

• If the award balance is equal to or greater than the relate_award_amount, the system applies the entire award amount to the order as a pro-rated merchandise discount. The system creates a record in the Order Transaction History table for the order indicating the award amount that was redeemed on the order. For example:

Date	Type	Transaction Note	Amount	User
3/06	UPSELL PROMO	Total Prorated Order Level Discount	25.00	SFLYE
3/06	UPSELL PROMO	Award Redeemed-ID: S444399	25.00	SFLYE

The award amount is applied as a pro-rated merchandise discount to all discountable order lines, including order lines that contain a price override reason code.

The system updates the Relate Award Amount in the Order Ship To table with the award amount applied to the order.

Note:

• The award discount does not apply to order lines that contain a non-discountable item or to sale items if the Exclude Sale Item When Prorating Discounts (I65) system control value is selected.

• If the discountable merchandise amount is less than the entered award amount, the system decreases the Relate Award Amount in the Order Ship To table to match the discountable merchandise amount. If the discountable merchandise amount is 0.00 or a negative amount, the system updates the Relate Award Amount in the Order Ship To table to 0.00.

• If more than one order ship to exists on the order, the system applies the award amount to the selected order ship to only.

• If you send a subsequent Inbound Order XML Message (CWORDERIN) to complete a web order with payment information or update an order with errors, in order to apply the relate_award_amount to the order, the payment_only flag for the subsequent message must be set to N so that the Order API program deletes the existing order and recreates it using the information provided in the inbound message. It is important that the subsequent message include all information required to complete the order, or the information that was not included in the subsequent message will be lost.

For more information: See Combining the Loyalty Award Amount with Other Discounts and Loyalty Award Discount Calculations for more information on how the award amount is applied to the order.

Combining the Loyalty Award Amount with Other Discounts

The loyalty award amount is applied as a pro-rated merchandise discount AFTER order detail coupons and any line level promotions have been applied to the lines on the order.

If the merchandise amount after applying discounts is less than the loyalty award amount to apply to the order, the system automatically adjusts the loyalty award amount so that the amount is equal to the discounted merchandise amount.

Loyalty Award Discount Calculations

The system uses the following calculations to determine the award discount amount to apply to each order line.

The system calculates the Discount Percentage for each order line:

Order line extended amount after applying order detail coupons and line level promotions / order merchandise total = discount percentage

The system calculates the Unit Selling Price for each order line:

order line post-discount unit price - [(total award amount X discount % from above calculation) / line unit quantity] = unit selling price

Example 1: Relate Award Amount Only

An order has the following order lines:

• line 1: 1 unit for 50.00

• line 2: 1 unit for 10.00 (non-discountable)

• line 3: 1 unit for 10.00

The merchandise total is 70.00, 60.00 of which is discountable.

The system applies a 10.00 loyalty award amount to the order.

The system calculates the discount percentage for each eligible order line:

line 1: 50.00 / 60.00 = .833 x 100 = 83.33% discount percentage

line 3: 10.00 / 60.00 = .166 x 100 = 16.66% discount percentage

The system calculates the unit selling price for each order line:

line 1: 10.00 loyalty award amount x 83.33% discount percentage = 8.33

8.33 / 1 line unit quantity = 8.33

50.00 unit price - 8.33 = 41.67 unit selling price

line 3: 10.00 loyalty award amount x 16.66% discount percentage = 1.666

1.666 / 1 line unit quantity = 1.666

10.00 unit price - 1.66 = 8.33 unit selling price

The merchandise total after applying the loyalty award amount is 60.00 (line 1 41.67 + line 2 10.00 + line 3 8.33).

Example 2: Relate Award Amount with Line Level Promotion

An order has the following order lines:

• line 1: 1 unit for 50.00

• line 2: 1 unit for 10.00 (non-discountable)

• line 3: 1 unit for 10.00

The merchandise total is 70.00, 60.00 of which is discountable.

The system applies a 5.00 line level promotion and 10.00 loyalty award amount to the order.

The system calculates the discount percentage for each eligible order line:

line 1: 50.00 / 60.00 = .833 x 100 = 83.33% discount percentage

line 3: 10.00 / 60.00 = .166 x 100 = 16.66% discount percentage

The system calculates the unit selling price for each order line:

line 1: 15.00 (line level promotion + loyalty award amount) x 83.33% discount percentage = 12.50

12.50 / 1 line unit quantity = 12.50

50.00 unit price - 12.50 = 37.50 unit selling price

line 3: 15.00 line level promotion + loyalty award amount x 16.66% discount percentage = 2.50

2.50 / 1 line unit quantity = 2.50

10.00 unit price - 2.50 = 7.50 unit selling price

The merchandise total after applying the line level promotion and loyalty award amount is 55.00 (line 1 37.50 + line 2 10.00 + line 3 7.50).

Example 3: Relate Award Amount with Order Level Coupon

An order has the following order lines:

• line 1: 1 unit for 50.00

• line 2: 1 unit for 10.00 (non-discountable)

• line 3: 1 unit for 10.00

The merchandise total is 70.00, 60.00 of which is discountable.

The system applies a 50.00 loyalty award amount and 20.00 order level coupon to the order.

The system calculates the discount percentage for each eligible order line:

line 1: 50.00 / 60.00 = .833 x 100 = 83.33% discount percentage

line 3: 10.00 / 60.00 = .166 x 100 = 16.66% discount percentage

The system calculates the unit selling price for each order line:

line 1: 70.00 (loyalty award amount + 20.00 order level coupon) x 83.33% discount percentage = 58.33

58.33 / 1 line unit quantity = 58.33

50.00 unit price - 58.33 = -8.33 unit selling price (the system updates the price of the line to .00)

line 3: 70.00 (loyalty award amount + 20.00 order level coupon) x 16.66% discount percentage = 11.66

11.66 / 1 line unit quantity = 11.66

10.00 unit price - 11.66 = -1.66 unit selling price (the system updates the price of the line to .00)

The merchandise total after applying the order level coupon and loyalty award amount is 10.00 (line 1 .00 + line 2 10.00 + line 3 .00).

Since the merchandise amount after applying discounts is less than the loyalty award amount to apply to the order, the system automatically adjusts the loyalty award amount so that the amount is equal to the discounted merchandise amount; in this example, the system adjusts the loyalty award amount to 40.00 (20.00 coupon amount + 40.00 loyalty award amount = 60.00 total discount, which matches the merchandise amount that is eligible for discount).

Redeeming Awards during Order Processing

To redeem the award amount applied to the order: During the final order accept process, if an award amount is defined on the order, the system:

• sends a Relate Automatic Redeem Request to Relate for the award amount applied to the order.

• Relate redeems award coupons associated with the customer’s loyalty account until the award amount applied to the order has been reached.

• Relate redeems coupons whose expiration date is closest to expiring first.

• If the award coupon amount is greater than the amount to redeem, Relate subtracts the redeemed amount from the coupon; for example, if the award coupon amount is $100.00 and the amount to redeem is $15.00, Relate updates the award coupon amount to $85.00.

• Relate subtracts the amount to redeem from the customer’s award balance.

• Relate sends a Relate Automatic Redeem Response to CWSerenade.

• CWSerenade creates a record in the Order Transaction History table for the order indicating the award amount that was redeemed. For example:

Date	Type	Transaction Note	Amount	User
3/06	UPSELL PROMO	Total Prorated Order Level Discount	10.00	SFLYE
3/06	UPSELL PROMO	Award Redeemed-ID: S444399	10.00	SFLYE

You can display order history by selecting Order History in standard order inquiry or at the Work with Order Lines screen in Order Maintenance, or by selecting History in streamlined order inquiry. See the Display Order Line History Screen for more information.

• updates the Relate Award Amount in the Order Ship To table with the award amount applied to the order.

If communication fails: See If Communication Fails during Coupon Redemption.

Reviewing the automatic redeem transaction in Relate: You can review the automatic redeem transaction in Relate by selecting the Award account on the Card / Account Association screen; activity for the award program associated with the card displays at the bottom of the screen.

Click on the automatic redeem transaction to advance to the Activity Detail window where you can review the details of the transaction.

If Communication Fails during Coupon Redemption

If CWSerenade cannot connect with Relate to redeem the award amount applied to an order, the system places the order on RL Relate Communication Failure hold and writes an order transaction history message indicating the award amount was not automatically redeemed: SYSTEM UPDATE Relate Loyalty Award Redemption Failed 20.00, where 20.00 is the award amount applied to the order.

In this situation, you can either:

• log in to Relate and void coupons until the award amount applied to the order is covered. If the amount voided is greater than the amount needed for redemption (for example, the amount applied to the order was $20.00 and you voided a $25.00 award coupon), you can issue a new award coupon for the difference (in this example, $5.00).

• cancel the order and create a new order with the award amount, making sure communication with Relate during the redemption process is successful.

Relate APIs used in the Relate Loyalty Integration

The following Relate APIs are used to communicate with Relate during the Relate Loyalty integration:

• Relate Customer Services API v2.3: used to interactively create and update customer information between Relate and CWSerenade; see the Relate Customer Integration for more information.

• Relate Stored Value Card Transaction Services API v1.1: used to generate a new loyalty card and assigns it to a customer.

• Relate Card Services v2.1 API: used to retrieve loyalty and award summary information for all accounts attached to the specified loyalty card number.

• Relate Loyalty Account Services v1.2 API: used to:

• issue points to the loyalty account specified.

• retrieve all of the loyalty points account activity for the loyalty account specified.

• Relate Award Account Services v1.2 API: used to:

• issue an award coupon to the loyalty account specified.

• automatically redeem award coupons for the specified amount.

• retrieve all of the award coupon account activity for the loyalty account specified.

Relate log: CWSerenade logs the loyalty transactions passed between CWSerenade and Relate in the Relate (Loyalty) Log.

For more information: See the Relate Batch Processing and Web Services Guide for more information on the Relate API interface.

Relate Stored Value Card Transaction Services API v1.1

CWSerenade calls the Relate Stored Value Card Transaction Services API version 1.1 to generate the Relate generateCard Method.

The system uses the RELATE_CUSTOMER_SERVICE_PREFIX and RELATE_SVC_SERVICE_SUFFIX settings in the Relate Properties File to build the URL for communication with Relate.

Relate generateCard Method

The generateCard method generates a new loyalty card and assigns it to a customer.

When called? The system calls this method when you select Yes on the Customer Loyalty Registration Window.

Relate Loyalty Generate Card Request

CWSerenade sends the following information to Relate.

Information	Description
cardPrefix	The card prefix associated with the Loyalty Card Definition in Relate; this is the card prefix defined in the Relate Loyalty Card Prefix (M08) system control value.
cardSeries Sequence	The card series sequence number associated with the Loyalty Card Definition in Relate; this is the card series sequence number defined in the Relate Loyalty Card Series Sequence Number (M09) system control value.
locationId	The location ID associated with the loyalty program; this is the location defined in the Default Location for Sales Download (K69) system control value. If you do not define a location in the Default Location for Sales Download (K69) system control value, Relate uses the location defined in the Default Location ID setting in Conflate.
currencyId	The currency code defined in the Local Currency Code (A55) system control value.
customer	The relate customer ID to assign to the loyalty card; this is the Relate ID defined for the customer in the Customer Sold To table.

Sample Relate Loyalty Generate Card Request

Card prefix: 13132 Customer type: Card series seq: 03 Location ID: 69007 Curr: USD Customer type: <?xml version="1.0" encoding="UTF-8"?>

</void>

</object>

</java>

Relate Loyalty Generate Card Response

The generateCard method returns a GenCardResponseContainerType element. Relate sends the following information to CWSerenade.

Information	Description
dateTime	The date and time when the response was generated.
cardSeries
CardPrefix	The card prefix associated with the Loyalty Card Definition in Relate.
CardSeries Sequence	The card series sequence number associated with the Loyalty Card Definition in Relate.
Instrument
CardName	The name of the Loyalty Card Definition in Relate.
CardNumber	The loyalty card number assigned to the customer in Relate.
BatchNumber	The batch number associated with the loyalty card in Relate.
Customer
CustomerID	The Relate customer ID assigned to the loyalty card.

Sample Relate Loyalty Generate Card Response

<com.dtv.csx.webservices.svc.v1__1.GenCardResponseContainerType>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>13</orig__day>

<orig__hour>11</orig__hour>

<orig__minute>44</orig__minute>

<orig__second>29</orig__second>

<orig__timezone>-2147483648</orig__timezone>

</dateTime>

<cardName>Benoit Loyalty Cards</cardName>

</program>

</instrument>

</customer>

</cardSeries>

</com.dtv.csx.webservices.svc.v1__1.GenCardResponseContainerType>

Relate Card Services v2.1 API

CWSerenade calls the Relate Card Services version 2.1 API to generate the Relate getCardInquiryData Method.

The system uses the RELATE_CUSTOMER_SERVICE_PREFIX and RELATE_CARD_SERVICE_SUFFIX settings in the Relate Properties File to build the URL for communication with Relate.

Relate getCardInquiryData Method

The getCardInquiryData method retrieves loyalty and award summary information for all accounts attached to the specified loyalty card number.

When called? The system calls this method when you:

• advance to the Display Loyalty Account Screen to review the customer’s loyalty points and award coupons.

• advance to the Customer Selection Screen; this screen displays the customer’s loyalty card number, current earned points, and current awards balance.

Relate Loyalty Card Request

CWSerenade sends the following information to Relate.

Variable	Description
cardNumber	The loyalty card number assigned to the customer whose loyalty and award information is retrieved from Relate.
currencyCode	The default currency defined in the Local Currency Code (A55) system control value.
transactionStoreId	The store ID associated with the loyalty program; this is the location defined in the Default Location for Sales Download (K69) system control value. If you do not define a location in the Default Location for Sales Download (K69) system control value, Relate uses the location defined in the Default Location ID setting in Conflate.

Sample Relate Loyalty Card Request

Relate Loyalty Card Inquiry Request: Card#: 8974903132247915 Curr: USD Store ID: 69007

Relate Loyalty Card Response

The getCardInquiry method returns a CardInquiryResponse class object. Relate sends the following information to CWSerenade.

Element	Description
ResponseStatus
DateTime	The date and time of the inquiry.
Instrument The Instrument element contains card information.
CardNumber	The loyalty card number assigned to the customer whose loyalty and award information you wish to review.
CardSerialNumber	The serial number assigned to the loyalty card in Relate.
CardExpiration Date	The date the card expires, if any.
LoyaltyAccount The LoyaltyAccount element contains the loyalty accounts associated with the card.
LoyaltyAccountID	The ID for the loyalty account in Relate.
LoyaltyProgram	The ID and name of the loyalty program associated with the account in Relate.
LoyaltyProgram Level	The ID and name of the current level of the loyalty program to which the loyalty account belongs.
PointsBalance	The current points balance for the loyalty account.
CardInqPoints Entry	The current points for the loyalty card for the following types of points: • EARNED: The amount of points earned. • ESCROW: The amount of escrow points. • BONUS: The amount of bonus points. • TYD: The total year to date points. • LTD: The total life to date points.
AwardAccount The AwardAccount element contains the award accounts associated with the card.
AwardAccountID	The award account ID associated with the loyalty card in Relate.
awardProgram	The ID and name of the award program in Relate.
CouponList	The award coupons associated with the loyalty card in Relate. For each coupon: • Amount: The amount of the coupon. • ID: The coupon ID. • ExpirationDate: The date when the coupon expires, if any.
Customer
CustomerID	The Relate customer ID associated with the loyalty card.

Sample Relate Loyalty Card Response

<com.dtv.csx.webservices.card.v2__1.CardInquiryResponse>

<com.dtv.csx.webservices.card.v2__1.CardInqLoyaltyAccount>

<value>Base Loyalty</value>

</loyaltyProgram>

</loyaltyProgramLevel>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>EARNED</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>ESCROW</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>BONUS</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</points>

</pointsBalance>

</com.dtv.csx.webservices.card.v2__1.CardInqLoyaltyAccount>

</loyaltyAccount>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardAccount>

<value>Base Award</value>

</awardProgram>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</coupon>

<type>BalanceAmounts</type>

</couponList>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardAccount>

</awardAccount>

</instrument>

</customer>

</com.dtv.csx.webservices.card.v2__1.CardInquiryResponse>

Relate Loyalty Account Services v1.2 API

CWSerenade calls the Relate Loyalty Account Services version 1.2 API to generate the following methods:

• Relate issuePoints Method

• Relate getLoyaltyAccountHistory Method

The system uses the RELATE_CUSTOMER_SERVICE_PREFIX and RELATE_LOYALTY_SERVICE_SUFFIX settings in the Relate Properties File to build the URL for communication with Relate.

Relate issuePoints Method

The issuePoints method issues points to the loyalty account specified and creates a retail transaction ID for the transaction.

When called? The system calls this method when you click OK on the Issue Loyalty Points Window.

Relate Issue Points Request

CWSerenade sends the following information to Relate.

Variable	Description
lylAccountId	The loyalty account ID associated with the issued points.
transactionStoreId	The store ID where the transaction was performed; this is the location defined in the Default Location for Sales Download (K69) system control value. If you do not define a location in the Default Location for Sales Download (K69) system control value, Relate uses the location defined in the Default Location ID setting in Conflate.
pointsAmount	The number of points being issued.
clientComments	Informational comments associated with the issue points transaction.

Sample Relate Issue Points Request

LoyaltyAcctID: 40544 Store ID: 69007 Points Amt: 1200.00 Comments: issue 1200 loyalty points on 3/4/14 at 3:25

Relate Issue Points Response

The issuePoints method returns a loyaltyActivity class object. Relate sends the following information to CWSerenade.

Element	Description
accountActivityId	The Relate activity transaction number for issuing points to the loyalty card.
accountId	The loyalty account ID associated with the issued points.
activityDatetime	The date and time when the activity occurred.
activityTypeCode	Issue defaults.
bonusPoints Balance	The bonus points balance at the time of the issue points transaction.
earnedPoints Balance	The earned points balance at the time of the issue points transaction.
escrowPoints Balance	The escrow points balance at the time of the issue points transaction.
escrowTransferred Flag	Indicates whether escrow points were transferred as part of the issue points transaction.
loyaltyRuleId	The ID for the loyalty rule used in the issue points transaction.
ltdPointsBalance	The current life to date points balance for the account at the time of the issue points transaction.
pointsAmount	The confirmed points amount issued to the loyalty card.
pointsMethodType Code	The code indicating the method uses for points calculations.
pointsOriginally Requested	The number of points that were defined in the issue points transaction.
retailTransaction BusinessDate	The business date when the issue points transaction occurred.
ytdPointsBalance	The current year to date points balance for the account at the time of the issue points transaction.

Sample Relate Issue Points Response

<com.dtv.csx.webservices.loyalty.v1__2.LoyaltyActivity>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>4</orig__day>

<orig__hour>15</orig__hour>

<orig__minute>25</orig__minute>

<orig__second>11</orig__second>

<orig__fracSeconds>0.074</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</activityDatetime>

<activityTypeCode>Issue</activityTypeCode>

<escrowTransferredFlag>false</escrowTransferredFlag>

</com.dtv.csx.webservices.loyalty.v1__2.LoyaltyActivity>

Relate getLoyaltyAccountHistory Method

The getLoyaltyAccountHistory method retrieves all of the loyalty points account activity for the loyalty account specified. This method is specific to the loyalty points transactions associated with the loyalty card and does not include award coupons.

When called? The system calls this method when you select Loyalty History on the Display Loyalty Account Screen. All loyalty points activity returned in the Relate Loyalty Account History Response except Inquiry activity displays on the Display Loyalty Account History Screen.

Note: If the number of records available in the Sample Loyalty Account History Response exceeds the maximum setting in Relate, a relateExceptionCode will be in the response with a value of MAXIMUM_LOOKUP_RESULTS_ERROR and the response will not include any history. If this occurs, Serenade displays a message similar to the following, where 400 is the maximum setting defined in Relate: Max results exceeded of: 400.

Relate Loyalty Account History Request

CWSerenade sends the following information to Relate.

Variable	Description
cardNumber	The loyalty card number whose loyalty points account activity you wish to review.
currencyCode	The default currency defined in the Local Currency Code (A55) system control value.
historyStartDate	The start date of the loyalty points account activity to return in the Relate Loyalty Account History Response, in YYYY-MM-DD format. The start date defaults to the current date minus 2 years in order to get 2 year’s worth of loyalty points account activity; for example, if the current date is 3/4/2014, the start date will be 3/4/2012.
historyEndDate	The end date of the loyalty points account activity to return in the Relate Loyalty Account History Response, in YYYY-MM-DD format. The end date defaults to the current date.

Sample Relate Loyalty Account History Request

Card#: 5228538909752630 Curr: USD Start date: 2012-03-04T16:18:36.002-05:00 End date: 2014-03-04T16:18:36.018-05:00

Relate Loyalty Account History Response

The getLoyaltyAccountHistory method returns a CardInquiryResponse class object. Relate sends the following information to CWSerenade.

Element	Description
CardInqResponseStatus The status of the inquiry response.
dateTime	The date and time of the inquiry.
status	OK defaults if there are no problems with the records in the reponse.
CardInqInstrument Card information.
CardNumber	The loyalty card number associated with the loyalty points account activity.
CardSerialNumber	The serial number assigned to the loyalty card in Relate.
CardExpiration Date	The date the card expires, if any.
CardInqLoyaltyAccount
LoyaltyAccountID	The ID for the loyalty account in Relate.
LoyaltyProgram	The ID and name of the loyalty program associated with the account.
LoyaltyProgram Level	The ID and name of the current level of the loyalty program to which the loyalty account belongs.
PointsBalance	The current points balance for the account.
CardInqPoints Entry	The current points for the loyalty card for the following types of points: • EARNED: The amount of points earned. • ESCROW: The amount of escrow points. • BONUS: The amount of bonus points. • TYD: The total year to date points. • LTD: The total life to date points.
LoyaltyActivityList A list of loyalty account activities performed.
TransactionType	The type of transaction activity performed. The Display Loyalty Account History Screen displays all types of activity except Inquiry.
NumPoints	The amount of points that were applied as a negative or positive to the loyalty card.
PendingFlag	true defaults if the points are pending being issued; otherwise, false defaults.
AccountActivityId	The Relate assigned activity transaction number for the record.
LocationId	The location ID where the transaction was performed.
CreateUser	The ID of the user who performed the activity.
UpdateUser	The ID of the user who updated the activity.
VoidFlag	true defaults if the activity has been voided; otherwise, false defaults.
EscrowPoints Balance	Escrow points balance for the account at the time of the activity.
EarnedPoints Balance	Earned points balance for the account at the time of the activity.
BonusPoints Balance	Bonus points balance for the account at the time of the activity.
Comments	Informational comments associated with the activity.
BusinessDate	The business date on which the activity occurred.
RuleName	The rule that governed the points in the activity.
ReferenceTranId	The ID for the transaction referred to by the activity.
RetailTransaction Id	The retail transaction ID associated with the activity.
CardInqCustomer The customer associated with the card.
CustomerID	The Relate customer ID associated with the loyalty card.

Sample Loyalty Account History Response

<com.dtv.csx.webservices.loyalty.v1__2.CardInquiryResponse>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>4</orig__day>

<orig__hour>16</orig__hour>

<orig__minute>18</orig__minute>

<orig__second>36</orig__second>

<orig__fracSeconds>0.000</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</dateTime>

</responseStatus>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyAccount>

<value>Base Loyalty</value>

</loyaltyProgram>

<value>Silver</value>

</loyaltyProgramLevel>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<type>EARNED</type>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<type>ESCROW</type>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<type>BONUS</type>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqPointsEntry>

</points>

</pointsBalance>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

<transactionType>Inquiry</transactionType>

<pendingFlag>false</pendingFlag>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>4</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

<transactionType>Issue</transactionType>

<pendingFlag>false</pendingFlag>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<comments>250 points issued to loyalty card # 5228538909752630 on 3/4/14</comments>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>4</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

<ruleName>Default Issue Rule</ruleName>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

<com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

<transactionType>Activate</transactionType>

<pendingFlag>false</pendingFlag>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>4</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyActivity>

</loyaltyActivity>

</loyaltyActivityList>

</com.dtv.csx.webservices.loyalty.v1__2.CardInqLoyaltyAccount>

</loyaltyAccount>

</instrument>

</customer>

</com.dtv.csx.webservices.loyalty.v1__2.CardInquiryResponse>

Relate Award Account Services v1.2 API

CWSerenade calls the Relate Award Account Services version 1.2 API to generate the following methods:

• Relate issueCoupon Method

• Relate automaticRedeem Method

• Relate getAwardAccoutHistory Method

The system uses the RELATE_CUSTOMER_SERVICE_PREFIX and RELATE_LOYALTY_AWARD_SERVICE_SUFFIX settings in the Relate Properties File to build the URL for communication with Relate.

Relate issueCoupon Method

The issueCoupon method issues an award coupon to the loyalty account specified and creates a retail transaction ID for the transaction.

When called? The system calls this method when you click OK on the Issue Loyalty Coupon Window.

Relate Issue Coupon Request

CWSerenade sends the following information to Relate.

Variable	Description
awardAccountId	The award account ID associated with the loyalty card.
storeId	The store ID where the transaction was performed; this is the location defined in the Default Location for Sales Download (K69) system control value. If you do not define a location in the Default Location for Sales Download (K69) system control value, Relate uses the location defined in the Default Location ID setting in Conflate.
userId	SERENADE + the user ID of the CWSerenade user that issued the coupon; for example, EXAMPLE.
cardNumber	The loyalty card number associated with the award coupon.
currencyId	The default currency defined in the A55 system control value.
amount	The amount of the award coupon to issue to the loyalty card.
expirationDate	The date the award coupon expires.
comments	Informational comments about the issued award coupon.

Sample Relate Issue Coupon Request

AwardAcctID: 40545 Info: <?xml version="1.0" encoding="UTF-8"?>

</void>

</void>

</void>

</void>

<string>EXAMPLE</string>

</void>

</object>

</java>

Instrument: <?xml version="1.0" encoding="UTF-8"?>

</void>

</void>

</void>

</object>

</java>

Curr: USD Amt: 500.00

Relate Issue Coupon Response

The issueCoupon method returns an awardTransactionResult class object. Relate sends the following information to CWSerenade.

Element	Description
awardTransaction Id	The Relate activity transaction number for issuing an award coupon to the loyalty card.
accountId	The award account ID associated with the award coupon.
amount	The confirmed award coupon amount issued to the loyalty card.
couponId	The award coupon ID generated by Relate for the issued award coupon.
expirationDate	The date when the award coupon expires.

Sample Relate Issue Coupon Response

<com.dtv.csx.webservices.award.v1__2.AwardTransactionResult>

<com.dtv.csx.webservices.award.v1__2.AwardTransactedAccount>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>31</orig__day>

<orig__hour>0</orig__hour>

<orig__minute>0</orig__minute>

<orig__second>0</orig__second>

<orig__timezone>-240</orig__timezone>

</expirationDate>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>31</orig__day>

<orig__hour>0</orig__hour>

<orig__minute>0</orig__minute>

<orig__second>0</orig__second>

<orig__timezone>-240</orig__timezone>

</expirationDate>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

</couponBalances>

<com.dtv.csx.webservices.award.v1__2.AwardCoupon>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>31</orig__day>

<orig__hour>0</orig__hour>

<orig__minute>0</orig__minute>

<orig__second>0</orig__second>

<orig__timezone>-240</orig__timezone>

</expirationDate>

</com.dtv.csx.webservices.award.v1__2.AwardCoupon>

</transactedCoupons>

</com.dtv.csx.webservices.award.v1__2.AwardTransactedAccount>

</transactedAccounts>

</com.dtv.csx.webservices.award.v1__2.AwardTransactionResult>

Relate automaticRedeem Method

The automaticRedeem method automatically redeems award coupons for the specified amount and creates a retail transaction ID for the transaction. Award coupons with the closet expiration date are redeemed first.

When called? The system calls this method during the final order accept for an order that contains a loyalty award coupon discount; see Applying and Redeeming Relate Awards during Order Processing.

Relate Automatic Redeem Request

CWSerenade sends the following information to Relate.

Variable	Description
awardAccountId	The award account ID associated with the loyalty card.
storeId	The store ID where the transaction was performed; this is the location defined in the Default Location for Sales Download (K69) system control value. If you do not define a location in the Default Location for Sales Download (K69) system control value, Relate uses the location defined in the Default Location ID setting in Conflate.
userId	SERENADE + the user ID of the CWSerenade user that issued the coupon; for example, EXAMPLE.
cardNumber	The loyalty card number to redeem the award coupon against.
currencyId	The default currency defined in the A55 system control value.
amount	The amount of the award coupon to redeem against the loyalty card.
comments	Informational comments about the redeemed award coupon. A message similar to the following defaults if the award coupon was redeemed through the Order API: Awards redeemed through Serenade Order API. A message similar to the following defaults if the award coupon was redeemed through interactive Order Entry: Awards redeemed through Serenade Order Entry.

Sample Relate Automatic Redeem Request

AwardAcctID: 40624 Info: <?xml version="1.0" encoding="UTF-8"?>

</void>

</void>

</void>

</void>

<string>EXAMPLE</string>

</void>

</object>

</java>

Instrument: <?xml version="1.0" encoding="UTF-8"?>

</void>

</void>

</void>

</object>

</java>

Curr: USD Amt: 10.00 Comments: Awards redeemed through Serenade Order Entry

Relate Automatic Redeem Response

The automaticRedeem method returns a CardInquiryResponse class object. Relate sends the following information to CWSerenade.

Element	Description
cardNumber	The loyalty card number redeemed against.
cardSerialNumber	The serial number assigned to the loyalty card in Relate.
loyaltyAccountId	The ID for the loyalty account in Relate.
loyaltyProgram	The ID and name of the loyalty program associated with the account in Relate.
LoyaltyProgram Level	The ID and name of the current level of the loyalty program to which the loyalty account belongs.
PointsBalance	The current points balance for the account.
CardInqPoints Entry	The current points for the loyalty card for the following types of points: • EARNED: The amount of points earned. • ESCROW: The amount of escrow points. • BONUS: The amount of bonus points. • TYD: The total year to date points. • LTD: The total life to date points.
awardAccountId	The ID for the award account in Relate.
awardProgram	The ID and name of the award program associated with the account in Relate.
coupon amount	The amount of awards that were applied as a negative or positive to the loyalty card.
coupon ID	The ID of the coupon associated with the award coupon activity.
customerID	The Relate customer ID associated with the loyalty card.

Sample Relate Automatic Redeem Response

<com.dtv.csx.webservices.card.v2__1.CardInquiryResponse>

<com.dtv.csx.webservices.card.v2__1.CardInqLoyaltyAccount>

<value>Base Loyalty</value>

</loyaltyProgram>

<value>Silver</value>

</loyaltyProgramLevel>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>EARNED</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>ESCROW</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<type>BONUS</type>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

<com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</com.dtv.csx.webservices.card.v2__1.CardInqPointsEntry>

</points>

</pointsBalance>

</com.dtv.csx.webservices.card.v2__1.CardInqLoyaltyAccount>

</loyaltyAccount>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardAccount>

<value>Base Award</value>

</awardProgram>

<com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardCoupon>

</coupon>

<type>BalanceAmounts</type>

</couponList>

</com.dtv.csx.webservices.card.v2__1.CardInqAwardAccount>

</awardAccount>

</instrument>

</customer>

</com.dtv.csx.webservices.card.v2__1.CardInquiryResponse>

Relate getAwardAccoutHistory Method

The getAwardAccountHistory method retrieves all of the award coupon account activity for the loyalty account specified. This method is specific to the award coupon transactions associated with the loyalty card and does not include loyalty points.

When called? The system calls this method when you select Loyalty History on the Display Loyalty Account Screen.

Note: If the number of records available in the Relate Award Account History Response exceeds the maximum setting in Relate, a relateExceptionCode will be in the response with a value of MAXIMUM_LOOKUP_RESULTS_ERROR and the response will not include any history. If this occurs, Serenade displays a message similar to the following, where 400 is the maximum setting defined in Relate: Max results exceeded of: 400.

Relate Award Account History Request

CWSerenade sends the following information to Relate.

Variable	Description
cardNumber	The loyalty card number whose loyalty award coupon account activity you wish to review.
currencyCode	The default currency defined in the A55 system control value.
historyStartDate	The start date of the loyalty award coupon account activity to return in the Relate Loyalty Account History Response, in YYYY-MM-DD format. The start date defaults to the current date minus 2 years in order to get 2 year’s worth of loyalty points account activity; for example, if the current date is 3/4/2014, the start date will be 3/4/2012.
historyEndDate	The end date of the loyalty award coupon account activity to return in the Relate Loyalty Account History Response, in YYYY-MM-DD format. The end date defaults to the current date.

Sample Relate Award Account History Request

Card#: 8903177188783483 Curr: USD Start date: 2012-03-05T09:46:43.580-05:00 End date: 2014-03-05T09:46:43.580-05:00

Relate Award Account History Response

The getAwardAccountHistory method returns a CardInquiryResponse. Relate sends the following information to CWSerenade.

Element	Description
status	OK defaults if there are no problems with the records in the reponse.
cardNumber	The loyalty card number associated with the loyalty award coupon account activity.
cardSerialNumber	The serial number assigned to the loyalty card in Relate.
awardAccountId	The ID for the award account in Relate.
awardProgram	The ID and name of the award program associated with the account in Relate.
coupon amount	The amount of awards that were applied as a negative or positive to the loyalty card.
coupon ID	The ID of the coupon associated with the award coupon activity.
transactionType	The type of transaction activity performed. The Display Loyalty Account History Screen displays all types of activity except Inquiry.
awardTransaction ID	The Relate assigned activity transaction number for the record.
locationID	The location ID where the transaction was performed.
createUser	The ID of the user that performed the activity.
voidFlag	true defaults if the activity has been voided; otherwise, false defaults.
comments	Informational comments associated with the activity.
retailTransactionId	The retail transaction ID associated with the activity.
activityDateTime	The date when the activity occurred.
activityAmount	The amount of awards that were applied as a negative or positive to the loyalty card.
requestedAmount	The amount of awards that were applied as a negative or positive to the loyalty card.
couponId	The ID of the coupon associated with the award coupon activity.
reasonCode	The reason for the award coupon activity.

Sample Award Account History Response

<com.dtv.csx.webservices.award.v1__2.CardInquiryResponse>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>9</orig__hour>

<orig__minute>46</orig__minute>

<orig__second>43</orig__second>

<orig__fracSeconds>0.000</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</dateTime>

</responseStatus>

<com.dtv.csx.webservices.award.v1__2.CardInqAwardAccount>

<value>Base Award</value>

</awardProgram>

<com.dtv.csx.webservices.award.v1__2.CardInqAwardCoupon>

</com.dtv.csx.webservices.award.v1__2.CardInqAwardCoupon>

</coupon>

<type>BalanceAmounts</type>

</couponList>

<com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

<transactionType>Inquiry</transactionType>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>9</orig__hour>

<orig__minute>46</orig__minute>

<orig__second>39</orig__second>

<orig__fracSeconds>0.000</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</activityDateTime>

</com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

<com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

<transactionType>IssueCoupon</transactionType>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>9</orig__hour>

<orig__minute>35</orig__minute>

<orig__second>10</orig__second>

<orig__fracSeconds>0.000</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</activityDateTime>

<reasonCode>SYSTEM</reasonCode>

</com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

<com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

<transactionType>ActivateAccount</transactionType>

<createUser>EXAMPLE</createUser>

<voidFlag>false</voidFlag>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>-2147483648</orig__hour>

<orig__minute>-2147483648</orig__minute>

<orig__second>-2147483648</orig__second>

<orig__timezone>-300</orig__timezone>

</businessDate>

<orig__year>2014</orig__year>

<orig__month>3</orig__month>

<orig__day>5</orig__day>

<orig__hour>9</orig__hour>

<orig__minute>35</orig__minute>

<orig__second>10</orig__second>

<orig__fracSeconds>0.000</orig__fracSeconds>

<orig__timezone>-300</orig__timezone>

</activityDateTime>

<reasonCode>SYSTEM</reasonCode>

</com.dtv.csx.webservices.award.v1__2.CardInqAwardAccountActivity>

</awardAccountActivity>

</awardAccountActivityList>

</com.dtv.csx.webservices.award.v1__2.CardInqAwardAccount>

</awardAccount>

</instrument>

</customer>

</com.dtv.csx.webservices.award.v1__2.CardInquiryResponse>

Van Delivery Processing

Contents

SCVs

Search

Glossary

Reports

Database

Solutions

XML

Index

Relate Customer Wish List Integration

OE01_30 Serenade 5.0 March 2015