README

The Laravel-Discount is a Laravel package designed to handle discounts in your application effortlessly. This package provides a comprehensive and flexible solution to apply various discount strategies, making it easy to integrate promotional offers, seasonal sales, and other discount-related functionalities into your Laravel project.

Features

Percentage Discounts: Apply percentage-based discounts to your products or services.
Fixed Amount Discounts: Deduct a fixed amount from the total cost.
Buy X Get Y: Run "buy 2, get 1 free" deals that price the free items automatically.
Tiered Discounts: Grow the discount with the order total, e.g. 5% over 1,000,000 and 10% over 5,000,000.
Free Shipping: Waive the shipping cost instead of deducting from the total.
Conditional Discounts: Set conditions for discounts, such as minimum order value or specific product categories.
Discount Codes: Generate and manage discount codes for your customers.
Expiry Dates: Set expiration dates for discounts to create time-limited offers.
Usage Limits: Restrict the number of times a discount can be used.
Stackable Discounts: Allow multiple discounts to be applied simultaneously or restrict stacking.
Support Laravel Cart
Detailed Documentation: Comprehensive guides and examples to help you get started quickly.

Requirements
Installation
Publish Config & Migrations
- Upgrading an Existing Installation
Usage
Testing
Contributors
Security
License

Requirements

PHP 8.1 or higher
Laravel 9.0 or higher

Installation

Install the package with Composer:

composer require binafy/laravel-discount

The service provider is registered automatically. Run the migrations to create the discounts, discount_usages, and discountables tables:

php artisan migrate

Publish Config & Migrations

Publishing is optional — the package works out of the box. Publish the config to customize table names, the user model, or code generation defaults:

php artisan vendor:publish --tag="laravel-discount-config"

Publish the migrations if you want to change the table structure before migrating:

php artisan vendor:publish --tag="laravel-discount-migrations"

Once a migration is published, the package no longer loads its own copy of it, so php artisan migrate runs each migration exactly once.

Upgrading an Existing Installation

Fresh installs need nothing here. If you already migrated the discounts table before the buy_x_get_y, tiered, and free_shipping types existed, the type enum still rejects them. Widen it — and make value optional, since the new types do not use it — with your own migration:

use Binafy\LaravelDiscount\Enums\DiscountType;

Schema::table('discounts', function (Blueprint $table) {
    $table->enum('type', DiscountType::values())->default(DiscountType::Percentage->value)->change();
    $table->decimal('value', 10, 2)->default(0)->change();
});

On Laravel 10 and below, ->change() requires doctrine/dbal.

Usage

Create a Discount

Binafy\LaravelDiscount\Models\Discount is a regular Eloquent model.

Percentage Discount

use Binafy\LaravelDiscount\Enums\DiscountType;
use Binafy\LaravelDiscount\Models\Discount;

$discount = Discount::query()->create([
    'name' => 'Summer Sale',
    'type' => DiscountType::Percentage,
    'value' => 20, // 20%
]);

Fixed Amount Discount

$discount = Discount::query()->create([
    'name' => 'Ten dollars off',
    'type' => DiscountType::Fixed,
    'value' => 10, // deducts 10 from the total
]);

A fixed discount never exceeds the amount it is applied to, so the payable amount can never go below zero.

Maximum Discount Amount

Cap how much a discount can deduct — "20% off, up to 100":

$discount = Discount::query()->create([
    'code' => 'SAVE20',
    'type' => DiscountType::Percentage,
    'value' => 20,
    'max_discount_amount' => 100,
]);

LaravelDiscount::apply($discount, 300)->discountAmount;  // 60.0  (20% of 300)
LaravelDiscount::apply($discount, 1000)->discountAmount; // 100.0 (capped)

Buy X Get Y

"Buy 2, get 1 free" — the deal lives in the conditions column, and the manager works out how many items come free:

$discount = Discount::query()->create([
    'name' => 'Buy 2 get 1 free',
    'code' => 'BUY2GET1',
    'type' => DiscountType::BuyXGetY,
    'conditions' => ['buy' => 2, 'get' => 1],
]);

Because the deal counts items, pass the quantity the amount covers:

// 3 items at 100 each: the third one is free.
LaravelDiscount::apply($discount, 300, quantity: 3)->discountAmount; // 100.0

// 6 items at 50 each: two full sets, so two items are free.
LaravelDiscount::apply($discount, 300, quantity: 6)->discountAmount; // 100.0

