Promotion Concepts

In this guide, you’ll learn about the main promotion and rule concepts in the Promotion Module.

What is a Promotion?#

A promotion, represented by the Promotion data model, is a discount that can be 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.

Promotion Rules#

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.

A PromotionRule's attribute property indicates the property's name to which this rule is applied. For example, customer_group_id.

The expected value for the attribute 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 property 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 property 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 record with its attribute property set to customer_group_id and operator property to in.
• Add two PromotionRuleValue records 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.

How to Apply Rules on a Promotion?#

Using Workflows#

If you're managing promotions using Medusa's workflows or the API routes that use them, you can specify rules for the promotion or its application method.

For example, if you're creating a promotion using the createPromotionsWorkflow:

Code
1const { result } = await createPromotionsWorkflow(container)2  .run({3    input: {4      promotionsData: [{5        code: "10OFF",6        type: "standard",7        status: "active",8        application_method: {9          type: "percentage",10          target_type: "items",11          allocation: "across",12          value: 10,13          currency_code: "usd",14        },15        rules: [16          {17            attribute: "customer.group.id",18            operator: "eq",19            values: [20              "cusgrp_123",21            ],22          },23        ],24      }],25    },26  })

In this example, the promotion is restricted to customers with the cusgrp_123 customer group.

Using Promotion Module's Service#

If you're managing promotions using the Promotion Module's service, you can specify rules for the promotion or its application method in its methods.

For example, if you're creating a promotion with the createPromotions method:

Code
1const promotions = await promotionModuleService.createPromotions([2  {3    code: "50OFF",4    type: "standard",5    status: "active",6    application_method: {7      type: "percentage",8      target_type: "items",9      value: 50,10    },11    rules: [12      {13        attribute: "customer.group.id",14        operator: "eq",15        values: [16          "cusgrp_123",17        ],18      },19    ],20  },21])

In this example, the promotion is restricted to customers with the cusgrp_123 customer group.

How is the Promotion Rule Applied?#

A promotion is applied on a resource if its attributes match the promotion's rules.

For example, consider you have the following promotion with a rule that restricts the promotion to a specific customer:

Code
1{2  "code": "10OFF",3  "type": "standard",4  "status": "active",5  "application_method": {6    "type": "percentage",7    "target_type": "items",8    "allocation": "across",9    "value": 10,10    "currency_code": "usd"11  },12  "rules": [13    {14      "attribute": "customer_id",15      "operator": "eq",16      "values": [17        "cus_123"18      ]19    }20  ]21}

When you try to apply this promotion on a cart, the cart's customer_id is compared to the promotion rule's value based on the specified operator. So, the promotion will only be applied if the cart's customer_id is equal to cus_123.