> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# Provide voucher entry
> Add the voucher field to the basket page and order overview page, design the messages, and handle special cases such as non-applicable vouchers and the minimum order value.
Vouchers you have created are useless as long as the customer cannot enter them. This page describes how the input field gets into the ordering process, how the feedback messages are designed, and which two special cases require additional work.
The most important point up front: a typed-in voucher number alone does nothing. The customer must activate the voucher using a button; only then does the shop check it. Without this activation, the voucher is ignored in the rest of the ordering process.
## How redemption works in the shop
Entry is possible on the basket page `ws_basket.htm`, on the order overview page `ws_place_order.htm`, or on both.
| What the customer does | What the shop does |
| - | - |
| enters a number and clicks "Redeem voucher" | checks the number and applies the voucher |
| enters an invalid number | displays a message with the reason |
| clicks "Remove voucher" | clears the field; the ordering process continues without a voucher |
> [!WARNING]
>
> Nothing happens without a click on "Redeem voucher". A number that is only in the field is not taken into account when the order is completed. Therefore, place the button so prominently that nobody overlooks it.
After a successful check, the customer immediately sees the savings or the added product. Offer a "Remove voucher" button afterwards as well, so that the customer can keep the voucher for a later order.
> [!NOTE]
>
> If someone tries to redeem a personalized voucher without logging in, a login form can be displayed within the error message. After logging in, the buyer can be automatically redirected back to the basket page to enter the voucher again.
Guide: Redeem multiple vouchers
## Passing voucher numbers via link
A voucher number can already be passed in the URL parameter `voucher_number` when the shop is called up, for example via a link from a newsletter. The shop then automatically enters it into the input field in the ordering process.
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.beispielshop.de/?voucher_number=123456
```
> [!NOTE]
>
> The parameter is introduced with `?` if it is the first one in the address, and appended with `&` otherwise.
> [!WARNING]
>
> A number passed via link also initially just sits in the field. It is only checked and applied when the customer clicks "Redeem voucher". A newsletter link alone therefore does not redeem the voucher.
Materials: URL parameters · Guide: Newsletter vouchers
## Redeeming vouchers in brick-and-mortar retail
If you also run a physical store, you can print the voucher number as a barcode on the voucher and have it scanned at the checkout. The tag `WS-BarcodeURL` generates the barcode as an image.
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
```
> [!NOTE]
>
> The tag works on every template. Where you place it depends on which type of voucher you offer, i.e. whether on the purchase voucher for printing, in the newsletter voucher, or on the new customer voucher.
Reference: WS-BarcodeURL
## Integrating voucher entry
> [!WARNING]
>
> The `VOUCHER-` tag family is available for voucher features. The older `WS-Voucher…` tags are still supported but should no longer be used in new integrations. Do not mix the two families, not even when updating an existing integration. The only exception is `WS-VoucherNumber_input`, which continues to be used unchanged.
### Step 1: Activation
If you want to use the voucher generator, it must be activated for your shop. Contact your WEBSALE representative to do so.
> [!NOTE]
>
> If you use vouchers generated by an external system that are therefore not in WEBSALE format, add the entry `ExternalVouchers-Allow = yes` in the `` section of the `shop.config`.
Guide: Create or import vouchers
### Step 2: Settings in the shop configuration
All voucher parameters are located in the `` section of the `shop.config`.
```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Name = Gutschein
Remainder2 = Verfügbarer Restbetrag für Ihre nächste Bestellung:
SpecialSettings1-Allow = no
VoucherNotApplicable = Der eingegebene Gutschein ist mit diesen Produkten leider nicht verwendbar
UsedVoucherNumber = (verwendete Gutscheinnummer: ~VoucherNumber~)
ShowPercentalVoucherDiscountForPosition-Allow = no
VoucherInputLocation = PlaceOrder,Basket
```
`VoucherInputLocation` defines on which pages the shop expects voucher entry.
| Value | Effect |
| - | - |
| `Basket` | only on the basket page |
| `PlaceOrder` | only on the order overview page |
| `PlaceOrder,Basket` | on both pages |
| `PlaceOrderAndBasket` | equivalent to `PlaceOrder,Basket`, retained only for compatibility reasons |
> [!NOTE]
>
> The entry is a comma-separated list, not a choice from three fixed keywords. If the shop does not recognize any of the values, it uses `Basket`.
> [!WARNING]
>
> The value must match what you actually build into the templates. An input field on a page that is not listed here has no effect, and the customer clicks in vain.
Reference: Voucher-Txt section
### Step 3: Placing the input field and buttons
The input field and the two buttons belong inside `FORM-Basket` or `FORM-PlaceOrder` respectively, because only then are they submitted with the form.
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
```
> [!NOTE]
>
> The two sections `{VOUCHER-Number}` and `{!VOUCHER-Number}` are mutually exclusive. As long as no number is present, the customer sees the input field; afterwards, the entered number with the remove button. This way, both never appear on the page at the same time.
> [!NOTE]
>
> `ST-Voucher_checked` indicates that the number has already been checked, `ST-Voucher_OK` that it is valid. Only both together allow the statement "checked and not valid", which highlights the incorrect entry here.
Reference: BT-Voucher · BT-Voucher\_delete · VOUCHER-Number · VOUCHER-ChargeID · WS-VoucherNumber\_input · ST-Voucher\_OK · ST-Voucher\_checked
### Step 4: Placing messages
You can freely place success and error messages on the same pages where you have built in the entry. Each message is a separate section with the reason as a parameter, so you have full control over wording and design.
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{MSG-Voucher_success}
{MSG-Voucher_success(1)}Der Gutschein wurde übernommen.{/MSG-Voucher_success(1)}
{MSG-Voucher_success(2)}Der Gutschein wurde entfernt.{/MSG-Voucher_success(2)}
{/MSG-Voucher_success}
{MSG-Voucher_error}
{MSG-Voucher_error(2)}Ungültige Gutscheinnummer. Bitte überprüfen Sie Ihre Eingabe.{/MSG-Voucher_error(2)}
{MSG-Voucher_error(3)}Dieser Gutschein ist erst ab dem ~MSG-Voucher_error_validfrom~ gültig.{/MSG-Voucher_error(3)}
{/MSG-Voucher_error}
```
> [!WARNING]
>
> The outer section alone displays nothing. Only the inner sections with a parameter produce text. A reason for which you have not provided a section results in the customer seeing an empty message without knowing why their voucher was rejected. Therefore, create a text for every reason that can be triggered in your shop.
The shop knows the following reasons. The suggested texts are intended as a starting point and should be adapted to your tone.
| Reason | When it occurs | Suggested text |
| - | - | - |
| 1 | Voucher entry blocked due to too many failed attempts | Voucher entry has been blocked. You cannot use a voucher for this order. |
| 2 | Number invalid, which also includes wrong currency and wrong subshop | Invalid voucher number. Please check your entry. |
| 3 | Voucher not yet valid | This voucher is only valid from `~MSG-Voucher_error_validfrom~`. Order at that time or use a different voucher. |
| 4 | Voucher expired | This voucher has expired. |
| 5 | Voucher already used up | The voucher has already been redeemed. |
| 6 | Personalized voucher, customer not logged in | Please log in to redeem this voucher. |
| 7 | Personalized voucher, already redeemed | This voucher has already been redeemed. |
| 8 | Category- or product-dependent voucher, basket does not match | This voucher does not apply to the products in your basket. |
| 9 | Personalized voucher, valid for new customers only | This voucher is valid for new customers only. |
| 10 | Personalized new customer voucher, login required | This voucher is valid for new customers only. Please log in. |
| 11 | Voucher valid for new customers only | This voucher is valid for new customers only. |
| 12 | New customer voucher, login required | This voucher is valid for new customers only. Please log in. |
| 13 | Maximum number of redemptions reached | This voucher has already been fully redeemed. |
| 14 | Voucher not applicable and order therefore blocked | You cannot order with this voucher because it does not apply to any product in the basket. Remove it or add a matching product to the basket. |
| 15 | Voucher restricted to specific customers, login required | You must be logged in for this voucher. |
| 16 | Voucher restricted to specific customers, this customer is not one of them | This voucher is valid for specific customers only. |
| 17 | Customer-bound universal voucher, login required | You must be logged in for this voucher. |
| 18 | Customer-bound universal voucher, bound to a different account | This voucher is bound to a different customer account. |
| 19 | Special function guarantee, customer not logged in | You must be logged in for this voucher. |
| 20 | Special function guarantee, voucher cannot be deleted | This voucher cannot be removed. Please log out and start the order again. |
| 21 | Special function filter on additional product fields, basket does not match | This voucher does not apply to the products in your basket. |
| 22 | Special function stock level, no product with matching stock in the basket | This voucher is valid only for products with a specific stock level. |
| 23 | Customer excluded from voucher campaigns | Vouchers are not enabled for your customer account. |
| 24 | Voucher redeemable only in the app | You can only redeem this voucher in our app. |
| 25 | A discount or discount list is stored in the customer account | This voucher cannot be combined with your customer discount. |
| 26 | The same voucher number was entered multiple times | You have already entered this voucher number. |
| 27 | Voucher cannot be combined with other vouchers | This voucher cannot be combined with other vouchers. |
> [!NOTE]
>
> Several reasons lead to the same statement, for example 9 and 11, or 15, 17, and 19. The shop distinguishes them because different checks apply internally. The texts may be identical for the customer, but a separate section per reason is still required.
Reference: MSG-Voucher\_success · MSG-Voucher\_error · MSG-Voucher\_error\_validfrom
### Step 5: Placing a removal link (optional)
In addition to the button, you can offer a link with which the customer can get rid of a valid voucher as long as the order has not been completed.
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ST-Voucher_OK}
Gutschein entfernen
{/ST-Voucher_OK}
```
Reference: BASKET-VoucherDeleteLink
## Preventing order completion with non-applicable vouchers
By default, the customer may place an order even if their valid voucher has no effect on this order. This is intentional, because the customer then does not need an extra click to remove the voucher.
This case occurs, for example, with a promotional voucher in a basket that contains only products not eligible for promotional vouchers, or with a category-dependent voucher when there is no product from that category in the basket.
> [!NOTE]
>
> In some cases, explicit deletion by the customer still makes sense, for example if the voucher adds a product to the basket. The customer should then notice that they will not receive this product.
**Step 1:** On the page with voucher entry, add reason 14 to `MSG-Voucher_error`; see the table above.
**Step 2:** Set the following entry in the `` section of the `shop.config`.
```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
PreventOrdersWithVoucherNotApplicable = yes
```
> [!WARNING]
>
> The two steps belong together. If you set the entry without providing reason 14, the order is blocked and the customer sees no indication of why they cannot proceed.
## Adjustment for voucher entry on the order overview page and minimum order value
You need this addition if both of the following apply to your shop:
* The voucher number is entered exclusively on the order overview page `ws_place_order.htm`.
* The voucher discount at item level is taken into account for the minimum order value, controlled via `MinimumOrder-ConsiderVoucherDiscount-Allow` in the `` section.
> [!NOTE]
>
> Taking it into account is the default setting. Only an explicit `MinimumOrder-ConsiderVoucherDiscount-Allow = no` switches it off and adds the voucher discount at item level back to the calculation basis.
If the voucher reduces the merchandise value below the minimum order value, the shop takes the customer back to the basket page. There, the customer must be able to delete the voucher, otherwise they are stuck: they can only enter it on the order overview page, but they can no longer get there.
Therefore, add the following block to the basket page `ws_basket.htm`.
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{MSG-Basket_Notify}
{ST-Voucher_checked}
{VOUCHER-Number}
{/VOUCHER-Number}
{/ST-Voucher_checked}
{/MSG-Basket_Notify}
```
> [!NOTE]
>
> The field is intentionally set to `disabled`. The customer should be able to see and recognize the number but not change it on this page, because an entry here would have no effect.
Reference: MSG-Basket\_Notify · ST-Voucher\_checked · VOUCHER-Number · BT-Voucher\_delete
## Related topics
* Guide: Offering vouchers: Overview
* Guide: Create or import vouchers
* Guide: Redeem multiple vouchers
* Reference: VOUCHER-
## Related topics
- [Percentage vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/prozentuale-gutscheine.md)
- [Newsletter vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/newsletter-gutscheine.md)
- [Purchase vouchers for printing](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/kaufgutscheine-zum-ausdrucken.md)
- [Vouchers with multiple currencies](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutscheine-mit-mehreren-waehrungen.md)
- [New customer vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/neukunden-gutscheine.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.