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

# SUBS- (Abo abschließen)

> Ein Produkt als Abo bestellen: die Zyklusauswahl aufbauen, prüfen ob es bereits abonniert ist, und Zahlungsart, Bankverbindung und Lieferadresse für das Abo festlegen.

Ein Abo entsteht auf der Produktseite. Der Käufer wählt dort nicht nur die Menge, sondern zusätzlich ein Lieferintervall, und je nach Einstellung auch die Zahlungsart, eine Bankverbindung und eine Lieferadresse, die dauerhaft für dieses Abo gelten.

Diese Seite beschreibt die Tags für genau diesen Schritt. Die Verwaltung bereits bestehender Abos steht auf einer eigenen Seite.

* Wegweiser: [Abo-Modul](https://dokumentation.websale.de/v8s/marketing-funktionen/abo-modul.md)
* Referenz: [SUBS- (Abos verwalten)](https://dokumentation.websale.de/v8s/referenz/tags/subs/abos-verwalten.md)

Die Abo-Funktion wird im Abschnitt `Subscription` der Shopkonfiguration freigeschaltet. Dort stehen auch die wählbaren Lieferintervalle und die zulässigen Zahlungsarten.

## Darf dieses Produkt abonniert werden

`SUBS-CycleSelection` ist die Klammerung um den gesamten Abo-Bereich. Sie greift, wenn das Produkt abonnierbar ist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-CycleSelection}
   <fieldset>
      <legend>Als Abo bestellen</legend>
      ...
   </fieldset>
{/SUBS-CycleSelection}
```

Setzen Sie den gesamten Abo-Teil des Produkttemplates in diese Klammerung. Ohne sie erscheinen die Eingabefelder auch bei Produkten, die gar nicht abonniert werden können.

## Die Zyklusauswahl

Die wählbaren Lieferintervalle sind im Shop konfiguriert, nicht am Produkt. `SUBS-CycleSelection_data` läuft als Schleife über sie und liefert als Einzel-Tag ihre Anzahl.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<select name="~SUBS-CycleSelection_input~">
   {@SUBS-CycleSelection_data}
      <option value="~SUBS-CycleSelection_data_value~" ~SUBS-CycleSelection_data_selected~>~SUBS-CycleSelection_data_descr~</option>
   {/@SUBS-CycleSelection_data}
</select>
```

| Tag | Liefert |
| - | - |
| `SUBS-CycleSelection_input` | den HTML-Namen des Auswahlfelds |
| `SUBS-CycleSelection_data` | die Schleife über die Intervalle, als Einzel-Tag deren Anzahl |
| `SUBS-CycleSelection_data_value` | den Wert des Eintrags für das `value`-Attribut |
| `SUBS-CycleSelection_data_descr` | die Beschriftung des Eintrags |
| `SUBS-CycleSelection_data_selected` | das Wort `selected`, wenn dieser Eintrag der gewählte ist |
| `SUBS-CycleSelection_data_count` | die Anzahl der Einheiten, beispielsweise die 3 in "alle 3 Monate" |
| `SUBS-CycleSelection_data_unit_code` | den technischen Code der Einheit |

> [!WARNING]
>
> `SUBS-CycleSelection_data_value` liefert nicht die Anzahl, sondern die Kombination aus Einheit und Anzahl in der Form `Einheit-Anzahl`. Ein Intervall von drei Monaten ergibt also `1-3`. Dieser Wert gehört unverändert in das `value`-Attribut, denn das Shopsystem erkennt die Auswahl daran wieder.

Die Beschriftung aus `SUBS-CycleSelection_data_descr` stammt aus dem Parameter `Description` des jeweiligen Intervalls in der Shopkonfiguration. Ist dort nichts hinterlegt, gibt das Tag nichts aus und greift auch als Klammerung nicht. Bauen Sie die Beschriftung in diesem Fall aus `_data_count` und den Einheiten-Klammerungen selbst zusammen.

`SUBS-CycleSelection_data_selected` gibt als Einzel-Tag ein führendes Leerzeichen gefolgt von `selected` aus. Sie können es deshalb direkt hinter das letzte Attribut schreiben, ohne selbst ein Trennzeichen zu setzen.

### Die Einheit des Intervalls

Vier Klammerungen beantworten, um welche Einheit es geht. Der technische Code dahinter steht in `SUBS-CycleSelection_data_unit_code`.

| Tag | Greift bei | Code |
| - | - | - |
| `SUBS-CycleSelection_data_unit_isday` | Tag | 0 |
| `SUBS-CycleSelection_data_unit_ismonth` | Monat | 1 |
| `SUBS-CycleSelection_data_unit_isyear` | Jahr | 2 |
| `SUBS-CycleSelection_data_unit_isweek` | Woche | 3 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-CycleSelection_data}
   <option value="~SUBS-CycleSelection_data_value~" ~SUBS-CycleSelection_data_selected~>
      alle ~SUBS-CycleSelection_data_count~
      {SUBS-CycleSelection_data_unit_isday}Tage{/SUBS-CycleSelection_data_unit_isday}
      {SUBS-CycleSelection_data_unit_isweek}Wochen{/SUBS-CycleSelection_data_unit_isweek}
      {SUBS-CycleSelection_data_unit_ismonth}Monate{/SUBS-CycleSelection_data_unit_ismonth}
      {SUBS-CycleSelection_data_unit_isyear}Jahre{/SUBS-CycleSelection_data_unit_isyear}
   </option>
{/@SUBS-CycleSelection_data}
```

> [!WARNING]
>
> Die Reihenfolge der Codes folgt nicht der Länge der Zeiträume. Die Woche hat den Code 3 und steht damit hinter dem Jahr. Werten Sie `_unit_code` deshalb nie mit einem Größenvergleich aus, sondern nehmen Sie die vier Klammerungen.

Die vier Einheiten-Tags sind laut Tag-Maske auch als Einzel-Tag zulässig. Sie geben dort jedoch nichts aus. Verwenden Sie sie ausschließlich als Klammerung.

### Einen Eintrag gezielt ansprechen

Alle `_data_`-Tags nehmen wahlweise einen Parameter entgegen, nämlich die laufende Nummer des Intervalls. Damit greifen Sie außerhalb der Schleife auf einen bestimmten Eintrag zu.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Standardintervall: ~SUBS-CycleSelection_data_descr(1)~
```

