API docs

tungnt March 6, 2026 30 min read

BonusLink Travel API Documentation

VERSION 1.0

February 2026

Change Log

Version Date Changes
1.0 Feb 2026 Initial API documentation for BonusLink Travel integration

Table of Contents

  1. Introduction
  2. API Workflow
  3. API Specification
  4. Authentication API
  5. Booking Retrieval API
  6. Booking Products API
    • 6.1 Request Headers
    • 6.2 Request Parameters
    • 6.3 Request Sample
    • 6.4 Response Parameters
    • 6.5 Product Data Object (Hotel)
    • 6.6 Room Object
    • 6.7 Room Rate Object
    • 6.8 Cancellation Object
    • 6.9 Product Type Object
    • 6.10 Currency Info Object
    • 6.11 Price Info Object
    • 6.12 Reward Info Object
    • 6.13 Response Sample
  7. Status Codes
  8. Error Codes

1. Introduction

This document provides guidance for integrating with the BonusLink Travel API system. The API provides authentication and booking retrieval capabilities for hotel bookings.

Key Features:

  • JWT-based authentication with agent scope
  • Comprehensive hotel booking retrieval with payment details
  • Support for multi-traveler hotel bookings
  • Detailed payment transaction information with WowPay gateway integration
  • Hotel-specific pricing breakdown and voucher status tracking

2. API Workflow

2.1 Complete Booking Retrieval Sequence

sequenceDiagram
    participant Client
    participant API as BonusLink Travel API
    participant IAM as IAM Service

    Client->>API: 1. POST /v2/auth
    Note over Client,API: email, password, flow_type, scope_type

    API->>IAM: Validate credentials

    alt Valid Credentials
        IAM-->>API: User authenticated
        API->>API: Generate JWT token
        API-->>Client: access_token, exp, account_id
    else Invalid Credentials
        IAM-->>API: Authentication failed
        API-->>Client: 401 Unauthorized
    end

    Note over Client: Store access_token

    Client->>API: 2. GET /booking?booking_code=XXX
    Note over Client,API: Authorization: Bearer {access_token}

    alt Token Valid
        API-->>Client: 200 OK (booking details)
    else Token Expired
        API-->>Client: 401 Unauthorized
        Note over Client: Re-authenticate
    end

    Client->>API: 3. GET /bookings/products?booking_code=XXX
    Note over Client,API: Authorization: Bearer {access_token}

    alt Token Valid
        API-->>Client: 200 OK (booking product details)
    else Token Expired
        API-->>Client: 401 Unauthorized
        Note over Client: Re-authenticate
    end

3. API Specification

  • Protocol: HTTPS only
  • Encoding: UTF-8
  • Content-Type: application/json
  • Authentication: Bearer token in Authorization header
  • Base URL: https://booking.travel.bonuslink.com.my

Authentication Header

Authorization: Bearer {access_token}

Error Response Format

{
    "error": "ErrorCode",
    "message": "Human readable error message",
    "meta": {
        "additional_info": "value"
    }
}

4. Authentication API

Endpoint: POST /v2/auth

This endpoint authenticates an agent user and returns a JWT access token for subsequent API requests.

4.1 Request Parameters

Parameter Type Required Description
email string Yes Agent email address
password string Yes Agent password
flow_type string Yes Authentication flow type (e.g., "Basic")
scope_type string Yes Access scope type (e.g., "Agent")

4.2 Request Sample

{
    "email": "agent@example.com",
    "password": "your_secure_password",
    "flow_type": "Basic",
    "scope_type": "Agent"
}

4.3 Response Parameters

Parameter Type Description
exp integer Token expiration timestamp (Unix timestamp)
account_id string Agent account identifier (UUID)
email string Agent email address
access_token string JWT token for API authentication

4.4 Success Response Sample

{
    "exp": 1752503790,
    "account_id": "2463c7d1-316f-452e-a903-0dc5038c9d0f",
    "email": "agent@example.com",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NTI1MDM3OTAsInJlZnJlc2hfdG9rZW4iOiIyNDYzYzdkMS0zMTZmLTQ1MmUtYTkwMy0wZGM1MDM4YzlkMGYiLCJhY2NvdW50X2lkIjoiMjQ2M2M3ZDEtMzE2Zi00NTJlLWE5MDMtMGRjNTAzOGM5ZDBmIn0..."
}

4.5 Token Usage

Include the access_token in the Authorization header for all subsequent API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

4.6 Token Expiration

  • The token expires at the Unix timestamp specified in the exp field
  • Tokens are typically valid for 30 days from issuance
  • When a token expires, you must authenticate again to obtain a new token
  • Monitor the exp timestamp and refresh before expiration to avoid service interruption

5. Booking Retrieval API

Endpoint: GET /booking

This endpoint retrieves complete booking details including contact information, payment status, travelers, products, and pricing.

5.1 Request Parameters (Query String)

Parameter Type Required Description
booking_code string Yes Unique booking confirmation code

5.2 Request Sample

GET /booking?booking_code=DEMOP010156
Authorization: Bearer {access_token}

5.3 Response Parameters

