Unified Redemptions

There are some cases where you may not wish to (or be able to) prompt the user for a selection of experiences, this API allows you to use filters rather than user-submitted data to redeem a voucher. The system will then use a 'best fit' algorithm to redeem the minimum amount from the voucher that covers the value that needs to be covered.
Filters are not required, if you wish to have all experiences considered for redemption regardless of classification or other filters, you can omit the filters parameter. Please note that monetary vouchers do not have classifications and are redeemable anywhere within the company as would be expected from a monetary voucher. This API call will redeem up to the value provided or the value of the voucher, whichever is less.
We offer the option to filter vouchers (the entire voucher) by custom meta fields attached to the voucher. This works for both experience and monetary vouchers but is 'all or nothing'.

Request

Headers

POST REQUEST (/redeem-unified)

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 submit the maximum value that should be redeemed, this would typically be the balance due on the bill to which the voucher is being applied.

For the classifications, we suggest that you set these in your applications configuration. Classifications include the below list, and companies are able to classify experiences under Settings > Revenue Centers within their dashboard.

"accommodation" (Accommodation)
"food_and_beverage" (Food & Beverage)
"events" (Events)
"spa" (Spa)
"sundry" (Sundry)

You can also include meta_conditions which are a new addition to the API that allows for a high degree of flexibility. Meta can be added to vouchers in the voucher configuration within the dashboard and all vouchers sold from that point will have the assigned meta fields available for filtering.

You can currently filter in the following ways:

equals: Checks the value of a singular key on the voucher and compares it with a singular value that you provide. 
contains: Checks an array of values assigned to the key passed in against your singular value.
in: Checks a singular value of the key provided, passing if the value of that key exists in the array you provide

Please note that meta_conditions work best when used sparingly.

{
    "voucher_no": "XXXXXXXXXX",
    "site_id": "X",
    "value": 250,
    "hold_token": "hold_token_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "filters": {
        "classifications": [
            "food_and_beverage"
        ],
        "meta_conditions": [
            {
                "key": "rate_plan",
                "operator": "equals",
                "value": "My Hotel Stay"
            },
            {
                "key": "room_type",
                "operator": "contains",
                "value": "double"
            },
            {
                "key": "area",
                "operator": "in",
                "value": [
                    "restaurant",
                    "bar"
                ]
            }
        ]
    }
}

Success Response

{
    "data": {
        "message": "The voucher has been redeemed.",
        "redeemed_value": 32.80,
        "overspend": 0,
        "redemptions": [
            1461
        ]
    }
}

The overspend property

If you use an experience voucher, this API method will find the best combination of the available experiences to redeem for the request. This will be the combination of experiences that covers the balance with the least amount of overspend. If the redemptions result in overspend, the amount will be detailed in the overspend value.

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

Invalid redemption value

If the value provided exceeds what is available for redemption, you will be returned the following response:

{
    "message": "The redemption value exceeds the remaining balance of the voucher",
    "errors": {
        "value": [
            "The redemption value exceeds the remaining balance of the voucher"
        ]
    }
}

Voucher is reserved

If a voucher has been reserved using our the hold endpoint, you will be returned the below response if you do not include a hold_token in your request.

{
    "message": "Voucher is reserved. Hold token is required",
    "errors": {
        "hold_token": [
            "Voucher is reserved. Hold token is required"
        ]
    }
}

Alternatively, if you provide an incorrect hold_token, you will get the below error.

{
    "message": "Invalid hold token provided",
    "errors": {
        "hold_token": [
            "Invalid hold token provided"
        ]
    }
}

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