`SUBS-CycleSelection_data_selected` ohne Parameter und außerhalb der Schleife hat eine eigene Bedeutung. Dort greift es als Klammerung, wenn der Käufer überhaupt schon ein Intervall gewählt hat. Das eignet sich für den Hinweis, dass die Auswahl noch aussteht.

> [!WARNING]
>
> Eine Nummer außerhalb des konfigurierten Bereichs macht das Tag ungültig. Das gilt auch innerhalb der Schleife, wenn Sie dort zusätzlich einen Parameter setzen.

## Ist das Produkt schon im Abo

Bevor Sie den Abo-Bereich anbieten, lohnt der Blick in die bestehenden Abos des Käufers. Zwei Klammerungen beantworten das, die eine über den Produktindex, die andere über die Produktnummer.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-ProdNumberOnSubscription(~PR-Number~)}
   <p>Dieses Produkt haben Sie bereits abonniert.</p>
{/SUBS-ProdNumberOnSubscription(~PR-Number~)}

{!SUBS-ProdNumberOnSubscription(~PR-Number~)}
   {SUBS-CycleSelection}
      ...
   {/SUBS-CycleSelection}
{/!SUBS-ProdNumberOnSubscription(~PR-Number~)}
```

> [!WARNING]
>
> Beide Tags brauchen ihren Parameter. Ohne Parameter greifen sie nie, auch die negative Klammerung nicht. Ein Fehler wird dabei nicht gemeldet, der Bereich bleibt einfach stumm.

Die Suche läuft über alle Abos des angemeldeten Käufers, unabhängig von deren Zustand. Ein pausiertes Abo gilt also ebenfalls als vorhanden.

## Die Zahlungsart für das Abo

Ein Abo wird immer wieder abgerechnet und verträgt deshalb nicht jede Zahlungsart. Welche zulässig sind, steht im Parameter `AllowedPayments` im Abschnitt `Subscription` der Shopkonfiguration.

| Tag | Liefert |
| - | - |
| `SUBS-AllowedPayments` | die Schleife über die zulässigen Zahlungsarten, im Durchlauf den Zahlungsartencode |
| `SUBS-PaymentMethod_input` | den HTML-Namen des Auswahlfelds |
| `SUBS-PaymentMethod_selected()` | Klammerung: dieser Zahlungsartencode ist gewählt |
| `SUBS-FixedPaymentCodeUsed()` | die fest eingestellte Zahlungsart, mit Parameter ein Vergleich darauf |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-AllowedPayments}
   <select name="~SUBS-PaymentMethod_input~">
      {@SUBS-AllowedPayments}
         <option value="~SUBS-AllowedPayments~"
                 {SUBS-PaymentMethod_selected($SUBS-AllowedPayments$)}selected{/SUBS-PaymentMethod_selected($SUBS-AllowedPayments$)}>
            {PAY-IsDebit(~SUBS-AllowedPayments~)}Lastschrift{/PAY-IsDebit(~SUBS-AllowedPayments~)}
            ...
         </option>
      {/@SUBS-AllowedPayments}
   </select>
{/SUBS-AllowedPayments}
```

