itmosoft / laravel-vendor-commissions
Configurable vendor commission rules and commission ledger for Laravel marketplace applications.
Package info
github.com/ITMOSOFT/laravel-vendor-commissions
pkg:composer/itmosoft/laravel-vendor-commissions
Requires
- php: ^8.3
- illuminate/database: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.0|^12.0
Suggests
- itmosoft/laravel-vendors: Recommended when using the default vendor model.
Provides
None
Conflicts
None
Replaces
None
README
Configurable vendor commission rules and a commission ledger for Laravel 12 and 13 marketplace applications.
Requirements
- PHP 8.3+
- Laravel 12 or 13
itmosoft/laravel-vendorswhen using the default vendor model (or pass a vendor model / ID)
Installation
composer require itmosoft/laravel-vendor-commissions php artisan vendor:publish --tag=itmosoft-vendor-commissions-config php artisan migrate
The package creates {table_prefix}vendor_commission_rules and {table_prefix}vendor_commissions. The Eloquent models use the same configured prefix, so migrations and queries remain aligned. Configure table_prefix before migrating if you need different table names.
Create commission rules
use ItmoSoft\VendorCommissions\VendorCommissionManager; $commissions = app(VendorCommissionManager::class); // Global rule: 10% commission for USD orders. $commissions->createRule([ 'name' => 'Default USD commission', 'rate_type' => 'percentage', 'rate' => '10.0000', 'currency' => 'USD', 'priority' => 0, ]); // Vendor-specific rules take precedence over global rules. $commissions->createRule([ 'name' => 'Preferred vendor rate', 'vendor_id' => $vendor->getKey(), 'rate_type' => 'percentage', 'rate' => '7.5000', 'currency' => 'USD', 'priority' => 10, ]);
Rules also support fixed rates, minimum_amount, maximum_amount, starts_at, ends_at, is_active, and priority.
Calculate and record a commission
$calculation = $commissions->calculate($vendor, '125.00', 'USD'); // commission_amount: 12.50; vendor_amount: 112.50 (with a 10% rule) $commission = $commissions->record($vendor, '125.00', 'USD', [ 'order_id' => $order->getKey(), 'order_item_id' => $item->getKey(), 'external_reference' => 'order-'.$order->getKey().'-item-'.$item->getKey(), 'metadata' => ['channel' => 'web'], ]);
Use a stable external_reference to make event retries idempotent. Reusing a reference with a different vendor, amount, or currency throws a RuntimeException.
Approve and reverse
$commissions->approve($commission); $commissions->reverse($commission, 'Order refunded'); $totals = $commissions->vendorTotals($vendor, 'USD');
Only pending commissions can be approved. A commission can be reversed once; reversal reason and timestamp are retained. Reversal does not delete the original record.
Configuration
config/itmosoft-vendor-commissions.php:
table_prefix: defaults toitmosoft_.default_currency: defaults toUSD.default_rate_type: defaults topercentage.default_rate: defaults to10.0000.
Important production notes
- Pass monetary amounts as decimal strings; avoid binary floating-point values in application code.
- Current schema stores money in
DECIMAL(18,2)and rates inDECIMAL(12,4). Adapt the migration and rounding policy for currencies with zero or three minor-unit digits. - Commission calculation uses the first matching vendor-specific rule, otherwise the highest-priority global rule. If no rule matches, configured defaults are used.
minimum_amountmeans the gross transaction must meet the threshold or the commission is zero.maximum_amountcaps the commission amount.- This package does not calculate taxes, refunds, chargebacks, payout eligibility, or transfer funds. Integrate those policies in the host application and coordinate reversals with the payout ledger.
- Protect rule management, approval, and reversal with host-application authorization. The package deliberately does not impose roles or policies.
- The commission record snapshots the selected rule's rate and calculated amounts so later rule edits do not rewrite historical records.
- Use database transactions and a stable
external_referencefor retry-safe event handling. For high-concurrency event ingestion, handle unique-key conflicts at the application boundary.
Testing
composer validate --strict
composer install
composer test
License
MIT. See LICENSE.