Vouchers

Contents

• Overview
• Issuing Vouchers and Monitoring Voucher Redemption
• Voucher Types
• Standalone vs. On-The-Fly Vouchers
• Important Properties of a Voucher
• Voucher Status
• Voucher Locking
• Redeeming Vouchers
• Associated API Endpoints

Overview

In the Spaaza data model, a ‘voucher’ does not only describe a “coupon” concept of a reserved right to a monetary discount on a retailer or customer organisation’s products and services, or a free product. Spaaza’s definition of a voucher broadly means a “title” or “right” which an end-user (customer) can exchange with a retailer or customer organisation against a defined item, reward or other object. In Spaaza, a voucher can be a title to a monetary or percentage discount, a free item, an experience or even an action taken by a third party.

A Spaaza voucher is always tied to a campaign configured in the Spaaza backend. What a voucher entitles an end-user (customer) to depends on the configuration details of the campaign and the type and configuration of the voucher itself.

Some examples of what vouchers are used to represent in the Spaaza data model:

• A fixed percentage discount on a purchase in a participating store or e-commerce site
• A free product when ordering a particular other item on an e-commerce site
• A monetary wallet amount converted into a discount on a purchase
• 10 minutes of free driving when you join a car-sharing service
• A personalised percentage discount on an individual item
• Free branded items in third-party stores
• Invitations to events
• The planting a specified number of trees by a charity when a customer has purchased certain items or services

Vouchers can be redeemed in a transaction or other event using the Spaaza API. The process of redeeming a voucher is described in the “Redeeming Vouchers” section below. It is important to note that voucher redemption mechanisms are generic, i.e. they are not specific to the type of voucher redeemed, meaning that API client logic does not need to be aware of the type of voucher being redeemed.

Issuing Vouchers and Monitoring Voucher Redemption

Vouchers can be issued automatically when certain events occur, such as when an end-user (customer) registers for an account or makes a purchase above a certain value, in bulk using Spaaza tasks, or individually using Spaaza’s voucher creation endpoint.

In almost all cases, how vouchers are issued is managed using the campaigns configuration section in the Spaaza Console portal. Redemption analytics can be tracked via the Spaaza console using our realtime analytics and graphing tools.

Voucher Types

It is possible to configure and manage multiple types of voucher through the Spaaza API. A brief explanation of each voucher type is provided below:

• Basket - a basket voucher provides a monetary discount at order level on a basket.
• Percentage Basket - a percentage basket voucher provides a percentage discount at order level on a basket.
• Honour - an honour voucher provides a title to “honour” a third-party promotion and is usually configured with a specific “honour code” which is used to identify the promotion in the third-party system. This is often used to issue free items or provide discounts in third-party locations. Honour vouchers can be used anonymously or tied to individual end-users (customers).

Standalone vs. On-The-Fly Vouchers

It is important to distinguish between the following two groups of voucher:

• Standalone - a standalone voucher is a voucher which is created in the Spaaza backend and is not tied to a specific transaction or event. Standalone vouchers exist, and are available to the end-user, before a transaction or redemption event takes place.
• On-The-Fly - an on-the-fly voucher is a voucher which is created in the Spaaza backend at the time of a transaction or redemption event, and is designed to represent a specific discount or title recognised by the logic of the API endpoint creating it.

Important Properties of a Voucher

The following is a list of some of the key properties of a voucher:

• Campaign - every voucher is tied to a campaign. A voucher’s campaign dictates its behaviour including when it can be awarded, how it can be redeemed, what happens if it is deleted or redeemed, whether a replacement is generated after a return, and many other aspects of its existence.
• Currency - a currency associated with a voucher. This field is not always populated. For example, in the case of an honour voucher, a currency may not be necessary.
• Description - a longer-form text field which can be displayed in a user interface.
• Discount Ratio - a percentage discount which applies to a “percentage basket” voucher, represented as a decimal.
• Expiry Date - a date and time beyond which it is no longer possible to change details of, or redeem, a voucher
• Image URL - the URL of an image which can be displayed in a user interface in association with a voucher.
• Key - every voucher has a unique key which can be used to identify it when retrieving details about it or carrying out actions on it such as claiming or redeeming it (see “Voucher status” section).
• Third Party ID - field is an optional unique identifier that can be used to identify it when retrieving details about it or carrying out actions on it such as claiming or redeeming it. This identifier is only applicable and assigned to vouchers where their chain has uses_third_party_voucher_id set true.
• Locking - to prevent fraud, a voucher can and should be locked during a transaction - see “Voucher locking” section below.
• Parent Voucher - in the case that a voucher has been redeemed in a transaction, and items purchased in that transaction are subsequently returned, a new voucher is created which represents the value of the voucher originally redeemed on the item(s) in the purchase transaction. The original voucher is listed as the “parent” of the new voucher.
• Status - see “Voucher status” section below.
• Title - a title or text string which can be displayed in a user interface.
• Value - a monetary value assigned to a voucher. This field is not always populated, for example in the case of an honour voucher, which may be redeemed in exchange for a free item.