Ohne sie lässt sich eine Auswahl der Zahlungsart nicht aufbauen.

Als Zahlungsart lässt das Shopsystem im Abo ausschließlich Lastschrift, Rechnung, PayPal Checkout und PayPal Checkout auf Rechnung zu. Ein anderer Code in `AllowedPayments` wird beim Einlesen der Konfiguration verworfen und protokolliert.

> [!WARNING]
>
> `SUBS-PaymentMethod_selected()` vergleicht den Parameter mit der zuletzt abgeschickten Auswahl, nicht mit einer am Abo gespeicherten Zahlungsart. Beim ersten Aufruf der Produktseite ist noch nichts gewählt, und das Tag greift ohne Parameter als Klammerung dann, wenn überhaupt eine Auswahl vorliegt.

Der Parameter `UsePaymentCode` ist der Vorläufer von `AllowedPayments` und sollte nicht mehr verwendet werden. Ist er gesetzt und `AllowedPayments` nicht, wird daraus eine Liste mit genau einem Eintrag. `SUBS-FixedPaymentCodeUsed` gibt diesen Code als Einzel-Tag aus und greift als Klammerung, solange er gesetzt ist.

Referenz: [PAY- (Zahlungsarten)](https://dokumentation.websale.de/v8s/referenz/tags/pay/zahlungsarten-anzeigen-und-auswaehlen.md)

## Die Bankverbindung

Bei Lastschrift braucht das Abo eine Bankverbindung. Vier Tags bilden das ab, und sie bauen aufeinander auf.

| Tag | Bedeutung |
| - | - |
| `SUBS-BankSelection` | Klammerung: eine Bankverbindung kann gewählt werden |
| `SUBS-BankData` | Klammerung: zum Abo ist bereits eine Bankverbindung hinterlegt |
| `SUBS-BankIndex` | die Kennung der hinterlegten Bankverbindung |
| `SUBS-BankIndex_input` | den HTML-Namen des Auswahlfelds |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-BankSelection}
   <select name="~SUBS-BankIndex_input~">
      {@BANK-Data}
         <option value="~BANK-Index~" {SUBS-BankIndex_selected($BANK-Index$)}selected{/SUBS-BankIndex_selected($BANK-Index$)}>
            ~BANK-IBAN~
         </option>
      {/@BANK-Data}
   </select>
{/SUBS-BankSelection}
```

> [!WARNING]
>
> `SUBS-BankSelection` greift nur, wenn drei Bedingungen zugleich erfüllt sind: ein Käufer ist angemeldet, die fest eingestellte Zahlungsart ist Lastschrift, und der Shop arbeitet nicht mit PayPal Checkout SEPA. Trifft eine davon nicht zu, bleibt der Bereich leer.
>
> Das Tag lädt beim ersten Auswerten die Bankverbindungen des Käufers aus der Datenbank. Setzen Sie es deshalb einmal als Klammerung um den gesamten Bankbereich und werten Sie darin aus, statt es mehrfach im Template zu verteilen.

`SUBS-BankData` lädt ebenfalls aus der Datenbank, und zwar die eine am Abo hinterlegte Verbindung. Es beantwortet die Frage "gibt es schon eine", während `SUBS-BankSelection` die Frage "darf überhaupt eine gewählt werden" beantwortet.

Es vergleicht seinen Parameter mit der zuletzt abgeschickten Auswahl und greift ohne Parameter dann, wenn überhaupt eine Auswahl vorliegt.

> [!WARNING]
>
> `SUBS-BankIndex_input` verhält sich auf der Abo-Seite anders als sonst. Ist dort genau eine Zahlungsart zulässig und diese Lastschrift, liefert es den Namen `ws_subscription_debitindex` und greift zusätzlich als Klammerung, nämlich dann, wenn eine Bankverbindung überhaupt gewählt werden darf. In allen anderen Fällen ist es ein reines Einzel-Tag mit dem Namen `ws_subscription_bank`. Diese Doppelbelegung ist im Shopsystem als Altlast vermerkt.

## Die Lieferadresse

Soll das Abo an eine andere Adresse gehen als die Rechnungsadresse, wählt der Käufer sie aus seinem Adressbuch.

| Tag | Liefert |
| - | - |
| `SUBS-DelivAddress_input` | den HTML-Namen des Auswahlfelds |
| `SUBS-DelivAddress_selected()` | Klammerung: dieser Adressindex ist gewählt |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<select name="~SUBS-DelivAddress_input~">
   <option value="0" {SUBS-DelivAddress_selected(0)}selected{/SUBS-DelivAddress_selected(0)}>Rechnungsadresse verwenden</option>
   {D-DeliverySelection}
      {@D-Data}
         <option value="~D-DeliverySelection_value~"
                 {SUBS-DelivAddress_selected($D-DeliverySelection_value$)}selected{/SUBS-DelivAddress_selected($D-DeliverySelection_value$)}>
            ~D-FirstName~ ~D-LastName~, ~D-Zip~ ~D-City~
         </option>
      {/@D-Data}
   {/D-DeliverySelection}
</select>
```

