Loyalty Account Services Version 3.4

51 Loyalty Account Services Version 3.4

This chapter provides the information necessary to send messages contained in Version 3.4 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/v3_4/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 3.4 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,
                                 string securityUserId)
                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.
securityUserId	Required	ID of Customer Engagement user performing the lookup.

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.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getLoyaltyAwardRules

LoyaltyAwardRulesRespType getLoyaltyAwardRules (
                                string cardNumber,
                                decimal pointsCost,
                                string securityUserId)
           throws RelateProcessingException

Variable	Required?	Description
cardNumber	Required	Card number of the loyalty card.
pointsCost	Required	Number of points that the customer would use to earn the award.
securityUserId	Required	ID of Customer Engagement user performing the lookup.

The getLoyaltyAwardRules method retrieves award rules matching the card number and points cost entered as search criteria.

This method returns a LoyaltyAwardRulesRespType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getEngagementRules

 LoyaltyEngagementRulesResponseType getEngagementRules (
                                 string cardNumber,
                                 decimal lylAccountId,
                                 string securityUserId)
           throws RelateProcessingException

Variable	Required?	Description
cardNumber	Required	Card number of the loyalty card.
lylAccountId	Required	ID of the loyalty account.
securityUserId	Required	ID of Customer Engagement user performing the lookup.

The getEngagementRules method retrieves marketing engagement rules matching the card number and loyalty account ID entered as search criteria. The account and the loyalty program must both be active.

This method returns a LoyaltyEngagementRulesResponseType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getLoyaltyTransactionDetail

loyaltyActivityList getLoyaltyTransactionDetail (
                         string cardNumber,
                         string transactionStoreId,
                         string transactionRegisterNumber,
                         dateTime transactionBusinessDate,
                         string transactionSequenceNumber,
                         string transactionLookupStoreId,
                         string transactionLookupRegisterNumber,
                         dateTime transactionLookupBusinessDate,
                         string transactionLookupSequenceNumber,
                         string updateUserId,
                         string clientComments,
                         string securityUserId)
                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.
updateUserId	Optional	ID of the POS user performing the lookup.
clientComments	Optional	Additional comments.
securityUserId	Required	ID of the Customer Engagement user performing the lookup.

The getLoyaltyTransactionDetail method retrieves detailed information about a loyalty activity.

This method returns a loyaltyActivityList class.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

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 updateUserId,
                                  string clientComments,
                                  string reasonCode,
                                  string securityUserId)
          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.
updateUserId	Optional	ID of the POS user performing the transaction.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for issuing the points.
securityUserId	Required	ID of the Customer Engagement user performing the transaction.

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.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

moveLoyaltyLevel

long moveLoyaltyLevel (
                        string cardNumber,
                        long lylAccountId,
                        int targetLylProgramLevelId,
                        decimal pointsCost,
                        string retailLocationId,
                        string updateUserId,
                        string clientComments,
                        string reasonCode,
                        string securityUserId)
        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.
updateUserId	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.
securityUserId	Required	ID of the Customer Engagement user performing the move.

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

This method returns a long value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

PostEngagementAction

LoyaltyEngagementActionResponseType postEngagementAction (
                                 string cardNumber,
                                 long lylAccountId,
                                 string transactionStoreId,
                                 string transactionRegisterNumber,
                                 date transactionBusinessDate,
                                 string transactionSequenceNumber)
                                 decimal pointsAmount)
                                 long issueRuleId)
                                 long promotionId,
                                 long offerId,
                                 string clientComments))
                                 string reasonCode))
                                 string updateUserId))
                                 string securityUserId)
                      throws RelateProcessingException

Variable	Required?	Description
cardNumber	Required	Card number associated with the activity.
lylAccountId	Required	ID of the loyalty account for which the points are being issued.
transactionStoreId	Optional	ID of the location where the activity was performed.
transactionRegisterNumber	Optional	Number of the register where the activity was performed.
transactionBusinessDate	Required	Business date of the transaction.
transactionSequenceNumber	Optional	Sequence number of the transaction.
pointsAmount	Optional	Number of points being issued. If specified, overrides amount defined for the issue rule.
issueRuleId	Optional	ID of the rule issuing the points. Must have the Calculation Type set to The number of marketing engagements.
promotionId	Optional	ID of the promotion that triggered the issuing of the points. Used in conjunction with offer Id. Promotion must be of Marketing Engagement offer type
offerId	Optional	ID of the offer that triggered the issuing of the points. Used in conjunction with promotion Id. Promotion must be of Marketing Engagement offer type.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for issuing the loyalty points.
updateUserId	Optional	ID of the user issuing the loyalty points.
securityUserId	Required	ID of Customer Engagement user performing the issue.

The PostEngagementAction method issues, to a customer for a specific transaction, loyalty points earned through an engagement activity. The activity must meet the requirements specified for the issue rule, such as those based on location, segment, and frequency eligibility.

This method returns a LoyaltyEngagementActionResponseType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

