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

# Produkte mittels Gutschein zusteuern

> Mit einem Gutschein bis zu drei Produkte automatisch in den Warenkorb legen, Produkte dafür kennzeichnen und die Variantenauswahl im Warenkorb anbieten.

Ein Gutschein muss nicht Geld abziehen, er kann auch etwas mitbringen. Gibt der Käufer auf der Warenkorbseite eine Gutscheinnummer ein und wird der Gutschein akzeptiert, legt der Shop bis zu drei vorher festgelegte Produkte automatisch in den Warenkorb.

Welche Produkte das sind, bestimmen Sie beim Anlegen des Gutscheins im Gutschein-Generator. Die Produkte selbst müssen dafür vorbereitet sein, und das ist der Teil, der im Shop Arbeit macht.

## Die Regeln für zusteuerbare Produkte

### Was das Produkt mitbringen muss

| Bedingung | Warum |
| - | - |
| Es ist über das Produktfeld `VoucherProduct` als zusteuerbar gekennzeichnet | Nur gekennzeichnete Produkte darf ein Gutschein in den Warenkorb legen |
| Es hat eine eindeutige Produktnummer | Der Gutschein speichert die Produktnummer, nicht den Produktindex. Der Shop sucht damit das Produkt und findet bei doppelten Nummern das falsche oder gar keines |
| Es steht in einer versteckten Kategorie | Sonst taucht es in der Suche und in Kategorielisten auf, obwohl es niemand kaufen kann |

Varianten werden unterstützt. Der Gutschein kann also auch ein Produkt zusteuern, bei dem der Käufer noch eine Größe oder Farbe wählt.

### Was nicht geht

Diese Produktarten lassen sich **nicht** zusteuern:

* Uploadprodukte
* Set-Produkte
* Produkte mit dynamischem Lagerbestand

> [!WARNING]
>
> Ein zusteuerbares Produkt kann nicht von der Produktansicht aus in den Warenkorb gelegt werden. Ohne eine passende Hinweismeldung klickt der Käufer dort ins Leere. Schritt 3 legt diese Meldung fest.

### Was der Käufer damit tun kann

| Aktion | Möglich |
| - | - |
| Variante ändern | ja, aus dem Warenkorb heraus |
| Menge ändern | nein, die Menge ist immer eins |
| Einzeln aus dem Warenkorb löschen | nein |
| Alle zugesteuerten Produkte entfernen | ja, durch Entfernen des Gutscheins |

Gibt der Käufer denselben Gutschein erneut ein, während dessen Produkte schon im Warenkorb liegen, steuert der Shop sie kein zweites Mal zu. Die Menge bleibt eins.

Zugesteuerte Produkte werden in den Bestelldaten als solche gekennzeichnet und sind damit im Warenwirtschaftssystem von regulär gekauften Positionen unterscheidbar.

## Voraussetzungen

**Der Gutschein-Generator muss freigeschaltet sein.** Wollen Sie ihn nutzen, wenden Sie sich 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`.

**Die Gutscheineingabe muss im Shop integriert sein.** Ohne sie kommt kein Gutschein in den Warenkorb und damit auch kein zugesteuertes Produkt.

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: Die Produkte kennzeichnen

Setzen Sie im WSPManager oder in Ihrem Warenwirtschaftssystem beim betreffenden Produkt das Feld `VoucherProduct`.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
VoucherProduct: y
```

> [!WARNING]
>
> Der Wert wird auf `y` geprüft. Jeder andere Wert und ein leeres Feld bedeuten "kein Gutscheinprodukt". Ein Tippfehler macht das Produkt zu einem gewöhnlichen Artikel, der dann offen im Shop kaufbar ist, und der Gutschein findet nichts zum Zusteuern.

## Schritt 2: Den Gutschein konfigurieren

Tragen Sie beim Anlegen des Gutscheins im Gutschein-Generator im Feld **Produkte für Warenkorb** die Produktnummern ein, höchstens drei.

