Search by

itmosoft / laravel-loyalty

adeelrao007

A configurable loyalty points and rewards ledger for Laravel applications, with customer balances, earning, redemption, and auditable transactions.

Package info

github.com/ITMOSOFT/laravel-loyalty

pkg:composer/itmosoft/laravel-loyalty

Statistics

Installs: 7

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-14 15:22 UTC

This package is auto-updated.

Last update: 2026-11-14 15:23:49 UTC


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_at metadata but does not automatically expire points or calculate spendable lots.
  • Redemption deducts from the aggregate account balance; FIFO/FEFO lot consumption is not implemented.
  • reference is 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.