Practical examples - Vouchers - WEBSALE Dokumentation

This section contains practical examples for using vouchers in the template. The first examples cover redemption in the checkout, the last one covers outputting purchased vouchers. Vouchers are created in the Admin Interface. This is described on the pages Vouchers and Creating a purchase voucher product.

Voucher input form with `maximumCount` check

The input form is only displayed as long as fewer vouchers have been redeemed than allowed. As soon as the upper limit is reached, the form disappears automatically.

{{ var $cActionVoucherAdd = $wsActions.create("VoucherAdd") }}
{{ include "components/errorAlert.htm" with $cAction = $cActionVoucherAdd, $cViewEachField = true }}

{{ if len($wsVoucher.vouchers) < $wsVoucher.maximumCount }}
    <form method="post" action="{{= $wsViews.current.url() }}" data-ws-ajax-form>
        <input type="hidden" name="wsReplaceIds" value="wsBasketWrapper,wsBasketEntries,wsBasketOffcanvasContent">
        <input type="hidden" name="wsact"    value="{{= $cActionVoucherAdd.id }}">
        <input type="hidden" name="wscsrf"   value="{{= $cActionVoucherAdd.csrf }}">
        <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">

        <input type="text" name="id" value="" placeholder="Enter voucher code">
        <button type="submit">Redeem</button>
    </form>
{{ /if }}

Error messages (e.g. “Minimum order value not reached”) are defined and rendered via components/errorAlert.htm.

Displaying the list of redeemed vouchers

A separate small form with a unique ID is output for each voucher. Valid vouchers appear in green, invalid ones in red.

{{ if $wsVoucher.vouchers }}
    <p>Redeemed vouchers</p>

    {{ foreach $cVoucher in $wsVoucher.vouchers }}
        {{ var $cVoucherIsValid = $cVoucher.valid | ifNull(true) }}
        {{ var $cActionVoucherDelete = $wsActions.create("VoucherDelete") }}

        <form method="post"
              action="{{= $wsViews.viewUrl('basket.htm') }}"
              data-ws-ajax-form>
            <input type="hidden" name="wsReplaceIds" value="wsBasketWrapper,wsBasketEntries,wsBasketOffcanvasContent">
            <input type="hidden" name="id"       value="{{= $cVoucher.id }}">
            <input type="hidden" name="wsact"    value="{{= $cActionVoucherDelete.id }}">
            <input type="hidden" name="wscsrf"   value="{{= $cActionVoucherDelete.csrf }}">
            <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">

            <span>{{= $cVoucher.id }}</span>
            <button type="submit">Remove</button>
        </form>
    {{ /foreach }}
{{ /if }}

Displaying all redeemed vouchers in the basket

In this example, all redeemed vouchers are shown in the basket. The customer can transparently see which codes are in the system and which one is currently being applied. Vouchers that have no effect are not added to the list and are indicated via an error message.

{{ var $cVoucherCount = 0 }}
{{ if $wsVoucher.vouchers }}
    {{ foreach $cVoucher in $wsVoucher.vouchers }}
        {{ $cVoucherCount = $cVoucherCount + 1 }}
        <tr>
            <td>
                <div>{{ if $cVoucherCount == 1 }}Voucher{{ else }}Additional voucher{{ /if }}</div>
                <div>{{= $cVoucher.id }}</div>
            </td>
            <td>
                -{{= $cVoucher.value | currency }}
            </td>
        </tr>
    {{ /foreach }}
{{ /if }}

Output voucher errors with reason and voucher ID

Instead of a generic notice, the customer sees the specific reason per voucher why the voucher does not apply. The texts come from checkout.voucherErrors; the fallback to code only kicks in if no text is maintained.

{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
    <div class="alert alert-danger" role="alert">
        <strong>Gutscheine können nicht eingelöst werden:</strong>
        <ul>
            {{ foreach $cError in $wsCheckout.ineffectiveVoucherErrors }}
                {{ if $cError.details.voucherId }}
                    <li>
                        Gutschein <strong>{{= $cError.details.voucherId }}</strong>:
                        {{= $cError.text | ifNull($cError.code) }}
                    </li>
                {{ else }}
                    {{#
                        Steht die Berechnung des Mindestbestellwerts auf "sum", wird die Summe
                        aller Mindestbestellwerte geprüft. Dieser Fehler gehört zu keinem
                        einzelnen Gutschein und kommt daher ohne Gutschein-ID.
                    #}}
                    <li>{{= $cError.text | ifNull($cError.code) }}</li>
                {{ /if }}
            {{ /foreach }}
        </ul>
    </div>
{{ /if }}

Always check details.voucherId before rendering. The voucher ID is deliberately missing when the error comes from the summed minimum-order-value check. Which error is raised when is documented under When each error occurs.

Free shipping method for voucher-only baskets

If a basket contains only (instant) vouchers, no physical shipping is required. For this case you can define a dedicated, always free shipping method under checkout.shippingMethod: the basicCost scale sets the cost to 0 from a subtotal of 0, and the validation shippingMethodValidation.productType with rule: deny blocks the shipping method as soon as a regular product (product type standard) is in the basket — so it can only be selected for pure voucher baskets.

{
  "active": true,
  "basicCost": [
    {
      "cost": 0,
      "subtotal": 0
    }
  ],
  "description": "checkout.shippingMethod.INSTANT_VOUCHER.description",
  "group": null,
  "id": "INSTANT_VOUCHER",
  "image": "",
  "link": "",
  "name": "checkout.shippingMethod.INSTANT_VOUCHER.name",
  "orderText": "checkout.shippingMethod.INSTANT_VOUCHER.orderText",
  "taxable": true,
  "type": "standard",
  "validations": [
    {
      "options": {
        "rule": "deny",
        "ruleList": [
          "standard"
        ]
      },
      "service": "shippingMethodValidation.productType"
    }
  ],
  "weightCost": null
}

The value standard in the ruleList is the value of the product type field of the products (the product data field defined as product type via content.usedFields) — not to be confused with the shipping method’s own type: "standard" parameter. Products for which the product type field is not set always pass the check.name, description and orderText refer to text snippets in this example, so the texts can be maintained per language via the text-snippet service.

Offering purchased vouchers for download

This example is not about redemption but about selling: if a purchase voucher product was ordered, the shop generates a voucher code per ordered unit at order completion. The codes of a basket position are available in the template under voucherIds; the associated PDF is generated via the URL parameter wsfilter=pdf from the view template stored on the product. The following block outputs a download link per position and code. It is suitable for the order confirmation page and for the email template of the order confirmation.

{{ foreach $basketItem in $wsBasket.items }}
   {{ if $basketItem.product.custom.voucherProductActive }}
      {{ foreach $voucherId in $basketItem.voucherIds }}
         <a href="{{= $wsViews.viewUrl('voucher/default_voucher.htm', {
             voucherId: $voucherId,
             productId: $basketItem.product.id,
             wsfilter: 'pdf'
         }, 'absolute') }}">
            Download voucher {{= $voucherId }}
         </a>
      {{ /foreach }}
   {{ /if }}
{{ /foreach }}

The type absolute generates a complete URL because emails cannot process relative links. The parameters voucherId and productId make the call independent of the session, so the link still works later on.voucher/default_voucher.htm stands here as a placeholder for the view template stored on the product in the “HTML template” field. How PDF views are built is described in PDF views.

For further processing outside the shop, the same information is available in the order data under data.orderList.item[].voucher, see API reference orders.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

Practical examples - Vouchers

Voucher input form with `maximumCount` check

Displaying the list of redeemed vouchers

Displaying all redeemed vouchers in the basket

Output voucher errors with reason and voucher ID

Free shipping method for voucher-only baskets

Offering purchased vouchers for download

​Voucher input form with maximumCount check

​Displaying the list of redeemed vouchers

​Displaying all redeemed vouchers in the basket

​Output voucher errors with reason and voucher ID

​Free shipping method for voucher-only baskets

​Offering purchased vouchers for download

Voucher input form with `maximumCount` check

Displaying the list of redeemed vouchers

Displaying all redeemed vouchers in the basket

Output voucher errors with reason and voucher ID

Free shipping method for voucher-only baskets

Offering purchased vouchers for download