bench get-app https://github.com/pankajxmathur/erpnext_promotions

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=pankajxmathur%2Ferpnext_promotions)](https://frappegems.com/gems/apps/pankajxmathur/erpnext_promotions)

ERPNext Promotions

A comprehensive promotions and campaigns management application for ERPNext, converted from the Medusa promotions module.

Features

Core Functionality

• Promotions Management: Create and manage discount promotions with flexible rules
• Campaign Management: Group promotions under campaigns with budget tracking
• Rule-based Eligibility: Define complex rules for promotion eligibility
• Multiple Discount Types: Support for fixed amount and percentage discounts
• Buy-Get Promotions: Advanced buy X get Y promotion types
• Budget Tracking: Track campaign spending and usage limits

Promotion Types

1. Standard Promotions: Simple discount promotions
2. Buy-Get Promotions: Buy X items, get Y items at discount

Application Methods

• Fixed Amount: Discount by a fixed monetary amount
• Percentage: Discount by a percentage of the order/item value

Target Types

• Order Level: Apply discount to entire order
• Item Level: Apply discount to specific items
• Shipping: Apply discount to shipping costs

Rule Engine

• Order Rules: Based on order total, subtotal, item count, etc.
• Customer Rules: Based on customer group, territory, etc.
• Item Rules: Based on item codes, groups, brands, categories
• Time Rules: Based on day of week, time of day
• Custom Attributes: Extensible rule system

Installation

1. Get the app from the repository:

bench get-app https://github.com/yourcompany/erpnext_promotions.git

2. Install the app on your site:

bench --site your-site install-app erpnext_promotions

3. Run migrations:

bench --site your-site migrate

Usage

Creating a Campaign

1. Go to Promotions > Campaign
2. Create a new campaign with:
   • Campaign name and identifier
   • Start and end dates
   • Budget type (Spend/Usage) and limit
   • Currency (for spend budgets)

Creating a Promotion

1. Go to Promotions > Promotion
2. Create a new promotion with:
   • Promotion name and code
   • Type (Standard/Buy Get)
   • Application method (Fixed/Percentage)
   • Target type (Order/Items/Shipping)
   • Discount value
   • Rules for eligibility

Applying Promotions

Promotions can be applied to: - Sales Orders: Add promotion codes during order creation - Sales Invoices: Apply promotions during invoicing

Rule Configuration

Configure rules to control when promotions apply: - Promotion Rules: General order-level conditions - Target Rules: Specific item conditions for discount application - Buy Rules: Item conditions for buy-get promotions

API Integration

Get Applicable Promotions

from erpnext_promotions.api.promotion_engine import PromotionEngine

engine = PromotionEngine()
context = {
    "total": 1000,
    "customer_group": "Retail",
    "items": [...]
}
promotions = engine.get_applicable_promotions(context)

Apply Promotion

promotion = frappe.get_doc("Promotion", "PROMO-001")
result = promotion.apply_promotion(context)

Scheduled Tasks

The app includes automated tasks: - Daily: Update campaign and promotion status based on dates - Daily: Check budget limits and send alerts - Hourly: Sync promotion usage counts from transactions

Permissions

Default roles with access: - System Manager: Full access to all features - Sales Manager: Create, edit, and manage promotions and campaigns - Sales User: View and apply promotions

Configuration

Custom Fields

The app automatically adds custom fields to: - Sales Order: promotion_codes, promotion_discount, applied_promotions - Sales Invoice: promotion_codes, promotion_discount, applied_promotions

Hooks

The app hooks into: - Sales Order validation and submission - Sales Invoice validation and submission

Migrating from Medusa

This app replicates the functionality of the Medusa promotions module:

Data Model Mapping

• Medusa Promotion → ERPNext Promotion
• Medusa Campaign → ERPNext Campaign
• Medusa ApplicationMethod → ERPNext Promotion (embedded)
• Medusa PromotionRule → ERPNext Promotion Rule
• Medusa CampaignBudget → ERPNext Campaign (embedded)

Feature Parity

• ✅ Promotion codes and automatic promotions
• ✅ Campaign management with budget tracking
• ✅ Rule-based promotion eligibility
• ✅ Multiple application methods (fixed/percentage)
• ✅ Target types (order/shipping/items)
• ✅ Buy-get promotions
• ✅ Budget validation and tracking
• ✅ Usage limits and tracking

Development

Running Tests

bench --site your-site run-tests --app erpnext_promotions

Custom Rule Attributes

Extend the rule engine by adding custom attributes in the promotion rule options.

Support

For support and documentation, visit: - GitHub: https://github.com/yourcompany/erpnextpromotions - Documentation: https://yourcompany.github.io/erpnextpromotions

License

MIT License