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

# Percentage vouchers

> Define a maximum redemption amount for percentage vouchers or show the discount per basket item instead of on the total merchandise value.

When creating a voucher, you decide whether it deducts a fixed amount or a percentage of the merchandise value. This page deals exclusively with the second case and two settings that only exist there.

| Setting | What it is for |
| - | - |
| Maximum redemption amount | caps the savings so that a percentage does not become arbitrarily expensive for large baskets |
| Display at item level | shows the discount per basket item instead of as one deduction from the total merchandise value |

> [!WARNING]
>
> The two are mutually exclusive. As soon as a voucher has a maximum redemption amount, it is always displayed globally, never per item. The section "Why the two are mutually exclusive" at the end of the page explains what the shop does in this case.

## Prerequisites for both

**The voucher generator must be activated.** If you want to use it, contact your WEBSALE representative.

> [!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`.

**Voucher entry must be integrated in the shop.** If your shop does not offer vouchers yet, the input field on the basket page `ws_basket.htm` and the order overview page `ws_place_order.htm` is missing.

Guide: Provide voucher entry · Reference: Voucher-Txt section

## Maximum redemption amount

A percentage grows with the basket. Ten percent of 50 euros costs you five euros; the same ten percent of 3,000 euros costs 300. With a maximum redemption amount, you cap these savings.

| Basket value | Voucher 10 percent, maximum 15.00 EUR | Deducted |
| - | - | - |
| 80.00 EUR | 8.00 EUR calculated, below the maximum | 8.00 EUR |
| 150.00 EUR | 15.00 EUR calculated, exactly the maximum | 15.00 EUR |
| 300.00 EUR | 30.00 EUR calculated, above the maximum | 15.00 EUR |

You define the amount when creating the voucher in the voucher generator in the online service area.

### Displaying the notice in the basket

The cap is only understandable for the buyer if you point it out. There are two sections for this.

| Section | When it applies |
| - | - |
| `BASKET-VoucherMaxDiscount` | a valid percentage voucher is present and has a maximum amount. As a single tag, it outputs the amount in the shop's price format |
| `BASKET-VoucherMaxDiscountReached` | the cap is currently in effect, i.e. the calculated discount has been reduced |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BASKET-VoucherMaxDiscount}
   Der maximale Einlösungsbetrag des Gutscheins beträgt ~BASKET-VoucherMaxDiscount~ ~WS-CurrencySymbol~.
{/BASKET-VoucherMaxDiscount}

{BASKET-VoucherMaxDiscountReached}
   Der maximale Einlösungsbetrag von ~BASKET-VoucherMaxDiscount~ ~WS-CurrencySymbol~ ist erreicht.<br>
   Es werden Ihnen deshalb nur ~BASKET-VoucherMaxDiscount~ ~WS-CurrencySymbol~ vom Warenwert abgezogen.
{/BASKET-VoucherMaxDiscountReached}
```

> [!NOTE]
>
> The two belong together and should both be set. The first notice appears as soon as the voucher is redeemed and spares the buyer a surprise. The second only appears at the moment the discount is actually reduced and explains the difference between the expected and the actual deduction.

> [!WARNING]
>
> Without these notices, a buyer with a 300-euro basket expects 30 euros in savings and sees 15. That is the classic reason for abandonment in the last ordering step.

Reference: BASKET-VoucherMaxDiscount · BASKET-VoucherMaxDiscountReached

## Displaying a percentage voucher per item

By default, a percentage voucher deducts an amount from the total merchandise value and appears as one line in the totals. Alternatively, it can be allocated to each basket item individually. The buyer then sees the original price, the discount amount, and the discounted price for each item.

### Step 1: Activating the calculation

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

### Step 2: Outputting the prices in the basket

Add the original price and the discount amount in the basket loop. The same block must also be placed in the loop of the set sub-products; otherwise their items remain without a discount indication.

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

   {BASKET-PR-Price}
      {BASKET-PR-PriceWithoutDiscounts}
         Originalpreis ~BASKET-PR-PriceWithoutDiscounts~ ~WS-CurrencySymbol~
         abzüglich ~BASKET-PR-Discount~ ~WS-CurrencySymbol~
      {/BASKET-PR-PriceWithoutDiscounts}
      <!-- Preis des Produkts beziehungsweise des Set-Oberprodukts -->
      ~BASKET-PR-Price~ ~WS-CurrencySymbol~
   {/BASKET-PR-Price}

   {@BASKET-PR-SetChildData}
      {BASKET-PR-Price}
         {BASKET-PR-PriceWithoutDiscounts}
            Originalpreis ~BASKET-PR-PriceWithoutDiscounts~ ~WS-CurrencySymbol~
            abzüglich ~BASKET-PR-Discount~ ~WS-CurrencySymbol~
         {/BASKET-PR-PriceWithoutDiscounts}
         <!-- Preis des Set-Unterprodukts -->
         ~BASKET-PR-Price~ ~WS-CurrencySymbol~
      {/BASKET-PR-Price}
   {/@BASKET-PR-SetChildData}

{/@BASKET-PR-Data}
```

| Tag | Content |
| - | - |
| `BASKET-PR-PriceWithoutDiscounts` | the original price of the item, without discount |
| `BASKET-PR-Discount` | the discount of this item as an absolute amount |
| `BASKET-PR-Price` | the price of the item after deduction |

> [!NOTE]
>
> `BASKET-PR-PriceWithoutDiscounts` is both a section and a single tag. As a section, it hides the original line as long as there is nothing to deduct, so that non-discounted items do not show a pointless line such as "Original price 20.00 EUR minus 0.00 EUR".

> [!WARNING]
>
> If you use a merchandise management system, clarify before activation whether it can process percentage vouchers at item level at all. The shop then transfers the order split up differently than usual. If the upstream system is not prepared for this, the problem only becomes apparent at invoicing.

Reference: BASKET-PR-PriceWithoutDiscounts · BASKET-PR-Discount

## Why the two are mutually exclusive

The shop displays a percentage voucher per item only if all three conditions apply:

1. The voucher is a percentage voucher.
2. `ShowPercentalVoucherDiscountForPosition-Allow` is set to `yes`.
3. The voucher has **no** maximum redemption amount.

If the voucher has a maximum amount, the third condition is not met and the voucher is displayed globally, as if `ShowPercentalVoucherDiscountForPosition-Allow` were set to `no`. The setting in the configuration remains unchanged; it simply does not apply to this one voucher.

> [!NOTE]
>
> The reason lies in the calculation. A cap affects the total amount, not individual items. As soon as a reduction takes place, it could no longer be allocated to the items in a way that reflects their contribution without becoming arbitrary.

> [!WARNING]
>
> If you are planning both, decide per voucher batch. A cap and a per-item display cannot be combined in one voucher.

## Related topics

* Guide: Offering vouchers: Overview
* Guide: Create or import vouchers
* Guide: Provide voucher entry


## Related topics

- [VOUCHER- (Voucher)](https://dokumentation.websale.de/en/v8s/referenz/tags/voucher-gutschein.md)
- [Vouchers in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/gutscheine-im-warenkorb.md)
- [$wsVoucher - Vouchers](https://dokumentation.websale.de/en/frontend/referenz/module/wsvoucher.md)
- [Vouchers with multiple currencies](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutscheine-mit-mehreren-waehrungen.md)
- [Redeeming multiple vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/mehrere-gutscheine-einloesen.md)


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