recoverLoyaltyPoints

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

Variable	Required?	Description
retailTransactionId	Optional	ID of the loyalty transaction.
cardNumber	Optional	Card number associated with the transaction.
updateUserId	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.
securityUserId	Required	ID of Customer Engagement user performing the recovery.

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.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

redeemPointsForAward

loyaltyActivity redeemPointsForAward (
                        string cardNumber,
                        long lylAccountId,
                        string transactionStoreId,
                        string transactionRegisterNumber,
                        dateTime transactionBusinessDate,
                        string transactionSequenceNumber,
                        decimal pointsAmount,
                        long awardRuleId,
                        string updateUserId,
                        string clientComments,
                        string reasonCode,
                        string securityUserId)
              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.
updateUserId	Optional	ID of the POS user performing the transaction.
clientComments	Optional	Additional comments.
reasonCode	Optional	ID code for the reason for the redemption.
securityUserId	Required	ID of the Customer Engagement user performing 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 loyaltyActivityclass object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

Classes

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

CardInquiryResponse

For a description of this class, see Introduction..

EntitlementDealType

The EntitlementDealType class contains the following elements:

Type	Element	Description
string	Name	The name of the entitlement deal.
string	Description	The description of the entitlement deal.
boolean	UnlimitedRedeemFlag	Indicates whether the entitlement deal is eligible for unlimited redemption.
boolean	ActiveFlag	Indicates whether the entitlement deal is active.
int	MaxRedeemCount	Indicates the maximum number of times the entitlement deal can be redeemed.
ReferencedDealType	Deal	Details of the referenced deal.

ImmediateAwardEntitlementType

The ImmediateAwardEntitlementType class contains the following elements:

Type	Element	Description
string	EntitlementDealName	Based on the name of the entitlement deal.
string	EntitlementDealPOSName	Based on the POS name of the entitlement deal.
string	EntitlementDealDescription	Description of the entitlement deal.
string	EntitlementDealID	ID number identifying a deal.
string	EntitlementRedeemCount	The maximum number of times a deal can be redeemed.
string	EntitlementDealEffectiveDate	The date when the deal becomes effective.
string	EntitlementDealExpirationDate	The date when the deal expires.
string	EntitlementCouponCount	The total number of entitlement coupons issued for the transaction.
ImmediateEntitlementCouponType	ImmediateEntitlementCoupon	Not used.

ImmediateAwardsType

The ImmediateAwardsType class contains the following elements:

Type	Element	Description
ImmediateMovementType	ImmediateMovement	Loyalty level movement immediately available.
ImmediateEAwardType	ImmediateEAward	E-award immediately available.
IImmediateAwardEntitlementType	ImmediateAwardEntitlement	Entitlement award immediately available.

ImmediateEAwardCouponType

Not used. For a description of the class, see Poslog Services, Version 3.2.

ImmediateEAwardType

The ImmediateEAwardType class contains the following elements:

Type	Element	Description
string	eAwardName	Name of the e-award.
string	eAwardPOSName	Name of the e-award displayed on the POS.
string	eAwardDescription	Description of the e-award.
string	eAwardAmount	Amount of the e-award.
string	eAwardCurrency	Currency used by the e-award.
string	eAwardEffectiveDate	Date on which the e-award becomes effective.
string	eAwardExpirationDate	Date on which the e-award expires.
string	eAwardCount	The number of e-awards.
ImmediateEAwardCouponType	ImmediateEAwardCoupon	Not used.

ImmediateEntitlementCouponType

Not used. For a description of the class, see Poslog Services, Version 3.2.

ImmediateMovementType

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

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.

LoyaltyAwardRuleParametersType

The LoyaltyAwardRuleParametersType class contains the following elements:

Type	Element	Description
string	PointsCostType	Indicates whether the point cost type is Cashback or Fixed.
decimal	AwardAmount	Set to 0.000.
string	AwardProgramName	The name of the award program used.
string	AwardProgramId	Numeric ID of the award program.
string	CouponPrefix	The coupon prefix for the award rule.
string	ExpirationPeriodType	Indicates whether the expiration period is weeks, months, days, or based on the program’s setting.
string	ExpirationPeriods	The number of periods until expiration.
decimal	AwardFactor	The award factor used to convert points to an e-award amount for a cashback award.
boolean	ResetBalanceFlag	Indicates whether to reset the loyalty points balance for a cashback award.

LoyaltyAwardRulesRespType

The LoyaltyAwardRulesRespType class contains the following elements:

Type	Element	Description
LoyaltyAwardRuleType[]	LoyaltyAwardRule	Details on the loyalty award rule.

LoyaltyAwardRuleType

The LoyaltyAwardRuleType class contains the following elements:

