Bookings

The booking endpoints handle the creation and management of hotel reservations. After completing a prebook, you can finalize the booking with guest details and payment information.

The booking model

Booking object

Name
id
Type
integer
Description
Unique booking identifier.
Name
status
Type
BookingStatus
Description
Booking status. See Enums section.
Name
booking_reference
Type
array of strings
Description
Array of confirmation numbers from the hotel/vendor.
Name
voucher_url
Type
string
Description
URL to download the booking voucher PDF.
Name
hotel_id
Type
integer
Description
Hotel identifier.
Name
check_in
Type
string
Description
Check-in date (YYYY-MM-DD).
Name
check_out
Type
string
Description
Check-out date (YYYY-MM-DD).
Name
nights
Type
integer
Description
Number of nights.
Name
first_name
Type
string
Description
Lead guest first name.
Name
last_name
Type
string
Description
Lead guest last name.
Name
email
Type
string
Description
Contact email address.
Name
phone
Type
string
Description
Contact phone number.
Name
price_per_night_avg
Type
number
Description
Average price per night.
Name
price_per_night
Type
array of numbers
Description
Price for each night.
Name
price_chargeable
Type
number
Description
Total amount charged.
Name
price_per_room
Type
array of numbers
Description
Price per room.
Name
price_per_night_per_room
Type
array of array of numbers
Description
Price breakdown per night per room.
Name
price_before_fees
Type
number
Description
Price before taxes and fees.
Name
price_fees
Type
number
Description
Taxes and fees amount.
Name
price_due_at_hotel
Type
number
Description
Amount payable at hotel.
Name
price_inclusive
Type
number
Description
Total inclusive price.
Name
price_retail
Type
number
Description
Retail/comparison price.
Name
price_currency
Type
string
Description
Currency code.
Name
cancellation_policy
Type
string
Description
Cancellation policy type.
Name
cancellation_policy_date
Type
string
Description
Free cancellation deadline.
Name
cancellation_policy_data
Type
array of CancellationPolicyData
Description
Detailed cancellation penalty schedule.
Name
remarks
Type
string
Description
Booking remarks and hotel policies.
Name
rate
Type
HotelRate
Description
The booked rate details.
Name
rooms
Type
array of BookingRoom
Description
Guest information per room.
Name
payment_method
Type
PaymentMethod
Description
Payment method used. See Enums section.
Name
is_sandbox
Type
boolean
Description
Whether this is a test booking.
Name
hotel
Type
HotelDetails
Description
Hotel details.
Name
loyalty_number
Type
string
Description
Loyalty program number if provided.
Name
special_request
Type
string
Description
Special requests for the hotel.
Name
price_commission
Type
number
Description
Commission amount earned.
Name
price_commission_paid
Type
number
Description
Commission amount paid (if applicable).
Name
price_commission_currency
Type
string
Description
Commission currency.
Name
created_at
Type
timestamp
Description
Booking creation timestamp (ISO 8601).
Name
updated_at
Type
timestamp
Description
Last update timestamp (ISO 8601).

BookingRoom object

Name
adults
Type
array of BookingGuest
Description
Adult guests in this room.
Name
children
Type
array of BookingChild
Description
Child guests in this room.

BookingGuest object

Name
title
Type
BookingTitle
Description
Guest title. See Enums section.
Name
first_name
Type
string
Description
Guest first name.
Name
last_name
Type
string
Description
Guest last name.

BookingChild object

Name
title
Type
BookingTitle
Description
Child title.
Name
first_name
Type
string
Description
Child first name.
Name
last_name
Type
string
Description
Child last name.
Name
age
Type
integer
Description
Child age.

CancellationPolicyData object

Name
from_datetime
Type
string
Description
Start datetime for this penalty period (ISO 8601).
Name
price_cancellation_penalty
Type
number
Description
Penalty amount if cancelled during this period.
Name
price_currency
Type
string
Description
Penalty currency.

Request models

BookCreateRequest object

Name
rooms
Type
array of BookingRoomWithLead
Description
Array of room lead guest names. Must match the number of rooms from prebook.
Name
email
Type
string
Description
Contact email address. Required.
Name
phone
Type
string
Description
Contact phone number. Required.
Name
payment_token
Type
string
Description
Payment processor token (required for credit_card).
Name
payment_first_name
Type
string
Description
Cardholder first name (required for credit_card).
Name
payment_last_name
Type
string
Description
Cardholder last name (required for credit_card).
Name
payment_postal_code
Type
string
Description
Billing postal code (required for credit_card).
Name
payment_expiration
Type
string
Description
Card expiration in MM/YY format (required for credit_card).
Name
promo_code
Type
string
Description
Promotional code for discounts.
Name
idempotency_key
Type
string
Description
Unique key to prevent duplicate bookings.
Name
loyalty_number
Type
string
Description
Hotel loyalty program number.
Name
special_request
Type
string
Description
Special requests for the hotel.

BookingRoomWithLead object

Name
lead_first_name
Type
string
Description
Lead guest first name. Required.
Name
lead_last_name
Type
string
Description
Lead guest last name. Required.