Parameter Type Description
id string Booking UUID
created_at string Booking creation timestamp (ISO 8601)
updated_at string Last update timestamp (ISO 8601)
deleted boolean Deletion status
code string Booking confirmation code
tax_invoice_number string Tax invoice number (if applicable)
app_id string Application identifier (UUID)
agent_id string Agent identifier (UUID)
payment_id string Payment transaction identifier (UUID)
account_id string Account identifier (UUID)
customer_id string Customer identifier (UUID)
shopping_id string Shopping session identifier
trip_id string Trip identifier (UUID)
package_id string Package identifier (UUID)
office_id string Office identifier (UUID)
flight_campaign_id string Flight campaign identifier (UUID)
currency_code string Currency code (e.g., "USD", "MYR")
language_code string Language code (e.g., "en-US")
promotion_code string Promotion code applied
partner_id string Partner identifier (UUID)
status string Booking status (success, pending, failed, cancelled)
number integer Booking sequence number
total_amount float Total booking amount
elevy_amount float E-levy amount
webhook_data object Webhook callback data
package_search object Package search criteria
promotion object Promotion details
group_booking boolean Group booking flag
group_booking_confirmed boolean Group booking confirmation status
departure_date string Travel departure date (ISO 8601)
offline_payment_ref string Offline payment reference
offline_payment_origin string Offline payment origin
is_offline_payment boolean Offline payment indicator
cid string Campaign identifier
contact object Contact person details (see Contact Object)
payment object Payment transaction details (see Payment Object)
json_url string JSON booking data URL
travel_start_date string Travel start date (ISO 8601)
travel_end_date string Travel end date (ISO 8601)
travelers array List of travelers (see Traveler Object)
products array List of booked products (see Product Object)
insurance object Insurance details
prices array Pricing breakdown by product (see Price Object)

5.4 Response Sample

{
    "id": "829763bb-950d-44a3-82b7-0c499463fb4f",
    "created_at": "2026-01-10T14:31:50.016973+00:00",
    "updated_at": "2026-01-10T14:32:40.417212+00:00",
    "deleted": false,
    "code": "DEMOP010156",
    "tax_invoice_number": null,
    "app_id": "bbf70af6-4382-4ff8-beb3-b2847f682f34",
    "agent_id": null,
    "payment_id": "f34b4742-01fd-422b-8f8f-57791da7e44c",
    "account_id": "bbfad219-30d7-4b00-bb4e-359fd42dcf43",
    "customer_id": null,
    "shopping_id": "17b6d15bbf5c4093abca1523ba34e647",
    "trip_id": null,
    "package_id": "4a5c9770-f901-4b96-8673-ecdc5ee49102",
    "office_id": null,
    "flight_campaign_id": null,
    "currency_code": "USD",
    "language_code": "en-US",
    "promotion_code": null,
    "partner_id": null,
    "status": "success",
    "number": 10156,
    "total_amount": 6727.05,
    "elevy_amount": 0.0,
    "webhook_data": {},
    "package_search": {},
    "promotion": null,
    "group_booking": false,
    "group_booking_confirmed": false,
    "departure_date": "2026-02-01T00:00:00+00:00",
    "offline_payment_ref": null,
    "offline_payment_origin": null,
    "is_offline_payment": false,
    "cid": "",
    "contact": {
        "id": "ce70ccc9399a4a68bd29f3649acdc627",
        "created_at": "2026-01-10T14:31:50.022467+00:00",
        "updated_at": "2026-01-10T14:31:50.022482+00:00",
        "deleted": false,
        "booking_id": "829763bb-950d-44a3-82b7-0c499463fb4f",
        "first_name": "asd",
        "last_name": "asd",
        "title": "Mr",
        "email": "abdelrhman.awaad@gmail.com",
        "phone": "+20 12346654",
        "city": null,
        "country_code": "EG",
        "country_name": null,
        "address": "cairo",
        "postcode": null,
        "country": null,
        "middle_name": "dsa",
        "details": {
            "country_code": "EG",
            "phone": "+20 12346654",
            "address": "cairo",
            "last_name": "asd",
            "email": "abdelrhman.awaad@gmail.com",
            "title": "Mr",
            "first_name": "asd",
            "middle_name": "dsa"
        }
    },
    "payment": {
        "id": "f34b4742-01fd-422b-8f8f-57791da7e44c",
        "created_at": "2026-01-10T14:31:50.428441+00:00",
        "updated_at": "2026-01-10T14:32:35.410683+00:00",
        "deleted": false,
        "scope_type": "App",
        "account_id": "bbfad219-30d7-4b00-bb4e-359fd42dcf43",
        "shopping_id": "17b6d15bbf5c4093abca1523ba34e647",
        "promotion_code": null,
        "scope_id": "bbf70af6-4382-4ff8-beb3-b2847f682f34",
        "transaction_id": "f76021490c6a6fca",
        "status": "success",
        "method": "wow-pay",
        "flow_type": "ProductBooking",
        "desc": "Payment for booking: DEMOP010156",
        "amount": 6727.05,
        "postpaid": false,
        "meta": {
            "booking_code": "DEMOP010156"
        },
        "currency_info": {
            "origin": "USD",
            "conversion": "USD",
            "rate": 1.0
        },
        "client_info": {
            "origin": "demo.apps.easygds.com",
            "redirect_url": "https://demo.apps.easygds.com/api/payment/callback",
            "ip": "156.201.113.66"
        },
        "contact": {
            "country_code": "EG",
            "phone_number": "+20 12346654",
            "phone": "+20 12346654",
            "title": "Mr",
            "first_name": "asd",
            "address": "cairo",
            "last_name": "asd",
            "email": "abdelrhman.awaad@gmail.com",
            "middle_name": "dsa"
        },
        "lines": [
            {
                "id": "f0bd63450e384a31b8464949b38ac104",
                "transaction_id": "450516165a075e07",
                "status": "success",
                "method": "wow-pay",
                "amount": 6727.05,
                "desc": "Payment for booking: DEMOP010156",
                "message": "Payment complete.",
                "meta": {
                    "app_id": "bbf70af6-4382-4ff8-beb3-b2847f682f34",
                    "switch_id": "cccce8af-f966-49eb-9b62-4080e15e6344",
                    "wow-pay": {
                        "response": {
                            "CARD_HOLDER_NAME": "",
                            "CURRENCY": "USD",
                            "PAYMENT_TYPE": "CreditCard",
                            "PAYMENT_REFERENCE3": "KCA002641",
                            "PAYMENT_REFERENCE1": "ch_3So3DRCbbjpW3zmI0xCpvpua",
                            "CARD_TYPE": "Visa",
                            "PAYMENT_DESCRIPTION": "Payment complete.",
                            "MERCHANT_ID": "e81932f2-71b7-4e78-96c8-f8cc42f2d6b7",
                            "ORDERREF": "450516165a075e07",
                            "PAYMENT_STATUSCODE": "1",
                            "APPROVAL_CODE": "pi_3So3DRCbbjpW3zmI0JQaGEjs",
                            "EXPIRY_YEAR": "2026",
                            "PAYMENT_STATUS": "APPROVED",
                            "CARD_NUMBER": "401288XXXXXX1881",
                            "EXPIRY_MONTH": "01",
                            "PAYMENT_CHANNEL": "Visa",
                            "AMOUNT": 6727.05
                        }
                    }
                },
                "created_at": "2026-01-10T14:31:50.432182+00:00"
            }
        ]
    },
    "json_url": "https://core.services.easygds.com/api/bookings/json?token=a0b3445308ac291a02b135e74d7be739302ee1dc14bfdc54eefcc53748b988bb&code=DEMOP010156",
    "travel_start_date": "2026-02-01T00:00:00",
    "travel_end_date": "2026-02-08T00:00:00",
    "travelers": [
        {
            "id": "a4d2ddac52c947b4a4fb597f53cfbebf",
            "created_at": "2026-01-10T14:31:51.203691+00:00",
            "updated_at": "2026-01-10T14:31:51.203706+00:00",
            "deleted": false,
            "booking_id": "829763bb-950d-44a3-82b7-0c499463fb4f",
            "details": {
                "title": {
                    "value": "Mr",
                    "key": "title",
                    "data_type": "str",
                    "translation_label": "travelers.title"
                },
                "birthday": {
                    "value": "2001-02-03",
                    "key": "birthday",
                    "data_type": "date",
                    "translation_label": "travelers.birthday"
                },
                "last_name": {
                    "value": "asd",
                    "key": "last_name",
                    "data_type": "str",
                    "translation_label": "travelers.last_name"
                },
                "country_code": {
                    "value": "EG",
                    "key": "country_code",
                    "data_type": "str",
                    "translation_label": "travelers.country_code"
                },
                "type": {
                    "value": "adult",
                    "key": "type",
                    "data_type": "str",
                    "translation_label": "travelers.type"
                },
                "first_name": {
                    "value": "asd",
                    "key": "first_name",
                    "data_type": "str",
                    "translation_label": "travelers.first_name"
                },
                "middle_name": {
                    "value": "dsa",
                    "key": "middle_name",
                    "data_type": "str",
                    "translation_label": "travelers.middle_name"
                }
            },
            "data": {
                "title": "Mr",
                "birthday": "2001-02-03",
                "last_name": "asd",
                "country_code": "EG",
                "type": "adult",
                "first_name": "asd",
                "middle_name": "dsa"
            }
        }
    ],
    "products": [
        {
            "id": "a2c4bb36-1072-47d8-ad82-5b3b1ffb1a27",
            "status": "vouchered",
            "product_code": "hotel"
        }
    ],
    "insurance": {},
    "prices": [
        {
            "product_code": "hotel",
            "total_amount": 6727.05,
            "currency_code": "USD",
            "scope_type": "BookingProduct"
        }
    ]
}

5.5 Booking Object Structure

The main booking object contains all booking-related information organized into the following sections:

  • Booking Metadata: Core booking identifiers and status
  • Contact Information: Primary contact person details
  • Payment Information: Payment transaction and processing details
  • Travelers: List of all travelers in the booking
  • Products: Booked travel products (hotels, flights, etc.)
  • Pricing: Detailed pricing breakdown by product

5.6 Contact Object

The contact object contains information about the primary contact person for the booking.

Parameter Type Description
id string Contact record identifier
created_at string Contact creation timestamp (ISO 8601)
updated_at string Last update timestamp (ISO 8601)
deleted boolean Deletion status
booking_id string Associated booking identifier (UUID)
first_name string Contact first name
last_name string Contact last name
title string Contact title (Mr, Ms, Mrs, etc.)
email string Contact email address
phone string Contact phone number with country code
city string Contact city
country_code string Contact country code (ISO 2-letter)
country_name string Contact country name
address string Contact address
postcode string Contact postal code
country string Contact country
middle_name string Contact middle name
details object Nested contact details object

