Reserving A Voucher

There may be times when you want to reserve a voucher for redemption without redeeming it right away. If you want to confirm that a voucher has a certain value remaining for use in a following step but also need to be sure that the value you just checked is not redeemed elsewhere first, you can reserve the voucher using this endpoint.

Request

Headers

POST REQUEST (/redeem/hold)

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

Body

For the body of this request, you only need to provide the voucher number; no site_id or value fields are required. If the request is successful, the voucher will be held for five minutes and you will be returned a hold_token that you can use to redeem the voucher later.

{
    "voucher_no":"XXXXXXXXXX"
}

Success Response

{
    "message": "Voucher hold successful",
    "hold_token": "hold_token_jY0VMM8zd5GLkk3jDpEjTOLr"
}

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.
This request is subject to various checks, but assuming that it follows a voucher check, the most likely error response would be that the voucher is already held. It is important to record the hold token in the response or you will have to wait until the voucher hold expires.

Voucher is already held

If the voucher is already held, you will be returned the following response:

{
    "message": "Voucher is already held",
    "errors": {
        "voucher_no": [
            "Voucher is already held"
        ]
    }
}

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

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