# Retrieve vouchers information
Retrieving vouchers details allows clients to retreive the vouchers detailed information and their current state (status, remaining balance, and expiration).
This page documents the endpoints:
- GET
/vouchers/{id}
for fetching a single voucher - GET
/vouchers?id={id1},{id2},etc.
for fetching up to 20 vouchers in a single request.
# Pre-requisites
To successfully retrieve voucher details, the following information is required:
- A valid auth token with read_vouchers scope obtained through an authentication request or reused if a token with sufficient remaining time-to-live is available. See the dedicated authentication and authorization page.
# Request for retrieving vouchers
This section provides brief instructions on how to retrieve vouchers. For more detailed technical information, please refer to the OpenAPI specification (opens new window) and the Postman collection (opens new window).
# Request path
# For a single voucher only
GET https://{environment}/v3/vouchers/{id} HTTP/1.1
# For 1 to 20 vouchers
GET https://{environment}/v3/vouchers?id={id1},{id2},etc. HTTP/1.1
environment
: Refer to the list of environments for the appropriate DEMO, UAT, or PRODUCTION URL.id
,id#
: The voucher id of the voucher or vouchers to be retrieved.
# Request headers
Authorization: Bearer {auth_token}
auth_token
: A valid authentication token. See the authentication and authorization page for information on how to obtain one.
# DEMO request example
The following example retrieves the voucher 1b5a607b-e5eb-4b17-80b0-5739c041e81b
issued previously in the DEMO environment.
GET https://api.demo.uniqrewards.com/v3/vouchers/1b5a607b-e5eb-4b17-80b0-5739c041e81b HTTP/1.1
Authorization: Bearer eyJraWQiOiJ3XC9TMTNMZXY0dkRhZDFhTHZPSDF5M0xzQmNhd1lTc3c0SjlQeGorczNuYz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiY2xpZW50X3YzX2RlbW9cL2lzc3VlX3ZvdWNoZXJzIGNsaWVudF92M19kZW1vXC9yZWFkX2NhdGFsb2d1ZSIsImF1dGhfdGltZSI6MTcwNDA3MDgwMCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmFwLXNvdXRoZWFzdC0xLmFtYXpvbmF3cy5jb21cL2FwLXNvdXRoZWFzdC0xX1pQQm8xRGZFVCIsImV4cCI6MTcwNDA3NDQwMCwiaWF0IjoxNzA0MDcwODAwLCJ2ZXJzaW9uIjoyLCJqdGkiOiIwYzJjYjIxNC1kOTdjLTQ5NDUtYTc2MS1lZWYzZjJlZDA1ZTEiLCJjbGllbnRfaWQiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiJ9.lT1Y_nCdCKrYGfK-booBRllLnpb3ekQ0k-nQ6GIWwZrjK6j9pZ9hCn_dbft8u5cGYnxWC4LypE7uNnq329PxXCFVj2YDXt_6i0IR6awTsvimA3wFqt0rb2pVdXKbB2LuP42CiW1NH8kM2_F456_UtYCG5dVbxnANypbdQq4kHEg29HrPuTqtbW6sqXT6b7Xobs2Rjop9AfLSufIGkRuIxKi9MOpkEnZGAhN0zAyOS2eXTFg0QuOIvlL4mwDtDMlIdbHw2NZ0M75rNQa-nzBueg8fcgECNegbJ6_67N26mj3Xbl5k07iMTvs2FQ4VbuvocwS1B5gqJYT9rFxpZOC1mw
Content-Type: application/json
# Retrieve vouchers successful response
A successful response is identified by the 200 OK
status code. If any other code is received, the request has failed. See error responses for more information on handling errors.
# Response body
The response body for a successful voucher retrieval is formatted in JSON.
- For GET
/vouchers/{id}
, it includes the keyvoucher
containing a single voucher object. - For GET
/vouchers?id={id1},{id2},etc.
, it includes the keyvouchers
containing an array of voucher objects.
{
"request_id": "{request_id}",
"voucher": {voucher_object}
}
or
{
"request_id": "{request_id}",
"vouchers": [
{voucher_object_1},
{voucher_object_2},
// etc.
]
}
request_id
: The request ID in UUID v4 format, assigned by the API to the request.voucher_object
,voucher_object_#
: JSON objects representing each retrieved voucher. The structure of these voucher objects is detailed on the vouchers page.
# DEMO response example
Below is a sample response corresponding to the DEMO request example. This response contains the details of the voucher 1b5a607b-e5eb-4b17-80b0-5739c041e81b
, which has been redeemed since its issuance.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"request_id": "bb1c73c1-da6a-4773-9a15-91de167fe263",
"voucher": {
"voucher_code": "UG1123456789",
"voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b",
"name": "$10 UNIQGIFT Value Based Test Voucher",
"status": "used",
"expiration": "2029-10-31T23:59:59+08:00",
"currency": "SGD",
"remaining_amount": 0,
"product_code": "MAMVDDMMYY01",
"product_name": "$10 UNIQGIFT Value Based Test Voucher",
"is_value_based": true,
"is_status_available": true,
"is_multiple_use": true,
"url": "https://{base_url}1b5a607b-e5eb-4b17-80b0-5739c041e81b",
"short_url": "https://{base_url_short}/v/BMhgQhHigm7",
"short_url_pin": 1234
}
}