> ## 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- (managing subscriptions)

> List and change a customer's subscriptions: output product data and delivery interval per subscription, show timestamps and state, pause, resume or delete subscriptions and evaluate the feedback on the last action.

Once a customer has subscribed to products, they also want to stay in control of them: see when the next delivery is due, change the quantity, pause a subscription for the summer or end it entirely. There is a separate page in the shop for this, and the tags on this page build it.

Everything revolves around a loop. `SUBS-Data` loops over the subscriptions of the logged-in customer, and within this loop all other tags return the details for the respective subscription.

* Guide: Subscription module
* Reference: SUBS- (taking out a subscription)

## The loop over the subscriptions

`SUBS-Data` can do three things: output the number of subscriptions as a single tag, check as a bracketing whether there are any at all, and loop over them.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-Data}
   <p>Sie haben ~SUBS-Data~ Abos abgeschlossen.</p>

   <form action="~FORM-Subscription~" method="post">
      {@SUBS-Data}
         ...
      {/@SUBS-Data}
   </form>
{/SUBS-Data}

{!SUBS-Data}
   <p>Sie haben derzeit keine Produkte abonniert.</p>
{/!SUBS-Data}
```

> [!WARNING]
>
> All other tags on this page are invalid tags outside the `SUBS-Data` loop. This also applies within the `{SUBS-Data}` bracketing, because only the loop determines which subscription is meant. The exception is the two tags for the button that triggers new subscriptions.

> [!NOTE]
>
> `SUBS-Data` is not limited to the management page. The loop works on all templates as long as a buyer is logged in. On an overview page, for example, you can use it to display the number of running subscriptions.

## The subscribed product

| Tag | Returns |
| - | - |
| `SUBS-Data_Index` | the technical identifier of the subscription |
| `SUBS-Data_PR_Index` | the product index |
| `SUBS-Data_PR_Number` | the product number |
| `SUBS-Data_PR_Name` | the product name |
| `SUBS-Data_PR_Price` | the price |
| `SUBS-Data_PR_CurrencyCode` | the currency code |
| `SUBS-Data_PR_Quantity` | the subscribed quantity |
| `SUBS-Data_PR_Quantity_input` | the HTML name of the quantity field |
| `SUBS-Data_SubShop()` | the identifier of the subshop in which the subscription was taken out |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   <h3>~SUBS-Data_PR_Name~</h3>
   {SUBS-Data_PR_Number}<p>Artikelnummer ~SUBS-Data_PR_Number~</p>{/SUBS-Data_PR_Number}
   <p>~SUBS-Data_PR_Price~ ~SUBS-Data_PR_CurrencyCode~</p>

   <label>
      Menge
      <input name="~SUBS-Data_PR_Quantity_input~" value="~SUBS-Data_PR_Quantity~">
   </label>
{/@SUBS-Data}
```

> [!WARNING]
>
> Product name, price and currency code are stored on the subscription and date from the time of the last order or the last change to the subscription. They are therefore a snapshot and not the current state of the product. If the current price is to appear, reload the product via its index.

> [!NOTE]
>
> `SUBS-Data_Index` is the identifier the shop system uses to address this one subscription. It is contained in all field names within the loop and ensures that a form page with several subscriptions remains unambiguous.

> [!NOTE]
>
> `SUBS-Data_SubShop()` optionally takes subshop identifiers as parameters and then applies as a bracketing only for these. Without a parameter, it outputs the identifier in which the product was subscribed.

## The delivery interval

| Tag | Returns |
| - | - |
| `SUBS-Data_Cycle_count` | the number of units |
| `SUBS-Data_Cycle_unit_code` | the technical code of the unit |
| `SUBS-Data_Cycle_unit_isday` | bracketing: the unit is day, code 0 |
| `SUBS-Data_Cycle_unit_ismonth` | bracketing: the unit is month, code 1 |
| `SUBS-Data_Cycle_unit_isyear` | bracketing: the unit is year, code 2 |
| `SUBS-Data_Cycle_unit_isweek` | bracketing: the unit is week, code 3 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_Cycle_count}
      <p>
         Lieferung alle ~SUBS-Data_Cycle_count~
         {SUBS-Data_Cycle_unit_isday}Tage{/SUBS-Data_Cycle_unit_isday}
         {SUBS-Data_Cycle_unit_isweek}Wochen{/SUBS-Data_Cycle_unit_isweek}
         {SUBS-Data_Cycle_unit_ismonth}Monate{/SUBS-Data_Cycle_unit_ismonth}
         {SUBS-Data_Cycle_unit_isyear}Jahre{/SUBS-Data_Cycle_unit_isyear}
      </p>
   {/SUBS-Data_Cycle_count}
{/@SUBS-Data}
```

> [!WARNING]
>
> Here, too, the codes do not follow the length of the periods. The week has code 3 and comes after the year. Therefore, never evaluate `_unit_code` with a size comparison.

### Letting the customer change the interval

If the customer is to change the interval, build the same selection within the loop as on the product page. There, `SUBS-CycleSelection_input` automatically returns the field name related to this subscription, and `SUBS-CycleSelection_data_selected` compares against the stored interval instead of against a form input.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   <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>
{/@SUBS-Data}
```