Der Wert 0 bedeutet "keine abweichende Lieferadresse", das Abo geht also an die Rechnungsadresse. Jeder Wert darüber ist der Index eines Adressbucheintrags, derselbe, den auch `D-DeliverySelection_value` liefert.

Referenz: [D- (Lieferadresse)](https://dokumentation.websale.de/v8s/referenz/tags/d-lieferadresse.md)

## Die HTML-Namen der Eingabefelder

Alle `_input`-Tags liefern feste Namen. Auf der Produktseite sind es diese:

| Tag | HTML-Name |
| - | - |
| `SUBS-CycleSelection_input` | `ws_subscription_cycle` |
| `SUBS-PaymentMethod_input` | `ws_subscription_payment` |
| `SUBS-BankIndex_input` | `ws_subscription_bank` oder `ws_subscription_debitindex` |
| `SUBS-DelivAddress_input` | `ws_subscription_deliv` |

Verwenden Sie trotzdem die Tags und nicht die Namen selbst. Innerhalb der Schleife über bestehende Abos liefern dieselben Tags einen anderen Namen, nämlich denselben mit angehängter Abo-Kennung. Das Template arbeitet dadurch in beiden Zusammenhängen.

## Die Tags im Überblick

| Tag | Einzel-Tag | Bereichs-Tag | negatives Bereichs-Tag | Schleifen-Tag |
| - | - | - | - | - |
| `SUBS-CycleSelection` | – | ja | ja | – |
| `SUBS-CycleSelection_input` | ja | – | – | – |
| `SUBS-CycleSelection_data` | ja | ja | ja | ja |
| `SUBS-CycleSelection_data_selected` | ja | ja | ja | – |
| `SUBS-CycleSelection_data_descr` | ja | ja | ja | – |
| `SUBS-CycleSelection_data_value` | ja | – | – | – |
| `SUBS-CycleSelection_data_count` | ja | – | – | – |
| `SUBS-CycleSelection_data_unit_code` | ja | – | – | – |
| `SUBS-CycleSelection_data_unit_isday` | ja | ja | ja | – |
| `SUBS-CycleSelection_data_unit_isweek` | ja | ja | ja | – |
| `SUBS-CycleSelection_data_unit_ismonth` | ja | ja | ja | – |
| `SUBS-CycleSelection_data_unit_isyear` | ja | ja | ja | – |
| `SUBS-ProdIndexOnSubscription()` | ja | ja | ja | – |
| `SUBS-ProdNumberOnSubscription()` | ja | ja | ja | – |
| `SUBS-AllowedPayments` | ja | ja | ja | ja |
| `SUBS-PaymentMethod_input` | ja | – | – | – |
| `SUBS-PaymentMethod_selected()` | – | ja | ja | – |
| `SUBS-FixedPaymentCodeUsed()` | ja | ja | ja | – |
| `SUBS-BankSelection` | ja | ja | ja | – |
| `SUBS-BankData` | – | ja | ja | – |
| `SUBS-BankIndex` | ja | ja | ja | – |
| `SUBS-BankIndex_input` | ja | ja | ja | – |
| `SUBS-BankIndex_selected()` | – | ja | ja | – |
| `SUBS-DelivAddress_input` | ja | – | – | – |
| `SUBS-DelivAddress_selected()` | – | ja | ja | – |

Mehrere Tags sind laut Tag-Maske als Einzel-Tag zulässig, geben dort aber nichts aus. Das betrifft die vier Einheiten-Klammerungen, `SUBS-ProdIndexOnSubscription()` und `SUBS-ProdNumberOnSubscription()`. Die Tabelle gibt die Maske des Shopsystems wieder.

> [!WARNING]
>
> `SUBS-BankIndex_input` ist im Shopsystem zweimal in der Tag-Tabelle eingetragen. Wirksam ist nur der erste Eintrag, der zweite wird nie erreicht. Für Templates ändert sich dadurch nichts, das Verhalten bleibt wie oben beschrieben.

## Verwandte Themen

* Wegweiser: [Abo-Modul](https://dokumentation.websale.de/v8s/marketing-funktionen/abo-modul.md)
* Referenz: [SUBS- (Abos verwalten)](https://dokumentation.websale.de/v8s/referenz/tags/subs/abos-verwalten.md)
* Referenz: [E-SUBS- (Abo-Modul)](https://dokumentation.websale.de/v8s/referenz/tags/e-subs-abo-modul.md)
* Referenz: [PAY- (Zahlungsarten)](https://dokumentation.websale.de/v8s/referenz/tags/pay/zahlungsarten-anzeigen-und-auswaehlen.md)
* Referenz: Abschnitt [`Subscription`](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/warenkorb-und-bestellprozess#subscription) in der Shopkonfiguration


## Related topics

- [SUBS- (Abos verwalten)](https://dokumentation.websale.de/v8s/referenz/tags/subs/abos-verwalten.md)
- [TAC- (Anzeige von Zahlungs- und Versandarten)](https://dokumentation.websale.de/v8s/referenz/tags/tac-anzeige-von-zahlungs-und-versandarten.md)
- [E-SUBS- (Abo-Modul)](https://dokumentation.websale.de/v8s/referenz/tags/e-subs-abo-modul.md)
- [Materialien Abo-Modul](https://dokumentation.websale.de/v8s/materialien/materialien-abo-modul.md)
- [Abo-Modul](https://dokumentation.websale.de/v8s/marketing-funktionen/abo-modul.md)


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