SUBS- (managing subscriptions) - WEBSALE Dokumentation

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.

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

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.

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

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

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.

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.

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

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

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.

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

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

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.

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`

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

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.

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.

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

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

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.

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.

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

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

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.

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.

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

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

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.

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.

{@SUBS-Data}
   {SUBS-Data_BankIndex(1)}
      <p>Dieses Abo wird über die erste Bankverbindung abgebucht.</p>
   {/SUBS-Data_BankIndex(1)}
{/@SUBS-Data}

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

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.

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

{SUBS-Buttonvalue_triggernewsubscriptions}
   <button type="submit" name="~SUBS-Buttonname~" value="~SUBS-Buttonvalue_triggernewsubscriptions~">
      Neue Abos jetzt starten
   </button>
{/SUBS-Buttonvalue_triggernewsubscriptions}

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.

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	–

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.

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

​The loop over the subscriptions

​The subscribed product

​The delivery interval

​Letting the customer change the interval

​Points in time and counters

​The state of the subscription

​Pausing, resuming and deleting

​The feedback after an action

​Payment method, bank details and delivery address per subscription

​Building the selection for changes

​Triggering new subscriptions

​Tags at a glance

​Related topics

The loop over the subscriptions

The subscribed product

The delivery interval

Letting the customer change the interval

Points in time and counters

The state of the subscription

Pausing, resuming and deleting

The feedback after an action

Payment method, bank details and delivery address per subscription

Building the selection for changes

Triggering new subscriptions

Tags at a glance

Related topics