$wsVoucher - Vouchers - WEBSALE Dokumentation

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

Name	Type	Description
`vouchers`	array	List of vouchers that are queued for redemption.
`totalValue`	float	Total value of the redeemed vouchers.
`totalUsedValue`	float	Value of the vouchers already used.
`maximumCount`	int	Maximum number of vouchers that may be redeemed at the same time. `0` = no limit set.
`load()`	map	Loads 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

Name	Type	Required	Description
`id`	string	yes	ID 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

Variable	Type	Description
`id`	string	Voucher ID.
`value`	float	Value of the voucher.
`currency`	string	Currency of the voucher.
`taxId`	string	Tax rate ID of the voucher.
`usedValue`	float	Value of the voucher already redeemed.
`percentValue`	float	For percentage vouchers, `percentValue` is filled (e.g. 10 for 10%); for fixed-amount vouchers, `absoluteValue` is filled (e.g. 5.00 for €5).
`absoluteValue`	float	For percentage vouchers, `percentValue` is filled (e.g. 10 for 10%); for fixed-amount vouchers, `absoluteValue` is filled (e.g. 5.00 for €5).
`validFrom`	string	Valid from (date).
`validUntil`	string	Valid 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.

Voucher settings
Practical examples for vouchers
Error texts for ineffective vouchers
$wsCheckout.ineffectiveVoucherErrors - Error list for vouchers that do not apply in the basket

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsVoucher - Vouchers

Module overview

Templates

Variables

$wsVoucher.vouchers

$wsVoucher.totalValue

$wsVoucher.totalUsedValue

$wsVoucher.maximumCount

Methods

$wsVoucher.load()

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

Actions

Example for displaying voucher data

Voucher value

Voucher type: percentage or fixed amount

Validity date of the voucher

Voucher currency

Display remaining amount of a voucher

Check voucher validity

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

​Module overview

​Templates

​Variables

​$wsVoucher.vouchers

​$wsVoucher.totalValue

​$wsVoucher.totalUsedValue

​$wsVoucher.maximumCount

​Methods

​$wsVoucher.load()

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

​Actions

​Example for displaying voucher data

​Voucher value

​Voucher type: percentage or fixed amount

​Validity date of the voucher

​Voucher currency

​Display remaining amount of a voucher

​Check voucher validity

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

​Related links

Module overview

Templates

Variables

$wsVoucher.vouchers

$wsVoucher.totalValue

$wsVoucher.totalUsedValue

$wsVoucher.maximumCount

Methods

$wsVoucher.load()

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

Actions

Example for displaying voucher data

Voucher value

Voucher type: percentage or fixed amount

Validity date of the voucher

Voucher currency

Display remaining amount of a voucher

Check voucher validity

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

Related links