> ## 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- (taking out a subscription)

> Order a product as a subscription: build the cycle selection, check whether it is already subscribed, and set the payment method, bank details and delivery address for the subscription.

A subscription is created on the product page. There, the buyer selects not only the quantity but also a delivery interval and, depending on the settings, the payment method, bank details and a delivery address that apply permanently to this subscription.

This page describes the tags for exactly this step. Managing existing subscriptions is covered on a separate page.

* Guide: Subscription module
* Reference: SUBS- (managing subscriptions)

> [!NOTE]
>
> The subscription function is enabled in the `Subscription` section of the shop configuration. The selectable delivery intervals and the permitted payment methods are also defined there.

## Can this product be subscribed to

`SUBS-CycleSelection` is the bracketing around the entire subscription area. It applies if the product can be subscribed to.

```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}
```

> [!NOTE]
>
> Put the entire subscription part of the product template in this bracketing. Without it, the input fields also appear for products that cannot be subscribed to at all.

## The cycle selection

The selectable delivery intervals are configured in the shop, not on the product. `SUBS-CycleSelection_data` loops over them and, as a single tag, returns their number.

```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 | Returns |
| - | - |
| `SUBS-CycleSelection_input` | the HTML name of the selection field |
| `SUBS-CycleSelection_data` | the loop over the intervals; as a single tag, their number |
| `SUBS-CycleSelection_data_value` | the value of the entry for the `value` attribute |
| `SUBS-CycleSelection_data_descr` | the label of the entry |
| `SUBS-CycleSelection_data_selected` | the word `selected` if this entry is the selected one |
| `SUBS-CycleSelection_data_count` | the number of units, for example the 3 in "every 3 months" |
| `SUBS-CycleSelection_data_unit_code` | the technical code of the unit |

> [!WARNING]
>
> `SUBS-CycleSelection_data_value` does not return the number but the combination of unit and number in the form `unit-number`. An interval of three months therefore results in `1-3`. This value belongs unchanged in the `value` attribute, because the shop system uses it to recognise the selection. The previous documentation does not describe the structure.

> [!NOTE]
>
> The label from `SUBS-CycleSelection_data_descr` comes from the `Description` parameter of the respective interval in the shop configuration. If nothing is stored there, the tag outputs nothing and does not apply as a bracketing either. In this case, build the label yourself from `_data_count` and the unit bracketings.

> [!NOTE]
>
> As a single tag, `SUBS-CycleSelection_data_selected` outputs a leading space followed by `selected`. You can therefore write it directly after the last attribute without adding a separator yourself.

### The unit of the interval

Four bracketings tell you which unit is involved. The technical code behind it is in `SUBS-CycleSelection_data_unit_code`.

| Tag | Applies for | Code |
| - | - | - |
| `SUBS-CycleSelection_data_unit_isday` | day | 0 |
| `SUBS-CycleSelection_data_unit_ismonth` | month | 1 |
| `SUBS-CycleSelection_data_unit_isyear` | year | 2 |
| `SUBS-CycleSelection_data_unit_isweek` | week | 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]
>
> The order of the codes does not follow the length of the periods. The week has code 3 and therefore comes after the year. Therefore, never evaluate `_unit_code` with a size comparison; use the four bracketings instead.

> [!NOTE]
>
> According to the tag mask, the four unit tags are also permitted as single tags. However, they output nothing there. Use them exclusively as bracketings. The previous documentation lists them only as bracketings, which corresponds to their sensible use.

### Addressing a specific entry

All `_data_` tags optionally take a parameter, namely the sequential number of the interval. This lets you access a specific entry outside the loop.

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

> [!NOTE]
>
> `SUBS-CycleSelection_data_selected` without a parameter and outside the loop has a meaning of its own. There it applies as a bracketing if the buyer has selected an interval at all. This is suitable for a notice that the selection is still pending.

> [!WARNING]
>
> A number outside the configured range makes the tag invalid. This also applies within the loop if you additionally set a parameter there.

## Is the product already subscribed

Before you offer the subscription area, it is worth checking the buyer's existing subscriptions. Two bracketings answer this, one via the product index and the other via the product number.

```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]
>
> Both tags require their parameter. Without a parameter they never apply, not even the negative bracketing. No error is reported; the area simply stays silent. The previous documentation does not state that the parameter is mandatory.