Reference: The cycle selection on the SUBS- (taking out a subscription) page

## Points in time and counters

All four time values come as Unix timestamps and are converted into a readable form via the date tags.

| Tag | Returns |
| - | - |
| `SUBS-Data_created_unixtimestamp` | when the subscription was created |
| `SUBS-Data_lastchange_unixtimestamp` | when it was last changed |
| `SUBS-Data_lastorder_unixtimestamp` | when the last order was placed |
| `SUBS-Data_nextorder_unixtimestamp` | when the next order will be triggered |
| `SUBS-Data_counter_orderedviasubscription` | how often orders have been placed via this subscription |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_nextorder_unixtimestamp}
      ~DC-DateTime_setunixtimestamp($SUBS-Data_nextorder_unixtimestamp$)~
      <p>Nächste Lieferung am ~DC-DateTime_day~.~DC-DateTime_month~.~DC-DateTime_year~</p>
   {/SUBS-Data_nextorder_unixtimestamp}
{/@SUBS-Data}
```

> [!NOTE]
>
> For `SUBS-Data_nextorder_unixtimestamp`, only the date part is reliable. The time it contains says nothing about when on that day the order is actually placed.

> [!NOTE]
>
> All five tags apply as a bracketing when a value is present. For a newly created subscription, the time of the last order and the counter are still empty. Therefore, bracket the output instead of displaying a 0 or 1 January 1970.

Reference: DC- (date and time)

## The state of the subscription

`SUBS-Data_state_code` outputs the technical code; four bracketings query it.

| Code | State | Bracketing |
| - | - | - |
| 0 | active | `SUBS-Data_state_isactive` |
| 1 | new and active | `SUBS-Data_state_isnew` |
| 2 | new, active and triggered | `SUBS-Data_state_istriggered` |
| 3 | paused | `SUBS-Data_state_ispaused` |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_state_ispaused}<span class="pausiert">pausiert</span>{/SUBS-Data_state_ispaused}
   {SUBS-Data_state_isactive}<span class="aktiv">läuft</span>{/SUBS-Data_state_isactive}
{/@SUBS-Data}
```

> [!WARNING]
>
> The four states are mutually exclusive. `SUBS-Data_state_isactive` applies exclusively for code 0 and therefore specifically not for a new subscription, even though it is also running. If you want to express "running" in the sense of "not paused", use the negative bracketing of `SUBS-Data_state_ispaused`.

> [!NOTE]
>
> States 1 and 2 concern the transition from taking out the subscription to the first delivery. A subscription is initially new, and as soon as the first order has been triggered, it is considered triggered. After that, it switches to active.

> [!NOTE]
>
> `SUBS-Data_state_code` is exclusively a single tag. For case distinctions, use the four bracketings.

## Pausing, resuming and deleting

Each action runs via its own button. `SUBS-Data_Buttonname` returns the name, the three `Buttonvalue` tags the value.

| Tag | Action |
| - | - |
| `SUBS-Data_Buttonvalue_pause` | pause the subscription |
| `SUBS-Data_Buttonvalue_resume` | resume the subscription |
| `SUBS-Data_Buttonvalue_delete` | delete the subscription |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_Buttonvalue_pause}
      <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_pause~">pausieren</button>
   {/SUBS-Data_Buttonvalue_pause}

   {SUBS-Data_Buttonvalue_resume}
      <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_resume~">fortsetzen</button>
   {/SUBS-Data_Buttonvalue_resume}

   <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_delete~">löschen</button>
{/@SUBS-Data}
```

> [!NOTE]
>
> Pausing and resuming are only available in the appropriate state. `SUBS-Data_Buttonvalue_pause` returns nothing for an already paused subscription and does not apply as a bracketing there either; conversely, `SUBS-Data_Buttonvalue_resume` only applies for a paused subscription. Therefore, bracket the two buttons with their own tag so that only the sensible one appears in each case.

> [!NOTE]
>
> Deleting is always available. The bracketing of `SUBS-Data_Buttonvalue_delete` applies in every state and serves the consistency of the template rather than a case distinction.

> [!WARNING]
>
> Deletion happens without a confirmation prompt from the shop system. Build a safety prompt into the template, because the customer cannot restore an accidentally deleted subscription.

## The feedback after an action

After submission, five tags per subscription tell you what happened to it.

| Tag | Applies |
| - | - |
| `SUBS-Data_affected` | if this subscription was affected by the last action |
| `SUBS-Data_affected_changed` | if quantity or delivery interval were changed, code 1 |
| `SUBS-Data_affected_paused` | if it was paused, code 2 |
| `SUBS-Data_affected_resumed` | if it was resumed, code 3 |
| `SUBS-Data_affected_code` | outputs the code and applies if there is one |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_affected}
      {SUBS-Data_affected_changed}<p class="hinweis">Ihre Änderung wurde übernommen.</p>{/SUBS-Data_affected_changed}
      {SUBS-Data_affected_paused}<p class="hinweis">Dieses Abo ist jetzt pausiert.</p>{/SUBS-Data_affected_paused}
      {SUBS-Data_affected_resumed}<p class="hinweis">Dieses Abo läuft wieder.</p>{/SUBS-Data_affected_resumed}
   {/SUBS-Data_affected}
{/@SUBS-Data}
```

