Skip to content

Discounts

The Discount model in Shopper, discount types and rules, eligibility, usage limits, automatic discounts, and how promotions stack on a cart.

A discount takes an amount off a cart: 20% off the whole order with the SUMMER20 code, $10.00 off orders above $50.00, or 15% off the Classic T-Shirt for a list of customers. The customer enters a code, or the cart applies an automatic discount without one. Several discounts can apply to the same cart, in the order their exclusivity class and priority decide.

Each discount carries its own rules: dates, usage limits, a minimum purchase, the customers who can use it and the zone it is sold in. A campaign can group several discounts under a shared budget. The models and enums live in shopper/core. The rules that decide whether a discount applies and how much it takes off live in shopper/cart, in Shopper\Cart\Discounts\DiscountValidator and Shopper\Cart\Discounts\PromotionResolver, which the calculation pipeline runs every time a cart is calculated.

Models

Shopper uses three models for discounts:

ModelPurpose
Shopper\Core\Models\DiscountThe discount: code, type, value and rules
Shopper\Core\Models\DiscountDetailLinks a discount to a product it applies to or a customer who can use it
Shopper\Core\Models\OrderPromotionOne discount applied to an order, documented on the Orders page

Discount implements the Shopper\Core\Models\Contracts\Discount contract. None of these models has a key in config/shopper/models.php, so they are always loaded with their own class: write Shopper\Core\Models\Discount in your code, and add a relationship with resolveRelationUsing(), as shown in Models You Cannot Swap.

The HasPublicId trait fills the public_id of a discount with a ULID when it is created, so you can find a discount with Discount::findByPublicId() or the wherePublicId() scope, described in Public IDs.

Database Schema

Discounts use two tables: one row per discount, and one row per product or customer linked to a discount.

Discount Table

The sh_discounts table holds one row per discount (sh_ is the default table prefix):

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
public_idulidyesgeneratedPublic identifier, unique
codestringyesnullCode the customer enters, unique; null for an automatic discount
triggerstringnocodecode or automatic, cast to PromotionSource
typestringno-percentage or fixed_amount, cast to DiscountType
valueintegerno-Percentage, or amount in cents
is_activebooleannofalseTurns the discount on
apply_tostringno-order or products, a DiscountApplyTo value
min_requiredstringno-none, price or quantity, a DiscountRequirement value
min_required_valuestringyesnullMinimum subtotal in cents, or minimum quantity
eligibilitystringno-Key of the eligibility rule, such as everyone or customers
usage_limitunsigned integeryesnullUses allowed across all customers, null for no limit
usage_limit_per_userbooleannofalseAllows one use per customer
total_useunsigned integerno0Uses so far
start_atdatetimeno-Start of the discount
end_atdatetimeyesnullEnd of the discount, null when it never expires
zone_idbigintyesnullZone the discount is limited to, null for every zone
campaign_idbigintyesnullCampaign of the discount
exclusivity_classstringnoorderorder, product or shipping, cast to ExclusivityClass
combinablebooleannofalseLets the discount stack with another discount of its class
priorityintegerno0Order within the class, highest first
metadatajsonbyesnullYour own data, cast to an array
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

start_at has no default, so pass it when you create a discount. Several automatic discounts can have a null code: the unique index accepts more than one null. Deleting a zone or a campaign sets zone_id or campaign_id to null. Shopper updates total_use at checkout; leave it out of your own writes.

Discountable Table (Pivot)

The sh_discountables table holds the DiscountDetail rows, one per product or customer linked to a discount:

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
discount_idbigintno-Foreign key to the discount, rows are deleted with it
discountable_typestringno-Morph type of the linked model
discountable_idunsigned bigintno-ID of the linked model
conditionstringyesnullapply_to or eligibility, cast to DiscountCondition
total_useunsigned integerno0Not updated by Shopper
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

A unique index on discount_id, discountable_type and discountable_id links a model to a discount once.

The orders table copies the discount that took the largest amount into its discount_id, discount_code, discount_type, discount_value_at_apply and discount_currency_code columns, and the sh_order_promotions table keeps every discount applied to the order. The Orders page documents both.

Discount Type

The type column is cast to Shopper\Core\Enum\DiscountType, which sets what value means:

