Loyalty Account Services Version 1.2

46 Loyalty Account Services Version 1.2

This chapter provides the information necessary to send messages contained in Version 1.2 of the Loyalty Account Services API. Information can be obtained using the Web Service Description Language (WSDL) in conjunction with a Simple Object Access Protocol (SOAP), XML Schema, and various methods contained in the classes of the API to provide the web service.

The URL for the Loyalty Account Services WSDL is:

https://<servername>:<portNumber>/ws/v1_2/LoyaltyAccountServices?wsdl

Where <servername> is the name or address of the server. The default port number is 443.

The information presented describes the methods and classes.

The format of the method and any arguments is shown along with an explanation of what the method does and any other information that is necessary to use the method properly. If an argument is shown in dark blue, it is a class and the class name is a link to a description of the class and its attributes.

The class section shows the attributes of the classes along with an explanation of each attribute and when necessary, when they are used.

Note:

Authentication is required. See Introduction for information on creating and implementing an authentication key.

Methods

This section presents the methods used in Version 1.2 of the Loyalty Account Services.

calculateProformaPoints

POSLogType calculateProformaPoints (
                  TransactionType transaction)
          throws RelateProcessingException

Variable	Required?	Description
transaction	Optional	Transaction information for which the proforma points will be calculated.

The calculateProformaPoints method processes the line items from a sales transaction and calculates the loyalty points that would be earned on a transaction.

However, no sales data or loyalty point information is saved at this time.

This method returns a POSLogType class object.

getLoyaltyAccountHistory

CardInquiryResponse getLoyaltyAccountHistory (
                                 string cardNumber,
                                 boolean cardSwiped,
                                 string authenticationData,
                                 string currencyCode,
                                 dateTime historyStartDate,
                                 dateTime historyEndDate)
                throws RelateProcessingException

Variable	Required?	Description
cardNumber	Optional	Card number of the loyalty card.
cardSwiped	Optional	Indicates whether the card was swiped.
authenticationData	Optional	Authentication data for the loyalty account.
currencyCode	Optional	ID code for the currency used by the loyalty account.
historyStartDate	Optional	Start of the date range.
historyEndDate	Optional	End of the date range.

The getLoyaltyAccountHistory method retrieves loyalty account activity information for all loyalty cards and actions matching the entered search criteria.

This method returns a CardInquiryResponse class object.

getLoyaltyTransactionDetail

loyaltyActivityList getLoyaltyTransactionDetail (
                         string cardNumber,
                         string transactionStoreId,
                         string transactionRegisterNumber,
                         dateTime transactionBusinessDate,
                         string transactionSequenceNumber,
                         string transactionLookupStoreId,
                         string transactionLookupRegisterNumber,
                         dateTime transactionLookupBusinessDate,
                         string transactionLookupSequenceNumber,
                         string clientUserId,
                         string clientComments)
                throws RelateProcessingException

Variable	Required?	Description
cardNumber	Optional	Card number used in the transaction.
transactionStoreId	Optional	ID of the location where the lookup is being performed.
transactionRegisterNumber	Optional	Number of the register where the lookup is being performed.
transactionBusinessDate	Optional	Business date of the lookup request.
transactionSequence Number	Optional	Sequence number of the transaction performing the lookup.
transactionLookupStore Id	Optional	ID of the location where the transaction being looked up was performed.
transactionLookupRegisterNumber	Optional	Number of the register where the transaction was performed.
transactionLookupBusinessDate	Optional	Business date of the transaction being looked up.
transactionLookupSequenceNumber	Optional	Sequence number of the transaction being looked up.
clientUserId	Optional	ID of the POS user performing the lookup.
clientComments	Optional	Additional comments.

The getLoyaltyTransactionDetail method retrieves detailed information about a loyalty activity.

This method returns a loyaltyActivityList class.

issuePoints

loyaltyActivity issuePoints (
                                  string cardNumber,
                                  long lylAccountId,
                                  string transactionStoreId,
                                  string transactionRegisterNumber,
                                  dateTime transactionBusinessDate,
                                  string transactionSequenceNumber,
                                  decimal pointsAmount,
                                  long issueRuleId,
                                  periodType escrowPeriodTypeCode,
                                  int escrowPeriods,
                                  boolean bonusFlag,
                                  string clientUserId,
                                  string clientComments,
                                  string reasonCode)
          throws RelateProcessingException

Variable	Required?	Description
cardNumber	Optional	Card number used in the transaction.
lylAccountId	Required	ID of the loyalty account being issued the points.
transactionStoreId	Optional	ID of the location where the transaction was performed.
transactionRegisterNumber	Optional	Number of the register where the transaction was performed.
transactionBusinessDate	Optional	Business date of the transaction.
transactionSequenceNumber	Optional	Sequence number of the transaction.
pointsAmount	Optional	Number of points to be issued.
issueRuleId	Optional	ID of the rule issuing the points.
escrowPeriodTypeCode	Optional	Code identifying the type of escrow period type.
escrowPeriods	Optional	Number of periods that the points will be placed in escrow.
bonusFlag	Optional	Indicates whether the points are bonus points.
clientUserId	Optional	ID of the POS user performing the transaction.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for issuing the points.

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

This method does not prevent you from issuing points more often than specified for the Issue Rule when the Calculation Type is set to The number of marketing engagements.

This method returns a loyaltyActivity class object.

moveLoyaltyLevel

