Client APIs

# Issue vouchers

Issuing vouchers is the main feature of this API.

This page documents the endpoint POST /products/{code}.

This endpoint generates digital vouchers on demand. The digital vouchers are returned in the API response body and can subsequently be distributed to the relevant voucher recipients (distribution is to be performed by the client).

# Pre-requisites

To submit a successful voucher issuance request, the following information is required:

  • A valid auth token with issue_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.
  • The product code from which to issue vouchers. This can be selected from the catalogue available through the retrieve catalogue feature or known beforehand.
  • The type of the requested product. Product details can be obtained via the retrieve product details feature, through retrieve catalogue, or known beforehand.
  • The quantity of vouchers to be issued, limited to 20 per request.
  • For open-value products only, the denomination required for the vouchers. This is the face value of the vouchers to be issued in SGD, and it can range from $1 to $1000.

Tip

To overcome the limitation on quantity, clients may issue more than 20 vouchers by submitting multiple voucher issuance requests.

# Request for issuing vouchers

This section provides guided instructions on how to perform a voucher issuance request. For more detailed technical information, please refer to the OpenAPI specification (opens new window) and the Postman collection (opens new window).

# Request path

POST https://{environment}/v3/products/{code} HTTP/1.1

# Request headers

Authorization: Bearer {auth_token}
Idempotency-Key: {idempotency_key}
Content-Type: application/json
  • auth_token: A valid authentication token. See the authentication and authorization page for information on how to obtain one.
  • idempotency_key: A newly generated UUID v4, used as the idempotency key for this request.
  • Content-Type: application/json: Specifies that the request body is formatted in JSON.

# Request body

{
  "quantity": {quantity},
  "face_value": {face_value}, // Only for open-value products
  "client_reference": "{client_reference}" // Optional reference
}
  • quantity number: The number of vouchers to be issued.
  • face_value numberfor open-value products only: The requested denomination of the vouchers, expressed in cents.
  • client_reference stringoptional: Optional reference which will be associated to the issued vouchers (maximum length 50, alphanumerical characters accepted with limited special characters - _ / # : .).

# DEMO request example

The following example illustrates how to issue a voucher in the DEMO environment using the value-based product MAMVDDMMYY01. Only the quantity of vouchers is required in the request body.

POST https://api.demo.uniqrewards.com/v3/products/MAMVDDMMYY01 HTTP/1.1

Authorization: Bearer eyJraWQiOiJ3XC9TMTNMZXY0dkRhZDFhTHZPSDF5M0xzQmNhd1lTc3c0SjlQeGorczNuYz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiY2xpZW50X3YzX2RlbW9cL2lzc3VlX3ZvdWNoZXJzIGNsaWVudF92M19kZW1vXC9yZWFkX2NhdGFsb2d1ZSIsImF1dGhfdGltZSI6MTcwNDA3MDgwMCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmFwLXNvdXRoZWFzdC0xLmFtYXpvbmF3cy5jb21cL2FwLXNvdXRoZWFzdC0xX1pQQm8xRGZFVCIsImV4cCI6MTcwNDA3NDQwMCwiaWF0IjoxNzA0MDcwODAwLCJ2ZXJzaW9uIjoyLCJqdGkiOiIwYzJjYjIxNC1kOTdjLTQ5NDUtYTc2MS1lZWYzZjJlZDA1ZTEiLCJjbGllbnRfaWQiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiJ9.lT1Y_nCdCKrYGfK-booBRllLnpb3ekQ0k-nQ6GIWwZrjK6j9pZ9hCn_dbft8u5cGYnxWC4LypE7uNnq329PxXCFVj2YDXt_6i0IR6awTsvimA3wFqt0rb2pVdXKbB2LuP42CiW1NH8kM2_F456_UtYCG5dVbxnANypbdQq4kHEg29HrPuTqtbW6sqXT6b7Xobs2Rjop9AfLSufIGkRuIxKi9MOpkEnZGAhN0zAyOS2eXTFg0QuOIvlL4mwDtDMlIdbHw2NZ0M75rNQa-nzBueg8fcgECNegbJ6_67N26mj3Xbl5k07iMTvs2FQ4VbuvocwS1B5gqJYT9rFxpZOC1mw
Idempotency-Key: 30c40ad6-f135-4aad-97d5-79f195680458
Content-Type: application/json

{
  "quantity": 1
}

# Voucher issuance 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 headers

Idempotency-Key: {idempotency_key}
Content-Type: application/json; charset=utf-8

# Response body

The response body for a successful voucher issuance is formatted in JSON and contains the key vouchers, which is an array of voucher objects.

{
  "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_#: JSON objects representing each issued 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 a voucher issued as part of a successful request.

HTTP/1.1 200 OK

Idempotency-Key: 424b9d10-6e3c-45f7-ae1e-0fa857ea1056
Content-Type: application/json; charset=utf-8

{
  "request_id": "bb1c73c1-da6a-4773-9a15-91de167fe263",
  "vouchers": [
    {
      "voucher_code": "UG1123456789",
      "voucher_id": "1b5a607b-e5eb-4b17-80b0-5739c041e81b",
      "name": "$10 UNIQGIFT Value Based Test Voucher",
      "status": "active",
      "expiration": "2029-10-31T23:59:59+08:00",
      "currency": "SGD",
      "remaining_amount": 1000,
      "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
    }
  ]
}

# Partially successful issuance

In rare cases, the API may return a 207 Partial Success response for an issuance request where the quantity is greater than 1.

This occurs only when a subset of the requested vouchers is successfully issued, while the remaining vouchers fail.

In such cases, the response structure combines a Voucher issuance successful response and an Error response.

The vouchers object will only contain the successfully issued vouchers. Please retry issuing the remaining vouchers.

# Response body

{
  "request_id": "{request_id}",
  "error": {
    "code": "{error_code}",
    "message": "{error_message}",
    "documentation": "{error_documentation}",
    "details": "{error_details}"
  },
  "vouchers": [
    {voucher_object_1},
    {voucher_object_2},
    // etc.
  ]
}

← Retrieve vouchers information →