Medusa Loyalty Plugin

A powerful loyalty points system plugin for Medusa e-commerce platform that allows you to manage customer loyalty points, track transactions, and implement reward programs.

Features

• 💰 Credit and debit points for customers
• 📊 Track point transactions with detailed history
• ⏱️ Configurable point expiration
• 🔄 Multiple reference types (order, referral, manual)
• 📝 Customizable transaction descriptions
• 🎯 Easy integration with Medusa workflows

Installation

1. Install the plugin in your Medusa backend:

npm install @devx-commerce/plugin-loyalty
# or
yarn add @devx-commerce/plugin-loyalty

2. Add the plugin to your medusa-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "@devx-commerce/plugin-loyalty",
    options: {
      // Add your configuration options here
    },
  },
];

Usage

Managing Points

The plugin provides a simple interface to manage customer loyalty points:

// Credit points to a customer
await loyaltyModuleService.addPoints({
  customerId: "cus_123",
  points: 100,
  referenceType: "order",
  description: "Points earned from order #123",
  expires_at: new Date("2024-12-31"), // Optional
});

// Deduct points from a customer
await loyaltyModuleService.deductPoints({
  customerId: "cus_123",
  points: 50,
  referenceType: "order",
  description: "Points redeemed for discount",
});

// Get customer's current points
const points = await loyaltyModuleService.getPoints("cus_123");

// Get transaction history
const transactions = await loyaltyModuleService.getTransactionHistory(
  "cus_123",
  {
    take: 10,
    skip: 0,
    type: "credit", // or "debit"
  }
);

Workflow Integration

The plugin includes a workflow step for managing points:

import { managePointsStep } from "@devx-commerce/plugin-loyalty/workflows";

// Use in your workflow
const result = await managePointsStep({
  customer_id: "cus_123",
  points: 100,
  type: "credit",
  reference_type: "order",
  description: "Points earned from order",
  expiry_days: 30, // Optional
});

Configuration

The plugin can be configured through the medusa-config.js file:

{
  resolve: "@devx-commerce/plugin-loyalty",
  options: {
    // Add your configuration options here
  },
}

Requirements

• Node.js >= 20
• Medusa v2.4.0 or higher
• PostgreSQL database

Development

1. Clone the repository:

git clone https://github.com/your-username/plugin-loyalty.git

2. Install dependencies:

yarn install

3. Build the plugin:

yarn build

4. Start development:

yarn dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue in the GitHub repository or contact the maintainers.

About Medusa

This plugin is built for Medusa, the open-source headless commerce engine.