> ## 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.

# Redeeming multiple vouchers

> Allow up to ten vouchers per order, set up the input fields for them and show percentage vouchers separately from fixed-amount vouchers.

By default, the shop accepts one voucher per order. With this extension, it accepts up to ten. As soon as the customer has redeemed the first number, another input field appears.

The ten are made up of the first voucher and nine additional ones. This split runs through the entire implementation: the first voucher is addressed in the template as before, while the nine additional ones are contained in a loop.

![Screen Multivoucher](https://mintcdn.com/websaleag-44ee7ea6/UyjGmXApgB40YKCW/images/screen-multivoucher.png?fit=max\&auto=format\&n=UyjGmXApgB40YKCW\&q=85\&s=2f91cdd82e66cc6052f1704a9311d26d)

## Which vouchers can be combined

Not every type of voucher can be combined. The following can currently be combined:

| Voucher type | Condition |
| - | - |
| Purchase and promotional vouchers with a percentage discount | must be shown at item level, i.e. `ShowPercentalVoucherDiscountForPosition-Allow = yes` |
| Purchase vouchers with a fixed amount | without an assigned VAT rate |
| Promotional vouchers with a fixed amount | without an assigned VAT rate |
| Vouchers with no effect on items or sums dependent on the goods value | for example shipping cost waivers, authorization codes and vouchers that add free products |

> [!WARNING]
>
> In this combination, a promotional voucher with a fixed amount applies **to all products without exception**. The usual exclusion of products not eligible for promotional vouchers does not apply here. Check this if you have price-fixed goods in your product range.

> [!NOTE]
>
> Whether two specific vouchers are compatible can additionally be controlled per voucher. Using the special function for combinability, vouchers can be marked as exclusive or linked to each other via allow and block lists. If this check fails, rejection reason 27 appears.

Guide: Percentage vouchers

## Prerequisite

The voucher generator must be activated. Contact your WEBSALE representative to arrange this.

> [!NOTE]
>
> If the vouchers come from an external system and are therefore not in WEBSALE format, add the entry `ExternalVouchers-Allow = yes` in the `<Voucher-Txt>` section of the `shop.config`.

## Step 1: Enable the function in test mode

The setup deliberately runs in two stages. First set the switch to `test`; the function then only takes effect in the shop's test mode, and nothing changes for real customers.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<Voucher-Txt>
   MultiVoucher-Allow                      = test
   UseRoundedPercentalMultiVoucherDiscount =        # [yes|no], Voreinstellung: no
   MultiVoucher-MinOrderBehavior           =        # [UseMax], Voreinstellung: Summe
</Voucher-Txt>
```

| Entry | Meaning |
| - | - |
| `MultiVoucher-Allow` | `yes` enables the function, `test` only in the shop's test mode; any other value leaves it off |
| `UseRoundedPercentalMultiVoucherDiscount` | `yes` rounds the intermediate results for percentage vouchers; otherwise rounding only takes place after all voucher amounts have been added up |
| `MultiVoucher-MinOrderBehavior` | `UseMax` checks against the highest minimum order value of the redeemed vouchers; any other value checks against their sum |

> [!NOTE]
>
> `MultiVoucher-MinOrderBehavior` determines how strict the promotion is. Three vouchers with a minimum order value of 50 euros each require a basket over 150 euros with the default setting; with `UseMax`, 50 euros is enough. This is the lever that determines the economic framework of a multi-voucher promotion.

> [!WARNING]
>
> Disabling is trickier than enabling. A running session that already contains several codes would end up in an inconsistent state if the function were disabled. The shop therefore only applies the switch to `no` to sessions in which no additional voucher has been entered yet. Existing sessions with multiple codes continue with the old setting.

Reference: Voucher-Txt section

## Step 2: Set up the input fields

The first voucher remains unchanged; the additional ones go into the `VOUCHER-MultiVoucher` loop.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-Basket~" method="post">

   <!-- Erster Gutschein -->
   <input type="text" name="~WS-VoucherNumber_input~" value="~WS-VoucherNumber~"
          {WS-VoucherNumber} disabled readonly{/WS-VoucherNumber}>
   {WS-VoucherNumber}
      {ST-Voucher_checked}
         <button type="submit" name="~BT-Voucher_delete~">Gutschein löschen</button>
      {/ST-Voucher_checked}
      {!ST-Voucher_checked}
         <button type="submit" name="~BT-Voucher~">Gutschein einlösen</button>
      {/!ST-Voucher_checked}
   {/WS-VoucherNumber}
   {!WS-VoucherNumber}
      <button type="submit" name="~BT-Voucher~">Gutschein einlösen</button>
   {/!WS-VoucherNumber}

   <!-- Weitere Gutscheine -->
   {VOUCHER-MultiVoucher}
      {@VOUCHER-MultiVoucher}
         <input type="text" name="~WS-VoucherNumber_input~" value="~WS-VoucherNumber~"
                {WS-VoucherNumber} disabled readonly{/WS-VoucherNumber}>
         {ST-Voucher_checked}
            <button type="submit" name="~BT-Voucher_delete~">Gutschein löschen</button>
         {/ST-Voucher_checked}
         {!ST-Voucher_checked}
            <button type="submit" name="~BT-Voucher~">Gutschein einlösen</button>
         {/!ST-Voucher_checked}
      {/@VOUCHER-MultiVoucher}
   {/VOUCHER-MultiVoucher}

</form>
```

> [!WARNING]
>
> The loop contains **only the additional** vouchers, not the first one. If you want to display all entered numbers, you have to place the tag twice, once outside and once inside the loop. This split is the most common source of errors with this extension.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Eingegebene Gutscheinnummern:

~WS-VoucherNumber~
{VOUCHER-MultiVoucher}
   {@VOUCHER-MultiVoucher}
      ~WS-VoucherNumber~
   {/@VOUCHER-MultiVoucher}
{/VOUCHER-MultiVoucher}
```

> [!NOTE]
>
> Inside the loop, the voucher-related tags refer to the voucher of the respective iteration. This applies to all `VOUCHER-` tags that read voucher data, for example `VOUCHER-DataExists`, `VOUCHER-Number` and `VOUCHER-ChargeID`, and additionally to `BASKET-VoucherRest`, `BASKET-VoucherDeleteLink`, `BASKET-VoucherNotApplicable`, `BASKET-PR-VoucherApplies` and `ST-Voucher_OK`.

You output the values of the additional vouchers following the same pattern.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{VOUCHER-MultiVoucher}
   {@VOUCHER-MultiVoucher}
      {ST-Voucher_checked}
         Gutschein (~WS-VoucherNumber~)
         ~BASKET-VoucherDiscount~ ~WS-CurrencySymbol~
      {/ST-Voucher_checked}
   {/@VOUCHER-MultiVoucher}
{/VOUCHER-MultiVoucher}
```

Reference: WS-VoucherNumber\_input · WS-VoucherNumber · ST-Voucher\_checked · BT-Voucher\_delete · BT-Voucher · VOUCHER-MultiVoucher · BASKET-VoucherDiscount

## Step 3: Add the two new error messages

With multiple vouchers, two rejection reasons are added that could not occur before. Add both wherever you have integrated the voucher entry.

| Reason | When it occurs |
| - | - |
| 26 | the same voucher number was entered a second time |
| 27 | the voucher is not compatible with one already redeemed |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{MSG-Voucher_error(26)}
   Diese Gutscheinnummer haben Sie bereits eingegeben.
{/MSG-Voucher_error(26)}

{MSG-Voucher_error(27)}
   Dieser Gutschein lässt sich nicht mit den bereits eingelösten kombinieren.
{/MSG-Voucher_error(27)}
```

Reference: MSG-Voucher\_error

## Step 4: Test in test mode

Open the shop in test mode and redeem various combinable vouchers.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.beispielshop.de/?test=on
https://www.beispielshop.de/?test=off
```

> [!NOTE]
>
> Check not only that multiple codes are accepted, but also the totals. The interaction between percentage and fixed-amount vouchers and the rounding in particular can only be assessed using real figures.

Guide: Enabling/disabling the shop's test modes

## Step 5: Go live

Set the switch to `yes` and remove any wrappers you added to the templates for testing.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<Voucher-Txt>
   MultiVoucher-Allow = yes
</Voucher-Txt>
```

## Showing percentage and fixed-amount vouchers separately

Percentage vouchers are already included in the subtotal, whereas fixed-amount vouchers are only deducted from it afterwards. The customer cannot tell this if both appear on one line. Both types can therefore be output separately, and the sections only appear if the respective type actually exists.

![Multivoucher Prozentuale Absolute Getrennt](https://mintcdn.com/websaleag-44ee7ea6/UyjGmXApgB40YKCW/images/multivoucher-prozentuale-absolute-getrennt.jpg?fit=max\&auto=format\&n=UyjGmXApgB40YKCW\&q=85\&s=0165bce11e72780bf239d81d0b3ad85c)

### Percentage vouchers at the subtotal

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BASKET-SubTotalSum}

   Zwischensumme: ~BASKET-SubTotalSum~ ~WS-CurrencySymbol~

   {BASKET-PercentalVoucherDiscountSum}
      nach Abzug prozentualer Gutscheine im Wert von
      ~BASKET-PercentalVoucherDiscountSum~ ~WS-CurrencySymbol~<br>

      {VOUCHER-Number}
         {ST-Voucher_checked}
            {VOUCHER-AmountType_isPercent}
               ~VOUCHER-Number~ ~BASKET-PercentalVoucherDiscount~ ~WS-CurrencySymbol~<br>
            {/VOUCHER-AmountType_isPercent}
         {/ST-Voucher_checked}
      {/VOUCHER-Number}

      {VOUCHER-MultiVoucher}
         {@VOUCHER-MultiVoucher}
            {ST-Voucher_checked}
               {VOUCHER-AmountType_isPercent}
                  ~VOUCHER-Number~ ~BASKET-PercentalVoucherDiscount~ ~WS-CurrencySymbol~<br>
               {/VOUCHER-AmountType_isPercent}
            {/ST-Voucher_checked}
         {/@VOUCHER-MultiVoucher}
      {/VOUCHER-MultiVoucher}
   {/BASKET-PercentalVoucherDiscountSum}

{/BASKET-SubTotalSum}
```

> [!NOTE]
>
> The pattern repeats twice, once for the first voucher and once in the loop. `VOUCHER-AmountType_isPercent` ensures that only percentage vouchers appear in this block.

### Fixed-amount vouchers below

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BASKET-VoucherDiscountSum}
   {ST-Voucher_checked}
      Gutschein-Rabatt<br>

      {VOUCHER-Number}
         {ST-Voucher_checked}
            {VOUCHER-AmountType_isAbsolute}
               ~VOUCHER-Number~ ~BASKET-VoucherDiscount~ ~WS-CurrencySymbol~<br>
            {/VOUCHER-AmountType_isAbsolute}
         {/ST-Voucher_checked}
      {/VOUCHER-Number}

      {VOUCHER-MultiVoucher}
         {@VOUCHER-MultiVoucher}
            {ST-Voucher_checked}
               {VOUCHER-AmountType_isAbsolute}
                  ~VOUCHER-Number~ ~BASKET-VoucherDiscount~ ~WS-CurrencySymbol~<br>
               {/VOUCHER-AmountType_isAbsolute}
            {/ST-Voucher_checked}
         {/@VOUCHER-MultiVoucher}
      {/VOUCHER-MultiVoucher}

      ~BASKET-VoucherDiscountSum~ ~WS-CurrencySymbol~
   {/ST-Voucher_checked}
{/BASKET-VoucherDiscountSum}
```

### Showing the total savings (optional)

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ST-Voucher_checked}
   Gewährte Gutschein-Rabatte<br>
      ~WS-DisablePriceAndNumberFormat~
      ~DC-CommercialCalc1_set($BASKET-PercentalVoucherDiscountSum$)~
      ~DC-CommercialCalc1_add($BASKET-VoucherDiscountSum$)~
      ~WS-EnablePriceAndNumberFormat~
      ~DC-CommercialCalc1~ ~WS-CurrencySymbol~<br>

   davon prozentuale Gutscheine:
      ~BASKET-PercentalVoucherDiscountSum~ ~WS-CurrencySymbol~<br>

   davon absolute Gutscheine:
      ~BASKET-VoucherDiscountSum~ ~WS-CurrencySymbol~<br>
{/ST-Voucher_checked}
```

> [!WARNING]
>
> Price formatting must be switched off for the calculation. Otherwise, the amounts go into the addition with thousands separators and decimal commas, and the result is wrong. Switch it back on immediately afterwards so that the formatting is retained in the rest of the template.

Reference: BASKET-SubTotalSum · BASKET-PercentalVoucherDiscountSum · BASKET-PercentalVoucherDiscount · BASKET-VoucherDiscountSum · VOUCHER-AmountType\_isPercent · VOUCHER-AmountType\_isAbsolute · WS-DisablePriceAndNumberFormat · DC-CommercialCalc1\_set

## Related topics

* Guide: Offering vouchers: Overview
* Guide: Providing voucher entry
* Guide: Percentage vouchers
* Guide: Enabling/disabling the shop's test modes


## Related topics

- [META vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/meta-gutscheine.md)
- [Vouchers with multiple currencies](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutscheine-mit-mehreren-waehrungen.md)
- [Provide voucher entry](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutschein-eingabe-vorsehen.md)
- [Prices, taxes, and currency](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.md)
- [VOUCHER- (Voucher)](https://dokumentation.websale.de/en/v8s/referenz/tags/voucher-gutschein.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.