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

> Modul $wsVoucher: eingelöste Gutscheine auflisten, Gesamtwert berechnen und Details zu einzelnen Gutscheinen im Warenkorb und Checkout anzeigen.

Mit dem `$wsVoucher` Modul können Sie Gutschein-Daten dynamisch im Frontend verwenden und anzeigen. Sie können eingelöste Gutscheine auflisten, den Gesamtwert berechnen und Details zu einzelnen Gutscheinen laden. In diesem Abschnitt erfahren Sie, wie Sie Gutscheindaten abrufen und im Warenkorb oder Checkout darstellen können.

***

## Modulübersicht

**Beispiel / Ausschnitt über** `$wsVoucher`

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

**JSON-Ausgabe**

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

**Anmerkung:** `ƒ()` kennzeichnet eine Funktion.

**Variablen und Methoden in der Übersicht**

| **Name**         | **Typ** | **Beschreibung**                                                                                         |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `vouchers`       | array   | Liste der Gutscheine, die zum Einlösen vorgemerkt sind.                                                  |
| `totalValue`     | float   | Gesamtwert der eingesetzten Gutscheine.                                                                  |
| `totalUsedValue` | float   | Bereits genutzter Wert der Gutscheine.                                                                   |
| `maximumCount`   | int     | Maximale Anzahl der Gutscheine, die gleichzeitig eingelöst werden dürfen.<br />`0` = kein Limit gesetzt. |
| `load()`         | map     | Lädt einen Gutschein anhand seiner ID.                                                                   |

***

## Templates

Gutscheindaten können grundsätzlich auf allen Templates geladen und angezeigt werden. Eine Eingabe bzw. Einlösung eines Gutscheincodes ist im gesamten Shop möglich. Am sinnvollsten erfolgt dies jedoch innerhalb des Bestellprozesses oder im Warenkorb.

***

## Variablen

### \$wsVoucher.vouchers

Gibt eine Liste aller Gutscheine aus, die der Kunde im aktuellen Warenkorb eingelöst hat.

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

### \$wsVoucher.totalValue

Gibt den Gesamtwert der eingesetzten Gutscheine aus.

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

### \$wsVoucher.totalUsedValue

Gibt den bereits vom Warenkorb abgezogenen Gutscheinwert aus.

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

### \$wsVoucher.maximumCount

Gibt die maximale Anzahl der Gutscheine zurück, die ein Kunde gleichzeitig einlösen darf.

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

***

## Methoden

### \$wsVoucher.load()

Lädt einen Gutschein anhand seiner ID.

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

**Rückgabe**\
`Map` - Voucher-Map mit den Gutschein-Daten.

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**   |
| -------- | ------- | ----------- | ------------------ |
| `id`     | string  | ja          | ID des Gutscheins. |

**Beispiel,** das einen Gutschein lädt:

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

<Info>
  Mit Verwendung der Funktion `$wsVoucher.load()` stehen verschiedene Variablen zur Verfügung, um Gutschein-Daten abzurufen und auszugeben. Nachfolgend eine Übersicht, welche Variablen verfügbar sind.
</Info>

### **Gutschein-Daten (Rückgabe von \$wsVoucher.load() )**

Zunächst ist es notwendig, die Map mit den Gutschein-Daten, wie im obigen Beispiel dargestellt, einer lokalen Variable zuzuweisen. Diese kann anschließend an verschiedenen Stellen im Template verwendet werden.

**JSON-Ausgabe**

```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": "..."
}
```

**Variablen in der Übersicht**

| **Variable**    | **Typ** | **Beschreibung**                                                                                                                                       |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`            | string  | Gutschein-ID.                                                                                                                                          |
| `value`         | float   | Wert des Gutscheins.                                                                                                                                   |
| `currency`      | string  | Währung des Gutscheins.                                                                                                                                |
| `taxId`         | string  | Steuersatz-ID des Gutscheins.                                                                                                                          |
| `usedValue`     | float   | Bereits eingelöster Wert des Gutscheins.                                                                                                               |
| `percentValue`  | float   | Bei prozentualen Gutscheinen ist `percentValue` gefüllt (z.B. 10 für 10%), bei Festbetrags-Gutscheinen ist `absoluteValue` gefüllt (z.B. 5.00 für 5€). |
| `absoluteValue` | float   | Bei prozentualen Gutscheinen ist `percentValue` gefüllt (z.B. 10 für 10%), bei Festbetrags-Gutscheinen ist `absoluteValue` gefüllt (z.B. 5.00 für 5€). |
| `validFrom`     | string  | Gültig ab (Datum).                                                                                                                                     |
| `validUntil`    | string  | Gültig bis (Datum).                                                                                                                                    |

***

## Aktionen

Aktionen zu diesem Modul, die Änderungen auslösen, sind separat im Kapitel “Aktionen” dokumentiert: [Voucher](/frontend/referenz/aktionen/voucher)

***

## Beispiel für Anzeige von Gutscheindaten

### Wert des Gutscheins

In diesem Beispiel wird der Wert des Gutscheins angezeigt.

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

### Gutschein-Typ: Prozentualer oder Festbetrag

In diesem Beispiel wird geprüft und angezeigt, ob der Gutschein einen prozentualen Rabatt oder einen festen Betrag gewährt.

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

### Gültigkeitsdatum des Gutscheins

In diesem Beispiel werden das Start- und Enddatum der Gültigkeit eines Gutscheins angezeigt.

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

### Währung des Gutscheins

In diesem Beispiel wird die Währung angezeigt, in der der Gutschein ausgestellt wurde.

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

### Restbetrag eines Gutscheins anzeigen

In diesem Beispiel wird angezeigt, wie viel Restbetrag ein teilgenutzter Gutschein noch hat.

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

### Gültigkeit eines Gutscheins prüfen

In diesem Beispiel wird überprüft, ob der Gutschein grundsätzlich gültig ist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $voucherAddAction.success }}
  Gutschein erfolgreich in den Warenkorb gelegt.
{{ /if }}
```

### Formular nur anzeigen, bis die maximale Anzahl an Gutscheinen eingelöst ist

Das Formular erscheint nur, wenn die Anzahl bereits eingelöster Gutscheine kleiner ist als das konfigurierte Limit. Ist das Limit erreicht, wird das Formular ausgeblendet und der Kunde erhält einen Hinweis.

```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">Einlösen</button>
    </form>
{{ /if }}
```

Weitere Praxisbeispiele zum Thema Gutscheine finden Sie [hier](/gutscheine).

***

## Weiterführende Links

* [Einstellungen für Gutscheine](https://dokumentation.websale.de/konfiguration/checkout-bestellablauf#checkout-voucher-einstellungen-für-gutscheine)
* [Praxisbeispiele für Gutscheine](/gutscheine)