> [!NOTE]
>
> The search covers all subscriptions of the logged-in buyer, regardless of their state. A paused subscription therefore also counts as existing.

## The payment method for the subscription

A subscription is billed repeatedly and therefore does not work with every payment method. Which ones are permitted is defined in the `AllowedPayments` parameter in the `Subscription` section of the shop configuration.

| Tag | Returns |
| - | - |
| `SUBS-AllowedPayments` | the loop over the permitted payment methods; within the iteration, the payment method code |
| `SUBS-PaymentMethod_input` | the HTML name of the selection field |
| `SUBS-PaymentMethod_selected()` | bracketing: this payment method code is selected |
| `SUBS-FixedPaymentCodeUsed()` | the fixed payment method; with a parameter, a comparison against it |

```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}
```

> [!NOTE]
>
> `SUBS-AllowedPayments` and `SUBS-PaymentMethod_selected()` exist in the shop system but are not described in the previous documentation. Without them, a payment method selection cannot be built, even though the previous documentation already uses them in its examples.

> [!NOTE]
>
> For subscriptions, the shop system only permits direct debit, invoice, PayPal Checkout and PayPal Checkout pay upon invoice as payment methods. Any other code in `AllowedPayments` is discarded and logged when the configuration is read.

> [!WARNING]
>
> `SUBS-PaymentMethod_selected()` compares the parameter with the most recently submitted selection, not with a payment method stored on the subscription. When the product page is first called, nothing has been selected yet, and without a parameter the tag applies as a bracketing if any selection exists at all.

> [!NOTE]
>
> The `UsePaymentCode` parameter is the predecessor of `AllowedPayments` and should no longer be used. If it is set and `AllowedPayments` is not, it results in a list with exactly one entry. `SUBS-FixedPaymentCodeUsed` outputs this code as a single tag and applies as a bracketing as long as it is set.

Reference: PAY- (payment methods)

## The bank details

For direct debit, the subscription needs bank details. Four tags cover this, and they build on one another.

| Tag | Meaning |
| - | - |
| `SUBS-BankSelection` | bracketing: bank details can be selected |
| `SUBS-BankData` | bracketing: bank details are already stored for the subscription |
| `SUBS-BankIndex` | the identifier of the stored bank details |
| `SUBS-BankIndex_input` | the HTML name of the selection field |

```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` only applies if three conditions are met at the same time: a buyer is logged in, the fixed payment method is direct debit, and the shop does not work with PayPal Checkout SEPA. If any one of them does not apply, the area remains empty. The previous documentation does not mention these conditions.

> [!WARNING]
>
> On first evaluation, the tag loads the buyer's bank details from the database. Therefore, place it once as a bracketing around the entire bank area and evaluate within it, instead of spreading it across the template several times.

> [!NOTE]
>
> `SUBS-BankData` also loads from the database, namely the one set of bank details stored on the subscription. It answers the question "is there already one", while `SUBS-BankSelection` answers the question "may one be selected at all".

> [!NOTE]
>
> `SUBS-BankIndex_selected()` exists in the shop system but is not described in the previous documentation. It compares its parameter with the most recently submitted selection and, without a parameter, applies if any selection exists at all.

> [!WARNING]
>
> `SUBS-BankIndex_input` behaves differently on the subscription page than elsewhere. If exactly one payment method is permitted there and it is direct debit, it returns the name `ws_subscription_debitindex` and additionally applies as a bracketing, namely when bank details may be selected at all. In all other cases, it is a pure single tag with the name `ws_subscription_bank`. This double assignment is noted as a legacy issue in the shop system.

## The delivery address

If the subscription is to go to a different address than the billing address, the buyer selects it from their address book.

| Tag | Returns |
| - | - |
| `SUBS-DelivAddress_input` | the HTML name of the selection field |
| `SUBS-DelivAddress_selected()` | bracketing: this address index is selected |

```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>
```

> [!NOTE]
>
> Both tags exist in the shop system but are not described in the previous documentation. The previous documentation already uses `SUBS-DelivAddress_input` in an example without explaining it.

> [!NOTE]
>
> The value 0 means "no different delivery address", so the subscription goes to the billing address. Any value above that is the index of an address book entry, the same one that `D-DeliverySelection_value` returns.