PromoCodeRequest object

Name
code
Type
string
Description
The promotional code to validate.
Name
booking_amount
Type
number
Description
The booking amount to calculate discount against.

PromoCodeResponse object

Name
price_discount_amount
Type
number
Description
Discount amount if code is valid.
Name
price_currency
Type
string
Description
Discount currency.

Enums

BookingStatus enum

confirmed - Booking is confirmed
cancelled - Booking has been cancelled
pending - Booking is pending confirmation
failed - Booking failed

PaymentMethod enum

account - Account-based payment (deducted from client balance)
credit_card - Credit card payment

BookingTitle enum

Mr - Mr.
Mrs - Mrs.
Ms - Ms.

POST/v1/book/:hotel_id/:session_id/:rate_id/:payment_method

Create booking

Creates a booking after a successful prebook. Requires guest information and payment details.

Path parameters

Name
hotel_id
Type
integer
Description
The hotel identifier.
Name
session_id
Type
uuid
Description
The session ID from availability search.
Name
rate_id
Type
uuid
Description
The rate identifier.
Name
payment_method
Type
PaymentMethod
Description
Either "account" or "credit_card".

Required attributes

Name
rooms
Type
array
Description
Array of room lead guest names.
Name
email
Type
string
Description
Contact email address.
Name
phone
Type
string
Description
Contact phone number.

Credit card payment (required when payment_method is credit_card)

Name
payment_token
Type
string
Description
Payment processor token.
Name
payment_first_name
Type
string
Description
Cardholder first name.
Name
payment_last_name
Type
string
Description
Cardholder last name.
Name
payment_postal_code
Type
string
Description
Billing postal code.
Name
payment_expiration
Type
string
Description
Card expiration in MM/YY format.

Error responses

400 Bad Request - Validation errors, payment issues, or room mismatch
404 Not Found - Session expired or rate unavailable

Request

POST

/v1/book/1234/session-uuid/rate-uuid/account

curl -X POST https://api.tripedge.com/v1/book/1234/550e8400-e29b-41d4-a716-446655440000/a1b2c3d4-e5f6-7890-abcd-ef1234567890/account \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rooms": [
      {
        "lead_first_name": "John",
        "lead_last_name": "Doe"
      }
    ],
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "loyalty_number": "MB123456789",
    "special_request": "Late check-in requested"
  }'

Response

{
  "data": {
    "id": 12345,
    "status": "confirmed",
    "booking_reference": ["ABC123", "XYZ789"],
    "voucher_url": "https://api.tripedge.com/vouchers/12345.pdf",
    "hotel_id": 1234,
    "check_in": "2024-03-15",
    "check_out": "2024-03-18",
    "nights": 3,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "price_per_night_avg": 250.00,
    "price_per_night": [250.00, 250.00, 250.00],
    "price_chargeable": 750.00,
    "price_per_room": [750.00],
    "price_per_night_per_room": [[250.00, 250.00, 250.00]],
    "price_before_fees": 700.00,
    "price_fees": 50.00,
    "price_due_at_hotel": 0.00,
    "price_inclusive": 750.00,
    "price_retail": 850.00,
    "price_currency": "USD",
    "cancellation_policy": "Refundable",
    "cancellation_policy_date": "2024-03-14T23:59:00Z",
    "cancellation_policy_data": [
      {
        "from_datetime": "2024-03-14T23:59:00Z",
        "price_cancellation_penalty": 250.00,
        "price_currency": "USD"
      }
    ],
    "remarks": "Check-in time: 3:00 PM. Photo ID required.",
    "rate": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "hotel_id": 1234,
      "rooms": [
        {
          "name": "Deluxe King Room",
          "board": "BB",
          "room_data": {
            "images": ["https://images.tripedge.com/rooms/deluxe-king.jpg"],
            "size_sqft": 450,
            "max_occupancy": 3,
            "beds": [{ "name": "King", "size": "king", "quantity": 1 }],
            "amenities": ["minibar", "safe", "balcony"]
          },
          "price_chargeable": 750.00,
          "price_currency": "USD",
          "adults": 2,
          "children": 1
        }
      ],
      "price_chargeable": 750.00,
      "price_currency": "USD",
      "cancellation_policy": "Refundable",
      "brand_loyalty_eligible": true,
      "brand_loyalty_name": "Marriott Bonvoy",
      "payment_type": "account"
    },
    "rooms": [
      {
        "adults": [
          {
            "title": "Mr",
            "first_name": "John",
            "last_name": "Doe"
          }
        ],
        "children": []
      }
    ],
    "payment_method": "account",
    "is_sandbox": false,
    "created_at": "2024-03-10T10:30:00Z",
    "updated_at": "2024-03-10T10:30:00Z",
    "hotel": {
      "id": 1234,
      "name": "Grand Hotel New York",
      "stars": 5.0,
      "rating": 4.5,
      "review_count": 1200,
      "amenities": ["pool", "spa", "wifi", "gym"],
      "check_in_begin_time": "15:00",
      "check_out_before_time": "11:00",
      "images": ["https://images.tripedge.com/hotels/1234/main.jpg"],
      "coordinates": { "lat": 40.7128, "lng": -74.0060 },
      "address": {
        "address": "123 Main Street",
        "city": "New York",
        "country": "US",
        "postal_code": "10001",
        "region": "NY"
      },
      "type": "hotel"
    },
    "loyalty_number": "MB123456789",
    "special_request": "Late check-in requested",
    "price_commission": 75.00,
    "price_commission_paid": null,
    "price_commission_currency": "USD"
  },
  "success": true,
  "message": null
}

