SUBS- (taking out a subscription) - WEBSALE Dokumentation

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)

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.

{SUBS-CycleSelection}
   <fieldset>
      <legend>Als Abo bestellen</legend>
      ...
   </fieldset>
{/SUBS-CycleSelection}

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.

<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

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.

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.

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

{@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}

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.

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.

Standardintervall: ~SUBS-CycleSelection_data_descr(1)~

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.

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.

{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~)}

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.

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

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

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.

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.

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.

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

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

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.

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.

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

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.

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

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

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.

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`

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	–

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.

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.

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

​Can this product be subscribed to

​The cycle selection

​The unit of the interval

​Addressing a specific entry

​Is the product already subscribed

​The payment method for the subscription

​The bank details

​The delivery address

​The HTML names of the input fields

​Tags at a glance

​Related topics

Can this product be subscribed to

The cycle selection

The unit of the interval

Addressing a specific entry

Is the product already subscribed

The payment method for the subscription

The bank details

The delivery address

The HTML names of the input fields

Tags at a glance

Related topics