Items promotions are applied to a specific item based on quantity or price tiers.

This article explains how to install the Item Promotions module. To create Item Promotions, see Item and Order Trade Promotions Editor Guide. (You can also view a recorded training webinar on creating promotions - Product Education - Trade Promotions training).

To install Item Trade Promotions, log in to the Pepperi Webapp as an Admin user.

Click on Settings -> Configuration -> Add on Manager

NOTE: If you have a custom Webapp Main Bar configured in the webapp, the Settings gear will not be visible. You will need to remove the custom Main Bar for the Admin profile only (add the Admin profile to the Webapp Main Bar customization with no file selected). This will not affect the view of buyers or other profiles using the webapp.

Select Item Trade Promotions

Select the Edit Menu and Install

(If you don't see the add-on you want in the list or get a notification that you don't have access to install this Add on, contact us to enable it)

Steps to completing the installation

To complete the installation, the admin must complete the following steps. Once the admin completes these steps, then any user can use the promotions editor to create the promotions themselves.

Before installation - check your internal delimiter in ERP Integration Configuration settings. The internal delimiter cannot be set to ':' otherwise the data from the promotions will not be displayed in the editors. If your internal delimiter is set to ':' and you need to change it to ';' or '~' consult with your Pepperi project manager first, because this will affect your integration data.

1. Run the installation for each Transaction Type where Item Trade Promotions should be applied.
2. Define Promotion Types in the Types Editor
3. Indicate custom pricing fields for Item Promotions
4. Modification or Translation of the Next Discount message text (ex: $ $ $ Buy 10 get 5% off)
5. Create one or more Items lists (you can define which Item list will be used as default for selection of items when creating promotions in the Item TP Editor)
6. Create a shortcut button to the editor for the user who will be configuring the trade promotions (marketing manager, sales manager etc.)

Detailed instructions for each step appear below.

1. Run the installation for each Transaction Type where Item Trade Promotions should be applied.

After installation the Item Trade Promotions Add on will be added. For Item Trade Promotions to be configured, you must run the installation for each Transaction Type where Item Trade Promotions should be applied.

For example: B2B Transaction, Sales Rep Order, etc.

                                                                                                                                                                  

Best practice

It is best practice to first duplicate the transaction you want to use promotion on - for example duplicate your Sales Order Transaction to "Sales Order with Promotions" -  and install the promotion on the duplicated transaction. That way you can use the duplicated transaction during the configuration and testing period and once done, run the installation again on the original transaction. Once you are done testing, you will need to modify those promotion types to apply to the original "Sales Order". Promotion types are explained below.

How to Duplicate a Transaction Type

 Create test orders with test values of your duplicated transaction:

If you are limiting promotions by Transaction Type, you will need to create at least one test order on the duplicated Transaction Type in order for the editor to recognize this transaction. Also, any Transaction fields that you want to use to limit the promotion by will need to have at least one test order with each value so that you can select it when configuring the promotion types (ie if you want to limit promotions by payment method of cash, you must have at least one test order where the value cash was selected for the payment method field in the database, for the editor to recognize this value).

                                                                                                                                                                  

Go to Settings -> Promotion Setup -> Item TP Setup

Select the Transaction Type that will support Item Trade Promotions (note the best practice tip above before selecting your transaction).

Select the Transaction Type that will support Item Trade Promotions (note the best practice tip above before selecting your transaction). 

 

After the installation, the following objects will be created in your Pepperi back office.

NOTE: Do not delete or change these objects otherwise the promotion will not work properly.

• User defined tables with the prefix of 'PPI_ItemPromotion'

• Custom Transaction Line-Item fields in the selected Transaction Type with the prefix of 'PPI_ItemPromotion' (in addition to any existing custom fields you already may have in this Transaction)

_____________________________________________________________________________________________________

 Tip!

To allow customers to understand which promotion discount they are getting, add the following fields to the order center view or cart view:

• PPI_ItemPromotion_Reason - will show the name of the promotion applied
• Unit Price After Discount - will show the newly calculated unit price after the promotion was applied
• Item Discount - if the promotion includes an item discount (on the specific item, not tier-based), will show the percentage discount applied by the promotion.

 

2. Define Promotion Types in the Types Editor

In order to use Item Trade Promotions, you must first define the combinations of properties that the item promotions apply to. These are called "Item Promotion Types", and they are defined in the Promotions Setup -> Item TP Types Editor. Their values will later be selected in the Promotions Editor to define the promotions themselves.

Here are some examples:

Promotion Applies to	Properties to add to the Item Promotion Type (Object -> Property)
Medium sized Accounts, and Items of Brand "X"	Account -> Size  Item ->Main Category
Small customers located in City "A", and Items in SubCategory "S" only when buyers are ordering on Pepperi B2B eCommerce site	Account -> Size Account -> City Item -> SubCategory Transaction -> Type
Items in SubCategory "F", only when sales reps are ordering on the app for all customers	Item -> SubCategory Transaction -> Type

In the Type definition, you define which fields will be used, and not the values of the fields to be filtered. (You will define the values in the Item Promotion editor).

Select Item TP Types, and click Add+, to define a type.

Description - name the Promotion Type, make it a descriptive name so that it is clear to the person who will need to select the type in the Promotions Editor.

Priority - give a priority to each type. If there is more than one Item Promotion that applies to certain Items, then the promotions will be applied in order of their priority. 

The priority is relevant only if you don't want to apply multiple promotions.

Apply multiple promotions - 

• Yes, continue to the next promotion - means that all promotions will apply on top of each other. In this case, the Priority does not matter, enter "1" for Priority.
• No - means that if more than one Item Promotion applies to the Item, then no additional promotions will be applied after the current one. 

Example: There is an Item of Brand A with a discount, and Brand A itself also has a discount

Brand discount - Priority=1

Item discount - Priority=2

If you choose "Yes, continue to next promotion" on Brand promotion type - the customer gets both discounts

If you choose "No" on the Brand promotion type - they get only the Brand discount, will not continue to the next promotion

Promotion Properties

Object Type - Select the object of the Promotion Type fields - Account, Item, or Transaction

Property - Select the field for the Object type, includes custom fields.

Click Add + to add more properties.

Click Save.

 

Continue to add all the types that you will need Item Trade Promotions defined for.

 

3. Indicate custom pricing fields for Item Promotions

By default, the Item Promotion module will use default fields from the Transaction Lines as input to determine if the promotion should be applied, and as output to set the new price or discount. These fields are listed in the table below.

If you are using custom fields for these fields, you will need to indicate which fields the promotions should be based on by editing the PPI_ItemPromotion_Init field.

To indicate your own custom fields:

• Edit the PPI_ItemPromotion_Init Custom Transaction Field
• Go to the Input or Output section (see below), uncomment the relevant lines and enter your custom field names. 

Examples of custom input fields:

If you are using a custom field TSACalcUnitPrice instead of the default UnitPrice, uncomment the API_UnitPrice line and enter your field API name instead of "TSAmyUnitPrice".

If you are using a custom field TSACalcUnitQuantity instead of the default UnitsQuantity, uncomment the API_Discount_BreakBy-Quantity and enter your field API name instead of "TSAmyUnitsQuantity".

 

Examples of custom output fields:

If you are using a custom field TSACalcUnitDiscount instead of the default UnitDiscountPercentage field, to store the percentage discount on the item, uncomment the API_UnitDiscount line and enter your field API name instead of "TSAmyUnitDiscountPercentage".

 

If you are using a custom field TSACalcUnitPriceAfterDiscount instead of the default UnitPriceAfterDiscount, to store the line total after the item promotion discount, uncomment the API_UnitPriceAfterDiscount and enter the API name of your field instead of "TSAmyUnitPriceAfterDiscounl".

/* Input fields: */
// config.APINames["API_UnitPrice"] = "TSAmyUnitPrice"; // The field which contains the item price
// config.APINames["API_Discount_BreakBy_Quantity"] = "TSAmyUnitsQuantity"; // The field which contains the item quantity (for a quantity based discount)
// config.APINames["API_Discount_BreakBy_Price"] = "TSAmyTotalUnitsPriceBeforeDiscount"; // The field which contains the item total price (for a price based discount)

/* Output fields: */
// config.APINames["API_UnitDiscount"] = "TSAmyUnitDiscountPercentage"; // This field will be set with the new discount
// config.APINames["API_UnitPriceAfterDiscount"] = "TSAmyUnitPriceAfterDiscount"; // This field will be set with the new unit price after discount
// config.APINames["API_TotalUnitsPriceAfterDiscount"] = "TSAmyTotalUnitsPriceAfterDiscount"; // This field will be set with the new total unit price after discount (for additional item)
// config.APINames["API_UnitsQuantity"] = "TSAmyUnitsQuantity";

 

3. Create one or more Items lists (you can define which one to use for selection)