Die Obergrenze von drei Produkten liegt im Shop fest und lässt sich nicht erhöhen. Werden mehr Nummern hinterlegt, verarbeitet der Shop die ersten drei.

## Schritt 3: Die Hinweismeldung festlegen

Versucht jemand, ein zusteuerbares Produkt direkt aus der Produktdetailansicht in den Warenkorb zu legen, lehnt der Shop das ab. Der Text dafür steht in der `shop.config`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<NotifyMessages-Txt>
   VoucherProduct = Dieses Produkt ist nur in Verbindung mit einem Gutschein verfügbar.
</NotifyMessages-Txt>
```

Referenz: [Abschnitt NotifyMessages-Txt](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/texte-und-meldungen.md#notifymessages-txt)

## Schritt 4: Das Mengenfeld in der Produktdetailansicht anpassen

Die Menge eines zugesteuerten Produkts ist immer eins. Auf der Produktdetailansicht gehört das Mengenfeld deshalb für diese Produkte als verstecktes Feld ins Formular, damit der Käufer gar nicht erst eine Menge eingibt, die der Shop anschließend verwirft.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-Product~" method="post">

   {PR-VoucherProduct}
      <input type="hidden" name="~PR-Quantity_Input~" value="1">
   {/PR-VoucherProduct}

   {!PR-VoucherProduct}
      <input type="text" name="~PR-Quantity_Input~" value="~PR-Quantity~">
   {/!PR-VoucherProduct}

</form>
```

Referenz: [PR-VoucherProduct](https://dokumentation.websale.de/v8s/referenz/tags/pr/grundlagen-und-produktdaten.md)

## Schritt 5: Gutscheinprodukte kennzeichnen (optional)

An zwei Stellen lohnt sich ein Hinweis, jeweils mit demselben Muster: ein Abschnitt, der nur bei Gutscheinprodukten greift.

| Template | Abschnitt | Sinnvoller Text |
| - | - | - |
| Produktdetailansicht `ws_product.htm` | `PR-VoucherProduct` | dass das Produkt nur mit Gutschein bestellbar ist |
| Warenkorbseite `ws_basket.htm` | `BASKET-PR-VoucherProduct` | dass die Position wegen des eingegebenen Gutscheins im Warenkorb liegt |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PR-VoucherProduct}
   Bitte beachten Sie: Dieses Produkt ist nur in Verbindung mit einem Gutschein verfügbar.
{/PR-VoucherProduct}
```

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@BASKET-PR-Data}
   {BASKET-PR-VoucherProduct}
      Dieses Produkt erhalten Sie aufgrund Ihres eingegebenen Gutscheins.
   {/BASKET-PR-VoucherProduct}
{/@BASKET-PR-Data}
```

Der Hinweis im Warenkorb ist mehr als Kosmetik. Weil die Position sich nicht einzeln löschen lässt, sucht der Käufer sonst nach dem fehlenden Löschsymbol. Der Satz erklärt ihm, woher die Position kommt.

