Promotion Module

Overview

The Promotion Module manages promotional campaigns, discount codes, and automated promotions. It provides rule-based promotion targeting and supports various discount types including percentage, fixed amount, and free shipping. Key Features:

Promotional campaigns with budgets
Discount codes and automatic promotions
Rule-based targeting (customer groups, products, etc.)
Multiple application methods (order, item, shipping)
Budget tracking and limits
Time-based promotions
Usage limits per customer
Buy X Get Y promotions

When to Use

Use the Promotion Module when you need to:

Create discount codes for customers
Run promotional campaigns
Offer free shipping promotions
Implement BOGO (Buy One Get One) offers
Target specific customer groups
Set promotion budgets and limits
Schedule time-limited sales
Track promotion usage

Data Models

Promotion

Represents a discount or promotional offer.

string

required

Unique promotion identifier

string

Discount code (e.g., “SUMMER20”)

PromotionType

required

Type: standard, buyget

boolean

required

Whether promotion applies automatically (default: false)

string

ID of the associated campaign

ApplicationMethod

How discount is applied

PromotionRule[]

Targeting rules

ApplicationMethod

Defines how and where a promotion discount applies.

string

required

Unique application method identifier

string

required

Method type: fixed, percentage

string

required

What to discount: order, items, shipping_methods

BigNumber

required

Discount value (amount for fixed, percentage for percentage)

number

Maximum items to discount

number

Number of items to apply discount to

number

Minimum quantity to buy (for buyget promotions)

string

How to allocate: each, across

PromotionRule

Defines targeting conditions for promotions.

string

required

Unique rule identifier

string

required

ID of the promotion

string

required

Rule attribute (e.g., “customer_group_id”, “product_id”)

string

required

Comparison operator: eq, ne, in, gt, gte, lt, lte

PromotionRuleValue[]

required

Rule values to match

Campaign

Groups promotions with budget management.

string

required

Unique campaign identifier

string

required

Campaign name

string

Campaign description

string

Campaign currency code

string

required

Unique campaign identifier (e.g., “summer-2024”)

DateTime

When campaign starts

DateTime

When campaign ends

CampaignBudget

Campaign budget configuration

Promotion[]

Promotions in this campaign

CampaignBudget

Tracks campaign budget and usage.

string

required

Unique budget identifier

string

Budget type: spend, usage

BigNumber

Budget limit

BigNumber

Amount used so far

Service Interface

The Promotion Module service is available at @medusajs/medusa/promotion.

Create Promotion

Create a new promotion.

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPromotionModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const promotionModuleService: IPromotionModuleService = req.scope.resolve(
    Modules.PROMOTION
  )

  const promotion = await promotionModuleService.createPromotions({
    code: "SUMMER20",
    type: "standard",
    is_automatic: false,
    application_method: {
      type: "percentage",
      target_type: "order",
      value: 20, // 20% off
    },
    rules: [
      {
        attribute: "customer_group_id",
        operator: "in",
        values: ["cgroup_retail"],
      },
    ],
  })

  res.json({ promotion })
}

const promotion = await promotionModuleService.createPromotions({
  code: "SAVE10",
  type: "standard",
  application_method: {
    type: "fixed",
    target_type: "order",
    value: 1000, // $10 off
  },
})

const promotion = await promotionModuleService.createPromotions({
  code: "FREESHIP",
  type: "standard",
  application_method: {
    type: "fixed",
    target_type: "shipping_methods",
    value: 100, // 100% discount on shipping
  },
  rules: [
    {
      attribute: "subtotal",
      operator: "gte",
      values: [5000], // Minimum $50 order
    },
  ],
})

CreatePromotionDTO | CreatePromotionDTO[]

required

Promotion data

string

Discount code (required for non-automatic promotions)

PromotionType

required

Promotion type: standard, buyget

boolean

Whether promotion applies automatically

CreateApplicationMethodDTO

required

How to apply the discount

CreatePromotionRuleDTO[]

Targeting rules

PromotionDTO | PromotionDTO[]

