1. Batch Processing and Web Services Guide
  2. Promotion Services, Version 1.0

66 Promotion Services, Version 1.0

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

The version 1.0 of Promotion Services API covers POST request to create a product promotion.

The REST endpoint URL for creating a promotion is:

http://<servername>:<portNumber>/ws/v1/promotions/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.

Create Promotion

This section describes creating a promotion.

Sample Request

An example json payload request to create a product promotion:

{
    "promotionName": "Black Friday Promotion",
"description": "Black Friday Promotion",
"startDateTime": "2021-11-20 1:50",
"endDateTime": "2025-11-25 08:00",
"promotionType": "PRODUCT",
"targetType": "NONE",
    "bypassPromoOfferAttributes": false,
"promotionAttributes": [{
"attributeId": 26,
       "attributeValues": ["Red"]
    },{
    "attributeId": 28,
       "attributeValues": ["9.8"]
    }],
"offers": [{
"offerId": 1,
"enabledFlag": false,
"optionalCode": "DEAL",
"promoOfferAttributes": [{
"attributeId": 22,    "attributeValues": ["Blue","Green"]
}]
}],
"franchisees": [{
"franchiseeId": 74 
}],
"locations": [{
"locationId": 103,
        "includeFlag": true
}],
"securityUserId": "Taslim"
}

Classes

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

RelateProcessingException

For a description of this class, see Introduction.

Promotion Detail

This class represents the fields used in the json payload request for creating a Product promotion.

It contains the following fields:

Table 66-1 Promotion Detail

Type Element Description Default Value (if any) Required (Y/N)

string

promotionName

The name of the Promotion

Y

string

description

The description of the Promotion

Y

string

startDateTime

Date on which the promotion is first active.

Y

string

endDateTime

Last date on which the promotion is active.

Y

string

promotionType

Type of promotion

Y

string

targetType

Indicates the type of targeting used by the promotion

NONE

N

Boolean

bypassPromoDealAttrFlag

Flag used to bypass the promo offer attributes

true

N

List<LocationDetail>

locations

Locations included in a promotion.

0

N

List<AttributeDetail>

promotionAttributes

Attributes associated with the promotion

Y [ If required Promotion Attributes exist ]

List<PromoOfferDetail>

offers

Offers associated with the promotion

Y

List<FranchiseeDetail>

franchisees

List of franchisees associated with the offer

N

string

securityUserId

User id

Y

The fields that are marked as required above are the ones that must be supplied in the json request to create a promotion. 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 66-2 Franchisee Detail

Type Element Description Default Value (if any) Required (Y/N)

long

franchiseeId

Franchisee id

N
LocationDetail

This class represents the locations included in a promotion.

It contains the following fields:

Table 66-3 Location Detail

Type Element Description Default Value (if any) Required (Y/N)

string

locationId

Location ID

N

Boolean

includeFlag

Indicates whether the location is included or not

false

N
PromotionOfferDetail

This class represents the offers associated with the promotionIt contains the following fields:

Table 66-4 Promotion Offer Detail

Type Element Description Default Value (if any) Required (Y/N)

long

offerId

Offer ID

Y

Boolean

enabledFlag

Indicates if the offer is enabled

true

N

List<AttributeDetail>

promoOfferAttributes

Attributes associated with the Promotion

Y [ If required Promo-Offer Attributes exist

AttributeDetail

This class represents an attribute associated with the promotionIt contains the following fields:

Table 66-5 Attribute Detail

Type Element Description Default Value (if any) Required (Y/N)

string

attributeId

ID of the attribute

Y

List<string>

attributeValues

List of Attribute Values

Y
Validations and Errors

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

Table 66-6 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_START_DATE_NOT_VALID

Start datetime is specified earlier than Today's date or later than End datetime.

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_PROMOTION_NAME_REQUIRED

The promotion name was not specified

INVALID_REQUEST_DESCRIPTION_REQUIRED

The promotion description was not specified

INVALID_REQUEST_PROMOTION_START_DATETIME_REQUIRED

Promotion start datetime was not specified

INVALID_REQUEST_PROMOTION_END_DATETIME_REQUIRED

Promotion end datetime was not specified

INVALID_REQUEST_PROMOTION_TYPE_REQUIRED

Promotion type was not specified

INVALID_REQUEST_TARGET_TYPE_REQUIRED

Promotion target type was not specified

INVALID_REQUEST_PROMOTION_TYPE_NOT_VALID

Promotion type specified was not valid

INVALID_REQUEST_TARGET_TYPE_NOT_VALID

Promotion target type was not specified

INVALID_REQUEST_NO_OFFERS_ADDED

No offers added to the Promotion

INVALID_REQUEST_PROMO_OFFER_ATTRIBUTE_ID_DOES_NOT_EXIST

Promotion offer attribute id did not exist

INVALID_REQUEST_DEAL_ID_DOES_NOT_EXIST

Promotion Offer ID specified did not exist

INVALID_REQUEST_DEAL_TYPE_NOT_SUPPORTED

Any one of the specified offer has invalid/unsupported Deal Type

INVALID_REQUEST_DEAL_NOT_ASSOCIATED_TO_FRANCHISEE

Any one of the specified deals not associated to the specified franchisees

INVALID_REQUEST_LOCATION_NOT_ASSOCIATED_TO_FRANCHISEE

Any one of the specified locations not associated to the specified franchisees

INVALID_REQUEST_REQUIRED_PROMO_ATTRIBUTE_NOT_ADDED

One or more required promotion attributes were not added

INVALID_REQUEST_REQUIRED_PROMO_DEAL_ATTRIBUTE_NOT_ADDED

One or more required promotion offer attributes were not added

INVALID_REQUEST_BYPASS_PROMO_OFFER_ATTRIBUTES_FLAG_IS_ON

Promo-Offer Attributes are added, even though bypassPromoDealAttrFlag is set to true.

INVALID_REQUEST_PROMOTION_NAME_TOO_LONG

Length of promotion name specified was more than 64 characters.

INVALID_REQUEST_PROMOTION_DESCRIPTION_TOO_LONG

Length of promotion description specified was more than 254 characters.

INVALID_REQUEST_ATTRIBUTE_ID_INTENDED_USE_NOT_VALID

Intended use specified for an attribute was not valid

INVALID_REQUEST_REQUIRED_ATTRIBUTE_VALUE_EMPTY

No value was specified for a required attribute

INVALID_REQUEST_DUPLICATE_OFFERS

Duplicate offers were specified in the promotion

INVALID_REQUEST_DUPLICATE_FRANCHISEES

Duplicate offers were specified in the promotion

INVALID_REQUEST_DUPLICATE_LOCATIONS

Duplicate locations were specified in the promotion