Referenz: [BASKET-PR-VoucherProduct](https://dokumentation.websale.de/v8s/referenz/tags/basket/gutscheine-im-warenkorb.md#basket-pr-voucherproduct)

## Schritt 6: Nicht aufgelöste Gutscheinprodukte (optional)

Hat ein zugesteuertes Produkt Varianten, gibt es zwei Möglichkeiten. Entweder Sie legen die Variante im Gutschein fest, dann ist nichts weiter zu tun. Oder der Käufer soll sie selbst wählen. In diesem Fall landet das Produkt zunächst **nicht aufgelöst** im Warenkorb, und die Bestellung lässt sich erst abschließen, wenn die Wahl getroffen ist.

Dieser Abschnitt beschreibt den zweiten Fall und besteht aus drei Teilen: der Konfiguration, dem Hinweis im Warenkorb und der Auswahl selbst.

### 6.1 Die Funktion aktivieren

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

### 6.2 Den Hinweis im Warenkorb anzeigen

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@BASKET-PR-Data}
   {BASKET-PR-UnresolvedVoucherProduct}
      Bitte wählen Sie die gewünschte Variante Ihres Gutscheinproduktes aus,
      um die Bestellung abschließen zu können.
   {/BASKET-PR-UnresolvedVoucherProduct}
{/@BASKET-PR-Data}
```

> [!WARNING]
>
> Dieser Hinweis ist nicht optional, wenn Sie die Funktion einschalten. Solange ein nicht aufgelöstes Gutscheinprodukt im Warenkorb liegt, blockiert der Shop den Bestellabschluss. Ohne den Hinweis steht der Käufer vor einem Bestellbutton, der nichts tut, und kennt den Grund nicht.

Referenz: [BASKET-PR-UnresolvedVoucherProduct](https://dokumentation.websale.de/v8s/referenz/tags/basket/gutscheine-im-warenkorb.md#basket-pr-unresolvedvoucherproduct)

### 6.3 Die Variantenauswahl im Warenkorb anbieten

Die Auswahl selbst läuft über AJAX und ein eigenes Template. Das folgende Beispiel verwendet FastInclude.

#### Ergänzung in der FastInclude-Datei

Fügen Sie im Abschnitt `Incl-Basket` der Datei `incl_fast_includes.htm` den folgenden Block ein.

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

         {BASKET-PR-UnresolvedVoucherProduct}
            ~DC-FPshowVariationBtn_set(true)~
         {/BASKET-PR-UnresolvedVoucherProduct}

         {BASKET-PR-VoucherProduct}
            {BASKET-PR-Variations}
               ~DC-FPshowVariationBtn_set(true)~
            {/BASKET-PR-Variations}
         {/BASKET-PR-VoucherProduct}

         {VOUCHER-VoucherProducts_data}
            {@VOUCHER-VoucherProducts_data}
               ~DC-SPvoucherProductIndex_set($VOUCHER-VoucherProducts_data_prodnumber$)~
            {/@VOUCHER-VoucherProducts_data}
         {/VOUCHER-VoucherProducts_data}

         {DC-FPshowVariationBtn(true)}
            <button type="button" id="wsVoucherProductVariationBtn"
                    onclick="ws_AJAXloadTemplate('~BASKET-PR-ChangeLink~'+'&tpl=incl_voucher_product_change.htm&otp1=~BASKET-PR-ProdIndex~', '~WS-CharSet~', ws_AJAXVoucherProductChangeQuantityStart, ws_AJAXVoucherProductChangeQuantityError, 'ws_AJAXVoucherProductChangeQuantityResponseSuccess()', 'ws_AJAXVoucherProductChangeQuantityResponseError()');"
                    {BASKET-PR-UnresolvedVoucherProduct} style="display:none"{/BASKET-PR-UnresolvedVoucherProduct}>Gutscheinprodukt wählen</button>

            <script>
               function ws_AJAXVoucherProductChangeQuantityStart() {}
               function ws_AJAXVoucherProductChangeQuantityError() {}
               function ws_AJAXVoucherProductChangeQuantityResponseSuccess() {}
               function ws_AJAXVoucherProductChangeQuantityResponseError() {}

               $(document).on("change", '.select_dep_variations', function() {
                  $("#voucherProductForm_~BASKET-PR-ProdIndex~ input[name='js_dep_var']").val("on");
               });
            </script>
         {/DC-FPshowVariationBtn(true)}
      {/ST-BasketPage}
   {/@BASKET-PR-Data}
{/BASKET-PR-Data}
```

Der Schalter `DC-FPshowVariationBtn` wird je Warenkorbposition zurückgesetzt und nur dann gesetzt, wenn die Position entweder ein nicht aufgelöstes Gutscheinprodukt ist oder ein Gutscheinprodukt mit Varianten. Dadurch erscheint der Button nur dort, wo es etwas zu wählen gibt.

