Loyalty Module

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

Medusa has loyalty related features available through the Loyalty 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 Loyalty Module.

Features#

• Gift Card Products: Create physical or digital gift cards as products that customers can purchase
• Gift Card Management: Issue, redeem, and track gift cards with unique codes
• Cart Integration: Apply gift cards as payment during checkout

How to Use the Loyalty Module#

1. Install the Loyalty Plugin#

The Loyalty Module is part of the Loyalty Plugin. So, install the loyalty plugin:

yarn
pnpm
npm

Then, add it to your medusa-config.js:

medusa-config.js
1module.exports = defineConfig({2  // ... other configurations3  plugins: [4    {5      resolve: `@medusajs/loyalty-plugin`,6      options: {},7    },8    // ... other plugins9  ],10})

2. Run Migrations#

After installing the plugin, run the migrations to create the necessary tables in the database:

yarn
pnpm
npx

3. Use Loyalty Features in Your Application#

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 the Loyalty Plugin's workflows and steps.

For example:

src/workflows/create-gift-card.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7
8const createGiftCardStep = createStep(9  "create-gift-card",10  async ({}, { container }) => {11    const loyaltyModuleService = container.resolve("loyalty")12
13    const giftCard = await loyaltyModuleService.createGiftCards({14      code: "test-code",15      value: 50,16      currency_code: "usd",17      expires_at: null,18      reference_id: "order_123",19      reference: "order",20      line_item_id: "litem_123",21      customer_id: "customer_123",22    })23
24    return new StepResponse({ giftCard }, giftCard.id)25  },26  async (giftCardId, { container }) => {27    const loyaltyModuleService = container.resolve("loyalty")28
29    await loyaltyModuleService.deleteGiftCards([giftCardId])30  }31)32
33export const createGiftCardWorkflow = createWorkflow(34  "create-gift-card",35  () => {36    const { giftCard } = createGiftCardStep()37
38    return new WorkflowResponse({39      giftCard,40    })41  }42)

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

Learn more about workflows in this documentation.