Offer Services, Version 1.0

52 Offer Services, Version 1.0

This chapter provides the information that is necessary to make REST API calls associated with offers, the methods and classes used in the process, for version 1.0 of the Offer Services API.

The version 1.0 of Offer Services API covers POST request to create a Line Item Discount offer.

The REST endpoint URL for creating an offer is:

http://<servername>:<portNumber>/ws/v1/offers/

where <servername> is the name or address of the server.

The information presented below is divided into four sections:

Example
Classes
Methods
Validations

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.

Add Offer

This section describes Add Offer.

Example

An example json payload request to create a line item discount offer

{  "securityUserId" : "sampleuser","name": "Forest Essentials Autumn-4","activeFlag": true,"allowZeroPrice": 78,"comment": "Test deal","dealLimit": 1,"dealType": "LINE_ITEM_DISCOUNT","exclusiveFlag": false,"includeNonMerchCharges": false,"includeTax": false,"intendedIndustry": "Merchandise","intendedPromotionType": "PRODUCT","maxAwardAmount": 999,"posDealName": "Deal 5820-1","primaryDeal": 0,"priority": 3,"subtotalMax": 1000,"subtotalMin": 10,"attributes": [      {        "attributeId" : "22",        "attributeValues" : ["a","b"]      },{       	"attributeId" : "21",        "attributeValues" : ["abc"]      }         ],"franchisees": [{"franchiseeId": 2}],
"itemSets": [{"itemSpecifierGroups": [{"excludeFlag": false,"matchAny": false,"itemSpecifiers": [{"type": "_ITEM_ID_","value": "111100056"}, {"type": "_ITEM_ID_","value": "111100066"}]}, {"excludeFlag": false,"matchAny": true,"itemSpecifiers": [{"type": "DEPT","value": "925"}]
}, {"excludeFlag": true,"matchAny": true,"itemSpecifiers": [{"type": "SUB_DEPT","value": "925-B"}, {"type": "SUB_DEPT","value": "900-W"}]
}, {"excludeFlag": true,"matchAny": false,"itemSpecifiers": [{"type": "CLASS","value": "900-M-A"}, {"type": "CLASS","value": "900-W-A"}, {"type": "STYLE_ID","value": "BELTS"}, {"type": "STYLE_ID","value": "JACKETS"}]}],"award": {"type": "PERCENT_OFF","value": 25,	"maxQuantity": 99},"proratedDiscount": false,"threshold": 2,"thresholdStyle": "MINIMUM","thresholdType": "QUANTITY"}]}

Classes

This section represents the classes used in the version 1.0 of the Offer Services API.

RelateProcessingException

For a description of this class, see Introduction.

OfferDetail

This class represents the fields used in the json payload request for creating an offer of type Line Item Discount.

It contains the following fields:

Table 52-1 Offer Detail

Type	Element	Description	Default Value (if any)	Required (Y/N)
string	name	The name of the Deal. Length should not be more than 64 characters.		Y
string	posDealName	The name of the Deal displayed on the POS system. Length should not be more than 128 characters.		N
string	dealType	Type of deal.Possible values for v1 are LINE_ITEM_DISCOUNT		Y
string	comment	Deal comment. Length should not be more than 1000 characters.		N
BigDecimal	subtotalMin	Minimum subtotal amount for a transaction to be eligible for the Deal. Valid range for this field is 0- 99999999999.		N
BigDecimal	subtotalMax	Maximum subtotal amount for a transaction to be eligible for the Deal. Valid range for this field is 1- 99999999999.		N
BigDecimal	maxAwardAmount	The maximum currency amount of the Award. Valid range for this field is 0- 99999999999.		N
integer	priority	The priority given to the Deal, if more than one Deal can be applied to a Transaction. Valid range for this field is 1-5	1	N
integer	dealLimit	The maximum number of times the deal can be applied to the same transaction. Valid range for this field is 0-99999	0	N
Boolean	advancedFeaturesFlag		false	N
Boolean	includeTax	whether Redlines are included in the deal	false	N
Boolean	includeNonMerchCharges	whether non-merchandise charges are included in the Deal.	false	N
Boolean	allowZeroPrice	whether zero-priced items are included in the deal	false	N
Boolean	exclusiveFlag	whether the items used in the Offer can be used again in other Offers applied to a transaction.	false	N
string	intendedPromotionType	The type of use for the Deal.		Y
long	primaryDeal		0	N
Boolean	activeFlag		false	N
Industry/Typecode	intendedIndustry	The Intended Industry for the Deal. Possible values are Culinary or Merchandise.	Merchandise	N
List<FranchiseeDetail>	franchisees	List of franchisees associated with the offer		N
List<ItemSets>	itemSets	List of Item Qualifying Rules for the Deal.		Y
List<AttributeDetail>	attributes	List of attributes associated with the deal		Y (if required deal attributes exist)
string	securityUserId	ID of the Customer Engagement user performingthe transaction.		Y

