Promotion Concepts

In this document, you’ll learn about the concepts in the Promotion Module.

Promotion

A promotion, represented by the Promotion data model, represents a discount applied on cart items, shipping methods, or entire orders.

A promotion has two types:

• standard: A standard promotion with rules.
• buyget: “A buy X get Y” promotion with rules.

standard Promotion Examples	buyget Promotion Examples
A coupon code that gives customers 10% off their entire order.	Buy two shirts and get another for free.
A coupon code that gives customers $15 off any shirt in their order.	Buy two shirts and get 10% off the entire order.
A discount applied automatically for VIP customers that removes 10% off their shipping method’s amount.	Spend $100 and get free shipping.

PromotionRule

A promotion can be restricted by a set of rules, each rule is represented by the PromotionRule data model. For example, you can create a promotion that only customers of the VIP customer group can use it.

A PromotionRule's attribute attribute indicates the attribute's name to which this rule is applied. For example, customer_group_id. Its value is stored in the PromotionRuleValue data model. So, a rule can have multiple values.

When testing whether a promotion can be applied to a cart, the rule's attribute attribute and its values are tested on the cart itself. For example, the cart's customer must be part of the customer group(s) indicated in the promotion rule's value.

Flexible Rules

The PromotionRule's operator attribute adds more flexibility to the rule’s condition rather than simple equality (eq).

For example, to restrict the promotion to only VIP and B2B customer groups:

• Add a PromotionRule with its attribute attribute set to customer_group_id and operator attribute to in.
• Add two PromotionRuleValue associated with the rule: one with the value VIP and the other B2B.

In this case, a customer’s group must be in the VIP and B2B set of values to use the promotion.

---

Application Method

The ApplicationMethod data model defines how a promotion is applied:

attribute	Purpose
type	Does the promotion discount a fixed amount or a percentage?
target_type	Is the promotion applied on a cart item, shipping method, or the entire order?
allocation	Is the discounted amount applied on each item or split between the applicable items?

Target Promotion Rules

When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.

The ApplicationMethod data model has a collection of PromotionRule records to restrict which items or shipping methods the promotion applies to. The target_rules attribute represents this relation.

In this example, the promotion is only applied on products in the cart having the SKU SHIRT.

Buy Promotion Rules

When the promotion’s type is buyget, you must specify the “buy X” condition. For example, a cart must have two shirts before the promotion can be applied.

The application method has a collection of PromotionRule items to define the “buy X” rule. The buy_rules attribute represents this relation.

In this example, the cart must have two products with the SKU SHIRT for the promotion to be applied.

---

Campaign

A Campaign combines promotions under the same conditions, such as start and end dates.

Campaign Limits

Each campaign has a budget represented by the CampaignBudget data model. The budget limits how many times the promotion can be used.

There are two types of budgets:

• spend: An amount that, when crossed, the promotion becomes unusable. For example, if the amount limit is set to $100, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
• usage: The number of times that a promotion can be used. For example, if the usage limit is set to 10, the promotion can be used only 10 times by customers. After that, it can no longer be applied.

---

Full Data Models Diagram