The created promotion(s)

Create Campaign

Create a promotional campaign with budget.

const campaign = await promotionModuleService.createCampaigns({
  name: "Summer Sale 2024",
  description: "Annual summer promotion",
  campaign_identifier: "summer-2024",
  starts_at: new Date("2024-06-01"),
  ends_at: new Date("2024-08-31"),
  budget: {
    type: "spend",
    limit: 10000, // $100 budget
  },
})

CreateCampaignDTO | CreateCampaignDTO[]

required

Campaign data

string

required

Campaign name

string

required

Unique identifier

Date

Campaign start date

Date

Campaign end date

CreateCampaignBudgetDTO

Budget configuration

Add Promotion to Campaign

Associate a promotion with a campaign.

const promotion = await promotionModuleService.updatePromotions(
  "promo_123",
  {
    campaign_id: "camp_summer2024",
  }
)

Compute Actions

Calculate promotion discounts for a cart or order.

const result = await promotionModuleService.computeActions(
  ["promo_summer20"],
  {
    items: [
      {
        id: "item_123",
        product_id: "prod_456",
        variant_id: "variant_789",
        quantity: 2,
        subtotal: 4000,
      },
    ],
    shipping_methods: [
      {
        id: "sm_123",
        subtotal: 500,
      },
    ],
  }
)

for (const action of result.actions) {
  console.log(`Apply ${action.amount} discount to ${action.item_id}`)
}

string[]

required

IDs of promotions to compute

object

required

Cart/order context

object[]

Cart or order items

object[]

Shipping methods

object

Customer data

ComputeActionsResult

Computed discount actions

Register Usage

Track promotion usage.

await promotionModuleService.registerUsage({
  promotion_id: "promo_123",
  amount: 1000,
  customer_id: "cus_456",
})

Revert Usage

Revert promotion usage (e.g., on order cancellation).

await promotionModuleService.revertUsage({
  promotion_id: "promo_123",
  amount: 1000,
})

Promotion Types

Standard Promotions

Basic discount promotions.

{
  code: "SAVE20",
  type: "standard",
  application_method: {
    type: "percentage",
    target_type: "order",
    value: 20,
  },
}

{
  code: "10OFF",
  type: "standard",
  application_method: {
    type: "fixed",
    target_type: "order",
    value: 1000,
  },
}

{
  code: "ITEM5OFF",
  type: "standard",
  application_method: {
    type: "fixed",
    target_type: "items",
    value: 500,
    allocation: "each", // $5 off each item
  },
  rules: [
    {
      attribute: "product_id",
      operator: "in",
      values: ["prod_123", "prod_456"],
    },
  ],
}

Buy X Get Y (BOGO)

{
  code: "BOGO",
  type: "buyget",
  application_method: {
    type: "percentage",
    target_type: "items",
    value: 100, // 100% off
    buy_rules_min_quantity: 2,
    apply_to_quantity: 1,
  },
  rules: [
    {
      attribute: "product_id",
      operator: "in",
      values: ["prod_tshirt"],
    },
  ],
}

{
  code: "BUY3GET50",
  type: "buyget",
  application_method: {
    type: "percentage",
    target_type: "items",
    value: 50,
    buy_rules_min_quantity: 3,
    apply_to_quantity: 1,
  },
}

Automatic Promotions

{
  type: "standard",
  is_automatic: true,
  application_method: {
    type: "percentage",
    target_type: "shipping_methods",
    value: 100,
  },
  rules: [
    {
      attribute: "subtotal",
      operator: "gte",
      values: [5000], // Free shipping over $50
    },
  ],
}

Rule Examples

Customer Group Targeting

rules: [
  {
    attribute: "customer_group_id",
    operator: "in",
    values: ["cgroup_vip"],
  },
]

Product Targeting

rules: [
  {
    attribute: "product_id",
    operator: "in",
    values: ["prod_123", "prod_456"],
  },
]

rules: [
  {
    attribute: "product_category_id",
    operator: "in",
    values: ["pcat_summer"],
  },
]