CaseValuevalue holds
DiscountType::PercentagepercentageThe percentage, from 1 to 100
DiscountType::FixedAmountfixed_amountThe amount, in cents

A percentage is computed on each line the discount applies to and rounded to the nearest cent per line. A fixed amount is capped at the subtotal of the lines it applies to, then split between them in proportion to their subtotals; the last line takes what is left, so the parts always add up to the amount.

Discount Application

The apply_to column holds a Shopper\Core\Enum\DiscountApplyTo value:

CaseValueLines the discount reduces
DiscountApplyTo::OrderorderEvery line of the cart
DiscountApplyTo::ProductsproductsThe lines of the products linked to the discount, and of their variants

A discount reduces line subtotals: the shipping amount is never discounted. The cart records what each discount takes off each line, and tax is computed on the line subtotal minus those amounts, as described on the Taxes page.

Discount Eligibility

The eligibility column holds the key of an eligibility rule, which decides who can use the discount. Shopper\Cart\Discounts\DiscountEligibilityManager holds the rules, and Shopper registers two of them, whose keys are the cases of Shopper\Core\Enum\DiscountEligibility:

KeyRulePasses when
everyoneShopper\Cart\Discounts\Eligibility\EveryoneEligibilityRuleAlways
customersShopper\Cart\Discounts\Eligibility\CustomersEligibilityRuleThe cart belongs to a customer linked to the discount

The customers rule refuses a guest cart with "Discount requires a logged-in customer." and a customer who is not linked with "Customer is not eligible for this discount.". Eligible customers are DiscountDetail rows with the Eligibility condition and the class of your user model, config('auth.providers.users.model'), as discountable_type.

To set the eligible customers of a discount, call Shopper\Cart\Discounts\SyncDiscountEligibilityAction. It replaces the eligibility rows of the discount with the IDs you pass, using the morph type of the rule. It does not change the eligibility column, so set the column yourself, as shown in VIP Customer Discount.

Custom Eligibility Rules

A rule implements Shopper\Cart\Contracts\DiscountEligibilityRule. key() is the value stored in the eligibility column, label() and description() appear in the admin panel, discountableType() is the morph type of the models the rule links to a discount (null when it links none), and passes() decides for a cart. This rule keeps a discount for customers who never ordered:

app/Discounts/FirstOrderEligibilityRule.php
<?php

namespace App\Discounts;

use Shopper\Cart\Contracts\DiscountEligibilityRule;
use Shopper\Cart\Discounts\DiscountValidationResult;
use Shopper\Cart\Pipelines\CartPipelineContext;
use Shopper\Core\Models\Contracts\Order;
use Shopper\Core\Models\Discount;

class FirstOrderEligibilityRule implements DiscountEligibilityRule
{
    public function key(): string
    {
        return 'first_order';
    }

    public function label(): string
    {
        return __('First order');
    }

    public function description(): string
    {
        return __('Only customers who have never ordered can use it.');
    }

    public function discountableType(): ?string
    {
        return null;
    }

    public function passes(Discount $discount, CartPipelineContext $context): DiscountValidationResult
    {
        $customerId = $context->cart->customer_id;

        if ($customerId === null) {
            return new DiscountValidationResult(false, __('Sign in to use this discount.'));
        }

        $hasOrdered = resolve(Order::class)::query()
            ->where('customer_id', $customerId)
            ->exists();

        if ($hasOrdered) {
            return new DiscountValidationResult(false, __('This discount is for your first order.'));
        }

        return new DiscountValidationResult(true);
    }
}

Register the rule in the boot method of a service provider that every process loads (web requests, the Store API and queue workers), so the cart finds it wherever it is calculated:

app/Providers/AppServiceProvider.php
use App\Discounts\FirstOrderEligibilityRule;
use Shopper\Cart\Discounts\DiscountEligibilityManager;

public function boot(): void
{
    resolve(DiscountEligibilityManager::class)->register(new FirstOrderEligibilityRule);
}

The discount form of the admin panel lists every registered rule with its label and description. A rule that links models, like customers, also needs a field to pick them: Shopper\Discounts\DiscountEligibilityFieldRegistry from the admin package holds these fields, and its register() method takes the rule key, the form state key, a closure that returns the Filament schema component, and a closure that keeps the allowed IDs among the submitted ones. A rule that links nothing, like the one above, needs no field.