Before configuring Trade Promotions in the editor, the admin will need to create at least one Items List. The Items List is used to select items that the promotion applies to. (If you've already created the Items List for another type of Trade Promotion, no need to do it again. The same list can be used to configure all Promotion types). 

To create an Items List please follow these instructions carefully - Item Lists

When creating the list, make sure to include fields in the List View layout, and Smart Search of each list that will enable quick filtering of the lists, so that it's easier to find the Items that the promotions will apply to.

If you have created a specific Item List (or Account List) that is more convenient for you to use for selecting Items or Accounts for a promotion, you can define that as the default list that will be shown.

To define a specific Account or Item selection list:

Settings -> Promotion Setup -> Item TP Setup

Click on Advanced Setup and enter the List ID(s)

You can find the List ID as explained in section #9 in Package Promotions Advanced Configuration

4. Modification or Translation of the Next Discount message text 

The field PPI_ItemPromotion_NextDiscount displays to the user the quantity/price they need to purchase to be eligible for the promotion incentive(s). You can translate the text in this message to your language.

In each Transaction Type you need to translate the text for (Sales Order, B2B Order, etc.):

• Go to the Fields tab
• Edit the PPI_ItemPromotionLogic field in the Transaction Custom Fields section
• Locate the following part of the code in the field's Formula area (it is closer to the beginning, so scroll up in the field formula to find it)
• Replace the English words (ie "Buy", "more", "get", "You got ") with translation to your language. Make sure to leave spaces where needed in your language for the values that will follow. 
• Test it in the Admin view and make sure it looks right before adding it to the users' views.

// Next discount text (for translation override via the init field)
var NextDiscountTextBuyPrefix = 'Buy ';
var NextDiscountTextBuySuffix = '';
var NextDiscountTextBuyMorePrefix = 'Buy ';
var NextDiscountTextBuyMoreSuffix = ' more';
var NextDiscountTextEligiblePrefix = 'You got ';
var NextDiscountTextEligibleSuffix = '. ';
var NextDiscountTextGetPrefix = ' to get ';
var NextDiscountTextGetSuffix = '';
var NextDiscountTextGetPercentagePrefix = '';
var NextDiscountTextGetPercentageSuffix = ' off';
var NextDiscountTextGetPricePrefix = '';
var NextDiscountTextGetPriceSuffix = ' off';
var NextDiscountTextGetAdditionalItemPrefix = 'an additional item';
var NextDiscountTextGetAdditionalItemSuffix = '';
var NextDiscountTextGetAdditionalItemsPrefix = '';
var NextDiscountTextGetAdditionalItemsSuffix = ' additional items';
var NextDiscountTextGetSeparator = ' + ';

If you want to change the "$ $ $" icons that appear before the message with your own icons or any emoji:

Edit the PPI_ItemPromotionNextDiscount field in the Transaction Line Item Custom Fields section

Enter the symbols or emoji you require in-between the single quotes in place of the "$ $ $ "

Examples:

To replace the $ with a star emoji:

Erase the $ and add the emoji and a space 

nextDiscountMessage = '⭐️  ' + nextDiscountMessage;

To add a star before and after the nextDiscountMessage:

Add the emoji and a space before nextDiscountMessage, and a space and the emoji after nextDiscountMessage.

nextDiscountMessage = '⭐️  ' + nextDiscountMessage +' ⭐️';

 

// This code returns the next discount details for the current item.

// Definition:
// * Level: Transaction Line
// * Trigger: On Demand
// * Available Fields: 'ItemWrntyID', 'ItemUUID', 'LineNumber'

var nextDiscountMessage = this.PPI_ItemPromotion.getNextDiscount(ItemWrntyID, ItemUUID, LineNumber);
if (nextDiscountMessage != '') {
nextDiscountMessage = '💲💲💲 ' + nextDiscountMessage;
}
return nextDiscountMessage;

5. Create a shortcut button to the editor for the user who will be configuring the trade promotions (marketing manager, sales manager etc.)

The user who will configure the promotions in the editor will need access to the editor page (they won't have access via the Settings Add-ons if they are not an Admin).

First set the Addon Permissions for the profile in order to allow them to access the add ons: How to set Addon Permissions.

Then copy the editor page link and add it as an Online Add-on shortcut button to the user's Pepperi home screen.

If you want the user to have access to the editors for all 3 types of Trade Promotions - Item, Order, and Package - you will need to create 3 shortcuts (each editor has its own link. Instructions for each editor are in the installation guide for that editor).

If you upgrade the version of a promotion Add-on you will need to re-copy the link and replace it in the online add on.

To copy the link: click on the Items Promotions Editor in the Add-on menu 

When the editor loads, copy the URL. It will look like this (with your ID):

https://app.pepperi.com/CustomPlugin/<Item Trade Promotions_ID>/defaultEditor

Then add it as an online add-on button on the user's home screen - How to add shortcuts to links on the App Home Screen and Menus

User's home screen with Promotion Editor shortcut buttons