Vouchers

Vouchers your customers keep in their account, for Magento 2 stores on Hyvä. Each voucher is a coupon code backed by a regular cart price rule, so the discount works exactly as Magento’s; the module adds what the rule lacks: a coupon code that belongs to one customer, an expiry per voucher, offers customers save themselves, vouchers you assign, and a “My Vouchers” page that shows all of it.

What it does

• Campaigns on top of cart price rules. A campaign gives a rule with a Specific Coupon a face: a title, bullet points, a “See products” link. Discount, minimum order, categories, dates and customer groups stay in the rule, where your team already manages them.
• A unique coupon code per customer. Each customer gets their own code (e.g. SHOP-AB12-CD34), single use, valid only on their account and only until it expires: a number of days from issue, never past the rule’s end. Someone else trying the code gets the cart’s usual “invalid code” message, the same as for any wrong code.
• Or a shared code. The rule’s fixed code, handed out through the account, for open promotions.
• Public offers. Customers see the current offers in their account and save the ones they want with one click.
• Personal vouchers. Assign a campaign to e-mails, to whole customer groups or right from the customer page, with an optional own expiry and an internal note (“late delivery, order #123”). A reusable personal campaign (“Sorry for the delay: 10 off”) makes one-off compensations a two-field job.
• “My Vouchers” in the account. Active, scheduled, used (with a link to the order) and expired vouchers, each code with a copy button; the public offers below.
• Used and released automatically. A voucher is marked as used when the order is placed, and becomes active again if the order is cancelled.
• Guard rails in the admin. Saving a campaign warns about the two rule settings that are valid but rarely what a voucher means: an amount taken off every item instead of the whole cart, and a subtotal condition calculated without tax.
• Pick a voucher in the cart. Under Apply Discount Code on the Hyvä cart page, a “Vouchers and offers” row opens a dialog with the customer’s vouchers and the current offers, each marked as applicable to this cart or not (and why). One click applies it; an offer not saved yet is saved on the same click. Guests are invited to sign in.
• Ready for custom carts. The same list, with its verdicts, is available to any custom cart or checkout through a view model and two endpoints. See Voucher picker in a custom cart.
• Your theme’s look. The account page is built on the theme’s colours (or an accent colour you set), with scoped styles: no Tailwind build. Every heading is editable per store view; English and Romanian included.

Requirements

Magento Open Source / Adobe Commerce	2.4.8 (tested on 2.4.8-p5)
Hyvä Theme	1.3 or newer (tested on 1.5.3)
PHP	8.3 – 8.4 (as required by Magento 2.4.8)

The storefront uses Hyvä’s view models (icons) and Alpine.js; Luma storefronts are not supported. hyva-themes/magento2-theme-module comes from Hyvä’s own Composer repository, which every Hyvä store already has configured.

Installation

Add the repository you received with your license to composer.json (once), then:

composer require slova/module-vouchers:^1.0
bin/magento module:enable Slova_Vouchers
bin/magento setup:upgrade
bin/magento setup:di:compile          # production mode
bin/magento cache:flush

Without Composer, unpack the zip into app/code/Slova/Vouchers (so that app/code/Slova/Vouchers/registration.php exists) and run the same bin/magento commands.

setup:upgrade creates two tables: slova_voucher_campaign and slova_voucher.

Upgrading

composer update slova/module-vouchers
bin/magento setup:upgrade
bin/magento setup:di:compile          # production mode
bin/magento cache:flush

Read CHANGELOG.md first; campaigns and vouchers are kept across versions.

Uninstalling

Installed with Composer:

bin/magento module:uninstall Slova_Vouchers --remove-data

Installed from the zip: bin/magento module:disable Slova_Vouchers, delete app/code/Slova/Vouchers, then drop the two tables. The cart price rules and the coupon codes generated on them are Magento’s and stay; deactivate the rules you no longer need.

Getting started

1. Create the cart price rule (Marketing > Cart Price Rules): the discount, conditions, dates and customer groups you want, and Coupon = Specific Coupon.
   • For a unique code per customer, check Use Auto Generation (no code to type).
   • For a shared code, type the code and leave Use Auto Generation unchecked.
   • For a fixed amount once per order, choose Fixed amount discount for whole cart. Fixed amount discount takes the amount off every item.
   • For “minimum order of X” as the customer sees it in a store with prices including tax, use the condition Subtotal (Incl. Tax); Subtotal is calculated without tax.
2. Create the campaign (Marketing > Vouchers > Campaigns > New Campaign): title, description (one line per bullet point; the validity period is added automatically), the rule, the code type, how many days a unique code stays valid, and the visibility:
   • Public: listed in every eligible customer’s account under Current offers, to save with one click;
   • Personal: never listed; you assign it.
3. Assign a personal campaign from Assign Now in the campaign form (e-mails and/or customer groups), from Marketing > Vouchers > Issued Vouchers > Assign Voucher, or from the Vouchers tab of a customer.

Customers use a voucher from the voucher picker in the cart (Vouchers and offers, under Apply Discount Code) or by typing its code in the discount code field. A unique code needs the customer to be signed in.

The voucher picker in the cart

On the Hyvä cart page, under Apply Discount Code:

• The row shows which voucher is on the cart (“You chose: …”, with Change) or how many of the customer’s vouchers and offers can be used with it.
• The dialog (“Choose your voucher”) lists the customer’s active and scheduled vouchers and the current public offers. Those that can be applied come first, with Apply; the others are dimmed, with the reason (conditions not met, products not covered, already used, not started yet).
• Apply goes through the cart’s own coupon form, exactly like a typed code: Magento computes the discount and shows its usual message. An offer the customer has not saved yet is saved to their account first. The dialog opens again with the result, so the customer can pick another voucher (it replaces the first), Remove it, or press Done.
• Guests see “Have vouchers? Sign in to see them.”, which brings them back to the cart.

The list is rendered with the page, so nothing jumps in once it loads. The components are Hyvä CSP compatible. To turn the picker off (for example when your cart is replaced by a custom one), set Display > Voucher Picker in the Cart to No.

How it behaves

• Who sees an offer. A public campaign is listed when it is active, its rule is active and running today, and the rule includes the customer’s group and website. A customer saves each campaign once, also after using it.
• Expiry. A unique code expires after the campaign’s Valid For days, or at the end of the rule’s last day if that comes first. An expiry set on assignment replaces it. Shared codes follow the rule’s dates.
• Single use. A unique code is created with a usage limit of 1, whatever the rule says.
• Assigning twice. A customer who already holds an active voucher from the campaign is skipped; a used or expired one does not block a new assignment.
• Revoking. Revoking a voucher (grid or customer page) removes it from the account and deletes its unique coupon, so a code the customer noted down stops working. Used vouchers cannot be revoked. Deleting a campaign revokes all its vouchers.
• One code per cart. Magento Open Source applies one coupon code per cart; applying another voucher replaces the first.

Settings

Stores > Configuration > Slova > Vouchers (also Marketing > Vouchers > Settings):

Setting	Scope	Default
Codes: Unique Code Prefix	global	none
Codes: Unique Code Length	global	8 (a dash every 4 characters)
Display: Accent Colour	store view	the theme’s primary colour
Display: Voucher Picker in the Cart	store view	Yes
Texts: Account Menu Link and Page Title	store view	My Vouchers
Texts: Customer’s Vouchers Heading	store view	My vouchers
Texts: Public Offers Heading	store view	Current offers

The account page lives at /vouchers. To show it under another URL, add a URL rewrite (Marketing > URL Rewrites, custom: request path of your choice → target path vouchers) and point the account menu link to it in your theme (customer-account-navigation-vouchers-link, argument path).

Styling

The account page uses CSS custom properties on .slova-vouchers, so a theme can change any colour without touching the template:

.slova-vouchers {
    --sv-accent: #db2777;          /* titles, icons, code border (overrides the Accent Colour setting) */
    --sv-link: #006e8a;            /* links, copy button */
    --sv-button-bg: #ccf0f0;       /* Save voucher */
    --sv-button-fg: #006666;
    --sv-button-bg-hover: #99dddd;
    --sv-card-bg: #f3f4f6;
    --sv-heading: #111827;
    --sv-text: #1f2937;
    --sv-muted: #4b5563;
}

Voucher picker in a custom cart

The module’s picker sits on Hyvä’s cart page. A store with a custom cart or checkout (where that page is replaced) can build its own picker with the parts the module’s one uses:

• Slova\Vouchers\ViewModel\CartVouchers::getPayload() returns {loggedIn, appliedCode, items} for the session cart. Each item: key, kind (voucher = in the account, offer = public offer not saved yet), id, title, bullets, code (null for offers), productsUrl, eligible and reason (why it does not apply: conditions not met, products not covered, already used, not started yet). Applicable items come first. Render it into the page to avoid a layout shift.
• GET vouchers/cart returns the same JSON, to refresh the list after the cart changes.
• POST vouchers/cart/claim with JSON {"campaignId": 12, "formKey": "…"} saves an offer to the customer’s account and returns {"success": true, "code": "…"}; then apply the code with your cart’s coupon call.

The verdict repeats Magento’s checks (rule, dates, groups, per-customer limit, cart and product conditions) on the cart’s last calculated totals, without recalculating or saving the cart. If it ever disagrees with Magento, applying the code returns the usual error.

Support

Report issues with the Magento and Hyvä versions, steps to reproduce and any entries from var/log/system.log / var/log/exception.log mentioning Slova_Vouchers.