Discount Requirements

The min_required column holds a Shopper\Core\Enum\DiscountRequirement value, and min_required_value the minimum:

CaseValuemin_required_value
DiscountRequirement::NonenoneNot used
DiscountRequirement::PricepriceMinimum subtotal, in cents
DiscountRequirement::QuantityquantityMinimum number of items

The price requirement compares the subtotal of the whole cart before any discount (unit price times quantity, for every line), whatever apply_to is. The quantity requirement adds up the quantities of every line. min_required_value is a string column: the cart reads it as an integer.

Discount Condition

The condition column of a DiscountDetail row is cast to Shopper\Core\Enum\DiscountCondition and says why the model is linked:

CaseValueLinked model
DiscountCondition::ApplyToapply_toA product the discount applies to
DiscountCondition::EligibilityeligibilityA customer who can use the discount

Relationships

A discount has its linked products and customers, a zone, a campaign and the orders it was used on.

Items (DiscountDetail)

items() returns the DiscountDetail rows of the discount, a HasMany on discount_id. Each row points to its model through the polymorphic discountable() relationship, and discount() returns its discount:

use Shopper\Core\Enum\DiscountCondition;
use Shopper\Core\Models\Discount;

$discount = Discount::query()->where('code', 'TSHIRT15')->firstOrFail();

$products = $discount->items()
    ->where('condition', DiscountCondition::ApplyTo)
    ->with('discountable')
    ->get()
    ->pluck('discountable');

Link a product with its morph alias, $product->getMorphClass() (product in the morph map), so that $product->discounts finds the discount. Link a customer with the class of your user model, which SyncDiscountEligibilityAction does for you.

Zone

zone() returns the zone the discount is limited to, or null when it applies in every zone. A cart in another zone is refused with "Discount is not available in this zone.".

The zone also sets the currency of a fixed amount: a fixed-amount discount applies only to carts in the currency of its zone, or in the store default currency (shopper_currency()) when it has no zone. Once a fixed-amount discount has been used, its zone is frozen: saving a new zone_id throws Shopper\Core\Exceptions\DiscountZoneFrozenException, so past orders keep the currency they were discounted in.

Campaign

campaign() returns the campaign of the discount, or null. A campaign adds a currency check and a shared budget to the rules of its discounts, as described in Campaigns and Discounts.

Orders

Every order a discount was applied to has an OrderPromotion row with the code, type, value and amount at checkout. orders() is a HasMany on the discount_id column of the orders table, which holds only the discount that took the largest amount from each order. To list every order that used a discount, query the promotions:

use Shopper\Core\Models\OrderPromotion;

$orderIds = OrderPromotion::query()
    ->where('discount_id', $discount->id)
    ->pluck('order_id');

From the order side, $order->promotions returns its OrderPromotion rows.

Value Handling

The value of a percentage discount is the percentage as a whole number: 20 takes 20% off. The value of a fixed-amount discount is in cents: 1000 takes $10.00 off. Shopper\Core\Observers\DiscountObserver checks the value each time a discount is saved and throws Shopper\Core\Exceptions\InvalidDiscountValueException when it is 0 or less, or when a percentage is above 100.

Once a discount has been used (total_use above 0), its terms are frozen: saving a new code, type or value throws Shopper\Core\Exceptions\DiscountTermsFrozenException, so past orders keep matching the discount they used. To offer different terms, create a new discount, or duplicate the used one from the admin panel and change the copy.

Dates

start_at is required: a discount applies from that moment. end_at is optional, and a discount without one never expires. The cart compares both dates with the current time on every calculation. Before start_at, the code is refused with "Discount has not started yet.", and after end_at with "Discount has expired.". The checkout checks the dates again when it creates the order.

A discount stays off until is_active is true, whatever its dates. The active() scope combines the three columns with the usage limit, as shown in Retrieving Discounts.

Discount Status

The status attribute returns a Shopper\Core\Enum\DiscountStatus, computed when you read it. The first matching row wins:

StatusWhen
DraftThe discount is not saved yet
Disabledis_active is false
Expiredend_at is in the past
LimitReachedtotal_use reached usage_limit
Scheduledstart_at is in the future
InapplicableThe discount applies to products and every linked product was deleted
ActiveNone of the above