#### Der Container für die Anzeige

Der Container gehört **außerhalb** von `FORM-Basket`, weil das eingeblendete Template ein eigenes Formular mitbringt und verschachtelte Formulare im Browser nicht funktionieren.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{Incl-Basket}
   {ST-BasketPage}
      <div id="voucherProduct">
         <div id="voucherProductChangeAjax_~DC-SPvoucherProductIndex~"></div>
      </div>
   {/ST-BasketPage}
{/Incl-Basket}
```

#### Das Template `incl_voucher_product_change.htm`

Legen Sie ein neues Template unter diesem Namen in Ihrem Templateverzeichnis an, also beispielsweise unter `benutzer/templates`, in einem mehrsprachigen Shop im Verzeichnis des jeweiligen Subshops.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<WS-Ajax-voucherProductChangeAjax_~WS-OTP1~>
   {PR-Data}
      <form action="~FORM-Product~" method="post" id="voucherProductForm_~PR-Number~">

         {PR-Thumbnail}
            <img src="~PR-Thumbnail~" width="150" height="150" alt="~PR-Name~">
         {/PR-Thumbnail}

         {PR-DepVariationName1}
            ~PR-DepVariationName1~
            ~PR-DepVariationList1~
         {/PR-DepVariationName1}

         {PR-DepVariationName2}
            ~PR-DepVariationName2~
            ~PR-DepVariationList2~
         {/PR-DepVariationName2}

         {ST-PR_Change}
            ~PR-PrintHiddenDepVariations~
            <input type="hidden" name="tpl" value="incl_voucher_product_change.htm">
            <input type="hidden" name="otp1" value="~WS-OTP1~">
            <input type="hidden" name="otp2" value="~PR-Number~">
            <input type="hidden" name="~PR-Quantity_Input~" value="~PR-Quantity~">
         {/ST-PR_Change}

         <button type="submit"
                 {!ST-DepVar_OK} disabled{/!ST-DepVar_OK}{ST-DepVar_OK}{PR-Inventory}{PR-InventoryState(red-hard)} disabled{/PR-InventoryState(red-hard)}{/PR-Inventory}{/ST-DepVar_OK}>Speichern</button>

      </form>
   {/PR-Data}
</WS-Ajax-voucherProductChangeAjax_~WS-OTP1~>
```

Der Speichern-Button ist gesperrt, solange keine gültige Variantenkombination gewählt ist oder die gewählte Kombination nicht lieferbar ist. So kann der Käufer keine Auswahl absenden, die der Shop anschließend ablehnen müsste.

> [!WARNING]
>
> Der Name des Ajax-Bereichs, die Container-Kennung und der Parameter `otp1` müssen zusammenpassen. Weichen sie voneinander ab, lädt das Template, die Antwort landet aber in keinem Container und für den Käufer passiert sichtbar nichts.

Referenz: [VOUCHER-VoucherProducts\_data](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md#zugesteuerte-produkte) · [BASKET-PR-ChangeLink](https://dokumentation.websale.de/v8s/referenz/tags/basket/besondere-produktarten-im-warenkorb.md) · [DC-](https://dokumentation.websale.de/v8s/referenz/tags/dc/parameter.md) · WS-OTP1

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


## Related topics

- [Gutscheine anbieten: Übersicht](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anbieten-uebersicht.md)
- [Mehrere Gutscheine einlösen](https://dokumentation.websale.de/v8s/gutscheine-anbieten/mehrere-gutscheine-einloesen.md)
- [VOUCHER- (Gutschein)](https://dokumentation.websale.de/v8s/referenz/tags/voucher-gutschein.md)
- [Spezielle Themen](https://dokumentation.websale.de/v8s/schnittstellen/produkte-und-kategorien/ws-sftp-produkte-pro/spezielle-themen.md)
- [API Basics](https://dokumentation.websale.de/schnittstellen/admin-interface-api/api-basics.md)


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