Reference: D- (delivery address)

## The HTML names of the input fields

All `_input` tags return fixed names. On the product page, they are these:

| Tag | HTML name |
| - | - |
| `SUBS-CycleSelection_input` | `ws_subscription_cycle` |
| `SUBS-PaymentMethod_input` | `ws_subscription_payment` |
| `SUBS-BankIndex_input` | `ws_subscription_bank` or `ws_subscription_debitindex` |
| `SUBS-DelivAddress_input` | `ws_subscription_deliv` |

> [!NOTE]
>
> Nevertheless, use the tags and not the names themselves. Within the loop over existing subscriptions, the same tags return a different name, namely the same one with the subscription identifier appended. This way, the template works in both contexts.

## Tags at a glance

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `SUBS-CycleSelection` | – | yes | yes | – |
| `SUBS-CycleSelection_input` | yes | – | – | – |
| `SUBS-CycleSelection_data` | yes | yes | yes | yes |
| `SUBS-CycleSelection_data_selected` | yes | yes | yes | – |
| `SUBS-CycleSelection_data_descr` | yes | yes | yes | – |
| `SUBS-CycleSelection_data_value` | yes | – | – | – |
| `SUBS-CycleSelection_data_count` | yes | – | – | – |
| `SUBS-CycleSelection_data_unit_code` | yes | – | – | – |
| `SUBS-CycleSelection_data_unit_isday` | yes | yes | yes | – |
| `SUBS-CycleSelection_data_unit_isweek` | yes | yes | yes | – |
| `SUBS-CycleSelection_data_unit_ismonth` | yes | yes | yes | – |
| `SUBS-CycleSelection_data_unit_isyear` | yes | yes | yes | – |
| `SUBS-ProdIndexOnSubscription()` | yes | yes | yes | – |
| `SUBS-ProdNumberOnSubscription()` | yes | yes | yes | – |
| `SUBS-AllowedPayments` | yes | yes | yes | yes |
| `SUBS-PaymentMethod_input` | yes | – | – | – |
| `SUBS-PaymentMethod_selected()` | – | yes | yes | – |
| `SUBS-FixedPaymentCodeUsed()` | yes | yes | yes | – |
| `SUBS-BankSelection` | yes | yes | yes | – |
| `SUBS-BankData` | – | yes | yes | – |
| `SUBS-BankIndex` | yes | yes | yes | – |
| `SUBS-BankIndex_input` | yes | yes | yes | – |
| `SUBS-BankIndex_selected()` | – | yes | yes | – |
| `SUBS-DelivAddress_input` | yes | – | – | – |
| `SUBS-DelivAddress_selected()` | – | yes | yes | – |

> [!NOTE]
>
> According to the tag mask, several tags are permitted as single tags but output nothing there. This concerns the four unit bracketings, `SUBS-ProdIndexOnSubscription()` and `SUBS-ProdNumberOnSubscription()`. The table reflects the mask of the shop system; the previous documentation lists these tags only as bracketings.

> [!WARNING]
>
> `SUBS-BankIndex_input` is entered twice in the tag table of the shop system. Only the first entry is effective; the second is never reached. This changes nothing for templates; the behaviour remains as described above.

## Related topics

* Guide: Subscription module
* Reference: SUBS- (managing subscriptions)
* Reference: E-SUBS- (subscription module)
* Reference: PAY- (payment methods)
* Reference: `Subscription` section in the shop configuration


## Related topics

- [SUBS- (managing subscriptions)](https://dokumentation.websale.de/en/v8s/referenz/tags/subs/abos-verwalten.md)
- [TAC- (display of payment and shipping methods)](https://dokumentation.websale.de/en/v8s/referenz/tags/tac-anzeige-von-zahlungs-und-versandarten.md)
- [E-SUBS- (Subscription module)](https://dokumentation.websale.de/en/v8s/referenz/tags/e-subs-abo-modul.md)
- [Materials: subscription module](https://dokumentation.websale.de/en/v8s/materialien/materialien-abo-modul.md)
- [E-NL- (Voucher for newsletter subscription)](https://dokumentation.websale.de/en/v8s/referenz/tags/e-nl/gutscheine.md)


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