itmosoft / laravel-loyalty
A configurable loyalty points and rewards ledger for Laravel applications, with customer balances, earning, redemption, and auditable transactions.
v1.0.0
2026-11-14 15:22 UTC
Requires
- php: ^8.3
- illuminate/contracts: ^12.0 || ^13.0
- 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
None
Provides
None
Conflicts
None
Replaces
None
README
A database-backed loyalty points ledger for Laravel 12 and 13.
Features
- Polymorphic loyalty accounts for Eloquent customer models.
- Earn, redeem, and manual adjustment transactions.
- Balance updates inside database transactions with row-level locking.
- Transaction history with balance-after snapshots.
- Optional reference, expiry timestamp, and JSON metadata.
- Prevents negative balances by default.
- Configurable table names, prefix, and minimum redemption.
Requirements
- PHP 8.3+
- Laravel 12 or 13
Installation
composer require itmosoft/laravel-loyalty php artisan vendor:publish --tag=itmosoft-loyalty-config php artisan migrate
Publishing config is optional.
Usage
Add the trait to your customer model:
use ItmoSoft\Loyalty\Concerns\HasLoyaltyAccount; class User extends Authenticatable { use HasLoyaltyAccount; }
Earn:
$transaction = app(\ItmoSoft\Loyalty\LoyaltyManager::class)->earn( customer: $user, points: 100, reason: 'Order completed', reference: 'ORDER-1001', metadata: ['order_id' => 1001], );
Redeem:
app(\ItmoSoft\Loyalty\LoyaltyManager::class)->redeem( customer: $user, points: 25, reason: 'Checkout redemption' );
Adjust:
app(\ItmoSoft\Loyalty\LoyaltyManager::class)->adjust( customer: $user, points: 10, reason: 'Support correction' );
Read balance and ledger:
$account = $user->getOrCreateLoyaltyAccount(); $balance = $user->loyaltyBalance(); $transactions = $account->transactions;
Configuration
return [ 'accounts_table' => 'itmosoft_loyalty_accounts', 'transactions_table' => 'itmosoft_loyalty_transactions', 'prefix' => '', 'default_currency' => 'points', 'allow_negative_balance' => false, 'minimum_redemption' => 1, 'points_expire_after_days' => null, ];
Scope and accounting limitations
- Points are integer units; fractional points are unsupported.
- This release stores
expires_atmetadata but does not automatically expire points or calculate spendable lots. - Redemption deducts from the aggregate account balance; FIFO/FEFO lot consumption is not implemented.
referenceis informational and not unique/idempotent. Enforce idempotency in the consuming application.lockForUpdate()relies on database engine support; SQLite does not provide production-equivalent row-locking guarantees.- No monetary conversion, tax, discount, eligibility, or external reward fulfillment is included.
- The application is responsible for authorization, tenant scoping, and audit policy.
- This package alone is not a complete financial accounting system.
Testing
composer validate --strict
composer install
composer test
MIT License. See LICENSE.