Exceptions

Every exception lives in RoundlyConsulting\Coupons\Exceptions and extends CouponException, a RuntimeException, so you can catch the whole package with one type:

CouponException (RuntimeException)       — catch-all for the package
├── CouponNotFound                       ::forCode(string $code)
├── CouponCodeTaken                      ::forCode(string $code, ?Throwable $previous = null)
├── InvalidCouponDefinition              ::blankCode()
│                                        ::fixedWithoutCurrency(string $code)
│                                        ::percentOutOfRange(int $basisPoints)
│                                        ::negativeValue(int $value)
├── InvalidCouponConfiguration           ::invalidCharset(string $reason)  (+ bad coupons.code.length)
│                                        ::codeSpaceExhausted(int $attempts)
└── CouponNotRedeemable                  — catch-all for "cannot redeem"
    ├── CurrencyMismatch                 ::forCode(string $code, string $expected, string $actual)
    ├── MinimumSpendNotMet               ::forCode(string $code, Money $minimumSpend)
    ├── CouponExpired                    ::forCode(string $code)  (expired or not yet active)
    ├── CouponAtMaxUsage                 ::forCode(string $code)
    └── CouponAlreadyRedeemed            ::forCode(string $code)  (per-redeemer cap)

Exception	Extends	Thrown when
`CouponNotFound`	`CouponException`	No coupon matches the code — findOrFail(), preview(), redeem(), revoke(). check() reports NotFound instead.
`CouponCodeTaken`	`CouponException`	An explicit code a live coupon already holds, in any case — also when a concurrent request takes it between the check and the insert.
`InvalidCouponDefinition`	`CouponException`	A blank explicit code, a Fixed coupon without a currency, a negative fixed value, or a percentage outside 0..10 000 basis points.
`InvalidCouponConfiguration`	`CouponException`	An unusable code.length or code.charset, a non-string route_key or default_currency, or an exhausted code space. Names the key; a charset message never prints the alphabet.
`CouponNotRedeemable`	`CouponException`	Base type for every “cannot redeem” reason.
`CurrencyMismatch`	`CouponNotRedeemable`	The coupon is locked to another currency than the price.
`MinimumSpendNotMet`	`CouponNotRedeemable`	The price is below the minimum spend.
`CouponExpired`	`CouponNotRedeemable`	Expired or not yet active.
`CouponAtMaxUsage`	`CouponNotRedeemable`	The global usage cap is reached.
`CouponAlreadyRedeemed`	`CouponNotRedeemable`	The per-redeemer cap is reached.

Money-level errors

Some errors come from money-for-laravel: RoundlyConsulting\Money\Exceptions\CurrencyMismatch when discountFor(), apply() or meetsMinimumSpend() is called directly with a mismatched currency — distinct from the package’s redemption-time CurrencyMismatch — plus AmountOverflow, InvalidMoneyValue and RoundingNecessary for a percentage finer than whole basis points.

Coupons::prune() with a negative window throws a plain InvalidArgumentException rather than a CouponException — a window in the future would delete live coupons.

Exception messages are developer-facing English, e.g. “Coupon [SAVE20] is expired or not yet active.” For customer-facing text, use Coupons::check(), the Redeemable rule or RedemptionFailureReason::translationKey().

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages