Client APIs

# Products and catalogue

Products serve as templates from which vouchers are issued via this API. Every voucher derived from a product inherit a set of attributes such as name, description, and type.

Each product is identified by a unique code within a catalogue.

# Types of products

Identifying the product type is essential for successful voucher issuance, processing voucher statuses, and redeeming vouchers.

Product types are defined by the following properties:

  • Is the product value-based or product-based?
  • Is the value of the voucher fixed or can it be set at issuance?
  • Is the voucher's status available after issuance?
  • Can the vouchers be redeemed in multiple transactions?

# Value-based or product-based (is_value_based)

Value-based products are denominated in currency amounts as opposed to product-based which are directly exchanged for a quantity of a specific good or service.

Value-based examples typically include products like $10 SampleMerchant Voucher, representing a $10 value redeemable at SampleMerchant.

Product-based examples include 5 cups of coffee at SampleCafé or 1 dinner for 2 at SampleRestaurant, detailing the quantity, benefit, and merchant involved.

# Fixed or open-value products (is_open_value)

Fixed-value products have a predetermined amount or quantity for the vouchers issued, such as a $10 SampleMerchant Voucher, which will always be in $10 denominations.

Multiple fixed-value products are required to support different denominations.

Open-value products allow the denomination of the vouchers to be chosen at the time of issuance.

For value-based open-value products, the denomination range allowed is from $1 to $1000. The face_value must be specified during issuance.

Open-value products are typically named ${FV} SampleMerchant Voucher, where ${FV} represents the flexible face value. Issued vouchers might be named $10.51 SampleMerchant Voucher, $150 SampleMerchant Voucher, etc.

# Voucher status availability (is_status_available)

This property indicates whether the status and remaining amount of issued vouchers can be retrieved using the retrieve vouchers feature. Other voucher properties availability are not affected by this property.

# Single or multiple-use products (is_multiple_use)

This property defines whether vouchers are always redeemed in full (single-use) or can be used for partial redemptions (multiple-use).

Single-use vouchers are redeemed entirely in one transaction at the merchant.

Multiple-use vouchers allow for partial redemptions, which means a $50 voucher, for example, could be used to pay $9.5 in one transaction and $40.5 in another. This partial redemption is also known as a drawdown.

# Product object

This API follows a data-oriented design and uses JSON (opens new window) for structuring messages.

A product is represented as a JSON object with the following keys:

  • product_code: a unique set of alphanumeric characters assigned to the product within the product catalogue, serving as an SKU (opens new window).
  • name: the product's name.
  • description: a brief description of the product appropriate for an end-user interface.
  • is_value_based: Indicates whether the product is value-based (true) or product-based (false).
  • is_open_value: Allows for open denomination or quantity at issuance (true) or is a fixed denomination / quantity product (false).
  • is_status_available: Indicates whether the status of vouchers issued from this product can be retrieved (true) or not (false) via the retrieve vouchers feature.
  • is_multiple_use: Indicates whether the vouchers can be redeemed in multiple transactions or will be fully redeemed in a single transaction.
  • currency: the currency code (in ISO 4217 format (opens new window), e.g. SGD) for the product's amount, or an empty string for product-based types.
  • amount: the product's face value in cents for value-based products, or the number of items for product-based products. null for open-value products.
  • quantity: quantity of this product in stock or null if stock is unlimited.
  • expiry_scheme: specifies how the voucher's expiration date is determined upon issuance.
  • valid_from: the start date and time of the product's validity.
  • valid_until: the end date and time of the product's validity, if applicable.
  • image: a URL linking to the product's image, intended for an end-user interface.
  • terms_and_conditions: the product's terms and conditions, formatted for use in an end-user interface.

Important

The field list may expand with new API features. Ensure your integration can handle additional fields seamlessly.

# Example of a demo product object

{
  "product_code": "MAMVDDMMYY01",
  "name": "$10 UNIQGIFT Value Based Test Voucher",
  "description": "UNIQGIFT Value Based Test Voucher",
  "is_value_based": true,
  "is_open_value": false,
  "is_status_available": true,
  "is_multiple_use": true,
  "currency": "SGD",
  "amount": 1000,
  "quantity": null,
  "expiry_scheme": "1 year from issuance",
  "valid_from": "2023-01-01T00:00:00+08:00",
  "valid_until": null,
  "image": "https://images.qa.uniqgift.com/voucher/750x288/MAMVDDMMYY01.jpg",
  "terms_and_conditions": "• This voucher may be used for multiple transactions in denominations of SGD1.00 until it runs out or expires.\n• This voucher is issued by Option Gift Pte Ltd which owns the registered trademark UNIQGIFT.\n• This voucher must be presented before payment.\n• This voucher cannot be exchanged for cash and any unused balance at expiry will not be refunded.\n• This voucher cannot be replaced if lost, damaged, stolen or expired.\n• Option Gift Pte Ltd reserves the right to vary these terms and conditions at any time without prior notice.\n• Option Gift Pte Ltd shall not be responsible for any issue that arises in connection with the redemption and/or use of this voucher and shall not be responsible or held liable for any loss, injury, damage or harm suffered or incurred by or in connection with the redemption or use of the voucher by any person."
}

For any product, the product object can be retrieved using the retrieve product details feature of the API, with the product code as the parameter.

# Catalogue of products

The catalogue is a list of all products available for issuance as digital vouchers through this API.

This selection is known as the client catalogue to differentiate it from the complete UNIQGIFT catalogue.

While the catalogue can be provided as a file, accessing it via the API ensures it is always current. The most up-to-date catalogue can be retrieved using the retrieve catalogue feature.

The API returns the catalogue as a JSON array of product objects.

For details on the application of catalogues in the integration workflow, refer to the integration process page page.

← Vouchers →