Voucher Status

Each voucher in Spaaza has a status. A voucher’s status dictates which properties a voucher can exhibit and which actions can be carried out on a voucher. The statuses are as follows:

• generated - a voucher exists in the Spaaza data store and may have been assigned to an end-user (customer), but cannot yet be redeemed or exchanged (until it has “claimed” status).
• claimed - an end-user (customer) who “owns” the voucher or an admin user or system has flagged the voucher as being ready to be redeemed in a transaction or other event. In order to be redeemed, a voucher must have this status.
• redeemed - a voucher has been redeemed (used) in a transaction or other event. The voucher can no longer be used or be altered in any way.

The following points regarding voucher status are also to be noted:

• A voucher is normally created with a status of ‘generated,’ but it is possible to configure a campaign to “auto-claim” vouchers when they are created, meaning they will be created with status ‘claimed’.
• It is possible to claim or unclaim a voucher using the claim-voucher and unclaim-voucher endpoints. It is not possible for an end-user (customer) to unclaim a voucher which is “locked” (see “Voucher locking” section).

Voucher Locking

To prevent fraud a voucher should be locked before it is redeemed. This prevents an end-user (customer) making adjustments to a voucher when, for example, the value of the voucher is being used as a discount on a transaction. During the time a voucher is locked, it can only be adjusted by an administrative user or using privileged authentication.

A voucher has the following properties related to locking:

• Locked status - if a voucher is locked it will show "locked": true in API responses
• Locking period - a voucher is locked for a period of time. This is shown by the voucher_locked_until field in API responses for a locked voucher, a field representing a date and time until which the voucher is locked
• Exclusive retailer basket code - if a voucher is locked and can only be redeemed by a transaction with a specific retailer_basket_code, this is shown in the voucher_retailer_basket_code_exclusive field.
• Locking code - it is also possible to lock a voucher using a specific code which must also be supplied to redeem the voucher - this is shown in the voucher_locking_code field.

There are 3 ways a voucher can be locked:

• Automatically - during a transaction, when a call is made to the get-basket-price API endpoint, claimed vouchers are automatically locked for the default locking period (usually 5 minutes). If the basket_voucher_lock_exclusively parameter is also supplied, vouchers are locked so that they can only be redeemed by a call to the add-basket API endpoint with the same retailer_basket_code value. It is also possible to specify a different voucher_locking_code using this method, should retailer_basket_code not be a predictable value.
• On Creation - when using the create-voucher API endpoint it is possible to specify a voucher_lock_period to lock the voucher.
• Voucher Locking API Endpoint - the lock-voucher API endpoint can be used to explicitly lock a voucher.

When used with admin or privileged authentication, the unlock-voucher API endpoint can be used to unlock a voucher should that be necessary.

Redeeming Vouchers

There are currently two possible ways to redeem a voucher:

• Transaction - the normal flow is that i) a call is made by a client to the Spaaza get-basket-price API endpoint containing the provisional basket contents. The endpoint responds with JSON containing one or more claimed, unexpired vouchers. Then, ii) these are added to the payload of a call to the add-basket API endpoint and the voucher is redeemed. Should it not be possible to redeem the voucher, the API call will not error, but will return a warning inline in the response.
• Direct - it is possible to redeem a voucher directly using the redeem-voucher API endpoint. This is useful in the case of vouchers which are not redeemed in a transaction.

Please see the “Basket Discounts and Vouchers” and following sections in the add-basket API endpoint documentation for more information about redeeming vouchers in a transaction.

Associated API Endpoints

---

Table of contents

• Claim voucher
• Claim vouchers
• Create voucher
• Delete vouchers
• Expire voucher
• Get user vouchers
• Get vouchers
• Lock vouchers
• Redeem vouchers
• Unclaim vouchers
• Unlock vouchers
• Voucher priority rules