Client APIs

# 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}

# 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 key voucher containing a single voucher object.
  • For GET /vouchers?id={id1},{id2},etc., it includes the key vouchers 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
  }
}

← Error responses →