1 Introduction

There exist two kinds of promotions: implicit and explicit promotions.

An implicit promotion applies as soon as its condition is met. In contrast to this, an explicit promotion depends on a code, which must be entered by the consumer. Such a promotion is also called "code based promotion".

This document explains the concept of promotion code groups and single promotion codes. It covers the creation, management and redemption of codes.

2 Promotion Code Groups

The motivation for introducing promotion code groups is the wish to

• import & export of promotion codes in a convenient way,
• randomly generate promotion codes,
• trigger more than one promotion by one code,
• restrict code redemption.

Each promotion is created as an implicit promotion at first. The promotion manager has to enable the promotional code handling in the back office. The picture shows a promotion which is assigned to one promotion code group.

A promotion code group is an entity which:

• has a life span,
• has a collection of different promotion codes,
• can be assigned to various promotions,
• can be valid for different users or user groups.

Furthermore, it is possible to restrict the code redemption:

• Code reuse per customer: defines how often a single consumer can use the provided code.
• Total reuse per code: defines how often a code can be used in total over all customers.
• Application: defines which application supports that code group.

The screenshot shows a configuration of a promotion code group:

A new interface PromotionCodeGroup has been introduced. A promotion code group is a container for promotion codes. It holds all attributes to administer promotion codes. Therefore, a huge number of codes can be managed at the same time.
A promotion can be assigned to one or more promotion code groups. On the other hand, a promotion code group can be assigned to different promotions. In other words, a promotion code can trigger more than one promotion at the same time. However, promotion and promotion code group must be in the same domain.

The following interfaces or classes play a vital role in the promotion code (group) context.

In addition, there exists some business logic to maintain promotion codes and groups.

3 Promotion Codes

Promotion codes are arbitrary strings, inserted manually, or generated randomly. Promotion codes can have the following states:

The API is defined in interface PromotionCode. It provides functionality to handle codes.

There are different ways to create promotion codes:

• Manual insertion by a promotion manager
• Automatic generation
• Import from a CSV source file

Pipelines for code handling are: ViewPromotionCodeList (sld_ch_base) and ProcessPromotionCode (bc_marketing).
The promotion code creation is done in pipelet: CreatePromotionCodes (bc_marketing). It creates promotion codes for the given iterator of promotional code strings and commits them into the database. A commit level is set: a step size in order to save a such sized block of codes.

The API for creating promotion codes is available in PromotionCodeRepository. It offers methods to create a single code instance for the passed code string, and to create a collection of codes for the given code string iterator.

3.1 Manually Created Codes

The promotion manager can type codes in the input box or copy them from an external source. Each code must begin in a new line. (See screenshot.)

Manually added promotion codes have to be validated by profanity check functionality. Profanity check allows to configure a set of forbidden words. User entries can be checked against this black list and error messages will be shown when some of the words are used.

3.2 Generated Codes

It is possible to create randomly generated codes. The following input parameters are required:

3.3 Import/Export Codes

It is also possible to import promotion codes from a CSV file. The mapping template is PromotionCodeCSVConvert (bc_marketing).
The first line may contain some header information.

The import is done by the ImpEx framework. It performs a batch job. The processing pipeline is ProcessPromotionCodeImport (bc_marketing).
Additional pipelines are: ViewPromotionCodeImportUploadFile (sld_ch_base) to upload the import file and ViewPromotionCodeImportWizard  (sld_ch_base) to configure the import.

The snippet shows an example of a test file.

promotion-code
testAI
testCG
testIS
testQF
testT8

It is also possible to export promotion codes into a CSV format. Codes can be exported at once, or classified by their state: redeemed, not redeemed or deactivated. The export is executed by ProcessPromotionCodeExport (bc_marketing) as a batch job. Pipeline ViewPromotionCodeExportWizard (sld_ch_base) prepares the export.

3.4 Deactivate Promotion Codes

Promotion codes can be deactivated. Marketing managers have one or two options to deactivate a code this way:

1. Enter that code at <Consumer Channel> | Marketing | Deactivate Promotion Codes.
2. If the code belongs to a promotion code group, use the Deactivate button on the Codes tab of that promotion code group.

3.5 Single Promotion Code

As described before, a promotion code group is a container for many promotion codes. Promotion code groups can be used if a marketing manager wants to promote a product by providing individual codes, or trigger more than one promotion by a code. In contrast to that, it is possible to define only one code for a promotion: This is called Single Promotion Code. It is only valid in combination with the promotion it is defined for. The code redemption can be restricted the same ways as for promotion code groups:

• Code reuse per customer: defines how often a single consumer can use the code.
• Total reuse per code: defines how often the code can be used in total over all customers.

3.6 Promotion Code Appliance in the Web Shop

A customer can enter one or more codes for the order. As for the appliance of the code to the order following criteria are checked:

1. Is the specified maximum number of redemption already reached?
2. Is the promotion code valid?
3. Does the code belong to a group and if so, is that promotion code group valid?
4. Is at least one promotion of the assigned ones valid?
5. If the code does not belong to a group: Is it a valid single promotion code?

The logic is implemented in ViewCart-ApplyPromotion and ProcessPromotionCodeForBasket-CreatePromotionCodeLineItem.