Order Value Targeting

rules: [
  {
    attribute: "subtotal",
    operator: "gte",
    values: [10000], // $100 minimum
  },
]

Integration Examples

With Cart Module

Apply promotions to cart.

import { Modules } from "@medusajs/framework/utils"

const cartModule = container.resolve(Modules.CART)
const promotionModule = container.resolve(Modules.PROMOTION)

// Get cart
const cart = await cartModule.retrieveCart("cart_123", {
  relations: ["items"],
})

// Find applicable promotions
const promotions = await promotionModule.listPromotions({
  code: "SUMMER20",
})

// Compute discounts
const result = await promotionModule.computeActions(
  promotions.map(p => p.id),
  {
    items: cart.items,
    customer: { id: cart.customer_id },
  }
)

// Apply as line item adjustments
for (const action of result.actions) {
  await cartModule.createLineItemAdjustments({
    item_id: action.item_id,
    amount: -action.amount,
    code: promotions[0].code,
  })
}

With Customer Module

Customer group promotions.

import { Modules } from "@medusajs/framework/utils"

const customerModule = container.resolve(Modules.CUSTOMER)
const promotionModule = container.resolve(Modules.PROMOTION)

// Get customer groups
const customer = await customerModule.retrieveCustomer("cus_123", {
  relations: ["groups"],
})

// Find promotions for customer groups
const promotions = await promotionModule.listPromotions({
  is_automatic: true,
  rules: {
    attribute: "customer_group_id",
    value: customer.groups.map(g => g.id),
  },
})

Best Practices

Code Uniqueness: Promotion codes must be unique. Use descriptive codes that are easy for customers to remember.
Automatic vs Manual: Use automatic promotions for always-on offers (e.g., free shipping over $50). Use codes for targeted campaigns.
Rule Combinations: Rules are AND conditions. All rules must match for a promotion to apply.
Budget Tracking: Set campaign budgets to control promotion costs. Monitor usage regularly.
Target Specificity: Use specific targeting rules to prevent unintended discount application.
Testing: Always test promotions with sample carts before making them active.
Allocation:
- each: Apply discount to each matching item individually
- across: Apply total discount split across all matching items

Cart Module - Apply promotions to carts
Order Module - Track promotion usage
Customer Module - Customer group targeting
Product Module - Product targeting
Pricing Module - Work with price lists

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

Promotion Module

Overview

When to Use

Data Models

Promotion

ApplicationMethod

PromotionRule

Campaign

CampaignBudget

Service Interface

Create Promotion

Create Campaign

Add Promotion to Campaign

Compute Actions

Register Usage

Revert Usage

Promotion Types

Standard Promotions

Buy X Get Y (BOGO)

Automatic Promotions

Rule Examples

Customer Group Targeting

Product Targeting

Order Value Targeting

Integration Examples

With Cart Module

With Customer Module

Best Practices

​Overview

​When to Use

​Data Models

​Promotion

​ApplicationMethod

​PromotionRule

​Campaign

​CampaignBudget

​Service Interface

​Create Promotion

​Create Campaign

​Add Promotion to Campaign

​Compute Actions

​Register Usage

​Revert Usage

​Promotion Types

​Standard Promotions

​Buy X Get Y (BOGO)

​Automatic Promotions

​Rule Examples

​Customer Group Targeting

​Product Targeting

​Order Value Targeting

​Integration Examples

​With Cart Module

​With Customer Module

​Best Practices

​Related Modules

Overview

When to Use

Data Models

Promotion

ApplicationMethod

PromotionRule

Campaign

CampaignBudget

Service Interface

Create Promotion

Create Campaign

Add Promotion to Campaign

Compute Actions

Register Usage

Revert Usage

Promotion Types

Standard Promotions

Buy X Get Y (BOGO)

Automatic Promotions

Rule Examples

Customer Group Targeting

Product Targeting

Order Value Targeting

Integration Examples

With Cart Module

With Customer Module

Best Practices

Related Modules