{warning} This API is likely to change before the Beta period is over, please check back regularly to see the latest changes.

Redeem A Voucher

Redeeming a voucher only requires that you send us the voucher number and a limited set of fields, like the value to redeem or the experiences that are being used.

Request

Headers

POST REQUEST (/redeem)

Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXX

Body

You can find the site number you should submit along with this request in the company configuration on the Smart Gift dashboard.

For the value you should either submit the monetary value in the case of a monetary voucher OR the sum of the bit_value field values of the experiences that you wish to redeem for experience vouchers. For example, if you wanted to redeem 2 experiences from an experience voucher and those experiences had bit_value values of 2 and 8 respectively, you would submit a value of 10.

{
    "voucher_no":"XXXXXXXXXX",
    "site_id": "X",
    "value": 10
}

Success Response

{
    "data": {
        "message": "The voucher has been redeemed.",
        "redemptions": [
            21, 22, 23
        ]
    }
}

Error Responses

Errors will be displayed in the following format and will be returned along with a 422 http response code. In cases where a single field has multiple errors, it is most likely the case that the first message is the error you need to look out for.

Invalid voucher number

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."
        ]
    }
}

Invalid site number

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"
        ]
    }
}

Voucher does not belong to company

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"
        ]
    }
}

Voucher has expired

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."
        ]
    }
}

Voucher is fully redeemed

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."
        ]
    }
}