5.7 Payment Object

The payment object contains comprehensive payment transaction information.

Parameter Type Description
id string Payment record identifier (UUID)
created_at string Payment creation timestamp (ISO 8601)
updated_at string Last update timestamp (ISO 8601)
deleted boolean Deletion status
scope_type string Payment scope type (App, Agent, etc.)
account_id string Account identifier (UUID)
shopping_id string Shopping session identifier
promotion_code string Applied promotion code
scope_id string Scope identifier (UUID)
transaction_id string Unique transaction identifier
status string Payment status (success, pending, failed)
method string Payment method (wow-pay, credit-card, etc.)
flow_type string Payment flow type (ProductBooking, etc.)
desc string Payment description
amount float Payment amount
postpaid boolean Postpaid payment indicator
meta object Payment metadata including booking code
currency_info object Currency conversion information
client_info object Client origin and IP information
contact object Payment contact information
lines array Payment transaction lines with detailed gateway response

Payment Lines Object

Each payment line represents a payment transaction attempt.

Parameter Type Description
id string Payment line identifier
transaction_id string Transaction identifier
status string Transaction status (success, failed)
method string Payment method used
amount float Transaction amount
desc string Transaction description
message string Transaction status message
meta object Detailed payment gateway response
created_at string Transaction creation timestamp

5.8 Traveler Object

The traveler object contains information about each traveler in the booking.

Parameter Type Description
id string Traveler record identifier
created_at string Traveler record creation timestamp (ISO 8601)
updated_at string Last update timestamp (ISO 8601)
deleted boolean Deletion status
booking_id string Associated booking identifier (UUID)
details object Detailed traveler attributes with metadata
data object Simplified traveler data object

Traveler Details Structure

The details object contains structured traveler attributes:

Attribute Type Description
title object Traveler title (value, key, data_type, translation_label)
birthday object Traveler date of birth (value, key, data_type, translation_label)
first_name object Traveler first name (value, key, data_type, translation_label)
last_name object Traveler last name (value, key, data_type, translation_label)
middle_name object Traveler middle name (value, key, data_type, translation_label)
country_code object Traveler country code (value, key, data_type, translation_label)
type object Traveler type: adult, child, infant (value, key, data_type, translation_label)

Traveler Data Structure

The data object contains simplified traveler information:

Parameter Type Description
title string Traveler title
birthday string Date of birth (YYYY-MM-DD)
first_name string First name
last_name string Last name
middle_name string Middle name
country_code string Country code (ISO 2-letter)
type string Traveler type (adult, child, infant)

5.9 Product Object

The product object represents a booked hotel product.

Parameter Type Description
id string Product record identifier (UUID)
status string Hotel product status (see Product Status for all possible values)
product_code string Product type code (currently only "hotel" is supported)

Note: This API currently supports hotel bookings only. For detailed information on all hotel product status values and their meanings, see Section 7.2 - Product Status (Hotel Only).

5.10 Price Object

The price object provides pricing breakdown by hotel product.

Parameter Type Description
product_code string Product type code (currently only "hotel")
total_amount float Total amount for the hotel booking
currency_code string Currency code (e.g., "USD", "MYR")
scope_type string Pricing scope type (typically "BookingProduct")

6. Booking Products API

Endpoint: GET /bookings/products

This endpoint retrieves detailed product information for a specific booking, including hotel booking data, supplier details, voucher information, and room-level pricing breakdown.

6.1 Request Headers

Header Required Description
Authorization Yes Bearer token obtained from Authentication API. Format: Bearer {access_token}

6.2 Request Parameters (Query String)

Parameter Type Required Description
booking_code string Yes Unique booking confirmation code

6.3 Request Sample

GET /bookings/products?booking_code=BL100022
Authorization: Bearer {access_token}

6.4 Response Parameters

The response contains a total count and a result array of booking product objects.

Parameter Type Description
total integer Total number of booking products
result array List of booking product objects

Booking Product Object

Parameter Type Description
id string Booking product identifier (UUID)
created_at string Product creation timestamp (ISO 8601)
updated_at string Last update timestamp (ISO 8601)
deleted boolean Deletion status
booking_id string Associated booking identifier (UUID)
package_id string Package identifier (UUID, nullable)
product_id string Product definition identifier
product_ref string Product reference identifier
shopping_id string Shopping session identifier
shopping_item_id string Shopping item identifier
status string Product status (see Product Status for all possible values)
free_cancellation_deadline string Free cancellation deadline (ISO 8601, nullable)
free_cancellation boolean Whether free cancellation is currently available
data object Detailed hotel product data (see Section 6.5 Product Data Object)
currency_info object Currency conversion information (see Section 6.10 Currency Info Object)
product object Product type metadata (see Section 6.9 Product Type Object)
pdf_url string URL to download the booking voucher PDF
error_message string Error message if booking failed (nullable)
search object Original search parameters and metadata
logs array Product processing log entries

6.5 Product Data Object (Hotel)

The data object contains comprehensive hotel booking details including supplier information, room details, pricing, and hotel content.