> [!NOTE]
>
> Code 0 means "not affected". It is never output, because in this case `SUBS-Data_affected` already does not apply. The four codes are therefore: 0 not affected, 1 changed, 2 paused, 3 resumed.

> [!WARNING]
>
> There is no feedback for a deleted subscription. After the action, it is no longer in the list, and the loop does not iterate over it. A success message for deletion therefore belongs outside the loop, not inside it.

> [!NOTE]
>
> The feedback applies to the call immediately after submission. If the customer reloads the page, it is gone.

## Payment method, bank details and delivery address per subscription

These three details are stored on the individual subscription. All three tags output the value as a single tag and apply as a bracketing if it is set. With a parameter, they check for equality instead.

| Tag | Returns |
| - | - |
| `SUBS-Data_PaymentCode()` | the payment method code of the subscription |
| `SUBS-Data_BankIndex()` | the identifier of the bank details |
| `SUBS-Data_DelivAddress()` | the index of the delivery address |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_DelivAddress}
      <p>Lieferung an Adresse ~SUBS-Data_DelivAddress~</p>
   {/SUBS-Data_DelivAddress}

   {!SUBS-Data_DelivAddress}
      <p>Lieferung an die Rechnungsadresse</p>
   {/!SUBS-Data_DelivAddress}
{/@SUBS-Data}
```

> [!NOTE]
>
> For index 0, the bracketing does not apply. Here this is not a missing value but a statement: for `SUBS-Data_DelivAddress()`, 0 means that no different delivery address is stored, and for `SUBS-Data_BankIndex()`, that no bank details are attached to the subscription. Catch this case with the negative bracketing.

> [!WARNING]
>
> In the example for `SUBS-Data_BankIndex()`, the previous documentation shows the comparison with `SUBS-Data_PaymentCode(1)` instead of `SUBS-Data_BankIndex(1)`. This is an error in the original. The corrected comparison is shown here.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@SUBS-Data}
   {SUBS-Data_BankIndex(1)}
      <p>Dieses Abo wird über die erste Bankverbindung abgebucht.</p>
   {/SUBS-Data_BankIndex(1)}
{/@SUBS-Data}
```

> [!NOTE]
>
> The bank index is only relevant for direct debit. For other payment methods, it is usually 0.

### Building the selection for changes

If the customer is to change these three details, use the same `_input` and `_selected` tags as on the product page. Within the loop, the `_input` tags append the subscription identifier to the field name, so that a page with several subscriptions also remains unambiguous.

| Tag | HTML name within the loop |
| - | - |
| `SUBS-CycleSelection_input` | `ws_subscription_cycle_<Kennung>` |
| `SUBS-Data_PR_Quantity_input` | `ws_subscription_qty_<Kennung>` |
| `SUBS-PaymentMethod_input` | `ws_subscription_payment_<Kennung>` |
| `SUBS-BankIndex_input` | `ws_subscription_bank_<Kennung>` |
| `SUBS-DelivAddress_input` | `ws_subscription_deliv_<Kennung>` |

> [!WARNING]
>
> The `_selected` tags compare against the most recently submitted form input, not against the value stored on the subscription. For the stored state, use `SUBS-Data_PaymentCode()`, `SUBS-Data_BankIndex()` and `SUBS-Data_DelivAddress()` with a parameter. The exception is `SUBS-CycleSelection_data_selected`, which within the loop checks against the stored interval by itself.

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

## Triggering new subscriptions

When the customer has just taken out a subscription, it initially appears as new in the list without any order having been placed yet. A separate button triggers the first order.