Each case has getLabel(), getColor() and getIcon() for display. The status reads the discount alone: it does not check the campaign budget, the eligibility or a cart.

Automatic Discounts

An automatic discount applies without a code. Its trigger column is automatic (Shopper\Core\Enum\PromotionSource::Automatic) instead of the default code, and it usually has no code.

The ApplyAutomaticPromotions step of the calculation pipeline loads the automatic discounts of the active() scope on every calculation. It attaches each one to the cart, as a CartPromotion of source automatic, when the discount passes its rules and would take at least one cent off the cart. It removes the ones the cart no longer qualifies for, and the ones whose discount was turned off or switched back to a code. The step does nothing while the cart holds a payment session with a provider, so the amount being paid does not change.

An automatic discount follows the same rules as a code: dates, usage limits, eligibility, zone, minimum requirement and campaign budget. It also competes with the codes of the cart under the rules of Priority and Combination. A limit reached at checkout names it "automatic promotion" in the exception message, since it has no code.

Priority and Combination

Three columns decide how the discounts of a cart stack. exclusivity_class (Shopper\Core\Enum\ExclusivityClass) puts the discount in the order, product or shipping class, priority orders the discounts within a class, and combinable lets a discount share its class with another one.

On each calculation, PromotionResolver sorts the valid promotions of the cart by class (order, then product, then shipping), then by priority from highest to lowest, then by the order they were attached to the cart, and applies them in that order:

  • The first discount applied in a class always applies.
  • A later discount in the same class stacks only when it and the first discount of the class are both combinable. Otherwise it stays on the cart with an amount of 0.
  • Discounts of different classes always stack.
  • Each discount is computed on the line subtotals before any discount, and capped at what the earlier discounts left on each line, so a line never goes below 0.
  • A discount that takes nothing off, or that its campaign budget cannot absorb, is skipped and does not count as the first of its class.
  • Once config('shopper.cart.max_promotions') discounts have applied (5 by default), the others stay on the cart with an amount of 0.

The shipping class sorts last. A discount of that class reduces line subtotals like the others; Shopper has no discount on the shipping amount.

A cart holds two Classic T-Shirts at $25.00 and a Hoodie at $60.00, so its line subtotals are 5000 and 6000 cents. It carries three discounts:

DiscountClassPriorityCombinableClassic T-Shirt lineHoodie line
SUMMER20, 20% off the orderorder10no10001200
WELCOME10, 10% off the orderorder0no00
TSHIRT10, 10% off the Classic T-Shirtproduct0no500-

SUMMER20 comes first: it is in the order class with the highest priority. WELCOME10 is in the same class and neither discount is combinable, so it is suppressed. TSHIRT10 is in another class and stacks: 10% of 5000, within the 4000 left on the line. The cart total discount is 2700 cents. With combinable set on both SUMMER20 and WELCOME10, WELCOME10 would add 500 and 600 cents.

Usage Limit Enforcement

Two columns limit how often a discount is used: usage_limit caps the uses across all customers, and usage_limit_per_user allows one use per customer. total_use counts the uses. The cart checks both limits on every calculation, so a customer sees that a code is used up before paying. The checkout checks them again in the transaction that creates the order, because another checkout may have taken the last use in the meantime.

Global Usage Limit

When the checkout creates the order, it increments total_use with a conditional update that only matches while total_use is below usage_limit. Two checkouts cannot both take the last use: the update of the second one matches no row, DiscountLimitReachedException::global() is thrown and the order transaction rolls back. On MySQL and MariaDB, the checkout also locks the discount rows of the cart, in ID order, at the start of the transaction.

When the payment provider already collected the payment before the order is created, the checkout honors the discount the customer paid with: it records the use even when the limit was reached in between, so total_use can end above usage_limit. total_use is never decremented: a cancelled or refunded order keeps its use, while the campaign budget of the discount is given back.

Per-User Limit

When usage_limit_per_user is true, the cart and the checkout look for an earlier order of the same customer with an OrderPromotion row for the discount: by customer_id for a signed-in customer, and by the email of the cart for a guest. The cart refuses the code with "Discount already used by this customer.", and the checkout throws DiscountLimitReachedException::perUser().

The Store API requires an email before it completes a cart. A checkout you build yourself sets it with setEmail() on CartManager before it creates the order.