Parameter Type Description
source_id string Supplier source identifier
contract_id string Hotel contract identifier
hotel_id string Hotel identifier in supplier system
easygds_id string EasyGDS internal hotel identifier
eps_id string Expedia property system identifier
supplier_code string Supplier code (e.g., "APItude", "HMS")
supplier_source string Supplier data source identifier
currency string Supplier pricing currency code
is_client boolean Whether this is a client-contracted rate
is_has_refundable_rooms boolean Whether refundable rooms are available
name string Hotel name
street_address string Hotel full street address
type string Product type (e.g., "hotel")
star float Hotel star rating
phone string Hotel phone number
room_count integer Number of rooms booked
pax_count integer Number of guests
night_count integer Number of nights
checkin_date string Check-in date (ISO 8601)
checkout_date string Check-out date (ISO 8601)
checkin_time string Check-in time
checkout_time string Check-out time
rooms array List of room objects (see Section 6.6 Room Object)
selected_rooms array List of selected/booked room objects with booking references
free_cancellation boolean Whether free cancellation is available
free_cancellation_deadline string Free cancellation deadline (ISO 8601, nullable)
cancellation_deadline string Cancellation deadline (ISO 8601, nullable)
price_info object Aggregated price information (see Section 6.11 Price Info Object)
prices array Price breakdown by level
reward_info object Reward/loyalty points information (see Section 6.12 Reward Info Object)
currency_info object Currency conversion information
search_id string Original search session identifier
package_id string Package identifier (nullable)
location object Hotel location with GPS coordinates
avatar object Hotel thumbnail image URLs (sm, md, lg)
ratings object Hotel ratings from various sources (expedia, liteapi, tripadvisor)
contents object Hotel content details (descriptions, amenities, policies, fees)
booking_ref string Supplier booking reference number
country_code string Booking country code (ISO 2-letter)

6.6 Room Object

Each room object within the rooms array contains details about a booked room.

Parameter Type Description
idx integer Room index (1-based)
room_name string Room type display name
room_type_id string Room type identifier
name string Room name (mapped)
supplier_room_name string Original room name from supplier
easygds_id string EasyGDS room identifier
source_id string Source identifier
supplier_code string Supplier code
hotel_id string Hotel identifier
hotel_easygds_id string Hotel EasyGDS identifier
free_cancellation boolean Whether free cancellation is available for this room
cancellation_deadline string Room cancellation deadline (ISO 8601, nullable)
supplier_cancellation_deadline string Supplier cancellation deadline (ISO 8601)
cancellation_buffer integer Cancellation buffer in hours
images array Room image URLs
contents object Room description content
area object Room area (square_meters, square_feet)
occupancy object Room occupancy limits (adults, children, infants)
beds object Bed configuration (nullable)
attribute_ids array Room amenity/attribute identifiers
rate object Room rate details (see Section 6.7 Room Rate Object)
rates array Rate breakdown array
remainings integer Number of remaining rooms available
prebook_map_id string Pre-booking mapping identifier

6.7 Room Rate Object

The rate object within each room contains detailed pricing and cancellation policy.

Parameter Type Description
base_price float Base room price in supplier currency
net_price float Net price
gross_price float Gross price
price float Final price in supplier currency
tax integer Tax amount
currency string Rate currency code
board_basis string Board basis / meal plan description (e.g., "Room Only")
board_code string Board basis code (e.g., "RO")
board_basis_code string Normalized board basis code (e.g., "room-only")
non_refundable boolean Whether the rate is non-refundable
free_cancellation boolean Whether free cancellation applies
free_cancellation_deadline string Free cancellation deadline
cancellations array Cancellation policy periods with penalty amounts (see Section 6.8 Cancellation Object)
price_info object Price breakdown (see Section 6.11 Price Info Object)
currency_info object Currency conversion details
prices array Multi-level price breakdown
reward_info object Reward points information
remainings integer Remaining rooms at this rate
room_name string Room type name
room_type_id string Room type identifier
remarks array Special remarks or notes

6.8 Cancellation Object

The cancellations array defines time-based cancellation penalty periods. Each period specifies a date range and the penalty amount charged if the booking is cancelled within that period. Periods are ordered chronologically.

Parameter Type Description
from string Period start date (ISO 8601)
to string Period end date (ISO 8601)
utc_from string Period start date in UTC (ISO 8601)
utc_to string Period end date in UTC (ISO 8601)
amount float Cancellation penalty amount in supplier currency
price_info object Penalty price breakdown (see Section 6.11 Price Info Object)
currency_info object Currency conversion details (see Section 6.10 Currency Info Object)
prices array Multi-level penalty price breakdown
base_amount float Penalty base amount in converted currency
markup_amount float Penalty markup amount
discount_amount float Penalty discount amount
tax_amount float Penalty tax amount
vat_amount float Penalty VAT amount
total_amount float Penalty total amount in converted currency
supplier_base_amount float Penalty amount in supplier currency
supplier_total_amount float Penalty total in supplier currency

Cancellation Policy Example:

The following example shows a 3-period cancellation policy:

Period Date Range Penalty Description
1 2026-03-03 → 2026-03-25 14:58 0.00 MYR Free cancellation period
2 2026-03-25 14:58 → 2026-03-26 14:58 206.82 MYR Partial penalty (1 night charge)
3 2026-03-26 14:59 → 2026-03-26 23:59 1,034.16 MYR Full penalty (no refund)

Cancellation Sample:

{
    "cancellations": [
        {
            "from": "2026-03-03T05:48:23.437431",
            "to": "2026-03-25T14:58:00",
            "amount": 0,
            "utc_from": "2026-03-03T00:00:00",
            "utc_to": "2026-03-25T14:58:00",
            "price_info": {
                "base_amount": 0.0,
                "markup_amount": 0,
                "tax_amount": 0,
                "vat_amount": 0,
                "discount_amount": 0,
                "total_amount": 0.0,
                "supplier_base_amount": 0,
                "supplier_total_amount": 0
            },
            "currency_info": {
                "rate": 3.1798671043,
                "conversion": "MYR",
                "original": "SGD",
                "rounding": 2
            },
            "base_amount": 0.0,
            "total_amount": 0.0,
            "supplier_base_amount": 0,
            "supplier_total_amount": 0
        },
        {
            "from": "2026-03-25T14:58:00",
            "to": "2026-03-26T14:58:00",
            "amount": 65.04,
            "utc_from": "2026-03-25T14:59:00",
            "utc_to": "2026-03-26T14:58:00",
            "price_info": {
                "base_amount": 206.82,
                "markup_amount": 0,
                "tax_amount": 0,
                "vat_amount": 0,
                "discount_amount": 0,
                "total_amount": 206.82,
                "supplier_base_amount": 65.04,
                "supplier_total_amount": 65.04
            },
            "currency_info": {
                "rate": 3.1798671043,
                "conversion": "MYR",
                "original": "SGD",
                "rounding": 2
            },
            "base_amount": 206.82,
            "total_amount": 206.82,
            "supplier_base_amount": 65.04,
            "supplier_total_amount": 65.04
        },
        {
            "from": "2026-03-26T14:59:00",
            "to": "2026-03-26T23:59:00",
            "amount": 325.22,
            "utc_from": "2026-03-26T14:59:00",
            "utc_to": "2026-03-26T23:59:00",
            "price_info": {
                "base_amount": 1034.16,
                "markup_amount": 0,
                "tax_amount": 0,
                "vat_amount": 0,
                "discount_amount": 0,
                "total_amount": 1034.16,
                "supplier_base_amount": 325.22,
                "supplier_total_amount": 325.22
            },
            "currency_info": {
                "rate": 3.1798671043,
                "conversion": "MYR",
                "original": "SGD",
                "rounding": 2
            },
            "base_amount": 1034.16,
            "total_amount": 1034.16,
            "supplier_base_amount": 325.22,
            "supplier_total_amount": 325.22
        }
    ]
}

6.9 Product Type Object

Parameter Type Description
id string Product type identifier
code string Product code (e.g., "hotel")
name string Product display name (e.g., "Hotel")
icon string Product icon identifier

6.10 Currency Info Object

Parameter Type Description
rate float Exchange rate
conversion string Target currency code (e.g., "MYR")
original string Source currency code (e.g., "SGD")
rounding integer Decimal rounding precision

6.11 Price Info Object

Parameter Type Description
base_amount float Base price amount
markup_amount float Markup amount applied
tax_amount float Tax amount
vat_amount float VAT amount
discount_amount float Discount amount
total_amount float Total amount after all adjustments
supplier_base_amount float Original supplier base amount
supplier_total_amount float Original supplier total amount
reward_points float Reward points earned (if applicable)
old_amount float Original amount before promotions (if applicable)

6.12 Reward Info Object

Parameter Type Description
reward_points float Total reward points earned
rate float Points conversion rate
currency_code string Currency code for points calculation
conversion_id string Conversion rule identifier (nullable)
is_enabled boolean Whether rewards are enabled for this booking

6.13 Response Sample