The fields that are marked as required above are the ones that must be supplied in the json request to create an offer. Failure to do so will result in errors. More info about the errors is listed in the Validation and Errors section.

Note:

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

FranchiseeDetail

This class represents the franchisees associated with the promotion.

It contains the following fields:

Table 52-2 Franchisee Detail

Type	Element	Description	Default Value (if any)	Required (Y/N)
long	franchiseeId	Franchisee id		N

ItemSets

This class represents the Item Qualifying Rules for the offer.

It contains the following fields:

Table 52-3 Item Sets

Type	Element	Description	Default Value (if any)	Required (Y/N)
Award	award	Award associated with the qualifying item rule		Y
List<ItemSpecifierGroup>	itemSpecifierGroups	List of item specifiers in the item rule		Y
string	thresholdStyle	The style of threshold to set.Possible value is MINIMUM	MINIMUM	Y
string	thresholdType	The type of threshold. Possible Values are AMOUNT, QUANTITY.	QUANTITY	N
Boolean	proratedDiscount	Indicates whether discount is prorated across all items within a transaction.	false	N

ItemSpecifierGroup

This class represents a group of items or hierarchies with include/exclude rules.It contains the following fields:

Table 52-4 Item Specifier Group

Type	Element	Description	Default Value (if any)	Required (Y/N)
Boolean	excludeFlag	Indicates whether the Item(s) are excluded in the eligibility Set.	false	N
Boolean	matchAny	Indicates if all the attribute filters should be applied or any one of them is ok	false	N
List<ItemSpecifier>	itemSpecifiers	List of items or hierarchies in the set		Y

ItemSpecifier

This class represents an item or hierarchy.It contains the following fields:

Table 52-5 Item Specifier

Type	Element	Description	Default Value (if any)	Required (Y/N)
string	type	Indicates the type - an item, hierarchy, all items , etc. Possible values are "_ALL_ITEMS_" for all items, "_ITEM_ID_" for a specific item, or one of the configured Item hierarchy types.		Y
string	value	Indicates the ID of the type		Y

AttributeDetail

This class represents an item or hierarchy.It contains the following fields:

Table 52-6 Attribute Detail

Type	Element	Description	Default Value (if any)	Required (Y/N)
string	attributeId	ID of the attribute		Y
List<string>	attributeValues	Indicates the ID of the type		Y

Validations and Errors

The following table contains a list of errors that may occur and possible causes:

Table 52-7 Validations and Errors