// Below a full set, nothing applies.
LaravelDiscount::apply($discount, 200, quantity: 2)->discountAmount; // 0.0

The free items are priced at the basket's average unit price, so a mixed basket is handled too. Two optional conditions refine the deal:

Condition	Meaning	Default
`buy`	Items that must be paid for (required)	—
`get`	Items that come free per set (required)	—
`get_discount_percentage`	How much off the free items, e.g. `50` for "the third at half off"	`100`
`max_free_items`	Cap on free items per order	none

// Buy 2, get the third at 50% off, at most 2 discounted items per order.
'conditions' => ['buy' => 2, 'get' => 1, 'get_discount_percentage' => 50, 'max_free_items' => 2],

The quantity argument is also accepted by applyCode(), applyMany() and the applyDiscounts() trait method. Every other discount type ignores it.

Tiered Discount

Grow the discount with the order total. The ladder lives in the conditions column, and the highest tier the amount reaches wins:

$discount = Discount::query()->create([
    'name' => 'Spend more, save more',
    'type' => DiscountType::Tiered,
    'conditions' => ['tiers' => [
        ['min' => 1_000_000, 'value' => 5],  // over 1,000,000 → 5%
        ['min' => 5_000_000, 'value' => 10], // over 5,000,000 → 10%
    ]],
]);

LaravelDiscount::apply($discount, 900_000)->discountAmount;   // 0.0      (below every tier)
LaravelDiscount::apply($discount, 2_000_000)->discountAmount; // 100_000.0 (5%)
LaravelDiscount::apply($discount, 6_000_000)->discountAmount; // 600_000.0 (10%)

Tiers may be listed in any order, and a tier applies exactly at its min. A tier discounts by percentage unless it sets 'type' => 'fixed':

'conditions' => ['tiers' => [
    ['min' => 1_000_000, 'value' => 50_000, 'type' => 'fixed'],
    ['min' => 5_000_000, 'value' => 400_000, 'type' => 'fixed'],
]],

To show the customer which tier they landed on:

LaravelDiscount::matchingTier($discount, 6_000_000); // ['min' => 5000000, 'value' => 10]

Free Shipping

A free shipping discount deducts nothing from the order total. Instead it raises a flag on the result, which you honour when charging for shipping:

$discount = Discount::query()->create([
    'name' => 'Free shipping',
    'code' => 'FREESHIP',
    'type' => DiscountType::FreeShipping,
]);

$result = LaravelDiscount::applyCode('FREESHIP', 500);

$result->discountAmount;        // 0.0
$result->payableAmount();       // 500.0
$result->hasFreeShipping();     // true
$result->payableShipping(35);   // 0.0   (35 when shipping is not free)
$result->payableTotal(35);      // 500.0 (535 when shipping is not free)

Free shipping sits outside the stacking competition described in Stackable Discounts: since it saves nothing on the amount, it would always lose. Every valid free shipping discount is applied on top of whichever monetary discount wins:

$result = LaravelDiscount::applyMany([$freeShipping, $twentyPercent], 500);

$result->discountAmount;    // 100.0 (the 20%)
$result->hasFreeShipping(); // true

Everything else still applies, so min_order_value gates free shipping the usual way:

Discount::query()->create([
    'code' => 'SHIP-OVER-1000',
    'type' => DiscountType::FreeShipping,
    'min_order_value' => 1000,
]);

Apply a Discount

Use the LaravelDiscount facade to apply a discount to an amount. It validates the discount first and returns a DiscountResult:

use Binafy\LaravelDiscount\Facades\LaravelDiscount;

$result = LaravelDiscount::apply($discount, 200);

$result->originalAmount;    // 200.0
$result->discountAmount;    // 40.0
$result->payableAmount();   // 160.0
$result->discounts;         // Collection of the applied discounts
$result->hasFreeShipping(); // false — see Free Shipping

To check a discount without throwing exceptions:

LaravelDiscount::isValid($discount, orderAmount: 200, user: $user); // true|false

Discount Codes

A discount with a code acts as a coupon; a discount without one is an automatic discount.

$discount = Discount::query()->create([
    'code' => 'WELCOME10',
    'type' => DiscountType::Percentage,
    'value' => 10,
]);

Generate Codes

Generate cryptographically random, unique codes (ambiguous characters like 0/O and 1/I are excluded by default):

