65 Promotion Event Services, Version 3.3

This chapter provides the information necessary to send messages contained in Version 3.3 of the Promotion Event 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 described above.

The URL for the WSDL is:

https://<servername>:<portNumber>/ws/v3_3/PromotionEventServices?wsdl

where <servername> is the name or address of the server. For a cloud installation, the default port number is 443.

The information presented below 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.3 of the Promotion Event Services API.

addOrUpdatePromotionTarget

PromotionTargetResponseType addOrUpdatePromotionTarget(   PromoAddTargetRequestType PromoAddTargetRequestType)     throws RelateProcessingException

Variable	Required?	Description
PromoAddTargetRequestType	(Optional)	Customer being added or updated to a promotion.

The addOrUpdatePromotionTarget method adds or updates a target customer for a promotion.

This method returns a PromotionTargetResponseType element.

retrieveDeal

DealType retrieveDeal(         long dealId         string SecurityUserId)     throws RelateProcessingException

Variable	Required?	Description
dealID	(Required)	ID of the Deal.
SecurityUserId	(Required)	ID of the user requesting the information.

The retrieveDeal method retrieves the details of a deal.

This method returns a DealType element.

Note:

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

retrievePromotionDeals

PromoDealsResponseType retrievePromotionDeals(         long PromotionId         string SecurityUserId)     throws RelateProcessingException

Variable	Required?	Description
PromotionId	(Required)	ID of the Promotion.
SecurityUserId	(Required)	ID of the user requesting the information.

The retrievePromotionDeals method retrieves all deals associated with a promotion.

This method returns a PromoDealsResponseType element.

Note:

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

retrievePromotions

PromotionsResponseType retrievePromotions(               PromotionsRequestType PromotionRequest)     throws RelateProcessingException

Variable	Required?	Description
PromotionRequest	(Optional)	Promotion search criteria

The retrievePromotions method retrieves the promotions that match the PromotionRequest.

This method returns a PromotionsResponseType element.

retrievePromotionEventCustomerList

PromoEventCustomerResponseType[] retrievePromotionEventCustomerList(                                   long PromotionId,                                   string LocationId,                                   string AssociateId,                                   int startIndex,                                   int pageSize)     throws RelateProcessingException

Variable	Required?	Description
PromotionId	(Required)	ID of the promotion.
LocationId	(Optional)	ID of the location for the promotion.
AssociateId	(Optional)	ID of the associate assigned to customers.
startIndex	(Required)	Start index of the customer list.
pageSize	(Required)	Maximum number of records per page.

The retrievePromotionEventCustomerList method retrieves the customers targeted by a promotion.

This method returns aPromoEventCustomerResponseType element.

Classes

This section presents the classes used in Version 3.2 of the Promotion Event Services API.

AlternateKeyType

See Introduction.

AuthorizedFranchiseeResponseType

The AuthorizedFranchiseeResponseType class contains the following attributes:

Type	Attribute	Description
AuthorizedFranchiseeType	Franchisee	ID of the franchisee.

AuthorizedFranchiseeType

The AuthorizedFranchiseeType class contains the following attributes:

Type	Attribute	Description
long	FranchiseeId	ID of the franchisee.
string	FranchiseeName	Name of the franchisee.

AwardType

The AwardType class contains the following elements:

Type	Element	Description
string	AwardType	The type of award for the deal, such as PERCENT_OFF or OVERRIDE_PRICE.
string	AwardValue	The value of the award in either monetary amount, if the award carries a price override or discount amount, or a percentage.
string	MaxQuantity	The maximum quantity eligible for the award, if specified for the deal.

AwardPointsType

The AwardPointsType class contains the following elements:

Type	Element	Description
string	CalculationType	The calculation type to use for awarding points. Values can be: PerCheckValue (the value of each transaction), PerItem (The quantity of each item purchased), PerTransaction (The number of qualifying transactions) or PerMarketingEngagement.
string	BonusPointsFlag	Indicates if the points are to be issued as bonus points.
string	FixedAmount	The number of points to issue.
string	PointsMultiplier	The number to multiply the awarded points by.
string	MaxTransactionsPerDay	The maximum number of transactions allowed in a day to issue points to an account for this offer.
string	TransactionMinimum	The minimum transaction amount required to issue Amount points.
string	FrequencyPeriod	The frequency period to allow issuing points.The values can be: ONCE, DAILY, WEEKLY, MONTHLY or YEARLY.
string	IssuesPerPeriod	The number of times points can be issued to an account within the frequency period for this offer.
string	UnlimitedIssueFlag	Determines if points can be issued an unlimited number of times.
string	RuleCountLimit	The number of times in total points can be issued to an account for this offer.

DealAttributeType

The DealAttributeType class contains the following attributes:

Type	Attribute	Description
string	name	Name of the deal attribute.
string	value	Value of the deal attribute.

DealsAttributeType

The DealsAttributeType class contains the following attributes:

Type	Attribute	Description
string	name	Name of the deal attribute.
string	value	Value of the deal attribute.

DealType

The DealType class contains the following elements:

