Loyalty Plugin for Medusa: adds gift cards and store credit to a Medusa application, including gift card products, redeeming gift cards and store credit at checkout, and store credit accounts for customers. It provides the Loyalty Module and Store Credit Module, Admin and Store API routes, workflows, and Medusa Admin pages. It isn't registered by default: install it and add it to plugins in medusa-config.ts (Medusa v2.14.0+).

At a glance

| | | | --- | --- | | Package | @medusajs/loyalty-plugin | | Type | Plugin | | Modules | Loyalty Module ("loyalty"), Store Credit Module ("store_credit") | | Registered by default | No | | Import from | @medusajs/loyalty-plugin/workflows, @medusajs/loyalty-plugin/types |

Features

• Gift card products: sell physical or digital gift cards; a gift card with a generated code is created for each one purchased when the order is placed.
• Checkout: apply gift cards and store credit to a cart as payment (POST /store/carts/:id/gift-cards, POST /store/carts/:id/store-credits).
• Store credit accounts: credit, debit, and view transactions (/admin/store-credit-accounts), and let customers view and claim accounts (/store/store-credit-accounts).
• Admin API routes: manage gift cards under /admin/gift-cards. Store API routes: look up a gift card with GET /store/gift-cards/:idOrCode.
• Workflows such as createGiftCardsWorkflow, addGiftCardToCartWorkflow, and creditStoreCreditAccountWorkflow, plus hooks into Medusa's cart completion, payment refresh, and order credit line flows.
• Medusa Admin: Gift Cards, Gift Card Products, and Store Credits pages, and widgets on the customer, order, and sales channel details pages.

Installation

npm install @medusajs/loyalty-plugin

Usage

Register the plugin in medusa-config.ts:

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

module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "@medusajs/loyalty-plugin",
      options: {},
    },
  ],
})

Then run the migrations:

npx medusa db:migrate

Configuration

| Option | Type | Description | Default | | --- | --- | --- | --- | | prefix | string | Prefix of generated gift card codes. For example, "GC" generates GC-XXXX-XXXX-XXXX-XXXX. | "GIFT" | | sections | number | Number of 4-character sections in generated gift card codes. For example, 3 generates GIFT-XXXX-XXXX-XXXX. | 4 |

Resources

• Loyalty Module
• Store Credit Module
• Loyalty Plugin options
• Gift cards
• Loyalty workflows
• Loyalty user guide