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

# Gutscheine abhängig von Produktdaten

> Einen Gutschein nur für Produkte gelten lassen, die in einem bestimmten Produktdatenfeld einen festgelegten Wert tragen, auch in freien Feldern.

Ein Gutschein lässt sich auf Produkte einschränken, ohne jede einzelne Produktnummer aufzuzählen. Stattdessen prüft der Shop ein Produktdatenfeld: Trägt das Produkt dort einen der festgelegten Werte, gilt der Gutschein dafür. Auch freie Produktdatenfelder sind dabei verwendbar.

Damit lassen sich Aktionen an Eigenschaften knüpfen, die ohnehin gepflegt werden, beispielsweise an eine Marke, eine Saison oder ein Nachhaltigkeitskennzeichen.

## Wie die Prüfung wirkt

Der Shop geht den Warenkorb durch und prüft jede Position gegen die hinterlegten Filter. **Eine passende Position genügt**, damit der Gutschein angenommen wird. Passt keine einzige, lehnt der Shop ihn ab.

Mehrere Filter sind oder-verknüpft. Ein Gutschein mit zwei Filtern gilt also, sobald eine Warenkorbposition einen der beiden erfüllt. Ein Und wäre nur über ein einzelnes Feld mit entsprechend vorbereiteten Werten abbildbar.

## Voraussetzung

Der Gutschein-Generator muss freigeschaltet sein. Wenden Sie sich dafür an Ihren WEBSALE-Ansprechpartner.

Kommen die Gutscheine aus einem externen System und liegen deshalb nicht im WEBSALE-Format vor, ergänzen Sie im Abschnitt `<Voucher-Txt>` der `shop.config` den Eintrag `ExternalVouchers-Allow = yes`.