Type	Element	Description
string	PosDealName	The name of the deal in the POS system.
string	DealComment	Any comments entered about the deal.
CouponCodeType	CouponCode	Not used.
string	DealType	The type of discount provided by the deal.
string	DealId	Numeric ID of the deal.
string	IntendedIndustry	The industry, such as Merchandise, where the deal can be used.
string	SubtotalMin	The minimum subtotal required for the deal.
string	SubtotalMax	The maximum subtotal required for the deal.
string	MaxAwardAmount	The maximum award amount for the deal.
string	Priority	The priority of the deal.
string	DealLimit	The maximum number of times a customer can use the deal.
string	IncludeTax	Indicates whether the deal is configured to include redlines (true) or not (false).
string	IncludeNonMerchCharges	Indicates whether non-merchandise charges are included in the deal (true) or not (false).
string	AllowZeroPrice	Indicates whether zero-price items are included in the deal (true) or not (false).
string	ExclusiveFlag	Indicates whether items used by the deal can be used only for a single deal (true) or can be used again in other another for a transaction (false).
string	DiscountType	Not used.
string	DiscountValue	Not used.
string	TransactionLevel Award	Indicates if the deal is a transaction discount (true) or not (false).
string	PrimaryDeal	The ID of the primary deal. Included for a tier of a tiered discount deal.
string	ActiveFlag	Not used.
FranchiseesType	Franchisees	ID and name of the franchisee.
ItemSetType	ItemSet	Information about the threshold, items, and award application for the deal.
TimeRuleType	OfferTimeRule	Days of the week, and their corresponding beginning and end times, when the deal is active. (New for v3.2.)
DealsAttributeType	DealAttribute	Attributes set up for the deal.

The DealType class contains the following attributes:

Type	Attribute	Description
string	name	The name of the deal.
string	enabled	Not used.

FranchiseeType

The FranchiseeType class contains the following attributes:

Type	Attribute	Description
string	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.

FranchiseesType

The FranchiseesType class contains the following element:

Type	Element	Description
FranchiseeType	Franchisee	Identifies the Franchisee.

ItemAttributeGroup

The ItemAttributeGroup class contains the following elements:

Type	Element	Description
string	GroupSequence	Sequence number of the attribute group.
ItemAttributeType	ItemAttribute	Array of attributes assigned to the item.

ItemAttributeType

The ItemAtttributeType class contains the following attributes:

Type	Attribute	Description
string	AttributeName	Name of the attribute.
string	AttributeID	ID of the attribute.
string	AttributeValue	Value of the attribute.

ItemSetType

The ItemSetType class contains the following elements:

Type	Element	Description
string	ItemSetSequence	Sequence number of the item set.
string	ThresholdType	Indicates whether the threshold is based on quantity or amount.
string	ThresholdStyle	Indicates whether the threshold style is minimum or tiered.
string	ThresholdValue	The threshold value or amount.
ItemSpecifierType	ItemSpecifier	Identifies the item to include or exclude.
AwardType	Award	Identifies the award type, value, amount, and maximum quantity.
boolean	ProratedDiscount	Indicates whether the discount is prorated (true) or not (false).

ItemSpecifierType

The ItemSpecifierType class contains the following elements:

Type	Element	Description
string	SpecifierSequence	Sequence number of the item identifier.
string	Type	The type of item specifier, such as _ALL_ITEMS_.
string	Value	The item specifier value.
string	BrandCode	The brand code used as an item filter.
string	SeasonCode	The season code used as an item filter.
sting	MinPrice	The minimum price used as an item filter.
string	MaxPrice	The maximum price used as an item filter.
string	Color	The color used as an item filter.
ItemAttributeGroup	ItemAttributeGroup	The group assigned to the item attribute.
string	NewPrice	The new price of the item.

The ItemSpecifierType class contains the following attribute:

Type	Attribute	Description
string	exclude	Indicates whether to exclude the specified items (true) or include the specified items (false).

PromoAddTargetRequestType

The PromoAddTargetRequestType class contains the following elements:

Type	Element	Description
long	CampaignId	ID of the campaign for the promotion.
long	PromotionId	ID of the promotion.
string	CustomerId	ID of the customer.
AlternateKeyType[]	AlternateKey	Array of alternate keys for the customer.
string	Action	Action to perform.
boolean	ActiveFlag	Indicates whether the promotion is active.
boolean	EmailDeliveredFlag	Indicates whether an email to the customer was delivered.
boolean	EmailOpenedFlag	Indicates whether the email to the customer was opened.
boolean	EmailClickedThroughFlag	Indicates whether the customer clicked on the email to view the promotion information.
boolean	EmailUndeliveredFlag	Indicates whether the email could not be delivered.
date	CreateDate	Date the promotion was created in the system.
date	UpdateDate	Date the promotion was last updated in the system.
string	UpdateUser	User who last updated the promotion in the system.
string	CreateUser	User who created the promotion in the system.
string	SecurityUserId	ID of the user performing the action.

PromoDealAttributeType

The PromoDealAttributeType class contains the following attributes:

