|Coupon, Discount, Personal Price|
|Parameter Names Used|
- Issuing Vouchers and Monitoring Voucher Redemption
- Voucher Types
- Important Properties of a Voucher
- Voucher Status
- Voucher Locking
- Redeeming Vouchers
- Associated API Endpoints
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 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.
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.
- 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).
- Percentage Basket - a percentage basket voucher provides a percentage discount at order level on a basket.
- Variable Price (Product) - a variable price or product voucher denotes the right to a personalised percentage or monetary discount on a product at item level in a basket.
- Variable Price Meta (Product Meta) - a variable price metavoucher denotes the right to variable prices on one of a range of products in a basket. During the basket process, a variable price metavoucher is converted into a variable price voucher which is redeemed in a confirmed basket.
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).
- 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.
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).
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": truein API responses
- Locking period - a voucher is locked for a period of time. This is shown by the
voucher_locked_untilfield 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
- 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
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_exclusivelyparameter 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_codevalue. It is also possible to specify a different
voucher_locking_codeusing this method, should
retailer_basket_codenot be a predictable value.
- On Creation - when using the create-voucher API endpoint it is possible to specify a
voucher_lock_periodto 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.
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.
|get-card||Getting the “card” of an end-user (customer)|
|create-voucher||Creating a voucher|
|claim-voucher||Setting a voucher to “claimed” status|
|lock-voucher||Locking a voucher|
|expire-voucher||Expiring a voucher explicitly|
|delete-voucher||Deleting a voucher|
|get-vouchers||Getting all vouchers for an organisation, filterable to single voucher level|
|get-user-vouchers||Getting all vouchers for an end-user (customer)|
|get-basket-price||Requesting adjustments for a basket/transaction|
|add-basket||Confirming a basket/transaction|