Error	Cause
INVALID_REQUEST_MISSING_BODY	No request body specified
INVALID_REQUEST_FRANCHISEE_SUPPORT_DISABLED	The request contained franchisee info even if the franchisee support was disabled for the user
INVALID_REQUEST_DATE_PARSE_EXCEPTION	Invalid format for date was specified
INVALID_REQUEST_FRANCHISEE_ID_DOES_NOT_EXIST	The request contained a franchisee id which did not exist
INVALID_REQUEST_FRANCHISEE_NOT_ASSIGNED_TO_USER	The user specified a franchisee which was not assigned to him/her
INVALID_REQUEST_ATTRIBUTE_ID_DOES_NOT_EXIST	An attribute was specified which did not exist
INVALID_REQUEST_NUMBER_ATTRIBUTE_NOT_VALID	Invalid format specified for attribute of type number
INVALID_REQUEST_DATE_ATTRIBUTE_NOT_VALID	Invalid format specified for attribute of type date
INVALID_REQUEST_LIST_ATTRIBUTE_NOT_VALID	Invalid format specified for attribute of type list
INVALID_REQUEST_BOOLEAN_ATTRIBUTE_NOT_VALID	Invalid format specified for attribute of type boolean
INVALID_REQUEST_CURRENCY_ATTRIBUTE_NOT_VALID	Invalid format specified for attribute of type currency
INVALID_REQUEST_SECURITY_USER_ID_IS_NOT_ADDED	The security user id was not specified in the request body
INVALID_REQUEST_SECURITY_USER_NOT_FOUND	The security user specified was not found
INVALID_REQUEST_DUPLICATE_FRANCHISEES	Duplicate franchisees were specified in request
INVALID_REQUEST_DEAL_NAME_TOO_LONG	The length of deal name specified was longer than required
DEAL_NAME_EMPTY_ERROR	The deal name was not specified
INVALID_REQUEST_POS_NAME_TOO_LONG	The length of pos name specified was longer than required
INVALID_REQUEST_COMMENT_TOO_LONG	The length of comment specified was longer than required
INTENDED_PROMOTION_USE_ERROR	Invalid intended promotion use specified
DEAL_TYPE_ERROR	Invalid deal type specified
DEAL_TYPE_EMPTY_ERROR	No deal type was specified in the request
NO_ITEMSET_SPECIFIED	The user did not specify any itemsets.
NO_ITEMSPECIFIER_GROUP_SPECIFIED	The user did not specify any item specifier groups
NO_ITEM_SPECIFIERS_SPECIFIED	The user did not specify any item specifiers
ITEM_SPECIFIER_TYPE_MISSING	No type was specified for a particular item specifier
ITEM_SPECIFIER_VALUE_MISSING	No value was specified for a particular item specifier
MERCHANDISE_HIERARCHY_CODE_NOT_FOUND	Merchandise hierarchy code for one of the item specifiers could not be found
INVALID_ITEM_SPECIFIER_TYPE	Type mentioned for one of the item specifiers was not valid
INVALID_ITEM_SPECIFIER_VALUE	Value mentioned for one of the item specifiers was not valid
INVALID_AWARD_TYPE_SPECIFIED	Award type mentioned for one of the item sets was invalid
INVALID_PRORATED_DISCOUNT_FLAG_ERROR	Prorated discount flag was set true for award type PERCENT_OFF
INVALID_THRESHOLD_STYLE_SPECIFIED	Invalid threshold style was specified
INVALID_THRESHOLD_TYPE_SPECIFIED	Invalid threshold type was specified
INVALID_THRESHOLD_VALUE_SPECIFIED	Invalid threshold value was specified
REQUIRED_DEAL_ATTRIBUTES_MISSING	One or more of the required deal attributes were not specified
ITEMSET_AWARD_DETAILS_MISSING	Award details for a particular itemset was not specified
ITEMSET_THRESHOLD_STYLE_MISSING	Threshold style for a particular itemset was not specified
ITEMSET_THRESHOLD_MISSING	Threshold value for a particular itemset was not specified
ITEMSET_AWARD_TYPE_MISSING	Award type for a particular itemset was not specified
ITEMSET_AWARD_VALUE_INVALID	Award value for a particular itemset was not valid
ITEMSET_AWARD_VALUE_MISSING	Award value for a particular itemset was not specified
INVALID_DEAL_LIMIT	Deal limit specified was not valid
INVALID_MAX_AWARD_QUANTITY	Max award quantity specified was not valid
INVALID_MAX_AWARD_AMOUNT	Max award amount specified was not valid
INVALID_SUBTOTAL_MIN_AMOUNT	Subtotal min amount specified was not valid
INVALID_SUBTOTAL_MAX_AMOUNT	Subtotal max amount specified was not valid
INVALID_SUBTOTAL_MIN_MAX_AMOUNT	Subtotal min max amount specified was not valid
INVALID_AWARD_PRIORITY_VALUE	Award priority value specified was not valid
INTENDED_INDUSTRY_MISSING	Intended industry was not specified
INVALID_ITEMSET	The itemset defined did not have any qualifying items specified