{
    "total": 1,
    "result": [
        {
            "id": "d35036d1-1c44-4120-a6ca-36f1e39bc3c7",
            "created_at": "2026-03-03T05:49:49.925846+00:00",
            "updated_at": "2026-03-03T05:51:32.000741+00:00",
            "deleted": false,
            "booking_id": "82bd719f-99e4-4648-a304-ef4623cfe86b",
            "package_id": null,
            "product_id": "f20072987bfa43bfab8d60f584dbb5ea",
            "product_ref": "18997",
            "shopping_id": "e0381ba558704f7fa5d3d4713178d03e",
            "shopping_item_id": "70a2299335644efa9462080f32b65115",
            "status": "vouchered",
            "free_cancellation_deadline": "2026-03-25T14:58:00+00:00",
            "free_cancellation": true,
            "data": {
                "source_id": "apyacwgpawq",
                "contract_id": "166",
                "hotel_id": "109794",
                "easygds_id": "18997",
                "eps_id": "18997",
                "is_has_refundable_rooms": true,
                "supplier_code": "APItude",
                "supplier_source": "APItude",
                "currency": "SGD",
                "is_client": false,
                "name": "Shinagawa Prince Hotel",
                "street_address": "4-10-30 Takanawa Minato-ku, Tokyo, Tokyo-to, 108-8611, JP",
                "type": "hotel",
                "star": 4.0,
                "phone": "81-3-3440-1111",
                "room_count": 1,
                "pax_count": 2,
                "night_count": 1,
                "checkin_date": "2026-03-27T00:00:00",
                "checkout_date": "2026-03-28T00:00:00",
                "checkin_time": "midnight",
                "checkout_time": "11:00 AM",
                "free_cancellation": true,
                "free_cancellation_deadline": "2026-03-25T14:58:00",
                "cancellation_deadline": "2026-03-25T14:58:00",
                "country_code": "MY",
                "booking_ref": "gq-x102v0uezhfcv8z",
                "rooms": [
                    {
                        "idx": 1,
                        "room_name": "Main Tower Twin Room (6th–16th Floors) Non-Smoking",
                        "room_type_id": "TWN.C2-2",
                        "name": "16th floor Twin Main tower",
                        "supplier_room_name": "Main Tower Twin Room (6th–16th Floors) Non-Smoking",
                        "easygds_id": "6e7f65703b104cd09dd4abf333ad7ff3",
                        "free_cancellation": true,
                        "cancellation_deadline": "2026-03-25T14:58:00",
                        "supplier_cancellation_deadline": "2026-03-25T14:58:00",
                        "cancellation_buffer": 0,
                        "source_id": "apyacwgpawq",
                        "supplier_code": "APItude",
                        "hotel_id": "109794",
                        "hotel_easygds_id": "18997",
                        "images": [],
                        "contents": {
                            "description": "Rooms come with a fridge and an en suite bathroom with a bathtub and shower. Free toiletries and a hairdryer are provided. Guests will also find a personal locker in the room."
                        },
                        "area": {
                            "square_meters": 21,
                            "square_feet": null
                        },
                        "occupancy": {
                            "adults": 2,
                            "children": 2,
                            "infants": null
                        },
                        "beds": null,
                        "remainings": 19,
                        "rate": {
                            "base_price": 292.7,
                            "board_basis": "Room Only",
                            "board_code": "RO",
                            "currency": "SGD",
                            "gross_price": 292.7,
                            "net_price": 292.7,
                            "price": 292.7,
                            "tax": 0,
                            "non_refundable": false,
                            "free_cancellation": true,
                            "free_cancellation_deadline": "2026-03-25 14:58",
                            "board_basis_code": "room-only",
                            "cancellations": [
                                {
                                    "from": "2026-03-03T05:48:23.437431",
                                    "to": "2026-03-25T14:58:00",
                                    "amount": 0,
                                    "utc_from": "2026-03-03T00:00:00",
                                    "utc_to": "2026-03-25T14:58:00",
                                    "price_info": {
                                        "markup_amount": 0,
                                        "discount_amount": 0,
                                        "base_amount": 0.0,
                                        "tax_amount": 0,
                                        "vat_amount": 0,
                                        "total_amount": 0.0,
                                        "supplier_base_amount": 0,
                                        "supplier_total_amount": 0
                                    },
                                    "currency_info": {
                                        "rate": 3.1798671043,
                                        "conversion": "MYR",
                                        "original": "SGD",
                                        "rounding": 2
                                    },
                                    "base_amount": 0.0,
                                    "total_amount": 0.0,
                                    "supplier_base_amount": 0,
                                    "supplier_total_amount": 0
                                },
                                {
                                    "from": "2026-03-25T14:58:00",
                                    "to": "2026-03-26T14:58:00",
                                    "amount": 65.04,
                                    "utc_from": "2026-03-25T14:59:00",
                                    "utc_to": "2026-03-26T14:58:00",
                                    "price_info": {
                                        "markup_amount": 0,
                                        "discount_amount": 0,
                                        "base_amount": 206.82,
                                        "tax_amount": 0,
                                        "vat_amount": 0,
                                        "total_amount": 206.82,
                                        "supplier_base_amount": 65.04,
                                        "supplier_total_amount": 65.04
                                    },
                                    "currency_info": {
                                        "rate": 3.1798671043,
                                        "conversion": "MYR",
                                        "original": "SGD",
                                        "rounding": 2
                                    },
                                    "base_amount": 206.82,
                                    "total_amount": 206.82,
                                    "supplier_base_amount": 65.04,
                                    "supplier_total_amount": 65.04
                                },
                                {
                                    "from": "2026-03-26T14:59:00",
                                    "to": "2026-03-26T23:59:00",
                                    "amount": 325.22,
                                    "utc_from": "2026-03-26T14:59:00",
                                    "utc_to": "2026-03-26T23:59:00",
                                    "price_info": {
                                        "markup_amount": 0,
                                        "discount_amount": 0,
                                        "base_amount": 1034.16,
                                        "tax_amount": 0,
                                        "vat_amount": 0,
                                        "total_amount": 1034.16,
                                        "supplier_base_amount": 325.22,
                                        "supplier_total_amount": 325.22
                                    },
                                    "currency_info": {
                                        "rate": 3.1798671043,
                                        "conversion": "MYR",
                                        "original": "SGD",
                                        "rounding": 2
                                    },
                                    "base_amount": 1034.16,
                                    "total_amount": 1034.16,
                                    "supplier_base_amount": 325.22,
                                    "supplier_total_amount": 325.22
                                }
                            ],
                            "price_info": {
                                "markup_amount": 0,
                                "discount_amount": 0,
                                "base_amount": 930.75,
                                "tax_amount": 0,
                                "vat_amount": 0,
                                "total_amount": 930.75,
                                "supplier_base_amount": 292.7,
                                "supplier_total_amount": 292.7,
                                "reward_points": 9308.0
                            },
                            "currency_info": {
                                "rate": 3.1798671043,
                                "conversion": "MYR",
                                "original": "SGD",
                                "rounding": 2
                            },
                            "reward_info": {
                                "reward_points": 9308.0,
                                "rate": 10.0,
                                "currency_code": "MYR",
                                "conversion_id": null,
                                "is_enabled": true
                            },
                            "remainings": 19,
                            "room_name": "Main Tower Twin Room (6th–16th Floors) Non-Smoking",
                            "room_type_id": "TWN.C2-2",
                            "remarks": [
                                "Accommodation tax (100 - 200 yen per person per night) will be separately collected at the hotel from Oct 1st, 2021. .  Check-in hour 15:00-00:00.Car park YES (With additional debit notes).Check-out hour -11:00.Identification card at arrival.Single-Use Plastic Free."
                            ]
                        }
                    }
                ],
                "price_info": {
                    "base_amount": 930.75,
                    "markup_amount": 0,
                    "tax_amount": 0,
                    "vat_amount": 0,
                    "discount_amount": 0,
                    "total_amount": 930.75,
                    "supplier_base_amount": 292.7,
                    "supplier_total_amount": 292.7,
                    "reward_points": 9308.0,
                    "old_amount": 930.75
                },
                "reward_info": {
                    "reward_points": 9308.0,
                    "rate": 10.0,
                    "currency_code": "MYR",
                    "conversion_id": null,
                    "is_enabled": true
                },
                "currency_info": {
                    "rate": 3.1798671043,
                    "conversion": "MYR",
                    "original": "SGD",
                    "rounding": 2
                },
                "location": {
                    "point": {
                        "type": "Point",
                        "coordinates": [
                            139.73671,
                            35.62796
                        ]
                    },
                    "country_code": "JP",
                    "city_codes": [
                        "TYO"
                    ],
                    "city_code": "TYO"
                },
                "avatar": {
                    "caption": null,
                    "id": null,
                    "urls": {
                        "sm": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_t.jpg",
                        "md": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_b.jpg",
                        "lg": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_z.jpg"
                    },
                    "file_ids": null,
                    "sm": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_t.jpg",
                    "md": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_b.jpg",
                    "lg": "https://i.travelapi.com/lodging/1000000/20000/19000/18997/f43980b3_z.jpg"
                },
                "ratings": {
                    "tripadvisor": null,
                    "liteapi": {
                        "count": 9664,
                        "overall": 3.95
                    },
                    "expedia": {
                        "count": 3544,
                        "overall": 4.2,
                        "cleanliness": 4.3,
                        "service": 4.3,
                        "comfort": 4.1,
                        "condition": 4.0,
                        "amenities": 4.1
                    }
                },
                "search_id": "80755bf5f3d4458202e6c6545d1e0510",
                "package_id": null
            },
            "currency_info": {
                "rate": 3.1798671043,
                "conversion": "MYR",
                "original": "SGD",
                "rounding": 2
            },
            "product": {
                "id": "f20072987bfa43bfab8d60f584dbb5ea",
                "code": "hotel",
                "name": "Hotel",
                "icon": "hotel"
            },
            "pdf_url": "https://core.stg-services.easygds.com/api/bookings/products/pdf?bp_id=d35036d1-1c44-4120-a6ca-36f1e39bc3c7&token=ecbdc0c7d1b7a3584bdf576e2d18832514baf84dcf5698748583344cebb50731",
            "error_message": null,
            "search": {
                "id": "80755bf5f3d4458202e6c6545d1e0510",
                "trip_id": null,
                "package_id": null,
                "product_code": "hotel",
                "progress": 1
            }
        }
    ]
}

