CanVoucherApply Machine

Overview

Checks a sale to see if voucher products are present and that the conditions for redemption are valid.

A typical use is where serialised discount vouchers are being used. The salesperson can scan the voucher to apply to the sale, and this machine can be called near sale completion to ensure that the voucher is valid for use on this sale. This involves checking conditions such as expiry dates, voucher reuse, and excluded products. Essentially, this machine allows you to scan discount vouchers at any time during a sale and check the validity on an ongoing basis.

Interface

Pin#	Name	Contents
» 101	VoucherPid	Product Id of products that are vouchers.
» 102	ExcludePids	Product Ids of products that are not permitted for voucher discounting.
» 105	MaxVoucher	Maximum number of vouchers permitted per sale. This has a default of 1 voucher per sale. A value of 0 means an unlimited number of vouchers are permitted.
» 106	StartDate	Date before which this machine will always not allow vouchers to be used. Default value is not set.
» 107	EndDate	Date after which this machine will always not allow vouchers to be used. Default value is not set.
» 108	ExcludeDiscounts	If a product has already been discounted, had price overriden or otherwise, is it an excluded line. Load 1 to block discounted items as valid lines. Default is 0 which means discounted items are not checked. This machine cannot detect all methods of discounts and temporary price overrides
» 109	VoucherReuse	Check a voucher for validity if vouchers are uniquely numbered. This is pin is a coded value: 0. Do not check for reuse, freely allow reuse 1. (default) Check for reuse, but if unable to check fully (such as network offline) ALLOW voucher use. 2. Check voucher for reuse and FAIL if checks cannot be performed.
200 »	IsOK	Overall yes (1) or no (0) value. Indicates if sales are deemed suitable to progress or not. See information below for how this value is decided. A value of 2 will be returned if the voucher is ok but only partially redeemed.
201 »	OutputText	English technical descriptive text describing the error condition. This pin can also have a value when IsOK is yes, it is not limited to error conditions
202 »	VoucherCount	Total number of vouchers present on the sale
203 »	VoucherValue	Total Value of presented vouchers present on the sale
204 »	ErrorCode	Coded Number of which test failed. Where multiple tests fail, only one will be returned. Zero is never returned on this pin. Each test returns a different error code. Undocumented codes may be encountered in rare situations.
205 »	VoucherUsed	Total Value of vouchers applied. This figure can be lower than the voucher value presented (pin203), but will never be higher. This pin is only valid when IsOK (pin200) is 1 or 2.
206 »	VoucherLine	POS item number on sale for voucher. If more than one voucher is present this value will choose a voucher at random.

Logical Operation

Tests may be performed in any order unless explicitly stated. The following is only a logical overview not a guarantee of order.

Test		IsOK	Voucher Count	Voucher Value	Error Code
If no voucher products are defined or present on the sale (Performed first)	ALLOW	1	0	0	20

Count the number of vouchers on the sale. If this exceeds MaxVoucher (pin105)	FAIL	0	Valid	$	21

If dates are present (StartDate, EndDate) verify the sale date/time is between these times	FAIL	0	Valid	$	22

If the only non voucher products on the sale are all in the ExcludePids list. Fail. If there is a mixture of excluded and valid products, continue, but ignore the excluded products. This check also includes and excludes line items based on ExcludeDiscounts (pin 108). Note, this test will also fail if NO items exist on which the voucher can apply.	FAIL	0	Valid	$	23

Check for voucher reuse	FAIL	0	Valid	Not Set	Used: 24 Check Failed: 25

Ensure the value of the sale, after removing excluded items is positive. Return sales are therefore excluded.	FAIL	0	Valid	$	26

All tests ok	ALLOW	1	Valid	$	1

Examples

Using POS script, check sale for vouchers on product id #15966. With an expiry date of 31 March 2015

<fpscript name="machine_example_1">
	// First create the machine and set the input pins.  Sale is automatically loaded
	set t = machine(name(CanVoucherApply) pin(101,15966) pin(107,"31-mar-2015"))

	// Now just read the output pins we are interested in
	if (%t.IsOK%)
	then
		message(99,1,No problems - no voucher OR acceptable)
	else
		if (%t.ErrorCode% == 22) message(99,1,Voucher has expired)
	endif
</fpscript>