{warning} This API is likely to change before the Beta period is over, please check back regularly to see the latest changes.
By passing a Site ID and Voucher Number you can check what, if anything is redeemable for the voucher provided.
POST REQUEST (/redeem/check)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXXYou can find the site number you should submit along with this request in the company configuration on the Smart Gift dashboard.
{
"voucher_no":"XXXXXXXXXX",
"site_id": "X"
}There are 2 types of voucher with Smart Gift: monetary vouchers and experience vouchers.
In the case of monetary vouchers, it is the 'remaining_value' field which indicates the amount of value left on the voucher. In the following call to /redeem, an amount between 0.01 and the value of this field can be redeemed.
{
"data": {
"id": 11400,
"name": "Sample Monetary Voucher",
"description": "A sample monetary voucher",
"voucher_no": "XXXXXXXXXX",
"remaining_value": 10,
"type": "monetary",
"sold_out": false,
"experiences": []
}
}With experience vouchers, there will be an array of redeemable experiences returned in the 'experiences' field which represent what can be redeemed at the current site, if no experiences can be redeemed then a descriptive 422 response will be returned instead. In the case of experience vouchers, the value of the 'remaining_value' field will actually be the sum of the 'bit_value' field values for all remaining experiences on the voucher. Please note however that you cannot assume that the 'remaining_value' field value will equal the sum of 'bit_value' field values for the listed experiences of this response; this will only list the experiences redeemable at the site with the site_id passed in the request whereas 'remaining_value' will be the sum of all unredeemed experiences across all sites.
{
"data": {
"id": 1,
"name": "Tour & Tasting",
"description": "The tour of the Estate allows you to see how we turn our grapes into Sussex Sparkling wine. Walking through the vines in a small group with our experienced guide, exploring the Vineyard, history and wildlife of the Estate allows for full appreciation of Rathfinny’s place in this classic landscape. During this enjoyable tour, the group learns how a typical year of growing vines and wine production progresses and ends with a tasting of our Sussex wines. Among the highlights are a visit to our RIBA nominated Winery and modern Bottling building. Tours run on selected dates, May to September. To book, please call the Cellar Door on 01323 870022 or email cellardoor@rathfinnyestate.com. Booking in advance is essential and please mention the voucher at the time of booking. \r\n\r\nThis voucher is valid for 24 months after purchase.",
"voucher_no": "XXXXXXXXX",
"remaining_value": 3,
"type": "experience",
"experiences": [
{
"id": 1063,
"name": "Tours",
"site_id": 14,
"site_name": "Cellar Door",
"bit_value": 1,
"price": 15.00,
"revenue": {
"id": 100,
"name": "Tours",
"mapping_code": "1001", // department mapping code
"product_code": "1002", // additional mapping code for product or other reference
"rate": {
"id": 2,
"name": "5 Percent VAT",
"rate": 5,
"percent_text": "5%"
}
}
},
{
"id": 1064,
"name": "Tasting",
"site_id": 14,
"site_name": "Cellar Door",
"bit_value": 2,
"price": 9.50,
"revenue": {
"id": 101,
"name": "Tasting",
"mapping_code": "1001",
"product_code": "1002",
"rate": {
"id": 2,
"name": "5 Percent VAT",
"rate": 5,
"percent_text": "5%"
}
}
}
]
}
}If a voucher with the number you've provided does not exist, you will be returned the following response:
{
"message": "Sorry, that voucher number is invalid.",
"errors": {
"voucher_no": [
"Sorry, that voucher number is invalid."
]
}
}If the site id you pass with your request does not belong to the company that the Smart-Auth header authenticates you as, you will be returned the below response:
{
"message": "This site number is invalid",
"errors": {
"site_id": [
"This site number is invalid"
]
}
}If a voucher number is provided that matches an existing voucher, but that voucher does not belong to the company that the Smart-Auth header authenticates, the response below will be shown. This response is rare outside of development but may occur for customers that have a group of companies (each with their own company in Smart Gift), as their end users may confuse the entities.
{
"message": "This voucher does not belong to your company",
"errors": {
"voucher_no": [
"This voucher does not belong to your company"
]
}
}Vouchers can be assigned optional expiry dates, the customer is able to set a start date and end date for voucher validity which will ultimately affect when the purchaser of the voucher is able to redeem it. If the current time does not fall between the start and end dates for the voucher's validity, the below message will be returned.
{
"message": "The voucher number provided has expired.",
"errors": {
"voucher_no": [
"The voucher number provided has expired."
]
}
}If a voucher still has valid experiences but does not have any experiences that can be redeemed at the current site, a 422 response will be returned with the below message:
{
"message": "None of the remaining experiences can be redeemed at this site",
"errors": {
"site_id": [
"None of the remaining experiences can be redeemed at this site"
]
}
}Finally, if a voucher is fully redeemed already, the response below will be returned. We do not currently expose a list of voucher transactions over the API, however the customer is able to see a full audit from within their dashboard.
{
"message": "Sorry this voucher has already been redeemed.",
"errors": {
"voucher_no": [
"Sorry this voucher has already been redeemed."
]
}
}