Type	Attribute	Description
long	DealId	ID of the deal.
string	DealName	Name of the deal.
string	DealType	Type of deal.
string	DealDescription	Description of the deal.
DealAttributeType[]	DealAttribute	Array of deal attributes.
PromoDealAttributeType[]	PromoDealAttribute	Array of promotion-deal attributes.

PromoDealType

The PromoDealType class contains the following elements:

Type	Element	Description
long	DealId	ID of the deal.
string	DealName	Name of the deal.
string	DealType	Type of deal.
string	DealDescription	Description of the deal.
DealsAttributeType[]	DealAttribute	Array of deal attributes.
PromoDealAttributeType[]	PromoDealAttribute	Array of promotion-deal attributes.

PromoDealsContainerType

The PromoDealsContainerType class contains the following element:

Type	Element	Description
PromoDealType[]	PromoDeal	Array of promotion details

PromoDealsResponseType

The PromoDealsResponseType class contains the following elements:

Type	Element	Description
long	CampaignId	ID of the campaign.
long	PromotionId	ID of the promotion.
PromoDealsContainerType	PromoDeals	Deals.

PromoDealsResponseType class contains the following attribute:

Type	Attribute	Description
string	ResponseCode	Response code.

PromoEventCustomerResponseType

The PromoEventCustomerResponseType class contains the following elements:

Type	Element	Description
Promo Event Customer Type[]	PromotionEventCustomers	Details of customers

The PromoEventCustomerResponseType class contains the following attribute:

Type	Attribute	Description
int	startIndex	Sequence number indicating the order of the first customer in the page results
boolean	morePages	Indicates whether there are more pages in the results.
int	pageSize	Number of customers on the page.

PromoEventCustomerType

The PromoEventCustomerType class contains the following elements:

Type	Element	Description
string	CustId	ID of the customer.
string	FirstName	First name of the customer.
string	LastName	Last name of the customer.
string	PhoneNumber	Phone number for the customer.
string	Email	Email address for the customer.
string	Address	Primary street address for the customer.
string	City	City of the customer.

PromoAttributeType

The PromoAttributeType class contains the following elements:

Type	Element	Description
string	name	Name of the deal attribute.
string	value	Value of the deal attribute.

PromoEventDocumentType

The PromoEventDocumentType class contains the following elements:

Type	Element	Description
string	DocumentName	Name of the promotion event document.
string	DocumentLink	Link to the promotion event document.

PromotionType

The PromotionType class contains the following elements:

Type	Element	Description
long	PromotionId	ID of the promotion.
long	CampaignId	ID of the campaign.
string	EventType	Type of event.
string	PromoStartDateTime	Date and time at which the promotion starts.
string	PromoEndDateTime	Date and time at which the promotion starts.
string	TargetingRule	Targeting rule for the promotion.
string	EventDescription	Description of the promotion event.
PromoEventDocumentType[]	PromoEventDocuments	Array of promotion event documents.

PromotionsRequestType

The PromotionsRequestType class contains the following elements:

Type	Element	Description
long	CampaignId	ID of the campaign.
long	PromotionId	ID of the promotion.
string	EventType	Type of event.
date	StartDate	Date on which the promotion starts.
date	EndDate	Date on which the promotion ends.
string	SecurityUserId	ID of the user performing the action.

PromotionsResponseType

The PromotionsResponseType class contains the following element:

Type	Element	Description
PromotionType[]	Promotions	Array of Promotions.
string	ResponseMessage	Message for the response.
string	ResponseCode	Response code.

PromotionTargetResponseType

The PromotionTargetResponseType class contains the following elements:

Type	Element	Description
long	PromotionID	ID of the promotion.
string	CustomerID	ID of the customer.

PromotionTargetResponseType includes the following attributes:

Type	Attribute	Description
string	ResponseCode	Response code

OfferTimeRuleType

The OfferTimeRuleType class contains the following elements:

Type	Element	Description
string	SundayBeginTime	The time on Sundays when the deal is effective.
string	SundayEndTime	The time on Sundays when the deal is no longer effective.
string	MondayBeginTime	The time on Mondays when the deal is effective.
string	MondayEndTime	The time on Mondays when the deal is no longer effective.
string	TuesdayBeginTime	The time on Tuesdays when the deal is effective.
string	TuesdayEndTime	The time on Tuesdays when the deal is no longer effective.
string	WednesdayBeginTime	The time on Wednesdays when the deal is effective.
string	WednesdayEndTime	The time on Wednesdays when the deal is no longer effective.
string	ThursdayBeginTime	The time on Thursdays when the deal is effective.
string	ThursdayEndTime	The time on Thursdays when the deal is no longer effective.
string	FridayBeginTime	The time on Fridays when the deal is effective.
string	FridayEndTime	The time on Fridays when the deal is no longer effective.
string	SaturdayBeginTime	The time on Saturdays when the deal is effective.
string	SaturdayEndTime	The time on Saturdays when the deal is no longer effective.

The OfferTimeRuleType class contains the following attributes:

Type	Attribute	Description
string	name	Name of the time rule.
string	id	ID of the time rule.

TenderIdsType

The TenderIdsType class contains the following element:

Type	Element	Description
string	TenderId	Array of tender IDs.

RelateProcessingException

For a description of this class, see Introduction.