Promotions and Deals

The Promotions entity is one of the two necessary entities to create a functioning promotions in BEES, the other entity is Deals which will be covered in more details below.

The main purpose of the Promotion entity is to serve as a metadata, where it is possible to establish the type of promotion, as well as setting a title, description and image for the promotions.

In this page, all identifiers, properties and attributes of promotions is discussed in detail.

Payload Breakdown

1.1 Identifiers

Promotion has two main properties that serves as identifiers, the vendorPromotionId and type. Below the two properties, as well as their definitions and examples are presented:

vendorPromotionId: This is the unique identifier of the promotion, it is important that this unique identifier matches the identifier in Deals in order to establish a relationship between the promotion metadata as well as the mechanics (present in Deals);
type: The type is very important because it will affect directly how the promotion will be displayed in the BEES Application. Furthermore, it also serves as a validation to raise the mechanics established in Deals. Each type has a specific customization in the BEES Application, for instance DISCOUNT type will have the original price of the product crossed out and will displayed the discounted price.

1.2 Promotion Availability Period

The Promotions entity also has the capability of establishing the period in which the Promotion will available. To establish the period in which the Promotion will be available there are two required fields:

startDate: The date in which the promotion will start appearing in the BEES Application;
endDate: The final date in which the promotion will appear in the BEES Application, after this date the.

It is important to emphasize that given that the Promotions is responsible only for the visibility within the BEES Application, once the endDate passes the promotion customization in the BEES Application will stop showing, however, it is also necessary to have the mechanics of the promotions (within Deals entity) for the same period. Therefore, when the endDate for the Promotions and Deals passes, both the visibility and mechanics of the promotion will stop and the user wont be able to purchase that specific promotion any longer.

1.3 Promotion User Interface Elements

Given that the Promotions affects the visibility of the promotional product, it is also possible to set references such as titles and descriptions to all promotions.

It is important to emphasize that the image, although can be populated for all types of promotions, wont be displayed for all of them. Only the FLEXIBLE_DISCOUNT type has the flexibility of displaying the image set up in the Promotions entity.

Deals

Deals management documentation

Deals entity is responsible for creating the entire mechanics of a promotions, such as specifying what products will have a promotional price as well as the conditions that will make a promotional price available.

There are multiple properties that can be used as a condition and also there are various ways of defining which products will have a promotional price as well as the type of promotion within Deals. All conditions and outputs are covered in more detail below.

Deals also has the functionality to segment specific promotions to a very granular level, starting from POC level up to the entire partner’s POC base.

Payload breakdown

2.1 Identifiers

The main identifiers of Deals is designated to segment the promotional product to a specific audience. Similar to the Price entity, there are two main properties that are described below:

Type: This property defines the level of the granularity of the audience that will be viewing the promotional product. There are three available values, being the most granular is the ACCOUNT, which is able the create promotions to one or more specific accounts. The second option is the DELIVERY_CENTERtype, which is able to offer a promotional product at a DDC level. The third option is more broadly, which the is the VENDOR type that offers the promotional price to entire base of a specific vendor;
Ids: The ids will be the corresponding list or value of the type configured, for instance if the type is set as ACCOUNT then the ids will be accountIds for the specific POCs.

2.2 Deals identifiers

Within Deals, there are some properties that is responsible for the distinction of the promotional product. The two main promotional identifiers are described below:

Vendor Deal Id: This is the unique identifier of the deal, it can be used as a reference for partners to validate and manage the deal using a unique term;
Vendor Promotion Id: It is also a unique identifier of the promotion id, however, it is important to emphasize that the vendorPromotionId must match the promotion identification that was configured within the Promotions entity. If the two identification in Promotions and Deals, does not match, then the promotion wont work.

2.3 Deals conditions

There are two main factors that Deals takes into consideration to create a promotional product, Conditions and Output. The first factor, which the Condition, is explained in more details below, as well as a few examples of the most used condition types.

Condition:

The condition is a set of circumstances that can be configured for a specific promotional product. The condition types within Deals are very simple and straight forward, however, they can be combined with other conditions to create specific mechanics for a promotional product;
Below are a few examples of the most used condition types:
- Simulation Date Time:
  - The simulation date and time establishes that this promotion will be available with a time window, where it start date is set as startDateTimeand the end date of the promotion is populated in the endDateTime. It is important to emphasize Promotions entity also has this capability and a good recommendation is to have Simulation Date Time equals the Promotion entity tart and end date.
- Line Item:
  - The line item condition establishes what product(s) will trigger the promotion output. It is easier to understand if we ask the following question: “What product should be in the cart for a discount to be applied?”. Frequently the product configured in the line item condition is the same product will have the discount, but does not necessary need to be case;
  - Within the Line item it is possible to establish the SKUs/Vendor Item Id as well as establishing more parameters within the line item, such as:
    - Min Quantity: Defines the minimum quantity of the line item configured, if a min quantity is set as 5, then the promotion will be applicable only when 5 of that product is within the cart;
    - Shared Min Quantity: In case more than one line item is configured, it possible to use this property to define if it should group multiple lines items to count towards the minimum quantity or it should count each line item to validade the minimum quantity;
    - Cross Discount: This property identifies if there will be more than one product receiving a discount.

For a full list of all conditions available as well as the explanation for all of them, please refer to the Stoplight documentation:

Deals documentation

2.4 Deals Output

The second main factor of the Deals is the Output. A full definition of what Output is as well as the most used properties are described below:

Output

Output refers to what the customer will get once the Conditions are met. Through the Output it is possible to establish what are the vendorItem Ids/SKUs what will receive a specific discount, as well as determine the amount of discount to be given. There are more flexibility within Output, such as given products as bonification (free goods), or even establishing a scale discount.

The most used types and properties within outputs are described below:

Line Item:
- Line item, analog to the condition, is the property that referes to the vendorItemItem/SKU what will receive the discount. Within the line item is is possible to set the type of the discount, if it is percentage [%] or amount of [$] also the value of the discount;
- One important field is the proportion which designates when the discount must be applied based on the quantity of line items within the cart. For instance, if set as 1, given that the condition was met, every line item added to the cart will have a discount applicable. If the proportion is set as 5, for every 5 line item added to the cart, then the discount will be application. If the proportion is set as 0, then the discount will be applicable only once and wont add up if the customer adds more product.
Line Item Scaled Discount:
- Line item scaled discount defines different discounts for different ranges of products added, therefore with Line Item Scale discount is it possible to configure the following case:
  - 5% discount for 1-5 products added to the cart;
  - 10% discount for 6-10 products added to the cart;
  - 15% discount for 10+ products added to the cart.
Free Goods:
- Free Goods are outputs in which the customer will receive one or more products for free, once all conditions are met. Therefore, within freegoods it is possible to establish the items (SKU/vendorItemId), as well as the quantity of each item that will be available as bonification.

For a complete list of outputs, as well as more definition of each type, please refers to the stoplight below:

Deals output documentation