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

# $wsVoucher - Vouchers

> Reference for $wsVoucher: list redeemed vouchers, calculate the total value and display voucher details in the WEBSALE basket and checkout.

With the `$wsVoucher` module, you can use and display voucher data dynamically in the frontend. You can list redeemed vouchers, calculate the total value, and load details for individual vouchers. In this section, you will learn how to retrieve voucher data and display it in the basket or checkout.

***

## Module overview

**Example / excerpt of** `$wsVoucher`

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

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "vouchers": [...],
  "totalValue": 0.0,
  "totalUsedValue": 0.0,
  "maximumCount": 0,
  "load": "ƒ()"
}
```

**Note:** `ƒ()` denotes a function.

**Variables and methods overview**

| **Name**         | **Type** | **Description**                                                                            |
| ---------------- | -------- | ------------------------------------------------------------------------------------------ |
| `vouchers`       | array    | List of vouchers that are queued for redemption.                                           |
| `totalValue`     | float    | Total value of the redeemed vouchers.                                                      |
| `totalUsedValue` | float    | Value of the vouchers already used.                                                        |
| `maximumCount`   | int      | Maximum number of vouchers that may be redeemed at the same time.<br />`0` = no limit set. |
| `load()`         | map      | Loads a voucher by its ID.                                                                 |

***

## Templates

Voucher data can generally be loaded and displayed in any template. Entering or redeeming a voucher code is possible throughout the shop. However, it is most useful within the ordering process or in the basket.

***

## Variables

### \$wsVoucher.vouchers

Returns a list of all vouchers that the customer has redeemed in the current basket.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $myVoucher in $wsVoucher.vouchers }}
  Voucher: {{= $myVoucher.id }} – Value: {{= $myVoucher.value | currency }}
{{ /foreach }}
```

### \$wsVoucher.totalValue

Returns the total value of the redeemed vouchers.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Voucher value: {{= $wsVoucher.totalValue | currency }}
```

### \$wsVoucher.totalUsedValue

Returns the voucher value already deducted from the basket.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Already redeemed: {{= $wsVoucher.totalUsedValue | currency }}
```

### \$wsVoucher.maximumCount

Returns the maximum number of vouchers that a customer may redeem at the same time.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Redeemed: {{= len($wsVoucher.vouchers) }} of {{= $wsVoucher.maximumCount }}
```

***

## Methods

### \$wsVoucher.load()

Loads a voucher by its ID.

**Signature**\
`$wsVoucher.load(id)`

**Return value**\
`Map` - Voucher map with the voucher data.

**Parameters**

| **Name** | **Type** | **Required** | **Description**    |
| -------- | -------- | ------------ | ------------------ |
| `id`     | string   | yes          | ID of the voucher. |

**Example** that loads a voucher:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myVoucher = $wsVoucher.load("GUTSCHEIN123") }}
Value: {{= $myVoucher.value | currency }}
```

<Info>
  By using the `$wsVoucher.load()` function, various variables are available to retrieve and output voucher data. Below is an overview of which variables are available.
</Info>

### **Voucher data (return value of \$wsVoucher.load())**

First, it is necessary to assign the map with the voucher data, as shown in the example above, to a local variable. This can then be used at various places in the template.

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "id": "...",
  "value": 0.0,
  "currency": "...",
  "taxId": "...",
  "usedValue": 0.0,
  "percentValue": 0.0,
  "absoluteValue": 0.0,
  "validFrom": "...",
  "validUntil": "..."
}
```

**Variables overview**

| **Variable**    | **Type** | **Description**                                                                                                                               |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | string   | Voucher ID.                                                                                                                                   |
| `value`         | float    | Value of the voucher.                                                                                                                         |
| `currency`      | string   | Currency of the voucher.                                                                                                                      |
| `taxId`         | string   | Tax rate ID of the voucher.                                                                                                                   |
| `usedValue`     | float    | Value of the voucher already redeemed.                                                                                                        |
| `percentValue`  | float    | For percentage vouchers, `percentValue` is filled (e.g. 10 for 10%); for fixed-amount vouchers, `absoluteValue` is filled (e.g. 5.00 for €5). |
| `absoluteValue` | float    | For percentage vouchers, `percentValue` is filled (e.g. 10 for 10%); for fixed-amount vouchers, `absoluteValue` is filled (e.g. 5.00 for €5). |
| `validFrom`     | string   | Valid from (date).                                                                                                                            |
| `validUntil`    | string   | Valid until (date).                                                                                                                           |

***

## Actions

Actions for this module that trigger changes are documented separately in the "Actions" chapter: [Voucher](/en/frontend/referenz/aktionen/voucher)

***

## Example for displaying voucher data

### Voucher value

This example displays the value of the voucher.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Voucher Value: {{= $voucher.value }}
```

### Voucher type: percentage or fixed amount

This example checks and displays whether the voucher grants a percentage discount or a fixed amount.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Discount type: {{= $voucher.percentValue | ifNull("Percentage Value is null")}} {{= $voucher.absoluteValue | ifNull("absolute value is nulll")}}
```

### Validity date of the voucher

This example displays the start and end date of a voucher's validity.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Valid from: {{= $voucher.validFrom | dateFmt("%d.%m.%Y") }}
Valid until: {{= $voucher.validUntil | dateFmt("%d.%m.%Y") }}
```

### Voucher currency

This example displays the currency in which the voucher was issued.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Currency: {{= $voucher.currency }}
```

### Display remaining amount of a voucher

This example displays the remaining amount that a partially used voucher still has.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Remaining amount: {{= ($voucher.value - $voucher.usedValue) | currency }}
```

### Check voucher validity

This example checks whether the voucher is basically valid.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $voucherAddAction.success }}
  Voucher successfully added to the basket.
{{ /if }}
```

### Show form only until the maximum number of vouchers has been redeemed

The form is only displayed if the number of vouchers already redeemed is less than the configured limit. If the limit is reached, the form is hidden and the customer receives a notice.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if len($wsVoucher.vouchers) < $wsVoucher.maximumCount }}
    <form method="post" action="{{= $wsViews.current.url() }}">
        <input type="text" name="id">
        <input type="hidden" name="wsact" value="{{= $voucherAddAction.id }}">
        <input type="hidden" name="wscsrf" value="{{= $voucherAddAction.csrf }}">
        <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">

        <button type="submit" class="btn btn-primary">Redeem</button>
    </form>
{{ /if }}
```

You can find more practical examples on the topic of vouchers [here](/en/gutscheine).

***

## Related links

* [Voucher settings](https://dokumentation.websale.de/konfiguration/checkout-bestellablauf#checkout-voucher-einstellungen-für-gutscheine)
* [Practical examples for vouchers](/en/gutscheine)