Provide voucher entry - WEBSALE Dokumentation

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

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.

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.

https://www.beispielshop.de/?voucher_number=123456

The parameter is introduced with ? if it is the first one in the address, and appended with & otherwise.

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.

<img src="~WS-BarcodeURL($INSTANTVOUCHER-VoucherNumber$,TYPE_CODE_128_A,3,JPG)~" alt="Gutscheincode als Barcode">

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

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.

If you use vouchers generated by an external system that are therefore not in WEBSALE format, add the entry ExternalVouchers-Allow = yes in the <Voucher-Txt> section of the shop.config.

Guide: Create or import vouchers

Step 2: Settings in the shop configuration

All voucher parameters are located in the <Voucher-Txt> section of the shop.config.

<Voucher-Txt>
   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
</Voucher-Txt>

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

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.

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.

<form action="~FORM-Basket~" method="post">
   <!-- oder: <form action="~FORM-PlaceOrder~" method="post"> -->

   {!VOUCHER-Number}
      <!-- Es liegt noch keine Gutscheinnummer vor, also das Eingabefeld zeigen -->
      Gutscheinnummer:
      <input type="text" name="~WS-VoucherNumber_input~" value="">
      <input type="submit" name="~BT-Voucher~" value="Gutschein einlösen">
   {/!VOUCHER-Number}

   {VOUCHER-Number}
      <!-- Es liegt eine Nummer vor, eingetippt oder per Link übergeben -->
      {ST-Voucher_checked}
         {!ST-Voucher_OK}
            <span class="voucher-error">
         {/!ST-Voucher_OK}
      {/ST-Voucher_checked}

      Gutscheinnummer: ~VOUCHER-Number~
      <input type="submit" name="~BT-Voucher_delete~" value="Gutschein entfernen">

      {ST-Voucher_checked}
         {!ST-Voucher_OK}
            </span>
         {/!ST-Voucher_OK}
      {/ST-Voucher_checked}
   {/VOUCHER-Number}

</form>

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.

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.

{MSG-Voucher_success}
   <div class="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)}
   </div>
{/MSG-Voucher_success}

{MSG-Voucher_error}
   <div class="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)}
      <!-- weitere Gründe nach demselben Muster, siehe Tabelle -->
   </div>
{/MSG-Voucher_error}

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.

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.

{ST-Voucher_OK}
   <a href="~BASKET-VoucherDeleteLink~">Gutschein entfernen</a>
{/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.

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 <Voucher-Txt> section of the shop.config.

<Voucher-Txt>
   PreventOrdersWithVoucherNotApplicable = yes
</Voucher-Txt>

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 <OrderConditions> section.

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.

{MSG-Basket_Notify}
   {ST-Voucher_checked}
      {VOUCHER-Number}
         <input autocomplete="off" type="text" value="~VOUCHER-Number~" disabled>
         <input type="submit" name="~BT-Voucher_delete~" value="Gutschein entfernen">
      {/VOUCHER-Number}
   {/ST-Voucher_checked}
{/MSG-Basket_Notify}

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

Guide: Offering vouchers: Overview
Guide: Create or import vouchers
Guide: Redeem multiple vouchers
Reference: VOUCHER-

​How redemption works in the shop

​Passing voucher numbers via link

​Redeeming vouchers in brick-and-mortar retail

​Integrating voucher entry

​Step 1: Activation

​Step 2: Settings in the shop configuration

​Step 3: Placing the input field and buttons

​Step 4: Placing messages

​Step 5: Placing a removal link (optional)

​Preventing order completion with non-applicable vouchers

​Adjustment for voucher entry on the order overview page and minimum order value

​Related topics

How redemption works in the shop

Passing voucher numbers via link

Redeeming vouchers in brick-and-mortar retail

Integrating voucher entry

Step 1: Activation

Step 2: Settings in the shop configuration

Step 3: Placing the input field and buttons

Step 4: Placing messages

Step 5: Placing a removal link (optional)

Preventing order completion with non-applicable vouchers

Adjustment for voucher entry on the order overview page and minimum order value

Related topics