Wegweiser: [Gutschein-Eingabe vorsehen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutschein-eingabe-vorsehen.md) · Referenz: [Abschnitt Voucher-Txt](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.md#voucher-txt)

## Schritt 1: Das Produktdatenfeld in den Warenkorb übergeben

Der Shop prüft nur Felder, die er im Warenkorb überhaupt vorliegen hat. Tragen Sie das gewünschte Feld deshalb in der `shop.config` ein.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<AdditionalProductFieldsInBasket>
   +Field =    # technischer Name des Produktdatenfeldes
</AdditionalProductFieldsInBasket>
```

> [!WARNING]
>
> Ohne diesen Eintrag kennt der Warenkorb das Feld nicht, und der Filter findet nie einen Treffer. Der Gutschein wird dann bei jedem Warenkorb abgelehnt, ohne dass die Gutscheinkonfiguration falsch wäre. Das ist der wahrscheinlichste Grund, wenn ein solcher Gutschein "einfach nicht funktioniert".

Referenz: [Abschnitt AdditionalProductFieldsInBasket](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/warenkorb-und-bestellprozess.md#additionalproductfieldsinbasket)

## Schritt 2: Den Filter im Gutschein anlegen

Beim Anlegen des Gutscheins im Gutschein-Generator tragen Sie im Feld **Kundenspezifische Features** ganz unten eine Zeichenkette nach dem folgenden Schema ein.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<g><t>AdditionalProductFieldsFilter</t><setbehavior>asUnit</setbehavior><filter><fieldname>Feldname</fieldname><valueInList>a,b,c</valueInList></filter></g>
```

| Klammer | Bedeutung |
| - | - |
| `<g>…</g>` | umschließt die gesamte Funktion |
| `<t>…</t>` | der Typ, hier `AdditionalProductFieldsFilter` |
| `<setbehavior>…</setbehavior>` | Verhalten bei Setprodukten, optional |
| `<filter>…</filter>` | eine Bedingung. Mehrfach verwendbar |
| `<fieldname>…</fieldname>` | der technische Name des Produktdatenfeldes |
| `<valueInList>…</valueInList>` | kommagetrennte Liste der zulässigen Werte, ohne Leerzeichen |

### Das Verhalten bei Setprodukten

| Wert | Wirkung |
| - | - |
| `asUnit` | Set-Unterprodukte werden als Einheit betrachtet, geprüft wird das Set-Oberprodukt. Der Gutschein gilt für das ganze Set oder für keinen seiner Teile. Voreinstellung |
| `single` | Set-Unterprodukte werden einzeln geprüft. Der Gutschein gilt dann je nach Produktdaten für alle, einige oder keine Teile des Sets |

Ausgewertet wird ausschließlich der Wert `single`. Jeder andere Wert und ein leerer Eintrag bedeuten `asUnit`. Ein Tippfehler in `single` führt damit stillschweigend zum Verhalten als Einheit.

Die Gesamtlänge der Zeichenkette ist auf 1000 Zeichen begrenzt. Mehrere `<filter>`-Klammern lassen sich hintereinander in derselben `<g>`-Gruppe angeben und sind oder-verknüpft.

### Die umgekehrte Variante

Neben dem beschriebenen Filter kennt der Shop denselben Aufbau auch als Ausschluss. Dafür tragen Sie als Typ `AdditionalProductFieldsFilterNegative` ein, alles andere bleibt gleich.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<g><t>AdditionalProductFieldsFilterNegative</t><setbehavior>asUnit</setbehavior><filter><fieldname>Feldname</fieldname><valueInList>a,b,c</valueInList></filter></g>
```

> [!WARNING]
>
> Für die umgekehrte Variante gibt es eine eigene Tag-Familie mit dem Zusatz `Negative`, sonst aber keine eigene Dokumentation. Prüfen Sie ihr Verhalten in einem Testshop, bevor Sie sie in einer Aktion einsetzen.

## Schritt 3: Die Konfiguration im Template ausgeben

Zur Kontrolle lässt sich anzeigen, welche Prüfungen an einem eingegebenen Gutschein hängen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{VOUCHER-SpecialFeatures_AddProdFieldsFilter}
   Dieser Gutschein ist an Produktdaten geknüpft.
   Konfigurierte Prüfungen: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter~

   Verhalten bei Setprodukten:
   {VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(0)}Set als Einheit{/VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(0)}
   {VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(1)}Set-Unterprodukte einzeln{/VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(1)}

   {@VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter}
      Feldname: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_FieldName~<br>
      Zulässige Werte: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_ValueInList~<br>
   {/@VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter}

{/VOUCHER-SpecialFeatures_AddProdFieldsFilter}

{!VOUCHER-SpecialFeatures_AddProdFieldsFilter}
   Dieser Gutschein ist nicht an Produktdaten geknüpft.
{/!VOUCHER-SpecialFeatures_AddProdFieldsFilter}
```

> [!WARNING]
>
> `VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior` gibt als Einzeltag eine **Zahl** aus, `0` für `asUnit` und `1` für `single`, nicht den Text. Wer das Tag direkt hinter eine Beschriftung setzt, bekommt "Verhalten bei Setprodukten: 0" auf die Seite. Im Beispiel oben übersetzt die Abfrage mit Parameter die Zahl in Klartext.

Das Setverhalten gilt für die ganze Gruppe, nicht je Filter. Es gehört deshalb vor die Schleife und nicht hinein.

`VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_ValueInList` gibt die Werteliste mit führendem und abschließendem Komma aus, also `,a,b,c,`. So liegt sie intern vor, damit der Shop sauber auf ganze Werte prüfen kann. Für eine Anzeige entfernen Sie die äußeren Kommas.

Dasselbe Tagmuster gibt es für die umgekehrte Variante mit `AddProdFieldsFilterNegative` statt `AddProdFieldsFilter`.

Referenz: [VOUCHER-SpecialFeatures\_AddProdFieldsFilter](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#abhangigkeit-von-freien-produktdatenfeldern) · [VOUCHER-SpecialFeatures\_AddProdFieldsFilter\_SetBehavior](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#abhangigkeit-von-freien-produktdatenfeldern) · [VOUCHER-SpecialFeatures\_AddProdFieldsFilter\_Filter](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#abhangigkeit-von-freien-produktdatenfeldern) · [VOUCHER-SpecialFeatures\_AddProdFieldsFilter\_Filter\_FieldName](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#abhangigkeit-von-freien-produktdatenfeldern) · [VOUCHER-SpecialFeatures\_AddProdFieldsFilter\_Filter\_ValueInList](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#abhangigkeit-von-freien-produktdatenfeldern)

## Schritt 4: Die Fehlermeldung ergänzen

Passt keine Warenkorbposition zum Filter, lehnt der Shop den Gutschein mit dem Grund **21** ab. Ergänzen Sie diesen Grund dort, wo Sie die Gutscheineingabe eingebaut haben, also auf der Warenkorbseite `ws_basket.htm` oder der Bestellübersichtsseite `ws_place_order.htm`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{MSG-Voucher_error(21)}
   Dieser Gutschein gilt nicht für die Produkte in Ihrem Warenkorb.<br>
   Bitte entfernen Sie den Gutschein oder legen Sie ein passendes Produkt in den Warenkorb.
{/MSG-Voucher_error(21)}
```

> [!WARNING]
>
> Ohne diesen Text sieht der Kunde eine leere Meldung und weiß nicht, warum sein Code abgelehnt wurde. Gerade bei produktabhängigen Gutscheinen ist das die häufigste Ablehnung überhaupt.

Referenz: [MSG-Voucher\_error](https://dokumentation.websale.de/v8s/referenz/tags/msg-meldungen.md#gutscheine)

## Verwandte Themen

* Wegweiser: [Gutscheine anbieten: Übersicht](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anbieten-uebersicht.md)
* Wegweiser: [Gutscheine anlegen oder importieren](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anlegen-oder-importieren.md)
* Wegweiser: [Gutschein-Eingabe vorsehen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutschein-eingabe-vorsehen.md)
* Wegweiser: [Gutscheine abhängig vom Lagerbestand](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-abhaengig-vom-lagerbestand.md)


## Related topics

- [Gutscheine abhängig vom Lagerbestand](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-abhaengig-vom-lagerbestand.md)
- [Gutscheine anbieten: Übersicht](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anbieten-uebersicht.md)
- [Erweiterte Einstellungen beim Anlegen von Versandarten](https://dokumentation.websale.de/v8s/versandarten-anlegen/erweiterte-einstellungen.md)
- [Alternative Produktdaten](https://dokumentation.websale.de/v8s/produkte/alternative-produktdaten.md)
- [Abhängige Varianten als Tabelle darstellen](https://dokumentation.websale.de/v8s/abhaengige-varianten/abhaengige-varianten-als-tabelle-darstellen.md)


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