Helpers

hasReachedLimit() returns true once total_use reached usage_limit, and always false for a discount without a limit:

$discount->hasReachedLimit();

$remaining = $discount->usage_limit === null
    ? null
    : max(0, $discount->usage_limit - $discount->total_use);

total_use can pass usage_limit when a collected payment is honored, so floor the remaining uses at 0.

Handling DiscountLimitReachedException

Shopper\Cart\Actions\CreateOrderFromCartAction throws an exception when a discount of the cart stopped holding during checkout. The transaction rolls back and the cart keeps its promotions: calculate it again to show the new total, where the discount has an amount of 0.

app/Http/Controllers/CheckoutController.php
use Shopper\Cart\Actions\CreateOrderFromCartAction;
use Shopper\Cart\Exceptions\DiscountLimitReachedException;
use Shopper\Cart\Exceptions\PromotionUnavailableException;
use Shopper\Cart\Facades\Cart;

try {
    $order = resolve(CreateOrderFromCartAction::class)->execute(Cart::current() ?? abort(404));
} catch (DiscountLimitReachedException|PromotionUnavailableException $exception) {
    return back()->with('error', $exception->getMessage());
}
ExceptionThrown when
DiscountLimitReachedException::global($code)The discount reached its usage_limit
DiscountLimitReachedException::perUser($code)The customer already used a discount limited to one use per customer
PromotionUnavailableExceptionThe discount was deleted, or its terms stopped holding (turned off, expired, out of zone, minimum no longer reached)
Shopper\Core\Exceptions\CampaignBudgetExceededExceptionThe campaign budget cannot absorb the discount, see Budget Exceeded Exception

The messages of DiscountLimitReachedException read "The discount "SUMMER20" has reached its usage limit and can no longer be applied." and "You have already used the discount "SUMMER20", which is limited to one use per customer.". The Cart page covers the other checks of the checkout.

Discount Validation

DiscountValidator holds the discount rules. The pipeline runs it on every promotion of the cart, and you can call it yourself, for example to check a code before attaching it: applyCoupon() only checks that the code exists. validate() runs the checks below in order and stops at the first failure. validateTerms() runs the first eleven, which describe the discount and the cart, without the usage limits and the campaign budget. Both return a Shopper\Cart\Discounts\DiscountValidationResult with a valid boolean and a failureReason:

CheckFails whenMessage key
Activeis_active is falsenot_active
Valuevalue is 0 or lessinvalid_value
PercentageA percentage is above 100invalid_percentage
Startstart_at is in the futurenot_started
Endend_at is in the pastexpired
Campaign currencyThe campaign currency differs from the cart currencycurrency_mismatch
EligibilityThe rule of the eligibility key refuses the cartSet by the rule
ZoneThe cart is in another zone than zone_idnot_available_in_zone
Fixed amount currencyThe currency of the zone, or the store default currency, differs from the cart currencycurrency_mismatch
Minimum amountThe cart subtotal is below min_required_valuemin_amount_not_reached
Minimum quantityThe cart quantity is below min_required_valuemin_quantity_not_reached
Usage limithasReachedLimit() is trueusage_limit_reached
Campaign budgetThe campaign reached its budgetcampaign_budget_reached
One per customerThe customer already used the discountalready_used

The keys live in the shopper-cart::messages.discount group. To change a message, override it in lang/vendor/shopper-cart/en/messages.php. The validator needs a calculated cart context:

use Shopper\Cart\CartManager;
use Shopper\Cart\Discounts\DiscountValidator;
use Shopper\Cart\Facades\Cart;
use Shopper\Core\Models\Discount;

$context = resolve(CartManager::class)->calculate(Cart::current() ?? abort(404));
$discount = Discount::query()->where('code', 'SUMMER20')->firstOrFail();

$result = resolve(DiscountValidator::class)->validate($discount, $context);

if (! $result->valid) {
    return back()->withErrors(['code' => $result->failureReason]);
}

A valid discount can still take nothing off the cart: a product discount on a cart without its products, or a discount suppressed by another one of its class, as described in Priority and Combination.

Configuration

Discounts are on by default. Their settings are the feature flag, the cap on stacked promotions and the admin components; the model has no configuration key.

Disabling Discounts

If your store does not use discounts, disable the feature in config/shopper/features.php:

