¶ Extended Voucher Rules - OXID eShop 7
Advanced voucher restriction rules for OXID eShop 7 with payment, delivery, time window, first-order and combination rules.
Live Demo: Try all OXID eShop and Shopware plugins by Markus Michalski live — no installation, no risk. demo.markus-michalski.net
¶ Table of Contents
- Overview
- Features
- Requirements
- Installation
- Update
- Configuration
- The Pending Voucher Pattern
- Chain Extensions
- Practical Examples
- Troubleshooting
- Technical Details
- FAQ
- License
- Support and Changelog
¶ Overview
OXID eShop ships with basic voucher support — percentage discounts, fixed amounts, and minimum order values. What it does not provide is any way to restrict vouchers to specific payment methods, shipping methods, or time slots, or to control which vouchers may be combined.
The Extended Voucher Rules module (mmd/oxid7-voucherrules) fills exactly this gap. It hooks directly into the existing voucher chain without replacing core tables, adds seven additional restriction rule types per voucher series, and introduces a "pending voucher" mechanism that keeps the customer journey smooth even when required context (payment, delivery) has not yet been selected.
¶ Who is this module for?
- Shop operators who run payment-provider-specific promotions (e.g. "10% off when paying via PayPal")
- Shops offering carrier-specific vouchers (e.g. "Free shipping upgrade with DHL Express")
- Marketing teams running Happy-Hour or day-of-week promotions
- Any shop that needs to prevent specific voucher combinations or cap the number of stackable discounts
Problem without the module: A customer enters a voucher that is tied to a specific payment method, but OXID accepts it immediately regardless of the selected payment method. The discount is applied even when the wrong payment method is used at checkout, creating revenue leakage and complex manual correction workflows.
Solution with the module: Voucher validation is deferred intelligently. If the required payment method has not been selected yet, the voucher is stored as "pending" with a clear hint to the customer. The moment the correct payment method is chosen, the voucher activates automatically — no re-entry required.
¶ Features
| Feature | Description |
|---|---|
| Payment Restrictions | Whitelist of payment methods that allow a voucher |
| Delivery Restrictions | Whitelist of shipping methods that allow a voucher |
| First Order Only | Voucher valid only for customers with no previous orders |
| Time Windows (Happy Hour) | Weekday bitmask + start/end time per time window, multiple windows per voucher |
| Combination Blacklist | Explicit pairs of vouchers that cannot be used together |
| Max Combined Count | Maximum number of vouchers combinable in a single order |
| Payment-specific Minimum Order Values | Different MOV thresholds per payment method |
| Delivery-specific Minimum Order Values | Different MOV thresholds per shipping method |
| Pending Voucher Pattern | Graceful deferral instead of hard rejection for context-dependent rules |
| 4 Admin Tabs | Clean admin UI integrated into the existing voucher series detail view |
| DBAL-based Repositories | No Doctrine ORM overhead, fast raw DBAL queries |
| Full Translation Support | German and English out of the box |
| Shop Isolation | All tables carry OXSHOPID, multi-shop safe |
¶ Requirements
| Component | Requirement |
|---|---|
| OXID eShop | 7.x (CE, PE, EE) |
| PHP | >= 8.2 |
| Composer | >= 2.0 |
| Database | MySQL / MariaDB (standard OXID requirement) |
¶ Installation
# 1. Add the package
composer require mmd/oxid7-voucherrules
# 2. Run OXID module activation
vendor/bin/oe-console oe:module:activate mmd_voucherrules
# 3. Apply database migrations
vendor/bin/oe-console oe:migrations:apply-module --module-id=mmd_voucherrules
After activation, clear the shop cache:
vendor/bin/oe-console oe:cache:clear
Manual installation bypasses Composer autoloading. This method is not recommended for production environments and will complicate future updates.
- Download the release archive from the repository.
- Extract the contents into
source/modules/mmd/voucherrules/. - Register the namespace in the shop's
composer.json:
{
"autoload": {
"psr-4": {
"Mmd\\VoucherRules\\": "source/modules/mmd/voucherrules/src/"
}
}
}
- Run
composer dump-autoload. - Activate via the OXID Admin UI under Extensions > Modules or via console:
vendor/bin/oe-console oe:module:activate mmd_voucherrules
- Apply migrations:
vendor/bin/oe-console oe:migrations:apply-module --module-id=mmd_voucherrules
¶ Update
# Pull the new version
composer update mmd/oxid7-voucherrules
# Apply any new migrations
vendor/bin/oe-console oe:migrations:apply-module --module-id=mmd_voucherrules
# Clear cache
vendor/bin/oe-console oe:cache:clear
Always back up your database before running migrations on a production system.
¶ Configuration
After installation, every voucher series in the OXID Admin gains four additional detail tabs. Navigate to Admin > Shop Settings > Vouchers, open or create a voucher series, and you will find the following tabs alongside the standard OXID tabs.
¶ Extended Rules Tab
This is the main configuration tab (VoucherRulesMain). It covers:
Payment Restrictions
A multi-select list of all active payment methods in the shop. Selecting one or more methods restricts the voucher to those methods only. Leaving the list empty means all payment methods are permitted (whitelist semantics: empty = no restriction).
Delivery Restrictions
Identical semantics to payment restrictions, but applied to shipping methods. Selecting specific methods means the voucher is only valid when one of those shipping methods is active in the basket.
First Order Only
A single checkbox. When enabled, the voucher is only accepted if the currently logged-in customer has placed zero previous orders. Guest checkouts count as a first order.
Max Combined Vouchers
An integer field (0–99). When set to a value greater than zero, it caps the total number of vouchers that can be active in a single basket at the same time. A value of 0 disables this restriction.
¶ Time Windows Tab
The VoucherRulesTimeWindow tab allows you to define one or more time windows during which the voucher is valid.
Each time window entry consists of:
- Weekday checkboxes — Monday through Sunday, stored as a bitmask
- Start time — in
HH:MMformat - End time — in
HH:MMformat - Active flag — individual on/off switch per window
Multiple time windows per voucher series are supported. The voucher is valid if the current server time falls within any active time window. You can add, edit, and delete individual windows from this tab.
Time validation uses the server's local time. Ensure your server timezone matches the timezone your marketing team works with.
¶ Combinations Tab
The VoucherRulesCombination tab manages the explicit combination blacklist.
Each blacklist entry is a pair of voucher series IDs that may not be used together in the same order. Pairs are stored canonically (A < B) to prevent duplicate entries.
Use cases:
- Prevent two percentage vouchers from stacking
- Block a welcome voucher from combining with a seasonal sale voucher
- Protect margin on high-value vouchers by preventing any combination
The tab shows a table of all current blacklist pairs with a delete button per row, and an "Add pair" form at the bottom.
¶ Min Order Value Tab
The VoucherRulesPaymentMinVal tab provides payment-specific and delivery-specific minimum order values — separate from the standard OXID minimum order value on the voucher series.
Payment-specific MOV
A table with one row per payment method. Enter a minimum basket value (net or gross, matching your shop's pricing mode) that must be reached for the voucher to be valid when that payment method is selected.
Delivery-specific MOV
Same structure, but keyed by shipping method instead.
These thresholds are checked after the customer selects their payment/delivery method. If the basket value is below the threshold, the voucher is rejected with a clear error message.
¶ The Pending Voucher Pattern
This is the architectural centerpiece of the module. Understanding it is essential to predict how the module behaves in edge cases.
¶ The Problem
Several rule types (payment restrictions, delivery restrictions, payment MOV, delivery MOV) can only be evaluated once the customer has selected a payment or delivery method. This selection typically happens at the end of the checkout — well after the customer has already entered their voucher code on the basket page.
A naive implementation would reject the voucher immediately with an error like "This voucher requires PayPal". The customer then has to re-enter the voucher after switching payment methods, which degrades UX and increases abandonment.
¶ The Solution: Two Exception Types
The module distinguishes between two fundamentally different failure modes:
| Exception Type | Meaning | UI Treatment |
|---|---|---|
VoucherRuleViolationException |
Rule permanently violated, voucher invalid | Red error box, voucher removed |
VoucherRulePendingException |
Context not yet available, decision deferred | Yellow/blue hint box, voucher stored in session |
When a VoucherRulePendingException is thrown during validation, the voucher is not removed from the basket. Instead, its ID is stored in the session under a "pending vouchers" key, and a hint message is shown to the customer explaining what condition needs to be met.
The Basket extension hooks into basket recalculation. Each time the basket is recalculated (e.g. after the customer changes their payment method), it attempts to re-add all pending vouchers. If the condition is now satisfied, the voucher moves from "pending" to "active" automatically.
¶ Pending Voucher Flow
¶ Validation Flow
The central VoucherValidationService runs seven checks in sequence. Each check either passes silently, throws a VoucherRulePendingException (deferred), or throws a VoucherRuleViolationException (rejected).
Note that
validateFirstOrder(),validateTimeWindow(), andvalidateCombinations()never produce a pending state — their outcome is always immediately determinable and either passes or permanently rejects.
¶ Chain Extensions
The module uses OXID's standard chain extension mechanism. It extends six core classes without replacing them, ensuring compatibility with other modules that extend the same classes.
| Core Class | Extension Class | Purpose |
|---|---|---|
OxidEsales\...\Voucher |
Extension\Model\Voucher |
Central validation entry point, pending logic |
OxidEsales\...\VoucherSerie |
Extension\Model\VoucherSerie |
Config accessor for module rule data |
OxidEsales\...\Basket |
Extension\Model\Basket |
Auto-add pending vouchers from session, generate hint messages |
OxidEsales\...\BasketController |
Extension\Controller\BasketController |
Frontend error/hint rendering, removePendingVoucher action |
OxidEsales\...\ViewConfig |
Extension\Core\ViewConfig |
Exposes hint data and pending voucher list to templates |
OxidEsales\...\Order |
Extension\Model\Order |
Session cleanup after order completion |
The
Orderextension ensures that any remaining pending vouchers in the session are cleared after a successful order, preventing stale session state from affecting subsequent visits.
¶ Practical Examples
¶ Example 1: PayPal-Exclusive Promotional Voucher
Scenario: Marketing wants to issue a 15% voucher (PAYPAL15) that is only valid when the customer checks out via PayPal.
Configuration:
- Open the voucher series for
PAYPAL15in Admin. - Switch to the Extended Rules tab.
- In the Payment Restrictions multi-select, choose "PayPal" (or however your PayPal payment method is named).
- Save.
Customer journey:
- Customer adds items to basket and enters
PAYPAL15. - Customer has "Credit Card" selected as payment method at this point.
- Instead of a hard error, the customer sees: "Voucher PAYPAL15 requires payment via PayPal. Select PayPal to activate this voucher."
- Customer switches to PayPal in the payment step.
- Basket recalculates — voucher activates automatically. No re-entry needed.
¶ Example 2: Monday Morning Happy Hour
Scenario: Flash sale — 20% off on Monday mornings between 08:00 and 10:00.
Configuration:
- Open the voucher series in Admin.
- Switch to the Time Windows tab.
- Click "Add time window".
- Check Monday only.
- Set Start Time:
08:00, End Time:10:00. - Set Active to yes. Save.
Behavior:
- At 09:15 on a Monday: voucher validates successfully.
- At 10:30 on a Monday: voucher is rejected with "This voucher is only valid during specific time windows."
- At 09:15 on a Wednesday: rejected — Wednesday is not in the bitmask.
¶ Example 3: Preventing Stacking of Two High-Value Vouchers
Scenario: You have two voucher series — "WELCOME20" (20% for new customers) and "SUMMER30" (30% summer sale). You want to prevent customers from stacking both.
Configuration:
- Open either voucher series in Admin (the blacklist pair only needs to be entered once).
- Switch to the Combinations tab.
- In the "Add pair" form, select "WELCOME20" and "SUMMER30".
- Save.
Behavior:
- A customer with both codes tries to apply
SUMMER30after already havingWELCOME20active. - The system detects the blacklisted pair and rejects
SUMMER30with an error message. - Removing
WELCOME20first would allowSUMMER30to be applied.
¶ Troubleshooting
¶ Voucher is immediately rejected instead of going pending
Symptoms: Customer enters a voucher code that requires PayPal. Instead of the yellow "pending" hint, they immediately see a red error and the voucher is not stored.
Check:
- Verify that the
VoucherRulePendingExceptionis actually being thrown by the payment validation. Check your shop's exception log. - Check whether a different rule (e.g. Time Window or First Order) is also failing. Permanent violations always win over pending states — if any rule throws a
VoucherRuleViolationExceptionduring the same validation pass, the pending logic is bypassed.
Solution: Fix the additional violation first (e.g. the time window is currently inactive, or the customer has previous orders). The pending mechanism only applies when the only failing rules are context-dependent ones (payment, delivery, MOVs).
¶ Pending voucher is not automatically activated after payment method change
Symptoms: Customer selects the correct payment method but the pending voucher is not activated. The hint message remains.
Check:
- Confirm the pending voucher ID is actually stored in the session. Enable OXID's debug mode temporarily and inspect session data.
- Check whether the basket recalculation event is firing. In some custom checkout flows, basket recalculation is skipped or cached.
- Verify that
Basket::reAddPendingVouchers()is being called. Add a temporary log line if needed.
Solution: The most common cause is a custom checkout module that overrides Basket::calculateBasket() without calling the parent. Ensure that the module call chain includes the Basket extension from mmd_voucherrules. Check the module chain order in Admin > Extensions > Modules.
¶ Time window voucher is rejected despite correct time
Symptoms: A time window voucher shows "not valid during current time" even though the current time appears to be inside the configured window.
Check:
- Check the server's actual timezone:
dateon the command line or<?php echo date_default_timezone_get(); ?>. - Compare with the timezone assumed when the time window was configured.
- Verify the time window entry has Active = Yes.
- Check that the weekday bitmask includes the current day.
Solution: Align the server timezone with your shop's operational timezone, or adjust the time window boundaries to compensate for the offset. OXID does not automatically apply timezone conversion — times are stored and compared in server local time.
¶ Admin tabs not appearing after installation
Symptoms: The four extended rule tabs are missing from the voucher series detail view.
Check:
- Confirm the module is activated:
vendor/bin/oe-console oe:module:list | grep voucherrules - Confirm migrations ran successfully: check the
oevomigrationslog table for the module's migration entries. - Hard-refresh the admin browser (Ctrl+Shift+R) — admin UI is aggressively cached in some setups.
Solution: Re-run activation and migration:
vendor/bin/oe-console oe:module:deactivate mmd_voucherrules
vendor/bin/oe-console oe:module:activate mmd_voucherrules
vendor/bin/oe-console oe:migrations:apply-module --module-id=mmd_voucherrules
vendor/bin/oe-console oe:cache:clear
¶ Technical Details
¶ File Structure
oxid7-voucherrules/
├── src/
│ ├── Controller/
│ │ └── Admin/
│ │ ├── VoucherRulesMain.php
│ │ ├── VoucherRulesTimeWindow.php
│ │ ├── VoucherRulesCombination.php
│ │ └── VoucherRulesPaymentMinVal.php
│ ├── Extension/
│ │ ├── Model/
│ │ │ ├── Voucher.php
│ │ │ ├── VoucherSerie.php
│ │ │ ├── Basket.php
│ │ │ └── Order.php
│ │ ├── Controller/
│ │ │ └── BasketController.php
│ │ └── Core/
│ │ └── ViewConfig.php
│ ├── Service/
│ │ ├── VoucherValidationService.php
│ │ ├── FirstOrderCheckService.php
│ │ ├── CombinationCheckService.php
│ │ ├── TimeWindowCheckService.php
│ │ └── VoucherRestrictionHintService.php
│ ├── Repository/
│ │ ├── VoucherRulesConfigRepository.php
│ │ ├── PaymentRestrictionRepository.php
│ │ ├── DeliveryRestrictionRepository.php
│ │ ├── TimeWindowRepository.php
│ │ ├── CombinationRepository.php
│ │ ├── PaymentMinValueRepository.php
│ │ └── DeliveryMinValueRepository.php
│ ├── Exception/
│ │ ├── VoucherRuleViolationException.php
│ │ └── VoucherRulePendingException.php
│ └── Core/
│ └── ModuleEvents.php
├── views/
│ └── twig/
│ ├── admin/
│ │ ├── voucherrulesMain.html.twig
│ │ ├── voucherrulesTimewindow.html.twig
│ │ ├── voucherrulesCombination.html.twig
│ │ └── voucherrulesPaymentminval.html.twig
│ └── extensions/
│ └── themes/
│ └── apex/
│ └── (storefront overrides)
├── translations/
│ ├── de/
│ └── en/
├── metadata.php
├── composer.json
└── services.yaml
¶ Architecture Overview
¶ Database Schema
All tables use the prefix mmd_voucherrules_. All tables carry OXSHOPID for multi-shop isolation.
| Table | Relationship | Key Columns | Description |
|---|---|---|---|
mmd_voucherrules_config |
1:1 per voucher series | OXVOUCHERSERIEID, FIRSTORDERONLY (bool), MAXCOMBINED (int) |
Global flags for a voucher series |
mmd_voucherrules_payment |
n:m | OXVOUCHERSERIEID, OXPAYMENTID |
Payment method whitelist |
mmd_voucherrules_delivery |
n:m | OXVOUCHERSERIEID, OXDELIVERYID |
Shipping method whitelist |
mmd_voucherrules_timewindow |
1:n | OXVOUCHERSERIEID, WEEKDAYS (bitmask), STARTTIME, ENDTIME, ACTIVE |
Time window entries |
mmd_voucherrules_combination |
n:m | VOUCHERSERIEID_A, VOUCHERSERIEID_B |
Combination blacklist pairs |
mmd_voucherrules_payment_minval |
1:n | OXVOUCHERSERIEID, OXPAYMENTID, MINVALUE |
Payment-specific MOV |
mmd_voucherrules_delivery_minval |
1:n | OXVOUCHERSERIEID, OXDELIVERYID, MINVALUE |
Delivery-specific MOV |
Whitelist semantics: An empty _payment or _delivery table for a given voucher series means no restriction — all methods are permitted. Only when at least one row exists does the whitelist actively filter.
Combination blacklist canonicalization: Pairs are always stored with the lexicographically smaller ID in column A (VOUCHERSERIEID_A < VOUCHERSERIEID_B). This prevents duplicate entries like (A, B) and (B, A) representing the same restriction.
¶ Security Design
- Ownership validation: All DELETE and UPDATE operations in admin controllers verify that the record being modified belongs to the current shop (
OXSHOPID) and the correct voucher series ID before executing the query. - Shop isolation: Every query that reads rule data includes a
WHERE OXSHOPID = ?clause. A rule configured in Shop A cannot affect voucher validation in Shop B. - Input validation:
MaxCombinedis validated as an integer in range 0–99. Time fields are validated against theHH:MMformat before being stored. All IDs are type-cast before being used in queries. - DBAL usage: All queries use parameterized statements via DBAL's
executeQuery()/executeStatement()API. No string interpolation of user input into SQL.
¶ FAQ
Q: Does the module work with multi-shop (EE) setups?
Yes. All module tables carry an OXSHOPID column. Rules are always scoped to the shop they were configured in. A voucher series shared across shops will have its rules evaluated independently per shop.
Q: What happens to pending vouchers if the customer logs out or their session expires?
Pending vouchers are stored in the PHP session. If the session expires or the customer logs out, the pending voucher list is lost. The customer will need to re-enter the voucher code. This is intentional — retaining voucher codes across sessions would create security concerns.
Q: Can I configure multiple time windows for the same voucher?
Yes. The Time Windows tab supports an unlimited number of time window entries per voucher series. The voucher is valid if the current time falls within any active window (OR semantics). This allows you to configure, for example, a lunch promotion (12:00–14:00) and an evening promotion (19:00–21:00) on the same voucher.
Q: The combination blacklist only supports pairs. What if I want to block a voucher from combining with any other voucher?
Use the Max Combined Vouchers field on the Extended Rules tab instead. Setting it to 1 means only a single voucher can be active in the basket at any time, regardless of which specific vouchers they are.
Q: Does the First Order Only check work for guest checkouts?
A guest customer by definition has no registered purchase history. The FirstOrderCheckService checks the order history for the current customer account. Since a guest has no account, the check passes (the guest is treated as a first-time customer). If you want to prevent abuse by guests who have previously ordered, this cannot be enforced at the voucher level without a custom account-linking strategy.
Q: Are the admin tabs visible in all OXID editions (CE/PE/EE)?
Yes. The module targets OXID 7.x across all three editions. The admin controller integration uses standard OXID metadata tab extension, which is available in CE, PE, and EE.
Q: Can I combine payment restrictions with time window restrictions on the same voucher?
Yes. All rule types are independent and additive. A voucher can simultaneously require PayPal, be valid only on Fridays between 17:00 and 20:00, and require a minimum order value of €50 when using DHL Express. All configured rules must pass for the voucher to be accepted.
¶ License
This module is proprietary software. All rights reserved.
Contact the author for licensing inquiries.
¶ Support and Changelog
¶ Support
For bug reports and feature requests, please use the issue tracker associated with the repository.
For direct support inquiries: markus-michalski.net
¶ Changelog
¶ 1.0.0
- Initial release
- Payment method restrictions (whitelist)
- Delivery method restrictions (whitelist)
- First Order Only flag
- Time windows with weekday bitmask
- Combination blacklist
- Max combined vouchers
- Payment-specific minimum order values
- Delivery-specific minimum order values
- Pending Voucher Pattern with automatic re-activation
- 4 admin tabs integrated into voucher series detail view
- DBAL-based repositories
- German and English translations
- Multi-shop (OXSHOPID) isolation