LaravelDiscount::generateCode();              // "8FJ2K9QW"
LaravelDiscount::generateCode('SUMMER');      // "SUMMER-8FJ2K9QW"
LaravelDiscount::generateCodes(100, 'VIP');   // Collection of 100 unique codes

Customize the length, character set, prefix, and separator in config/laravel-discount.php under the codes key.

Apply by Code

$result = LaravelDiscount::applyCode('WELCOME10', 200, $user);

If the code does not exist, a DiscountNotFoundException is thrown. You can also look a discount up yourself:

$discount = LaravelDiscount::findByCode('WELCOME10');

Expiry Dates & Time Windows

Give a discount a start date, an expiry date, or both to create time-limited offers:

$discount = Discount::query()->create([
    'code' => 'BLACK-FRIDAY',
    'type' => DiscountType::Percentage,
    'value' => 30,
    'starts_at' => now()->startOfDay(),
    'expires_at' => now()->addDays(3),
]);

Before starts_at, applying throws DiscountNotStartedException.
After expires_at, applying throws DiscountExpiredException (and dispatches the DiscountExpired event).
Query only the currently applicable discounts with the valid() scope:

Discount::query()->valid()->get();

Usage Limits

Limit how many times a discount can be used — in total and per user:

$discount = Discount::query()->create([
    'code' => 'FIRST-100',
    'type' => DiscountType::Fixed,
    'value' => 15,
    'usage_limit' => 100,        // first 100 redemptions only
    'usage_limit_per_user' => 1, // once per user
]);

Redeeming

When an order is finalized, record the redemption. This creates a DiscountUsage row and increments the used_count counter atomically — the limit check happens inside the update query, so concurrent requests can never exceed the limit:

LaravelDiscount::redeem($discount, $user, $result->discountAmount);

When the limit is exhausted, DiscountUsageLimitReachedException is thrown.

Guest Discounts

Guests (not-logged-in visitors) can use discounts too. Pass a session id instead of a user, and the per-user limit is enforced per session:

$result = LaravelDiscount::applyCode('GUEST10', $total, sessionId: session()->getId());

LaravelDiscount::redeem($discount, amount: $result->discountAmount, sessionId: session()->getId());

The discount_usages.user_id column is nullable — guest redemptions store the session_id instead.

Conditional Discounts

Minimum Order Value

$discount = Discount::query()->create([
    'code' => 'BIG-SPENDER',
    'type' => DiscountType::Percentage,
    'value' => 15,
    'min_order_value' => 500,
]);

LaravelDiscount::applyCode('BIG-SPENDER', 300); // throws MinimumOrderValueException
LaravelDiscount::applyCode('BIG-SPENDER', 800); // OK

The conditions JSON column also configures the Buy X Get Y and Tiered types, and is otherwise free for your own arbitrary condition data.

Attach Discounts to Models

Add the HasDiscounts trait to any model (products, categories, ...) to make it discountable:

use Binafy\LaravelDiscount\Traits\HasDiscounts;

class Product extends Model
{
    use HasDiscounts;
}

// Attach and query
$product->discounts()->attach($discount);
$product->validDiscounts();       // only the currently applicable ones
$product->hasDiscount('TECH10');  // by code or by model instance

// Apply all attached valid discounts to a price (stacking rules included)
$result = $product->applyDiscounts($product->price);
$result->payableAmount();

Stackable Discounts

Mark a discount with is_stackable => true to allow it to combine with other stackable discounts. When you apply multiple discounts, the package resolves stacking automatically:

Stackable discounts are combined (their total never exceeds the amount).
Non-stackable discounts compete alone.
Whichever saves the customer the most wins.
Invalid discounts are silently skipped.
Free shipping discounts sit outside the competition and always apply.

$result = LaravelDiscount::applyMany([$tenPercent, $tenFixed, $bigSolo], 100);

$result->discounts;       // the discounts that were actually applied
$result->discountAmount;  // the winning total

Form Request Validation

Validate a submitted coupon code with the ValidDiscountCode rule. It checks that the code exists and is currently applicable, and the error message states the exact reason (not found, expired, usage limit reached, below minimum order, ...):

use Binafy\LaravelDiscount\Rules\ValidDiscountCode;

public function rules(): array
{
    return [
        'code' => ['required', new ValidDiscountCode(
            orderAmount: $this->cartTotal(),
            user: $this->user(),
        )],
    ];
}

