Shopkeeper Vendor Sales Report

A Magento 2.4.x module that generates monthly vendor sales reports with automated email delivery.

Features

• Manual Report Generation: Generate reports for any custom date range via admin interface
• Preview Grid: View report data before exporting
• Automated Monthly Reports: Automatic generation on the 1st of each month via cron
• Email Delivery: Automatically email reports with CSV attachment
• Configurable:
  • Order status filtering
  • Email recipients
  • Email subject line
  • Email sender
• State Abbreviation: Automatically converts full state names to 2-letter codes
• Cost Fallback: Uses current product cost if order item cost is missing

Installation

Method 1: Manual Installation

1. Upload the module files:

   # From your Magento root directory
   mkdir -p app/code/Shopkeeper/VendorSalesReport
   # Upload all module files to app/code/Shopkeeper/VendorSalesReport/
   

2. Enable the module:

   php bin/magento module:enable Shopkeeper_VendorSalesReport
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy -f
   php bin/magento cache:flush
   

3. Set permissions (if needed):

   chmod -R 755 app/code/Shopkeeper/
   

Method 2: Composer Installation (if you package it)

composer require shopkeeper/module-vendor-sales-report
php bin/magento module:enable Shopkeeper_VendorSalesReport
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Configuration

Admin Configuration Path

Stores > Configuration > Shopkeeper > Vendor Sales Report

Settings

General Settings

• Enable Automated Monthly Report: Enable/disable automatic monthly report generation
• Order Status Filter: Select which order statuses to include (default: Complete)

Email Settings

• Enable Email: Enable/disable email delivery
• Email Recipients: Comma-separated list of email addresses
• Email Subject: Subject line for automated emails (use {{month}} and {{year}} placeholders for dynamic values)
• Email Sender: Choose which store email identity to use as sender

Example Configuration

Enable Automated Monthly Report: Yes
Order Status Filter: complete
Enable Email: Yes
Email Recipients: vendor@example.com, admin@example.com
Email Subject: Monthly Thermo Report - {{month}} {{year}}
Email Sender: General Contact

Usage

Manual Report Generation

1. Go to Reports > Sales > Vendor Sales Report
2. Select date range using the date pickers
3. Click Preview Report to view data in a grid
4. Click Export CSV to download the report

The report will be downloaded as FF_SAC_730_MCQUEEN.csv

Automated Monthly Reports

Once configured, the module will automatically:

1. Generate a report on the 1st of each month at 2:00 AM
2. Include all orders from the previous month
3. Email the report as a CSV attachment to configured recipients

Report Format

The CSV file includes the following columns:

Column	Description
Date	Order date (MM/DD/YYYY format)
Vendor Product number	Product SKU
Description	Product name
Vendor code	(Empty - reserved for vendor use)
Vendor name	(Empty - reserved for vendor use)
Dealer product number	Order increment ID
Country	Shipping address country
City	Shipping address city
State	Shipping address state (abbreviated)
Zip code	Shipping address postal code
Quantity	Quantity ordered
Cost	Product cost (uses order item cost, falls back to current product cost if missing)

Cron Schedule

The automated report runs according to this schedule:

0 2 1 * *

Translation: At 2:00 AM on the 1st day of every month

To test the cron manually:

php bin/magento cron:run --group default

Troubleshooting

Reports not generating automatically

1. Check if cron is enabled:

   php bin/magento cron:run
   

2. Check cron_schedule table:

   SELECT * FROM cron_schedule 
   WHERE job_code = 'shopkeeper_vendorsalesreport_monthly' 
   ORDER BY scheduled_at DESC 
   LIMIT 10;
   

3. Check module configuration:

   • Ensure "Enable Automated Monthly Report" is set to Yes
   • Verify order status is configured

Emails not sending

1. Check email configuration:

   • Verify email recipients are configured
   • Ensure "Enable Email" is set to Yes
   • Check Magento's email sending is working (test with other emails)

2. Check logs:

   tail -f var/log/system.log | grep "Vendor Sales Report"
   

No data in report

1. Check order status filter:

   • Verify orders have the configured status (default: "complete")
   • Try including additional statuses like "processing"

2. Verify date range:

   • Ensure orders exist within the selected date range

State abbreviations not working

• The module includes all US states, DC, and territories
• If international addresses appear, they'll show as-is (not abbreviated)
• Already abbreviated states (2 characters) are left unchanged

Module Structure

Shopkeeper/VendorSalesReport/
├── Block/
│   └── Adminhtml/
│       └── Report.php
├── Controller/
│   └── Adminhtml/
│       └── Report/
│           ├── Export.php
│           ├── Grid.php
│           └── Index.php
├── Cron/
│   └── GenerateMonthlyReport.php
├── etc/
│   ├── acl.xml
│   ├── config.xml
│   ├── crontab.xml
│   ├── email_templates.xml
│   ├── module.xml
│   └── adminhtml/
│       ├── menu.xml
│       ├── routes.xml
│       └── system.xml
├── Helper/
│   └── Data.php
├── Model/
│   ├── EmailSender.php
│   └── ReportGenerator.php
├── view/
│   └── adminhtml/
│       ├── email/
│       │   └── report.html
│       ├── layout/
│       │   └── vendorsalesreport_report_index.xml
│       └── templates/
│           └── report/
│               └── view.phtml
└── registration.php

Requirements

• Magento 2.4.x
• PHP 7.4 or higher
• MySQL 5.7 or higher

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review Magento logs: var/log/system.log
3. Verify module is enabled: php bin/magento module:status

License

Proprietary - Shopkeeper

Version

1.0.0

Changelog

Version 1.0.0

• Initial release
• Manual report generation with date range selector
• Preview grid functionality
• Automated monthly cron job
• Email delivery with CSV attachment
• Configurable order status filter
• State abbreviation support
• Cost fallback to current product cost