| Tag | Returns |
| - | - |
| `SUBS-Buttonname` | the HTML name of the button, fixed as `button_subscription_global` |
| `SUBS-Buttonvalue_triggernewsubscriptions` | the value, and as a bracketing whether there are any new subscriptions at all |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SUBS-Buttonvalue_triggernewsubscriptions}
   <button type="submit" name="~SUBS-Buttonname~" value="~SUBS-Buttonvalue_triggernewsubscriptions~">
      Neue Abos jetzt starten
   </button>
{/SUBS-Buttonvalue_triggernewsubscriptions}
```

> [!NOTE]
>
> Both tags belong outside the `SUBS-Data` loop, because they refer to all new subscriptions at once and not to a single one. They are therefore also the only tags on this page that are available outside the loop.

> [!NOTE]
>
> The bracketing applies as long as at least one subscription is in the "new and active" state, that is, code 1. An already triggered subscription with code 2 no longer counts.

## Tags at a glance

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `SUBS-Data` | yes | yes | yes | yes |
| `SUBS-Data_Index` | yes | yes | yes | – |
| `SUBS-Data_SubShop()` | yes | yes | yes | – |
| `SUBS-Data_PR_Index` | yes | yes | yes | – |
| `SUBS-Data_PR_Number` | yes | yes | yes | – |
| `SUBS-Data_PR_Name` | yes | yes | yes | – |
| `SUBS-Data_PR_Price` | yes | yes | yes | – |
| `SUBS-Data_PR_CurrencyCode` | yes | yes | yes | – |
| `SUBS-Data_PR_Quantity` | yes | yes | yes | – |
| `SUBS-Data_PR_Quantity_input` | yes | yes | yes | – |
| `SUBS-Data_Cycle_count` | yes | yes | yes | – |
| `SUBS-Data_Cycle_unit_code` | yes | yes | yes | – |
| `SUBS-Data_Cycle_unit_isday` | yes | yes | yes | – |
| `SUBS-Data_Cycle_unit_isweek` | yes | yes | yes | – |
| `SUBS-Data_Cycle_unit_ismonth` | yes | yes | yes | – |
| `SUBS-Data_Cycle_unit_isyear` | yes | yes | yes | – |
| `SUBS-Data_created_unixtimestamp` | yes | yes | yes | – |
| `SUBS-Data_lastchange_unixtimestamp` | yes | yes | yes | – |
| `SUBS-Data_nextorder_unixtimestamp` | yes | yes | yes | – |
| `SUBS-Data_lastorder_unixtimestamp` | yes | yes | yes | – |
| `SUBS-Data_counter_orderedviasubscription` | yes | yes | yes | – |
| `SUBS-Data_state_code` | yes | – | – | – |
| `SUBS-Data_state_isactive` | yes | yes | yes | – |
| `SUBS-Data_state_isnew` | yes | yes | yes | – |
| `SUBS-Data_state_ispaused` | yes | yes | yes | – |
| `SUBS-Data_state_istriggered` | yes | yes | yes | – |
| `SUBS-Data_Buttonname` | yes | yes | yes | – |
| `SUBS-Data_Buttonvalue_delete` | yes | yes | yes | – |
| `SUBS-Data_Buttonvalue_pause` | yes | yes | yes | – |
| `SUBS-Data_Buttonvalue_resume` | yes | yes | yes | – |
| `SUBS-Data_affected` | yes | yes | yes | – |
| `SUBS-Data_affected_code` | yes | yes | yes | – |
| `SUBS-Data_affected_changed` | yes | yes | yes | – |
| `SUBS-Data_affected_paused` | yes | yes | yes | – |
| `SUBS-Data_affected_resumed` | yes | yes | yes | – |
| `SUBS-Data_PaymentCode()` | yes | yes | yes | – |
| `SUBS-Data_BankIndex()` | yes | yes | yes | – |
| `SUBS-Data_DelivAddress()` | yes | yes | yes | – |
| `SUBS-Buttonname` | yes | yes | yes | – |
| `SUBS-Buttonvalue_triggernewsubscriptions` | yes | yes | yes | – |

> [!NOTE]
>
> The table reflects the tag mask of the shop system. Several tags are permitted as single tags in it but output nothing there. This concerns all pure bracketings, that is, the units, the states and the tags of the `SUBS-Data_affected` family. The previous documentation lists these tags only as bracketings, which corresponds to their sensible use.

All tags except `SUBS-Buttonname` and `SUBS-Buttonvalue_triggernewsubscriptions` belong in the `SUBS-Data` loop. Outside it, they are invalid tags.

## Related topics

* Guide: Subscription module
* Reference: SUBS- (taking out a subscription)
* Reference: E-SUBS- (subscription module)
* Reference: DC- (date and time)
* Reference: `Subscription` section in the shop configuration


## Related topics

- [SUBS- (taking out a subscription)](https://dokumentation.websale.de/en/v8s/referenz/tags/subs/abo-abschliessen.md)
- [E-NL- (Managing the subscription)](https://dokumentation.websale.de/en/v8s/referenz/tags/e-nl/abonnement-verwalten.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.