For guests, pass a session id instead of a user:

'code' => ['required', new ValidDiscountCode($total, sessionId: session()->getId())],

Validation & Exceptions

Every failure case has its own exception, all extending Binafy\LaravelDiscount\Exceptions\DiscountException:

Exception	Thrown when
`DiscountNotFoundException`	The given code does not exist
`DiscountNotActiveException`	The discount is disabled (`is_active = false`)
`DiscountNotStartedException`	`starts_at` is in the future
`DiscountExpiredException`	`expires_at` is in the past
`DiscountUsageLimitReachedException`	The total or per-user usage limit is reached
`MinimumOrderValueException`	The order total is below `min_order_value`
`InvalidDiscountConditionsException`	A "buy X get Y" or tiered discount is misconfigured

Each exception carries the discount that failed, so you can handle every case separately:

use Binafy\LaravelDiscount\Exceptions\DiscountException;
use Binafy\LaravelDiscount\Exceptions\DiscountExpiredException;

try {
    $result = LaravelDiscount::applyCode($code, $total, $user);
} catch (DiscountExpiredException $e) {
    return back()->withErrors("Code {$e->getDiscount()->code} has expired.");
} catch (DiscountException $e) {
    return back()->withErrors($e->getMessage());
}

Events

Event	Dispatched when
`DiscountApplied`	One or more discounts are applied to an amount
`DiscountRedeemed`	A redemption is recorded (after the transaction commits)
`DiscountExpired`	Validation encounters an expired discount

use Binafy\LaravelDiscount\Events\DiscountRedeemed;

Event::listen(DiscountRedeemed::class, function (DiscountRedeemed $event) {
    // $event->discount, $event->usage
});

Laravel Cart Integration

If binafy/laravel-cart is installed, the CartDiscount service becomes available:

composer require binafy/laravel-cart

use Binafy\LaravelDiscount\Integrations\LaravelCart\CartDiscount;

$cartDiscount = app(CartDiscount::class);

// Apply a code (or discount models) to the whole cart total
$result = $cartDiscount->applyToCart($cart, 'SUMMER-8FJ2K9QW');
$result->payableAmount();

// Apply a discount to a specific cart item (price × quantity)
$result = $cartDiscount->applyToItem($cartItem, $discount);

// Automatically apply the discounts attached to each item's model
// (via the HasDiscounts trait) across the whole cart
$result = $cartDiscount->applyItemDiscounts($cart);

The cart total is checked against min_order_value, and the cart's user is used for per-user usage limits automatically.

Item quantities are counted for you, so Buy X Get Y discounts work without passing a quantity: applyToCart() counts every unit in the cart, while applyToItem() and applyItemDiscounts() count the units of each item. Free shipping attached to any single item makes the whole order's shipping free:

$result = $cartDiscount->applyItemDiscounts($cart);

$result->hasFreeShipping();  // true when any item's discount grants it
$result->payableTotal(35);   // the cart total plus the shipping still due

Artisan Commands

Generate unique discount codes from the command line:

php artisan discount:generate                    # one code
php artisan discount:generate 100 --prefix=VIP  # 100 codes like VIP-8FJ2K9QW

Delete expired discounts (their usage records are removed with them):

php artisan discount:prune            # everything already expired
php artisan discount:prune --days=30  # only discounts expired 30+ days ago

discount:prune works well as a scheduled task:

Schedule::command('discount:prune --days=30')->daily();

Testing

composer install
./vendor/bin/pest

Contributors

Thanks to all the people who contributed. Contributors.

Security

If you discover any security-related issues, please email binafy23@gmail.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

binafy / laravel-discount

Maintainers

Package info

Statistics

Security

README

Features

Table of Contents

Requirements

Installation

Publish Config & Migrations

Upgrading an Existing Installation

Usage

Create a Discount

Percentage Discount

Fixed Amount Discount

Maximum Discount Amount

Buy X Get Y

Tiered Discount

Free Shipping

Apply a Discount

Discount Codes

Generate Codes

Apply by Code

Expiry Dates & Time Windows

Usage Limits

Redeeming

Guest Discounts

Conditional Discounts

Minimum Order Value

Attach Discounts to Models

Stackable Discounts

Form Request Validation

Validation & Exceptions

Events

Laravel Cart Integration

Artisan Commands

Testing

Contributors

Security

License