long moveLoyaltyLevel (
                        string cardNumber,
                        long lylAccountId,
                        int targetLylProgramLevelId,
                        decimal pointsCost,
                        string retailLocationId,
                        string clientUserId,
                        string clientComments,
                        string reasonCode)
        throws RelateProcessingException

Variable	Required?	Description
cardNumber	Optional	Card number associated with the transaction.
lylAccountId	Optional	ID of the loyalty account.
targetLylProgramLevelId	Optional	ID of the loyalty level to which the account is being moved.
pointsCost	Optional	Points cost of the move.
retailLocationId	Optional	ID of the location where the move is being performed.
clientUserId	Optional	ID of the POS user performing the move.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for the loyalty level move.

The moveLoyaltyLevel method moves a loyalty account from one loyalty level to another.

This method returns a long value.

recoverLoyaltyPoints

loyaltyTransactionSummary[] recoverLoyaltyPoints (
                                 string retailTransactionId,
                                 string cardNumber,
                                 string clientUserId,
                                 string clientComments,
                                 string reasonCode)
                            throws RelateProcessingException

Variable	Required?	Description
retailTransactionId	Optional	ID of the loyalty transaction.
cardNumber	Optional	Card number associated with the transaction.
clientUserId	Optional	ID of the POS user recovering the loyalty points.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for recovering the loyalty points.

The recoverLoyaltyPoints method issues, to a customer for a specific transaction, loyalty points that were earned but not issued at the time of the transaction.

This method returns an array of loyaltyTransactionSummary class objects.

redeemPointsForAward

loyaltyActivity redeemPointsForAward (
                        string cardNumber,
                        long lylAccountId,
                        string transactionStoreId,
                        string transactionRegisterNumber,
                        dateTime transactionBusinessDate,
                        string transactionSequenceNumber,
                        decimal pointsAmount,
                        long awardRuleId,
                        string clientUserId,
                        string clientComments,
                        string reasonCode)
              throws RelateProcessingException

Variable	Required?	Description
cardNumber	Optional	Card number used in the transaction.
lylAccountId	Optional	ID of the loyalty account for which the points are being redeemed.
transactionStoreId	Optional	ID of the location where the transaction was performed.
transactionRegisterNumber	Optional	Number of the register where the transaction was performed.
transactionBusinessDate	Optional	Business date of the transaction.
transactionSequenceNumber	Optional	Sequence number of the transaction.
pointsAmount	Optional	Number of points being redeemed.
awardRuleId	Optional	ID of the award rule used.
clientUserId	Optional	ID of the POS user performing the transaction.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for the redemption.

The redeemPointsForAward method redeems loyalty points from the loyalty account specified and creates an award according to the award rule. The method also creates a retail transaction ID for the transaction.

This method returns a loyaltyActivity class object.

Classes

This section presents the classes used in Version 1.2 of the Loyalty Account Services.

CardInquiryResponse

For a description of this class, see Introduction..

loyaltyActivity

The loyaltyActivity class contains the following elements:

Type	Element	Description
long	accountActivityId	ID for the activity.
long	accountId	ID for the account used in the activity.
dateTime	activityDatetime	Date and time the activity occurred.
string	activityTypeCode	Code indicating the type of activity performed.
decimal	bonusPointsBalance	Bonus points balance at the time of the activity.
decimal	earnedPointsBalance	Earned points balance at the time of the activity.
decimal	escrowPointsBalance	Escrow points balance at the time of the activity.
dateTime	escrowTransferDate	The date when escrow points will convert to earned points.
boolean	escrowTransferredFlag	Indicates whether escrow points were transferred in the activity.
long	loyaltyRuleId	ID for the loyalty rule used in the activity
decimal	ltdPointsBalance	Current LTD points balance for the account at the time of the activity.
decimal	pointsAmount	Number of points in the activity.
string	pointsMethodTypeCode	Code indicating the method used for point calculations.
decimal	pointsOriginallyRequested	The number of points that were requested in a Redeem request.
dateTime	retailTransactionBusinessDate	Business date of the transaction that performed the activity.
string	transactionItemId	ID for the transaction item used in the activity.
decimal	transactionItemTotalQuantity	Quantity of the transaction item.
decimal	transactionItemUnitPrice	Price of one unit of the transaction item.
int	transactionSequenceNumber	Sequence number for the activity within the transaction.
decimal	ytdPointsBalance	Current YTD points balance for the account at the time of the activity.

loyaltyActivityList

The loyaltyActivityList class contains the following elements:

Type	Element	Description
loyaltyActivity[]	loyaltyActivityList	Array of loyalty activities.
string	systemCurrencyCode	Code identifying the standard currency used by the system.

loyaltyTransactionSummary

The loyaltyTransactionSummary class contains the following elements:

Type	Element	Description
relateExceptionCode	accountErrorCode	Description of any error that may occur.
decimal	bonusPointsBalance	Bonus points balance at the time of the transaction.
decimal	earnedPointsBalance	Earned points balance at the time of the transaction.
decimal	escrowPointsBalance	Escrow points balance at the time of the transaction.
	loyaltyAccountId	ID for the loyalty account used in the transaction.
decimal	ltdPointsBalance	LTD points balance at the time of the transaction.
decimal	numPoints	Number of points in the transaction.
decimal	ytdPointsBalance	YTD points balance at the time of the transaction.

POSLogType

For a description of this class, see Poslog Services, Version 1.0.

RelateProcessingException

For a description of this class, see Introduction..

TransactionType

For a description of this class, see Poslog Services, Version 1.0.