@pillexa/medusa-subscription-plugin

A comprehensive subscription management plugin for Medusa e-commerce platform, built with TypeScript.

Features

• 🚀 Subscription Management: Create, update, and cancel subscriptions
• 🔄 Recurring Billing: Support for weekly, monthly, and yearly billing cycles
• 📡 Event-Driven: Automatic subscription creation from orders
• 🛡️ TypeScript: Full TypeScript support with type safety
• 🧪 Testing: Comprehensive test coverage
• 📚 RESTful API: Complete API endpoints for subscription management
• 🔔 Event Handling: Subscribe to subscription lifecycle events

Installation

npm install @pillexa/medusa-subscription-plugin

Configuration

Add the plugin to your Medusa configuration:

// medusa-config.js
const plugins = [
  // ... other plugins
  {
    resolve: "@pillexa/medusa-subscription-plugin",
    options: {
      // Plugin options can be added here
    }
  }
];

module.exports = {
  projectConfig: {
    // ... your project config
  },
  plugins
};

Usage

Service Usage

import { SubscriptionService } from "@pillexa/medusa-subscription-plugin";

// Create a subscription
const subscription = await subscriptionService.create({
  customer_id: "cust_123",
  product_id: "prod_456",
  interval: "monthly",
  status: "active"
});

// Retrieve a subscription
const subscription = await subscriptionService.retrieve("sub_123");

// List subscriptions
const subscriptions = await subscriptionService.list({
  customer_id: "cust_123",
  status: "active"
});

// Update a subscription
const updatedSubscription = await subscriptionService.update("sub_123", {
  status: "paused",
  interval: "yearly"
});

// Cancel a subscription
const cancelledSubscription = await subscriptionService.cancel("sub_123");

// Process billing
const billingResult = await subscriptionService.processBilling("sub_123");

API Endpoints

The plugin provides the following REST API endpoints:

GET /subscriptions

List all subscriptions with optional filters.

Query Parameters:

• customer_id (string): Filter by customer ID
• status (string): Filter by status (active, cancelled, paused, expired)
• interval (string): Filter by interval (weekly, monthly, yearly)

Example:

GET /subscriptions?customer_id=cust_123&status=active

GET /subscriptions/:id

Get a specific subscription by ID.

Example:

GET /subscriptions/sub_123

POST /subscriptions

Create a new subscription.

Request Body:

{
  "customer_id": "cust_123",
  "product_id": "prod_456",
  "interval": "monthly",
  "status": "active"
}

PUT /subscriptions/:id

Update a subscription.

Request Body:

{
  "status": "paused",
  "interval": "yearly"
}

DELETE /subscriptions/:id

Cancel a subscription.

POST /subscriptions/:id/billing

Process billing for a subscription.

GET /subscriptions/customer/:customer_id

Get all subscriptions for a specific customer.

GET /subscriptions/status/:status

Get all subscriptions with a specific status.

Event Handling

The plugin automatically handles the following events:

Order Events

• order.placed: Creates subscriptions for subscription products
• order.payment_captured: Handles payment processing
• order.cancelled: Handles order cancellation

Subscription Events

• subscription.created: Triggered when a subscription is created
• subscription.updated: Triggered when a subscription is updated
• subscription.cancelled: Triggered when a subscription is cancelled
• subscription.billing_processed: Triggered when billing is processed

Types

interface Subscription {
  id: string;
  customer_id: string;
  product_id: string;
  interval: 'weekly' | 'monthly' | 'yearly';
  status: 'active' | 'cancelled' | 'paused' | 'expired';
  created_at: Date;
  updated_at: Date;
  next_billing_date: Date;
  order_id?: string;
}

interface CreateSubscriptionData {
  customer_id: string;
  product_id: string;
  interval: SubscriptionInterval;
  status?: SubscriptionStatus;
  order_id?: string;
}

interface UpdateSubscriptionData {
  customer_id?: string;
  product_id?: string;
  interval?: SubscriptionInterval;
  status?: SubscriptionStatus;
  next_billing_date?: Date;
}

Development

Prerequisites

• Node.js 18+
• npm or yarn
• Medusa backend

Setup

1. Clone the repository

2. Install dependencies:

   cd packages/subscriptions
   npm install

3. Build the plugin:

   npm run build

4. Run tests:

   npm test

5. Run linting:

   npm run lint

Scripts

• npm run build: Build the TypeScript code
• npm run watch: Watch for changes and rebuild
• npm test: Run tests
• npm run test:watch: Run tests in watch mode
• npm run lint: Run ESLint
• npm run lint:fix: Fix ESLint issues
• npm run type-check: Run TypeScript type checking

Testing

The plugin includes comprehensive tests covering:

• Service methods (create, retrieve, list, update, cancel, processBilling)
• API endpoints
• Event handling
• Error cases
• Type validation

Run tests with:

npm test

Run tests with coverage:

npm test -- --coverage

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT

Support

For support, please open an issue on GitHub or contact the Pillexa team.

Changelog

v0.1.0

• Initial release
• Basic subscription management
• TypeScript support
• RESTful API endpoints
• Event-driven architecture
• Comprehensive testing