config/shopper/features.php
use Shopper\Enum\FeatureState;

return [
    'discount' => FeatureState::Disabled,
];

The discount pages are no longer registered and the Promotions item leaves the Sales group of the sidebar. The flag only changes the admin panel: the cart keeps applying the active discounts, so turn them off with is_active if the store must stop honoring them. The Configuration page lists every feature flag.

Maximum Stacked Promotions

config('shopper.cart.max_promotions') caps the number of discounts that apply to one cart, 5 by default. It lives in config/shopper/cart.php, described in the Configuration section of the Cart page. A suppressed discount does not count against the cap.

Components

The discounts section of the admin panel is made of two pages and four components. To replace any of them with your own Livewire component, publish the component file of the section:

php artisan shopper:component:publish discount

The command creates config/shopper/components/discount.php:

config/shopper/components/discount.php
use Shopper\Livewire;

return [
    'pages' => [
        'discount-index' => Livewire\Pages\Discount\Index::class,
        'discount-edit' => Livewire\Pages\Discount\Edit::class,
    ],

    'components' => [
        'slide-overs.add-promotion' => Livewire\SlideOvers\AddPromotion::class,
        'slide-overs.products-picker' => Livewire\SlideOvers\ProductsPicker::class,
        'slide-overs.customers-picker' => Livewire\SlideOvers\CustomersPicker::class,
        'discounts.stats-panel' => Livewire\Components\Discounts\StatsPanel::class,
    ],
];

The Configuration page explains how component overriding works.

Usage

The examples below work with the core models directly, from a seeder, a command or the controllers of a storefront.

Creating Discounts

Create a discount with its type, value, rules and dates. type, trigger and exclusivity_class are cast to enums; apply_to, min_required and eligibility are plain strings, so pass the enum value. Each example below lists only the imports the earlier ones did not need.

Percentage Discount for All Orders

A SUMMER20 code takes 20% off every order for a month:

use Shopper\Core\Enum\DiscountApplyTo;
use Shopper\Core\Enum\DiscountEligibility;
use Shopper\Core\Enum\DiscountRequirement;
use Shopper\Core\Enum\DiscountType;
use Shopper\Core\Models\Discount;

$discount = Discount::query()->create([
    'code' => 'SUMMER20',
    'type' => DiscountType::Percentage,
    'value' => 20,
    'apply_to' => DiscountApplyTo::Order->value,
    'min_required' => DiscountRequirement::None->value,
    'eligibility' => DiscountEligibility::Everyone->value,
    'is_active' => true,
    'start_at' => now(),
    'end_at' => now()->addMonth(),
]);

Fixed Amount Discount with Minimum Order

A SAVE10 code takes $10.00 off orders of $50.00 or more, for the first 500 orders. Both amounts are in cents, in the store default currency since the discount has no zone:

$discount = Discount::query()->create([
    'code' => 'SAVE10',
    'type' => DiscountType::FixedAmount,
    'value' => 1000,
    'apply_to' => DiscountApplyTo::Order->value,
    'min_required' => DiscountRequirement::Price->value,
    'min_required_value' => '5000',
    'eligibility' => DiscountEligibility::Everyone->value,
    'usage_limit' => 500,
    'is_active' => true,
    'start_at' => now(),
]);

Product-Specific Discount

A TSHIRT15 code takes 15% off the Classic T-Shirt and its variants. Resolve the product through its contract so a swapped model is honored, and link it with its morph alias:

use Shopper\Core\Enum\DiscountCondition;
use Shopper\Core\Enum\ExclusivityClass;
use Shopper\Core\Models\Contracts\Product;

$product = resolve(Product::class)::query()->where('slug', 'classic-t-shirt')->firstOrFail();

$discount = Discount::query()->create([
    'code' => 'TSHIRT15',
    'type' => DiscountType::Percentage,
    'value' => 15,
    'apply_to' => DiscountApplyTo::Products->value,
    'min_required' => DiscountRequirement::None->value,
    'eligibility' => DiscountEligibility::Everyone->value,
    'exclusivity_class' => ExclusivityClass::Product,
    'is_active' => true,
    'start_at' => now(),
]);

$discount->items()->create([
    'condition' => DiscountCondition::ApplyTo,
    'discountable_type' => $product->getMorphClass(),
    'discountable_id' => $product->id,
]);