Note: The response sample above is trimmed for readability. The actual response may contain additional fields such as selected_rooms (rooms with booking reference numbers like pvd_bk_ref and bk_ref), contents (hotel descriptions, amenities, policies, fees), amenity_ids, and expanded search with full payload details.

7. Status Codes

7.1 Booking Status

The status field in the booking object indicates the current state of the booking.

Status Description
processing Booking is being processed after payment
success Booking completed successfully and confirmed
failed Booking failed due to payment or supplier error
canceled Booking has been cancelled
quote Booking created as a quote/estimate

7.2 Product Status (Hotel Only)

The status field in the products array indicates the state of each booked hotel product.

Status Description
processing Hotel booking is being processed
confirmed Hotel booking successful, awaiting voucher generation
vouchered Hotel voucher has been issued
failed Hotel booking failed
canceled Hotel reservation has been cancelled
refunded Hotel cancelled and payment refunded

7.3 Payment Status

The status field in the payment object indicates the payment transaction state.

Status Description
processing Payment being processed by gateway
success Payment successfully completed
failed Payment failed
refunded Payment refunded to customer

7.4 Payment Line Status

The status field in payment.lines[] array indicates individual payment transaction attempts. Each payment line represents a single attempt to process payment through the gateway.

Status Description
success Transaction completed successfully
failed Transaction failed
processing Transaction being processed

8. Error Codes

General Error Codes

Error Code HTTP Status Description
InvalidCredentials 401 Invalid email or password
Unauthorized 401 Invalid or expired access token
AccountLocked 403 Account has been locked
AccountInactive 403 Account is not active
BookingNotFound 404 Booking code does not exist
InvalidBookingCode 400 Invalid booking code format
InternalServerError 500 Server error occurred

Error Response Examples

Invalid Credentials

{
    "error": "InvalidCredentials",
    "message": "Invalid email or password"
}

Expired Token

{
    "error": "Unauthorized",
    "message": "Access token has expired"
}

Booking Not Found

{
    "error": "BookingNotFound",
    "message": "Booking with code DEMOP010156 not found"
}