Type	Element	Description
string	RuleName	The name of the award rule definition.
string	AwardRuleType	Indicates whether the award rule is for an e-award, coupon, or entitlement deal.
string	POSName	The name of the award rule in a POS system.
string	Description	Description of the award rule.
boolean	InstantAwardFlag	Indicates whether the award rule is flagged to issue immediately upon transaction posting (true) or not (false).
EntitlementDealType	EntitlementDeal	Information on an entitlement deal used for the award rule.
date	RuleEffectiveStartDate	The date when the award rule becomes effective.
date	RuleEffectiveEndDate	The Date when the award rule expires.
LoyaltyAwardRuleParametersType	LoyaltyAwardRuleParameters	Details on the award rules for an e-award or entitlement.
decimal	PointsCost	The number of points used for the award.
decimal	PointsThreshold	The number of points the customer must have to be eligible for the award.

LoyaltyEngagementActionResponseType

The LoyaltyEngagementActionResponseType class contains the following elements:

Type	Element	Description
long	LoyaltyActivityId	Unique identifier of the loyalty activity.
BigDecimal	PointsIssued	The number of points issued through the request.
string	Message	Message indicating why points could not be awarded if the request did not succeed.

LoyaltyEngagementRuleParameters

The LoyaltyEngagementRuleParameters class contains the following elements:

Type	Element	Description
boolean	BonusPointsFlag	Indicates whether loyalty points are flagged as bonus points.
string	PointsCalculationMethodType	The method of calculating loyalty points.
string	AdditionalPoints	The number of points to issue for the rule.
string	FrequencyPeriodType	The frequency period used to determine how often a customer can use the issue rule.
string	IssuesPerFrequencyPeriod	The maximum number of times a customer can use the issue rule in the frequency period.
boolean	UnlimitedIssuanceFlag	Indicates whether there is a limit to the number of times a customer can use the issue rule.
string	MaxIssuanceCount	The total maximum number of times a customer can use the issue rule.

LoyaltyEngagementRulesResponseType

The LoyaltyEngagementRulesResponseType class contains the following elements:

Type	Element	Description
LoyaltyEngagementRuleType[]	LoyaltyEngagementRuleType	Details on the loyalty engagement rule.

LoyaltyEngagementRuleType

The LoyaltyEngagementRulesResponseType class contains the following elements:

Type	Element	Description
string	RuleName	The name of the engagement rule definition.
string	POSName	The name of the engagement rule in a POS system.
string	Description	Description of the engagement rule.
date	RuleEffectiveStartDate	The date when the engagement rule becomes effective.
date	RuleEffectiveEndDate	The date when the engagement rule expires.
LoyaltyEngagementRuleParameters	Rule Parameters	The rules defined for application of the marketing engagement issue rules.
RetailLocationEligibilityRule	RetailLocationEligibilityRules	The eligibility rules defined based on the location where the marketing activity takes place.
SegmentEligibilityRules	SegmentEligibilityRules	The eligibility rules defined based on the segment that the customer belongs to.

LoyaltyPointsType

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

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.

PointsBalanceType

The PointsBalanceType class contains the following elements:

Type	Element	Description
PointsEntryType[]	Points	Array of point balances and point types in the account.

PointsEntryType

The getValue() function for the PointsEntryType class returns a string value.

PointsEntryType class contains the following attributes:

Type	Attribute	Description
PointsType	Type	Points type.

POSLogType

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

ReferencedDealType

Used for a referenced entitlement deal. For a description of this class, see Introduction.

RelateProcessingException

For a description of this class, see Introduction.

RetailLocationEligibilityRule

The RetailLocationEligibilityRule class contains the following elements:

Type	Element	Description
string	AttributeName	Retail location eligibility attribute name.
string	AttributeValue	Retail location eligibility attribute value.
boolean	IncludeFlag	Specifies whether the Attribute should used to include/exclude the retail location eligibility rule.
string	RuleGroup	The ID of the group to which the retail location Eligibility rule belongs.

RetailLocationEligibilityRule

The RetailLocationEligibilityRules class contains the following element:

Type	Element	Description
RetailLocationEligibilityRule	RetailLocationEligibilityRule	Details on location eligibility that apply to an issue rule.

SegmentEligibilityRule

The SegmentEligibilityRule class contains the following elements:

Type	Element	Description
string	SegmentID	ID for a segment used to determine eligibility for an issue rule.
string	StrataSequence	The strata sequence for the segment.

SegmentEligibilityRules

The SegmentEligibilityRules class contains the following elements:

Type	Element	Description
RetailLocationEligibilityRule	SegmentEligibilityRule	Details on segment eligibility that apply to an issue rule.

TransactionPointsType

The TransactionPointsType class contains the following elements:

Type	Element	Description
PointsEntryType[]	Points	Array of point balances and point types for the transaction.

TransactionReturnType

The TransactionReturnType class contains the following elements:

Type	Element	Description
string	ErrorDetails	Detailed message describing an error (if any) returned for the transaction.
string	LoyaltySystemDetails	Detailed message about the system.
LoyaltyPointsType[]	LoyaltyPoints	Array of information about loyalty points applied to loyalty accounts.

TransactionType

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