The product class lets the discount stack with an order discount such as SUMMER20.

VIP Customer Discount

A VIP25 code takes 25% off, once per customer, for a list of customers. Set the eligibility column, then link the customers:

use App\Models\User;
use Shopper\Cart\Discounts\SyncDiscountEligibilityAction;

$discount = Discount::query()->create([
    'code' => 'VIP25',
    'type' => DiscountType::Percentage,
    'value' => 25,
    'apply_to' => DiscountApplyTo::Order->value,
    'min_required' => DiscountRequirement::None->value,
    'eligibility' => DiscountEligibility::Customers->value,
    'usage_limit_per_user' => true,
    'is_active' => true,
    'start_at' => now(),
]);

$vipCustomerIds = User::query()
    ->whereIn('email', ['amelia@example.com', 'noah@example.com'])
    ->pluck('id')
    ->all();

resolve(SyncDiscountEligibilityAction::class)->execute(
    $discount,
    DiscountEligibility::Customers->value,
    $vipCustomerIds,
);

Calling the action again with another list replaces the eligible customers.

Automatic Discount

An automatic discount takes 10% off every order of $100.00 or more, without a code:

use Shopper\Core\Enum\PromotionSource;

$discount = Discount::query()->create([
    'trigger' => PromotionSource::Automatic,
    'type' => DiscountType::Percentage,
    'value' => 10,
    'apply_to' => DiscountApplyTo::Order->value,
    'min_required' => DiscountRequirement::Price->value,
    'min_required_value' => '10000',
    'eligibility' => DiscountEligibility::Everyone->value,
    'is_active' => true,
    'start_at' => now(),
]);

The next calculation of every qualifying cart attaches it, as described in Automatic Discounts.

Retrieving Discounts

The active() scope keeps the discounts that are active, started, not expired and below their usage limit:

use Illuminate\Database\Eloquent\Builder;
use Shopper\Core\Enum\PromotionSource;
use Shopper\Core\Models\Discount;

$running = Discount::query()->active()->get();

$summerSale = Discount::query()->where('code', 'SUMMER20')->first();

$automatic = Discount::query()
    ->active()
    ->where('trigger', PromotionSource::Automatic->value)
    ->get();

$forZone = Discount::query()
    ->active()
    ->where(fn (Builder $query) => $query->whereNull('zone_id')->orWhere('zone_id', $zone->id))
    ->get();

$summerSale->status->getLabel();

The scope does not check eligibility, the zone, the minimum requirement or the campaign budget. To know whether a discount applies to a cart, use the validator, as shown in Discount Validation.

Updating Discounts

Dates, limits, requirements, eligibility and the stacking columns can change at any time, and the next calculation of each cart uses the new values:

$summerSale->update([
    'end_at' => now()->addWeeks(2),
    'usage_limit' => 1000,
]);

The code, type and value are frozen once the discount has been used, and so is the zone of a used fixed-amount discount, as described in Value Handling. Deleting a discount deletes its DiscountDetail rows. Orders, order promotions and cart promotions keep their rows with a null discount_id, and each OrderPromotion keeps the code, type, value and amount of the discount.

Storefront Example

A Blade or Livewire storefront attaches a code with applyCoupon() on CartManager, described in Applying Coupons. applyCoupon() attaches any existing code, and the calculation then gives it an amount of 0 when it does not apply. To tell the customer right away, validate the discount first:

app/Http/Controllers/CouponController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Shopper\Cart\CartManager;
use Shopper\Cart\Discounts\DiscountValidator;
use Shopper\Cart\Facades\Cart;
use Shopper\Core\Models\Discount;

class CouponController extends Controller
{
    public function __construct(
        private CartManager $manager,
        private DiscountValidator $validator,
    ) {}

    public function store(Request $request): RedirectResponse
    {
        $request->validate(['code' => ['required', 'string']]);

        $cart = Cart::current() ?? abort(404);
        $discount = Discount::query()->where('code', $request->input('code'))->first();

        if ($discount === null || ! $this->validator->validate($discount, $this->manager->calculate($cart))->valid) {
            return back()->withErrors(['code' => __('This code does not apply to your cart.')]);
        }

        $this->manager->applyCoupon($cart, $discount->code);

        return back()->with('status', __('Discount applied.'));
    }

