====== Vouchers ======

If you want to use vouchers as incentives, you can manage them under **Special Features** -> **Manage Voucher Codes**.

The ''voucher()'' function retrieves a voucher code from the list and records the person to whom it was issued.

Each voucher code and each retrieval is assigned to a “drawing.” This allows you to issue voucher codes of varying values within a survey project, or to issue multiple voucher codes to the same person across multiple survey waves.

**Note** This feature has been disabled on the server %%www.soscisurvey.de%%. It is available on the Pro server %%s2survey.net%%.


===== Safety =====

Coupon codes can sometimes have considerable monetary value. Please note the following:

  * Be aware of potential fraud attempts when using coupons.
    * People may claim to have completed the survey but not received a coupon.
    * People will try to complete the survey multiple times to obtain multiple coupons.
    * People working on the survey project may be tempted to use the voucher codes themselves.
  * Any user account that has access to the voucher feature ([[:en:general:authorization]]) can retrieve the voucher codes directly.
  * Any user account authorized to **Compose a Questionnaire** can retrieve the coupon codes indirectly through the questionnaire.
  * Make sure to use coupon codes only in conjunction with an access-restricted questionnaire  ([[:en:create:access]]), for example via [[:en:survey:mailing|Mailings]].
  * If you do use coupons in a public survey, there is a risk that bots will “fill out” the survey just to retrieve as many coupons as possible. In this case, use an effective Captcha and other bot detection methods. Note that even these features cannot provide protection against advanced bots.


===== Import of Voucher Codes =====

Copy and paste the coupon codes into the input field under **Special Features** -> **Manage Voucher Codes** -> //Import Voucher Codes//.

  * Individual codes can be separated by line breaks and/or commas.
  * Characters that are not Latin letters (A–Z), Arabic numerals (0–9), hyphens, or colons are automatically removed—including, for example, quotation marks that Excel inserts when copying.
  * Coupon codes that already exist in the survey project are ignored during import.

Below are some examples of valid import formats:

<code>
55m5Hj40-FBKYQwLn-tRcBAUJn-5mF8ArS0
0wDcxXUD-myDUR6RD-6Atr9Qse-XJEwRN61
QmmWWJgJ-8A8vuCcX-Llc2a10t-pDCqUSie
ANVE251r-pqT5Rerm-oU30Ujzq-BHibeuZA
EENIjrr1-35rTXjxr-qsiTa8dk-YPVVx42i
PMt5KNjZ-MoN3Fj5Q-Lmgl4Viz-hAQYKXvG
</code>

<code>
55m5Hj40-FBKYQwLn-tRcBAUJn-5mF8ArS0, 0wDcxXUD-myDUR6RD-6Atr9Qse-XJEwRN61, QmmWWJgJ-8A8vuCcX-Llc2a10t-pDCqUSie, ...
</code>

<code>
"55m5Hj40-FBKYQwLn-tRcBAUJn-5mF8ArS0",
"0wDcxXUD-myDUR6RD-6Atr9Qse-XJEwRN61",
"QmmWWJgJ-8A8vuCcX-Llc2a10t-pDCqUSie",
"ANVE251r-pqT5Rerm-oU30Ujzq-BHibeuZA",
"EENIjrr1-35rTXjxr-qsiTa8dk-YPVVx42i",
"PMt5KNjZ-MoN3Fj5Q-Lmgl4Viz-hAQYKXvG"
</code>

During import, the raffle with number 1 is preselected. Change the preselection if you want to manage the vouchers separately from other coupon codes.


===== Issuing Coupon Codes =====

To select voucher codes, use the''voucher()'' function.

''string|NULL **voucher**(string //person_id//, [int //draw//], [bool //new_draw//])''

  * //person_id// -- A unique identifier for the person receiving the voucher
  * //draw// -- (optional) The number of the draw from which the voucher code should be selected
  * //new_draw// -- (optional) Should a voucher code be drawn for the person ID if none has been drawn for that ID in this drawing yet (Standard: ''true''). If set to ''false'' and no code has been drawn for the person ID in the drawing, the return value is ''null''.

The ''voucher()'' function always returns the same voucher code for a given combination of person ID and raffle. The page containing the voucher code can therefore be displayed multiple times. You can also provide a separate questionnaire where respondents can view the voucher code again.

If no voucher codes are available in the specified raffle, the function returns ''null''.

**Note:** If you are testing the questionnaire as a project manager, the ''voucher()'' function will only return a dummy voucher code (e.g. ''EXAMPLE-123456-7890''). Real voucher codes are used only for interviews (MODE=interview).

==== Displaying a Coupon Code in the Questionnaire ====

The person ID from the address entry in a mass email campaign (SERIAL) or a participation code can be used as the person ID. Both are available via ''caseSerial()''.

<code php>
$person = caseSerial();
$voucher = voucher($person);
html('<p>Your Voucher Code is: <strong>'.$voucher.'</strong></p>');
</code>

If another voucher is to be issued to the same person in a later survey wave, import voucher codes for drawing No. 2 and specify the number 2 in the ''voucher()'' function:

<code php>
$person = caseSerial();
$voucher = voucher($person, 2);
html('<p>Your Voucher Code for Wave 2 is: <strong>'.$voucher.'</strong></p>');
</code>

Take into account the possibility that all coupon codes will be used up during the survey.

<code php>
$person = caseSerial();
$voucher = voucher($person);
if ($voucher) {
    html('<p>Your Voucher Code is: <strong>'.$voucher.'</strong></p>');
} else {
    html('<p>There are no more Voucher Codes available. Please contact us at ....</p>');
}
</code>

In public questionnaires, the case number can also be used as a personal identifier. However, be sure to prevent bots from automatically filling in the form.

<code php>
// Only use this variant with great care!
$person = 'C'.caseNumber();
$voucher = voucher($person);
html('<p>Your Voucher Code for this interview is: <strong>'.$voucher.'</strong></p>');
</code>


==== Showing a Coupon Code again ====

If respondents did not write down the code, you can create an additional questionnaire that displays the coupon code again. To do this, set the third parameter of the ''voucher()'' function to ''false''. This ensures that someone who did not complete the original questionnaire — and therefore did not receive a coupon — cannot obtain one through this “shortcut.”

<code php>
$person = caseSerial();
$voucher = voucher($person, 1, false);
html('<p>Your Voucher Code from Wave 1 is still: <strong>'.$voucher.'</strong></p>');
</code>