Related Documents
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
Guidelines, Concepts & Cookbooks
  • ICM 7.7
  • ICM 7.8

Concept - Promotion Codes (valid to 7.8)

Table of Contents

Product Version


Product To Version



New Labels

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.





It holds the information about the code, its state and its redemption.


Container mapping promotions to codes, it can be assigned to different promotions.


A promotion can be assigned to different promotion code groups.



The group of users that are allowed to apply the code (per default the promotion's target groups are used).



The domain where the promotion code groups are valid (promotion and code group must be in same domain).

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





Provides business logic to handle promotion code groups, like create, remove and get.


Provides business logic to handle promotion codes, like create, remove and get.


Creates an instance of PromotionCodeGroup.

3 Promotion Codes

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




The promotion code is active and not redeemed.


The promotion code is active, but fully redeemed.


The promotion code is deactivated permanently.


Promotion codes cannot be redeemed partially.

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:



Code prefix

The promotion manager can define a code prefix, e.g., X-MAS. All generated codes will have that prefix.

Code length

The promotion manager can specify the number of characters in the generated code string.

No. of codes

The promotion manager can set the number of codes to be generated.


Since the prefix is part of the code, the specified code length must be greater than the number of characters in the prefix.

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.


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.


Promotion codes once deactivated cannot be reactivated again.

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.


The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources