Skip to main content
With the $wsVoucher module, you can use and display voucher data dynamically in the frontend. You can list redeemed vouchers, calculate the total value, and load details for individual vouchers. In this section, you will learn how to retrieve voucher data and display it in the basket or checkout.

​
Module overview

Example / excerpt of $wsVoucher 
{{= $wsVoucher | json }}
JSON output 
{
  "vouchers": [...],
  "totalValue": 0.0,
  "totalUsedValue": 0.0,
  "maximumCount": 0,
  "load": "ƒ()"
}
Note: ƒ() denotes a function. Variables and methods overview
NameTypeDescription
vouchersarrayList of vouchers that are queued for redemption.
totalValuefloatTotal value of the redeemed vouchers.
totalUsedValuefloatValue of the vouchers already used.
maximumCountintMaximum number of vouchers that may be redeemed at the same time.
0 = no limit set.
load()mapLoads a voucher by its ID.

​
Templates

Voucher data can generally be loaded and displayed in any template. Entering or redeeming a voucher code is possible throughout the shop. However, it is most useful within the ordering process or in the basket.

​
Variables

​
$wsVoucher.vouchers

Returns a list of all vouchers that the customer has redeemed in the current basket. 
{{ foreach $myVoucher in $wsVoucher.vouchers }}
  Voucher: {{= $myVoucher.id }} – Value: {{= $myVoucher.value | currency }}
{{ /foreach }}

​
$wsVoucher.totalValue

Returns the total value of the redeemed vouchers. 
Voucher value: {{= $wsVoucher.totalValue | currency }}

​
$wsVoucher.totalUsedValue

Returns the voucher value already deducted from the basket. 
Already redeemed: {{= $wsVoucher.totalUsedValue | currency }}

​
$wsVoucher.maximumCount

Returns the maximum number of vouchers that a customer may redeem at the same time. 
Redeemed: {{= len($wsVoucher.vouchers) }} of {{= $wsVoucher.maximumCount }}

​
Methods

​
$wsVoucher.load()

Loads a voucher by its ID. Signature
$wsVoucher.load(id) Return value
Map - Voucher map with the voucher data. Parameters
NameTypeRequiredDescription
idstringyesID of the voucher.
Example that loads a voucher: 
{{ var $myVoucher = $wsVoucher.load("GUTSCHEIN123") }}
Value: {{= $myVoucher.value | currency }}
By using the $wsVoucher.load() function, various variables are available to retrieve and output voucher data. Below is an overview of which variables are available.

​
Voucher data (return value of $wsVoucher.load())

First, it is necessary to assign the map with the voucher data, as shown in the example above, to a local variable. This can then be used at various places in the template. JSON output 
{
  "id": "...",
  "value": 0.0,
  "currency": "...",
  "taxId": "...",
  "usedValue": 0.0,
  "percentValue": 0.0,
  "absoluteValue": 0.0,
  "validFrom": "...",
  "validUntil": "..."
}
Variables overview
VariableTypeDescription
idstringVoucher ID.
valuefloatValue of the voucher.
currencystringCurrency of the voucher.
taxIdstringTax rate ID of the voucher.
usedValuefloatValue of the voucher already redeemed.
percentValuefloatFor percentage vouchers, percentValue is filled (e.g. 10 for 10%); for fixed-amount vouchers, absoluteValue is filled (e.g. 5.00 for €5).
absoluteValuefloatFor percentage vouchers, percentValue is filled (e.g. 10 for 10%); for fixed-amount vouchers, absoluteValue is filled (e.g. 5.00 for €5).
validFromstringValid from (date).
validUntilstringValid until (date).

​
Actions

Actions for this module that trigger changes are documented separately in the “Actions” chapter: Voucher

​
Example for displaying voucher data

​
Voucher value

This example displays the value of the voucher. 
Voucher Value: {{= $voucher.value }}

​
Voucher type: percentage or fixed amount

This example checks and displays whether the voucher grants a percentage discount or a fixed amount. 
Discount type: {{= $voucher.percentValue | ifNull("Percentage Value is null")}} {{= $voucher.absoluteValue | ifNull("absolute value is nulll")}}

​
Validity date of the voucher

This example displays the start and end date of a voucher’s validity. 
Valid from: {{= $voucher.validFrom | dateFmt("%d.%m.%Y") }}
Valid until: {{= $voucher.validUntil | dateFmt("%d.%m.%Y") }}

​
Voucher currency

This example displays the currency in which the voucher was issued. 
Currency: {{= $voucher.currency }}

​
Display remaining amount of a voucher

This example displays the remaining amount that a partially used voucher still has. 
Remaining amount: {{= ($voucher.value - $voucher.usedValue) | currency }}

​
Check voucher validity

This example checks whether the voucher is basically valid. 
{{ if $voucherAddAction.success }}
  Voucher successfully added to the basket.
{{ /if }}

​
Show form only until the maximum number of vouchers has been redeemed

The form is only displayed if the number of vouchers already redeemed is less than the configured limit. If the limit is reached, the form is hidden and the customer receives a notice. 
{{ if len($wsVoucher.vouchers) < $wsVoucher.maximumCount }}
    <form method="post" action="{{= $wsViews.current.url() }}">
        <input type="text" name="id">
        <input type="hidden" name="wsact" value="{{= $voucherAddAction.id }}">
        <input type="hidden" name="wscsrf" value="{{= $voucherAddAction.csrf }}">
        <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">

        <button type="submit" class="btn btn-primary">Redeem</button>
    </form>
{{ /if }}
You can find more practical examples on the topic of vouchers here.