API: Code Redemption
The Redemption API is used to track a successful order through Uniqodo and to allow a code to be expired after it has been redeemed/used.
- The API should only be queried using the coupon code provided by the customer (i.e. the Uniqodo code), not the merchant's own master / trigger code.
- You will need to persist the code used by the customer on the basket or checkout page (alongside the associated validation key) so that you can access and send it to the redemption API on the order confirmation page.
- The API should only be called when a transaction is confirmed and the code issued needs to be redeemed - typically when the customer reaches the order confirmation page.
- It is important to make sure that the call is made to the API to redeem a code; if this does not happen, the code will still be valid and usable.
End Point:
https://api.uniqodo.com/redeem/YOUR_API_KEY/CODE/YOUR_MERCHANT_ID
Example API call:
For merchant ID 1 using the API key 64a287ae534cf1bd58f45f3e23de9d433caec669, the code AB12E3GH is redeemed with order details in query string as below:
https://api.uniqodo.com/redeem/64a287ae534cf1bd58f45f3e23de9d433caec669/AB12E3GH/1?orderId=145789&orderValue=219.99&disount=50.95&valKey=f458re9we73wd23dwqd23ed32d23123d2ed433d323d3 ¤cy=GBP&p1=example1&p2=example2&p3=example3&p4=example4&p5=example5
Parameters:
Parameter | Description | Example | Type | Required? |
YOUR_API_KEY | The API key assigned to the merchant. Found on | 50d858e0985ecc7f60418aaf0cc5ab587f42c257 | String | Yes |
CODE | The code provided/used by the customer. | AB12E3GH | String | Yes |
YOUR_MERCHANT_ID | The Uniqodo ID for the merchant making the API call to redeem a code. Please check your details on the Uniqodo interface. | 1 | Integer | Yes |
valKey | The validation key received from the Uniqodo's Validation API when the customer added the promo code to their basket /checkout, during which the code was verified with Uniqodo. See the Validation API for details. | f458re9we73wd23dwqd23ed32d23123d2ed433d323d3 | String | Yes |
discount | The discount value that the customer received on the order, if any. Set this value to an empty string if no discount was applied. | 50.95 | Float | Yes |
currency | The currency of the transaction. | GBP | String | Yes |
orderId | The merchant’s unique ID for the transaction. | ABC123456 | String | Yes |
orderValue | The value of the transaction. | 24.99 | Float | Yes |
p1, p2, p3, p4, p5 ... | A custom value for reporting and data segmentation. For example, these parameters could contain customer type i.e. new or existing, location e.t.c | p1=electricals&p2=UK... | String | No |
source | The site or environment where this code redemption is taking place. You could pass values such as 'online' for transactions that take place on the eCommerce website and 'retail' for in-store transactions. | online | String | No |
uid | The unique identifier for the customer (such as an email or account ID) making the purchase. This is only required if the code being redeemed is a secure code type. | example@email.com | String | No |
Response:
Item | Description | Example |
id | A unique ID for the code validation. | 126478 |
offer_id | The ID of the offer associated with this code. | 1256 |
merchant_id | The ID of the merchant redeeming the code. | 56 |
distributor_id | The ID of the distributor that issued the code to the shopper. | 23 |
code | The code redeemed via the API call. | XY23T4DF |
order_value | The value of the transaction excluding VAT. | 219.99 |
order_id | The id passed with the order value in the api call | ABC123456 |
currency | The currency of the transaction. | USD |
client_user_agent | The details about the user’s web browser. | Mozilla/5.0 (Macintosh; |
custom_params | The serialised custom parameter data submitted with the redemption API for reporting and data segmentation purposes. | {\"p1\":\"example1\", |
redeemed_at | The UTC date and time that the code redemption occurred. | 2015-05-29T10:39:17+0000 |
Errors (All APIs)
Error code | Message | Reason |
101 | Invalid API key supplied | The API key entered is not a valid API key |
201 | Code already redeemed | The code entered has already been redeemed |
202 | Offer for this code has expired | The offer that the code is associated with has expired |
204 | Code not recognised | The code entered is not a valid or a code issued by Uniqodo |
206 | No more codes available | The limit for how many codes can be redeemed has been reached |
210 | This code has been used n times and can't be used further. | The multi-use unique has reached the number of time it can be redeemed |