    public function destroy(): RedirectResponse
    {
        $this->manager->removeCoupon(Cart::current() ?? abort(404));

        return back();
    }
}

removeCoupon() without a code removes every code of the cart; automatic discounts stay while the cart qualifies.

Use Cases

The columns combine into the usual promotions:

ScenarioTypeApply ToEligibilityRequirementTrigger
Site-wide salePercentageOrderEveryoneNoneCode
$10.00 off orders over $50.00Fixed amountOrderEveryonePriceCode
Buy 3 or more, get 10% offPercentageOrderEveryoneQuantityCode
10% off orders over $100.00, no codePercentageOrderEveryonePriceAutomatic
VIP member exclusivePercentageOrderCustomersNoneCode
Product clearancePercentageProductsEveryoneNoneAutomatic
First order discountFixed amountOrderA custom ruleNoneCode

Events

Shopper dispatches no discount event: nothing fires when a discount is created, used or reaches its limit, as noted in Cart and Discount Events. The cart dispatches CouponApplied and CouponRemoved from Shopper\Cart\Events when a code is added to or removed from a cart; that section lists their payloads.

To react to a use, listen to the Eloquent created event of OrderPromotion. The checkout increments total_use with a query, so the updated event of Discount does not fire when a discount is used:

app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Cache;
use Shopper\Core\Models\OrderPromotion;

public function boot(): void
{
    OrderPromotion::created(function (OrderPromotion $promotion): void {
        Cache::forget("discounts.{$promotion->discount_id}.remaining");
    });
}

The promotion is created inside the checkout transaction. The Events page covers listeners and queues.

Permissions

The admin panel checks four permissions of the discounts resource, in the Sales group:

PermissionAllows
discounts.browseOpening the discounts page and seeing the Promotions sidebar item
discounts.createCreating a discount with the wizard, and duplicating one
discounts.editOpening the edit page and saving changes
discounts.deleteDeleting a discount, from the list (one at a time or in bulk) or from its edit page

discounts.read is seeded with the others, but the admin panel never checks it. The 2.x names, such as browse_discounts, are gone: a store upgraded from 2.x follows Upgrading from 2.x.

In the Admin

Merchants manage discounts under Sales, Promotions. The list shows each discount with its code, method (code or automatic), type, amount, what it applies to, eligibility, status, dates, usage limit, redemptions, zone and campaign, and filters by active state, method, campaign, application, eligibility, zone and start date. A discount can be edited, duplicated (the copy is inactive, gets a new code and starts at 0 uses) or deleted. New discounts go through a three-step wizard: Type, Conditions and Campaign. The edit page groups the fields in General, Configuration, Targeting, Combinations and Advanced, locks the zone of a used fixed-amount discount and the campaign of a used discount, and shows the uses, remaining uses, gross revenue, discount cost, orders and average order value of the paid orders that used it. The User Guide walks through these screens.

From a Storefront

The Store API applies and removes codes on a cart and reports the discounts of the cart. It has no endpoint that lists discounts, so a storefront cannot show the available codes from it:

RequestDiscount effect
POST /store/carts/{cartId}/promotionAttaches the discount of the code in the body when it is active, passes its rules and takes something off the cart. A code suppressed by a discount of higher priority is accepted. Any refusal is a 422 error with code promotion_not_applicable on the /data/attributes/code pointer, which does not say why
DELETE /store/carts/{cartId}/promotionRemoves the discount of the code sent, or every code when none is sent. Automatic discounts stay
GET /store/carts/{cartId}promotions lists each discount of the cart with its code, source (code or automatic), amount and status (applied, or suppressed with an amount of 0). discount_total holds their sum, and each line has its own discount_total
POST /store/carts/{cartId}/completeA discount that stopped holding answers a 422 error on the /data/attributes/promotion pointer: promotion_limit_reached for a usage limit, promotion_not_applicable for its terms, promotion_budget_reached for its campaign budget. The cart is priced again without the discount: show the new total and let the customer confirm

Both promotion endpoints use the checkout rate limit. Amounts are in cents. The store prefix is set by SHOPPER_API_PREFIX. The Store API Cart guide covers promotion codes, and the Errors page lists every error code.

Last updated on

Edit on GitHub