How can we help?

RESTful API

1. Introduction

Welcome to the VaocherApp RESTful API, a powerful and user-friendly interface designed to streamline your voucher and gift card management. With a focus on simplicity and efficiency, our API is organized around REST principles, ensuring seamless integration into your applications and systems.

VaocherApp accepts JSON-encoded requests. The responses are also JSON-encoded, and the API leverages standard HTTP response codes, authentication methods, and verbs. Whether you're a developer looking to enhance your platform's capabilities or a business seeking a reliable solution for voucher management, VaocherApp's RESTful API offers the flexibility and functionality you need to elevate your experience. Unlock the potential of effortless voucher management such as building your own in-house dashboard, integrating with your software, or generating a custom report.

2. API Overview

2.1 Base URLs

VaocherApp's APIs are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

The API base url is:

https://api.vaocher.app

2.2. API Keys

You can obtain a new API key through VaocherApp dashboard.

Note: Your API keys carry many privileges, so be sure to keep them secure! Avoid disclosing your confidential API keys in publicly accessible platforms.

2.3 Live and test APIs

By default, API requests will be treated as LIVE mode. VaocherApp has a built-in test mode that allow you to play around with your account test data, and it does not affect your live data.

To enable test mode in your API requests, pass in a HTTP header:

x-vaocherapp-test-mode: 1

2.4 Response Codes

VaocherApp employs standard HTTP response status codes to signal whether an API request has been successful or has encountered failure.

2.5 Data Formats

  • The date and time fields are in UTC and they follow the ISO 8601 standard.
  • All API requests expect amounts to be provided in a currency’s smallest unit. For example, to charge 10 AUD, provide an amount value of 1000 (that is, 1000 cents).

3. Authentication

VaocherApp allows you to issue API tokens that can be used to authenticate API requests. When making requests using API tokens, the token should be included in the Authorization header as a Bearer token:

Authorization: Bearer {{apikey}}

Ensure the security of your VaocherApp API keys, as they come with significant privileges. Avoid sharing confidential API keys in publicly accessible spaces like GitHub or client-side code.

4. Accounts

An account is also known as a VaocherApp account. Multiple users can have access to a single VaocherApp account.

4.1 Account Object

Example account:

{
    "id": "98b73a81-8d6b-4e8e-8aa3-76ee9384d583",
    "name": "My Account",
    "email": "demo@demo.com",
    "phone": "0400000000",
    "address": "1 Swanson St, Melbourne VIC 3000",
    "website": "https://example.com",
    "country_code": "AU",
    "timezone": "Australia/Melbourne",
    "currency": "AUD",
    "created_at": "2020-12-31T00:00:00.000000Z",
    "updated_at": "2020-12-31T00:00:00.000000Z"
}

4.2 Get Account

Get the current account details.

Request:

MethodURL
GET/restful-api/v1/accounts/current

Response body:

Returns an account objects.

5. Gift Vouchers

A gift voucher in VaocherApp represents the entity sent to a recipient when an individual completes an order through the VaocherApp checkout or when it is issued through the dashboard/API.

5.1 Gift Voucher Object

Example gift voucher:

{
    "id": "98b7b342-28f5-4cf7-b1c3-baacca77cdc2",
    "item_name": "60 Minutes Massage",
    "item_terms": "Terms & conditions...",
    "code": "ABC123",
    "expiry": "2030-12-31T14:00:00.000000Z",
    "message": "Happy birthday!",
    "purchaser_name": "Buyer Name",
    "purchaser_email": "buyer@mail.com",
    "recipient_name": "Receiver Name",
    "recipient_email": "receiver@mail.com",
    "initial_balance": 10000,
    "remaining_balance": 10000,
    "status": "active",
    "test_mode": false,
    "created_at": "2023-01-01T02:00:00.000000Z",
    "updated_at": "2023-01-01T02:00:00.000000Z"
}
PropertyDescription
idUnique identifier for the entity
item_nameName of the purchased item
item_termsTerms and conditions associated with the item
codeGift voucher unique reference code
expiryExpiration date in ISO 8601 format. If empty, this gift voucher never expires
messagePersonalized message from the buyer
purchaser_namePurchaser's name
purchaser_emailPurchaser's email
recipient_nameRecipient's name
recipient_emailRecipient's email
initial_balanceInitial balance in a currency’s smallest unit
remaining_balanceRemaining balance in a currency’s smallest unit
statusCurrent status of the gift voucher.
Available values: active, expired, redeemed, voided, pending
test_modeA flag indicating whether this is a test gift voucher
created_atTimestamp indicating when the gift voucher was created
updated_atTimestamp indicating when the gift voucher was last updated

5.2 Get Gift Vouchers

Get a list of gift vouchers.

Request:

MethodURL
GET/restful-api/v1/gift-vouchers

URL parameters:

ParameterDescription
pageSpecify the desired page number

Response body:

Returns a list of gift voucher objects.

Example response:

{
    "data": [
        {
            "id": "98b7b342-28f5-4cf7-b1c3-baacca77cdc2",
            "item_name": "60 Minutes Massage",
            "item_terms": "Terms & conditions...",
            "code": "ABC123",
            "expiry": "2030-12-31T14:00:00.000000Z",
            "message": "Happy birthday!",
            "purchaser_name": "Buyer Name",
            "purchaser_email": "buyer@mail.com",
            "recipient_name": "Receiver Name",
            "recipient_email": "receiver@mail.com",
            "initial_balance": 10000,
            "remaining_balance": 10000,
            "status": "active",
            "test_mode": false,
            "created_at": "2023-01-01T02:00:00.000000Z",
            "updated_at": "2023-01-01T02:00:00.000000Z"
        },
        {...},
        {...}
    ],
    "meta": {
        "pagination": {
            "total": 50,
            "count": 10,
            "per_page": 10,
            "current_page": 1,
            "total_pages": 5,
            "links": {
                "next": "https://api.vaocher.app/restful-api/v1/gift-vouchers?page=2"
            }
        }
    }
}

5.3 Get A Gift Voucher

Retrieves a single gift voucher.

Request:

MethodURL
GET/restful-api/v1/gift-vouchers/{id}

URL parameters:

ParameterDescription
idGift voucher unique identifier

Response body:

Returns a gift voucher object.

5.4 Get A Gift Voucher By Code

Retrieves a single gift voucher using gift voucher unique reference code.

Request:

MethodURL
GET/restful-api/v1/gift-vouchers/search-by-code/{code}

URL parameters:

ParameterDescription
codeGift voucher unique reference code

Response body:

Returns a gift voucher object.

5.5 Redeem A Gift Voucher

Deduct the specified amount of balance from a gift voucher.

Request:

MethodURL
PUT/restful-api/v1/gift-vouchers/{id}/redeem

URL parameters:

ParameterDescription
idGift voucher unique identifier

Request body:

ParameterTypeRequiredDescription
amountintegerYesThe amount to redeem against this gift voucher
reasonstringNoThe reason for this redemption (will appear in the history log)

Response status 204 (No content).