API Overview
Introduction
Uniqodo’s APIs enable merchants to validate, redeem and check voucher codes issued via Uniqodo. This may be through code distributors on their website, mobile application or in-store point of sale systems.
Various pieces of information are needed to guide the functionality of the APIs - this guide explains what values are required and the response received when making each type of API call.
There are three APIs in total and these can be applied in conjunction. Each is described in the table below:
API | Purpose |
The Validation API is used to validate a code - i.e. to determine whether or not it is usable - and to receive a response that allows the merchant to know which offer to apply to the purchase. | |
The Redemption API is used to track a successful order through Uniqodo and to allow an issued code to be expired after it has been redeemed or used. | |
The Code Query API can be used to perform a lookup on a given coupon code and retrieve the associated promotion details and code validity information. Any redemptions that have taken place with that code will also be returned in the response. |
Important Considerations when using the APIs
Storing Validated Codes for Redemption
When a call is made to validate a code, the code must be stored so that it can be redeemed later using the Redemption API. Once the voucher code has been validated, it should be stored for as long as there are items in the basket and the purchase remains possible. This may necessitate storing the voucher code across sessions.
Validation Lock
By default, the validation API allows a voucher code to be repeatedly validated until a redemption occurs against the code. If multiple shoppers have the same single-use code and attempt to use it simultaneously, it is possible for more than one shopper to validate the same code - until one of the shoppers completes a purchase. This could mean multiple shoppers having the same code applied to their purchase. To prevent this scenario, a validation lock period can be set for the merchant that prevents a repeat validation of a code within a specified time period. The validation lock period is set in minutes and can be changed by Uniqodo staff upon request.
Auto-filling Codes
When Uniqodo issues voucher codes to distributors, it provides the URL that the merchant provided to set up the code offer. This URL is then used by the distributor to redirect shoppers through to the merchant's website. Uniqodo automatically appends to the URL, a parameter containing the voucher code issued to the shopper. This can be stored by merchants so that the value in the code entry field is autofilled, which allows shoppers on touch screen mobile devices to use codes on merchants' websites more readily.
The URL follows the format below, with the “uqd” parameter in the query string containing the voucher code value (see what follows the '=' sign).
http://www.example.com/?uqd=GL7SCBKL
Promotion Security
Uniqodo never makes a trigger code public but to provide an additional layer of security, trigger codes are prevented from being redeemable through the code entry field on your website. For example - if a '£100 off' promotion is created with the trigger code “100OFF” and 20 unique codes are made available for promotion, only the unique codes issued by Uniqodo would be able to trigger the offer; entering "100OFF” would not work.
Email Addresses and Data Protection
Uniqodo can issue voucher codes to shoppers and capture their email address simultaneously. This is useful for email marketing campaigns in which a voucher code is issued to a shopper and linked to their email address. In such campaigns, Uniqodo is able to ensure that voucher codes are only validated and redeemed alongside an email address.
If you wish to offer email-address-secured voucher codes (secure codes), you will need to be able to pass the email address at the point a voucher code is validated using the 'Validation API'. If the shopper has not logged in or entered their email address before attempting to validate the secure code, you may need to prompt the user to enter their email address or ask them to login (or create an account).
Uniqodo never stores email addresses in plain text format and always hash encrypts the address as soon as it is received. The email address is then unreadable by Uniqodo.
