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

# META-Gutscheine

> Mehrere Gutscheincodes hinter einem Sammel-Code bündeln, die Zuordnung in einer JSON-Datei pflegen und das Verhalten bei fehlerhaften Sub-Gutscheinen festlegen.

Ein META-Gutschein ist ein Sammel-Code. Der Kunde gibt eine einzige Nummer ein, und der Shop löst im Hintergrund mehrere hinterlegte Gutscheine auf einmal ein. Das ist nützlich, wenn eine Aktion aus mehreren Bausteinen besteht, beispielsweise zehn Prozent Rabatt zusammen mit freiem Versand, der Kunde aber nur einen Code merken soll.

Die Zuordnung steht nicht im Gutschein-Generator, sondern in einer Datei, die Sie selbst pflegen.

Diese Funktion muss nicht freigeschaltet werden.

## Wie das Einlösen abläuft

| Schritt | Was geschieht |
| - | - |
| Der Kunde gibt den META-Code ein | Der Shop sucht ihn in der Datei `meta_vouchers.json` |
| Code gefunden | Der Shop löst die hinterlegten Sub-Gutscheine der Reihe nach ein |
| Ein Sub-Code liegt bereits im Warenkorb | Er wird übersprungen, ohne Fehlermeldung |
| Ein Sub-Gutschein ist ungültig | Das weitere Vorgehen entscheidet `MetaVoucherErrorMode` |

> [!WARNING]
>
> Es kann immer nur **ein** META-Gutschein gleichzeitig eingelöst sein. Solange ein Gutschein aus einem META-Code im Warenkorb liegt, wird ein zweiter META-Code nicht erkannt und wie eine unbekannte Nummer behandelt.

Die Sub-Gutscheine belegen dieselben Plätze wie mehrfach eingelöste Gutscheine. Daraus ergibt sich die Obergrenze von neun Sub-Gutscheinen je META-Code.

Wegweiser: [Mehrere Gutscheine einlösen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/mehrere-gutscheine-einloesen.md)

## Die Datei `meta_vouchers.json`

