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.
Filters are an optional parameter which can be used to filter the voucher results. Filters can be used to filter by classifications, which are set against revenue centres in Smart Gift, and meta records which are stored against the voucher during creation.
Classifications affect the voucher's experience results that are returned. If you provide a classifications array, experiences will only be returned if their revenue centers match one of the classifications provided. This has no effect on monetary vouchers.
Meta conditions affect the voucher itself. If you provide a meta_conditions array, the voucher will only be returned if its meta records match the conditions provided, meta conditions work as AND logic rather than OR logic, so all meta conditions must be met for a voucher to be returned.
{
"voucher_no":"XXXXXXXXXX",
"site_id": "X",
"filters": {
"classifications": ["food_and_beverage"],
"meta_conditions": [
{
"key": "used_in",
"operator": "in",
"value": ["hotel", "bar"]
}
]
}
}There are 2 types of voucher with Smart Gift: monetary vouchers and experience vouchers.
| Field | Type | Description |
|---|---|---|
| id | integer | The unique identifier for the voucher |
| name | string | The name of the voucher |
| description | string | Description of the voucher |
| voucher_no | string | The voucher number |
| remaining_value | number | The remaining value on the voucher (monetary or sum of experience bits) |
| available_to_redeem | number | An object presenting the voucher value available to redeemed with the current set of parameters |
| type | string | Either "monetary" or "experience" |
| held_until | string or null | Expiry of the hold in ISO 8601 format or null if not held |
| sold_out | boolean | Whether the voucher is sold out |
| experiences | array | Array of redeemable experiences (empty for monetary vouchers) |
Please note that a hold_token does not need to be included to check a held voucher but if the voucher is held, one will
be needed if you want to redeem it (with either /redeem or /redeem-unified before the hold expires.
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,
"available_to_redeem": {
"as_bitmask": null,
"as_monetary": 10
},
"type": "monetary",
"held_until": null,
"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,
"available_to_redeem": {
"as_bitmask": 3,
"as_monetary": 24.50
},
"type": "experience",
"held_until": "2026-04-22T12:12:02.000000Z",
"sold_out": false,
"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",
"product_code": "1002",
"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%"
}
}
}
]
}
}| Field | Type | Description |
|---|---|---|
| id | integer | The id of the experience |
| name | string | The name of the experience |
| site_id | integer | The id of the site where the experience is redeemable |
| site_name | string | The name of the site where the experience is redeemable |
| bit_value | number | The value of the experience in bits |
| price | number | The price of the experience |
| revenue | object | Revenue information including mapping, product and rate |
| Field | Type | Description |
|---|---|---|
| id | integer | The unique identifier for the revenue item |
| name | string | The name of the revenue item |
| mapping_code | string | The mapping code for the revenue item (can be null) |
| product_code | string | The product code for the revenue item (can be null) |
| rate | object | Rate information including id, name, rate and percent_text |
| Field | Type | Description |
|---|---|---|
| id | integer | The unique identifier for the rate |
| name | string | The name of the rate (e.g., VAT rate name) |
| rate | number | The rate value as a number |
| percent_text | string | The rate as a percentage text (e.g., "5%") |
This object is most useful when querying experience vouchers but appears in the main object in both cases, it includes
the fields as_bitmask and as_monetary which give a convenient overview. For monetary vouchers, the as_monetary
value is the total amount available to redeem, and the as_bitmask field is always null. For the more configurable
experience vouchers, the as_bitmask field is the bit representation of the experiences that can be redeemed with the
current parameters (current site, filters, etc) and the as_monetary value is the monetary value of those experiences -
if you were to iterate over the experiences array and sum up the bit_value and price fields, you'd end up with
as_bitmask and as_monetary respectively.
Please note that the remaining_value field will not necessarily equal the bitmask for experience vouchers for this
reason, the remaining_value field represents the amount left on the voucher, the fields within available_to_redeem
show only what can be redeemed with the current parameters.
| Field | Type | Description |
|---|---|---|
| as_bitmask | integer | The available to redeem as a bitmask |
| as_monetary | number | The available to redeem as a monetary value |
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."
]
}
}