GET/v1/book

List bookings

Retrieves a paginated list of bookings for the authenticated client.

Query parameters

Name
page
Type
integer
Description
Page number. Default: 1.
Name
limit
Type
integer
Description
Results per page. Default: 50.
Name
sort_by
Type
string
Description
Field to sort by.
Name
sort_order
Type
string
Description
Sort direction: "asc" or "desc".

Filter parameters

Name
id
Type
integer
Description
Filter by booking ID.
Name
hotel_name
Type
string
Description
Filter by hotel name (partial match).
Name
created_at
Type
string
Description
Filter by creation date.
Name
first_name
Type
string
Description
Filter by guest first name.
Name
last_name
Type
string
Description
Filter by guest last name.
Name
check_in
Type
string
Description
Filter by check-in date.
Name
check_out
Type
string
Description
Filter by check-out date.
Name
status
Type
BookingStatus
Description
Filter by booking status.
Name
payment_method
Type
PaymentMethod
Description
Filter by payment method.
Name
vendor_reference
Type
string
Description
Filter by vendor reference number.

Response model

Name
data
Type
array of Booking
Description
Array of booking objects.
Name
total
Type
integer
Description
Total number of bookings matching the filters.
Name
success
Type
boolean
Description
Whether the request was successful.
Name
message
Type
string
Description
Error message if unsuccessful.

Request

GET

/v1/book

curl -G https://api.tripedge.com/v1/book \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10 \
  -d status=confirmed

Response

{
  "data": [
    {
      "id": 12345,
      "status": "confirmed",
      "booking_reference": ["ABC123"],
      "voucher_url": "https://api.tripedge.com/vouchers/12345.pdf",
      "hotel_id": 1234,
      "check_in": "2024-03-15",
      "check_out": "2024-03-18",
      "nights": 3,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "price_per_night_avg": 250.00,
      "price_per_night": [250.00, 250.00, 250.00],
      "price_chargeable": 750.00,
      "price_per_room": [750.00],
      "price_per_night_per_room": [[250.00, 250.00, 250.00]],
      "price_before_fees": 700.00,
      "price_fees": 50.00,
      "price_due_at_hotel": 0.00,
      "price_inclusive": 750.00,
      "price_retail": 850.00,
      "price_currency": "USD",
      "cancellation_policy": "Refundable",
      "cancellation_policy_date": "2024-03-14T23:59:00Z",
      "cancellation_policy_data": [
        {
          "from_datetime": "2024-03-14T23:59:00Z",
          "price_cancellation_penalty": 250.00,
          "price_currency": "USD"
        }
      ],
      "remarks": "Check-in time: 3:00 PM",
      "rate": { /* rate details */ },
      "rooms": [
        {
          "adults": [
            { "title": "Mr", "first_name": "John", "last_name": "Doe" }
          ],
          "children": []
        }
      ],
      "payment_method": "account",
      "is_sandbox": false,
      "created_at": "2024-03-10T10:30:00Z",
      "updated_at": "2024-03-10T10:30:00Z",
      "hotel": {
        "id": 1234,
        "name": "Grand Hotel New York",
        "stars": 5.0,
        "address": {
          "city": "New York",
          "country": "US"
        }
      },
      "loyalty_number": "MB123456789",
      "special_request": null,
      "price_commission": 75.00,
      "price_commission_paid": null,
      "price_commission_currency": "USD"
    }
  ],
  "total": 150,
  "success": true,
  "message": null
}

POST/v1/book/promocode

Validates a promotional code and returns the discount amount.

Required attributes

Name
code
Type
string
Description
The promotional code to validate.
Name
booking_amount
Type
number
Description
The booking amount to calculate discount against.

Request

POST

/v1/book/promocode

curl -X POST https://api.tripedge.com/v1/book/promocode \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE10",
    "booking_amount": 750.00
  }'

Response

{
  "data": {
    "price_discount_amount": 75.00,
    "price_currency": "USD"
  },
  "success": true,
  "message": null
}

Bookings

The booking model

Booking object

BookingRoom object

BookingGuest object

BookingChild object

CancellationPolicyData object

Request models

BookCreateRequest object

BookingRoomWithLead object

PromoCodeRequest object

PromoCodeResponse object

Enums

BookingStatus enum

PaymentMethod enum

BookingTitle enum

Create booking

Path parameters

Required attributes

Credit card payment (required when payment_method is credit_card)

Error responses

Request

Response

List bookings

Query parameters

Filter parameters

Response model

Request

Response

Validate promo code

Required attributes

Request

Response