Legen Sie die Datei von Hand im Konfigurationsverzeichnis des Shops an, also in dem Verzeichnis, das für alle Subshops gilt. Sie enthält je META-Code einen Eintrag.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "SOMMER2026": {
      "vouchers": ["RABATT10", "VERSANDFREI"],
      "showAsBlock": true
   },
   "WILLKOMMEN": {
      "vouchers": ["NEUKUNDE5", "GRATISPROBE", "VERSANDFREI"]
   }
}
```

| Feld | Bedeutung |
| - | - |
| Schlüssel | der Code, den der Kunde eingibt |
| `vouchers` | Liste der Sub-Gutscheincodes, die eingelöst werden sollen |
| `showAsBlock` | optional, steuert für diesen META-Code die Blockbehandlung. Ohne Angabe gilt die Einstellung aus der `shop.config` |

Der META-Code wird ohne Rücksicht auf Groß- und Kleinschreibung gesucht. Ein Kunde, der `sommer2026` eingibt, trifft also den Eintrag `SOMMER2026`.

> [!WARNING]
>
> Mehr als neun Einträge in `vouchers` sind wirkungslos. Der Shop verarbeitet die ersten neun und lässt den Rest stillschweigend liegen.
>
> `showAsBlock` muss ein echter JSON-Wahrheitswert sein, also `true` oder `false` ohne Anführungszeichen. Die Schreibweise `"true"` wird ignoriert, und es gilt die Voreinstellung aus der Konfiguration.
>
> Fehlt die Datei, wird der eingegebene Code einfach als unbekannt behandelt. Ist sie vorhanden, aber fehlerhaft aufgebaut, protokolliert der Shop einen Fehler, verhält sich nach außen aber genauso. Ein META-Code, der nicht erkannt wird, ist deshalb zuerst ein Anlass, die Datei zu prüfen.

## Die Einstellungen in der Shopkonfiguration

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

### `MetaVoucherErrorMode`

| Wert | Verhalten bei einem ungültigen Sub-Gutschein |
| - | - |
| `reject-all` | Der gesamte META-Gutschein wird abgelehnt, auch bereits eingelöste Sub-Gutscheine werden wieder entfernt. Voreinstellung |
| `accept-valid` | Der ungültige Sub-Gutschein wird übersprungen, die übrigen bleiben eingelöst |

`reject-all` ist die Voreinstellung und jeder nicht erkannte Wert führt ebenfalls dorthin. Sie ist die ehrlichere Variante: Der Kunde bekommt entweder das ganze Paket oder gar nichts und wundert sich nicht über einen Teilrabatt.

Bei `accept-valid` unterdrückt der Shop die Fehlermeldung nur, wenn zuvor schon mindestens ein Sub-Gutschein erfolgreich eingelöst wurde. Scheitert gleich der erste, sieht der Kunde dessen Fehlermeldung, auch wenn die folgenden Sub-Gutscheine greifen.

### `MetaVoucherShowAsBlock`

| Wert | Verhalten |
| - | - |
| `yes` | Die Sub-Gutscheine werden als Block behandelt. Ein Klick auf Löschen entfernt alle auf einmal. Voreinstellung |
| `no` | Jeder Sub-Gutschein lässt sich einzeln löschen |

Bei `no` zählt der Shop beim Löschen mit. Ist der letzte Sub-Gutschein entfernt, setzt er auch die META-Daten zurück, und der Kunde kann einen anderen META-Code eingeben.

Die Einstellung in der Datei sticht die Einstellung in der Konfiguration. So lässt sich eine einzelne Aktion abweichend behandeln, ohne die Voreinstellung für alle anderen zu ändern.

Referenz: [Abschnitt Voucher-Txt](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.md#voucher-txt)

## Die Templates ergänzen (optional)

Vier Tags machen im Template sichtbar, dass ein Gutschein aus einem META-Code stammt.

| Tag | Inhalt |
| - | - |
| `VOUCHER-IsFromMeta` | Abschnitt, der nur bei einem Gutschein aus einem META-Code greift |
| `VOUCHER-MetaCode` | der eingegebene META-Code |
| `VOUCHER-MetaSubCount` | Anzahl der erfolgreich eingelösten Sub-Gutscheine |
| `VOUCHER-MetaShowAsBlock` | Abschnitt, der greift, wenn die Blockbehandlung aktiv ist |

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

   Gutscheinnummer: ~VOUCHER-Number~

   {VOUCHER-IsFromMeta}
      Teil der Aktion ~VOUCHER-MetaCode~
      {VOUCHER-MetaSubCount}
         mit insgesamt ~VOUCHER-MetaSubCount~ Gutscheinen
      {/VOUCHER-MetaSubCount}

      {VOUCHER-MetaShowAsBlock}
         Diese Gutscheine gehören zusammen. Wenn Sie einen davon entfernen,
         werden alle entfernt.
      {/VOUCHER-MetaShowAsBlock}
   {/VOUCHER-IsFromMeta}

   <input type="submit" name="~BT-Voucher_delete~" value="Gutschein entfernen">

{/VOUCHER-Number}
```

> [!WARNING]
>
> Der Hinweis zur Blockbehandlung ist kein Beiwerk. Ohne ihn klickt der Kunde auf Löschen, um einen einzelnen Gutschein loszuwerden, und verliert die ganze Aktion. Wenn Sie `MetaVoucherShowAsBlock` auf `yes` lassen, schreiben Sie das dazu.

Die Tags stehen auch innerhalb der Schleife über die zusätzlichen Gutscheine zur Verfügung. Bei mehreren eingelösten Gutscheinen brauchen Sie den Block deshalb an beiden Stellen, außerhalb der Schleife für den ersten Gutschein und innerhalb für die weiteren.

Referenz: [VOUCHER-MetaCode](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#meta-gutscheine) · [VOUCHER-MetaSubCount](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#meta-gutscheine) · [VOUCHER-IsFromMeta](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#meta-gutscheine) · [VOUCHER-MetaShowAsBlock](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#meta-gutscheine) · [VOUCHER-MultiVoucher](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md)

## Verwandte Themen

* Wegweiser: [Gutscheine anbieten: Übersicht](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anbieten-uebersicht.md)
* Wegweiser: [Gutschein-Eingabe vorsehen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutschein-eingabe-vorsehen.md)
* Wegweiser: [Mehrere Gutscheine einlösen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/mehrere-gutscheine-einloesen.md)


## Related topics

- [Preise, Steuern und Währung](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.md)
- [VOUCHER- (Gutschein)](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md)
- [Meta-Felder](https://dokumentation.websale.de/v8s/schnittstellen/produkte-und-kategorien/ws-sftp-produkte-pro/meta-felder.md)
- [Gutscheine](https://dokumentation.websale.de/admin-interface/marketing/gutscheine.md)
- [Newsletter-Gutscheine](https://dokumentation.websale.de/v8s/gutscheine-anbieten/newsletter-gutscheine.md)


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