Promotion Module

In this section of the documentation, you will find resources to learn more about the Promotion Module and how to use it in your application.

Looking for no-code docs?: Refer to the Medusa Admin User Guide to learn how to manage promotions using the dashboard.

Medusa has promotion related features available out-of-the-box through the Promotion Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Promotion Module.

Note: Learn more about why modules are isolated in this documentation.

Promotion Features#

Discount Functionalities: A promotion discounts an amount or percentage of a cart's items, shipping methods, or the entire order.
Flexible Promotion Rules: A promotion has rules that restricts when the promotion is applied.
Campaign Management: A campaign combines promotions under the same conditions, such as start and end dates, and budget configurations.
Apply Promotion on Carts and Orders: Apply promotions on carts and orders to discount items, shipping methods, or the entire order.

How to Use the Promotion Module#

In your Medusa application, you build flows around commerce modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

src/workflows/create-promotion.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7import { Modules } from "@medusajs/framework/utils"8
9const createPromotionStep = createStep(10  "create-promotion",11  async ({}, { container }) => {12    const promotionModuleService = container.resolve(Modules.PROMOTION)13
14    const promotion = await promotionModuleService.createPromotions({15      code: "10%OFF",16      type: "standard",17      application_method: {18        type: "percentage",19        target_type: "order",20        value: 10,21        currency_code: "usd",22      },23    })24
25    return new StepResponse({ promotion }, promotion.id)26  },27  async (promotionId, { container }) => {28    if (!promotionId) {29      return30    }31    const promotionModuleService = container.resolve(Modules.PROMOTION)32
33    await promotionModuleService.deletePromotions(promotionId)34  }35)36
37export const createPromotionWorkflow = createWorkflow(38  "create-promotion",39  () => {40    const { promotion } = createPromotionStep()41
42    return new WorkflowResponse({43      promotion,44    })45  }46)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

Learn more about workflows in this documentation.

Was this page helpful?

Edit this page