TripEdge

V2 Book

The V2 book endpoint creates a hotel reservation using the rate ID from a successful V2 Prebook. Payment is always account-based — the booking amount is deducted from your client balance.

The book request model

  • Name
    rate_id
    Type
    string
    Description

    The rate ID from the V2 Prebook response. Required.

  • Name
    rooms
    Type
    array of V2BookRoomLead
    Description

    Array of room lead guest names. Must match the number of rooms from the prebook. Required.

  • Name
    email
    Type
    string
    Description

    Contact email address. Required.

  • Name
    phone
    Type
    string
    Description

    Contact phone number. Required.

  • Name
    loyalty_number
    Type
    string
    Description

    Hotel loyalty program number.

  • Name
    special_request
    Type
    string
    Description

    Special requests for the hotel.

  • Name
    client_reference
    Type
    string
    Description

    Your own unique reference for this booking. Must be unique per client — if a booking with this reference already exists, the request is rejected. Use GET /book?client_reference=XXX to look up a booking by this reference.

  • Name
    language
    Type
    string
    Description

    Optional. Localizes the hotel description in the booking response. Supported values: en, fr, es, pt (default en). lang is accepted as an alias. When omitted, the language from the prebook step is used. Hotels without a translation fall back to English.

V2BookRoomLead 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.

  • Name
    guests
    Type
    array of V2BookGuest
    Description

    Additional guests in this room beyond the lead. Optional. If provided, the total count (1 lead + guests) must exactly match the expected occupants for this room (adults + children from the search request). Order: remaining adults first, then children (matching children_ages order from the search).

V2BookGuest object

  • Name
    first_name
    Type
    string
    Description

    Guest first name. Required.

  • Name
    last_name
    Type
    string
    Description

    Guest last name. Required.

  • Name
    age
    Type
    integer
    Description

    Guest age. Required for child occupants — must exactly match the corresponding child age from the original search request's children_ages. Optional and ignored for adult occupants.

The book response model

  • Name
    id
    Type
    integer
    Description

    Unique booking identifier.

  • Name
    status
    Type
    string
    Description

    Booking status: "confirmed", "cancelled", "pending", or "failed".

  • 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
    string
    Description

    Payment method used ("account").

  • 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
    client_reference
    Type
    string
    Description

    Your client reference if one was provided at booking time.

  • 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
    string
    Description

    Guest title: "Mr", "Mrs", or "Ms".

  • Name
    first_name
    Type
    string
    Description

    Guest first name.

  • Name
    last_name
    Type
    string
    Description

    Guest last name.

BookingChild object

  • Name
    title
    Type
    string
    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.

HotelRate object

  • Name
    id
    Type
    string
    Description

    Unique rate identifier.

  • Name
    hotel_id
    Type
    integer
    Description

    Associated hotel ID.

  • Name
    rooms
    Type
    array of HotelRateRoom
    Description

    Room details for this rate.

  • 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 of the stay.

  • Name
    price_chargeable
    Type
    number
    Description

    Total amount to charge the customer.

  • Name
    price_per_room
    Type
    array of numbers
    Description

    Total 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_currency
    Type
    string
    Description

    Currency code (e.g., "USD").

  • Name
    price_retail
    Type
    number
    Description

    Retail/comparison price if available.

  • Name
    cancellation_policy
    Type
    string
    Description

    Either "Refundable" or "NonRefundable".

  • Name
    cancellation_policy_datetime
    Type
    string
    Description

    Free cancellation deadline (ISO 8601).

  • Name
    cancellation_policy_data
    Type
    array of CancellationPolicyData
    Description

    Detailed cancellation penalty schedule.

  • Name
    brand_loyalty_eligible
    Type
    boolean
    Description

    Whether loyalty points can be earned.

  • Name
    brand_loyalty_required
    Type
    boolean
    Description

    Whether loyalty number is required to book.

  • Name
    brand_loyalty_name
    Type
    string
    Description

    Loyalty program name (e.g., "Marriott Bonvoy").

  • Name
    elite
    Type
    HotelRateElite
    Description

    Elite/premium rate benefits if applicable.

  • Name
    price_commission
    Type
    number
    Description

    Commission amount.

  • Name
    price_commission_currency
    Type
    string
    Description

    Commission currency code.

  • Name
    payment_type
    Type
    string
    Description

    Payment type ("account" or "credit_card").

HotelRateRoom object

  • Name
    name
    Type
    string
    Description

    Room name/type.

  • Name
    board
    Type
    string
    Description

    Board type: RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).

  • Name
    room_data
    Type
    HotelRateRoomData
    Description

    Detailed room information.

  • Name
    price_per_night_avg
    Type
    number
    Description

    Average price per night for this room.

  • Name
    price_per_night
    Type
    array of numbers
    Description

    Price for each night.

  • Name
    price_chargeable
    Type
    number
    Description

    Total chargeable amount for this room.

  • Name
    price_per_room
    Type
    number
    Description

    Total price for this room.

  • Name
    price_before_fees
    Type
    number
    Description

    Price before fees.

  • Name
    price_fees
    Type
    number
    Description

    Fees amount.

  • Name
    price_due_at_hotel
    Type
    number
    Description

    Amount due at hotel.

  • Name
    price_inclusive
    Type
    number
    Description

    Inclusive price.

  • Name
    price_currency
    Type
    string
    Description

    Currency code.

  • Name
    fees
    Type
    array of HotelRateFee
    Description

    Itemized fees.

  • Name
    deposit_per_accomodation_per_night
    Type
    number
    Description

    Deposit amount per accommodation per night.

  • Name
    deposit_currency
    Type
    string
    Description

    Deposit currency.

  • Name
    adults
    Type
    integer
    Description

    Number of adults this room accommodates.

  • Name
    children
    Type
    integer
    Description

    Number of children this room accommodates.

  • Name
    children_ages
    Type
    array of integers
    Description

    Ages of children.

HotelRateRoomData object

  • Name
    images
    Type
    array of strings
    Description

    Room image URLs.

  • Name
    size_sqft
    Type
    integer
    Description

    Room size in square feet.

  • Name
    size_sqm
    Type
    integer
    Description

    Room size in square meters.

  • Name
    max_occupancy
    Type
    integer
    Description

    Maximum total occupancy.

  • Name
    max_adults
    Type
    integer
    Description

    Maximum adults allowed.

  • Name
    max_children
    Type
    integer
    Description

    Maximum children allowed.

  • Name
    beds
    Type
    array of HotelRateRoomBedType
    Description

    Bed configuration.

  • Name
    amenities
    Type
    array of strings
    Description

    Room amenities.

  • Name
    room_id
    Type
    integer
    Description

    Internal room type identifier.

HotelRateRoomBedType object

  • Name
    name
    Type
    string
    Description

    Bed type name (e.g., "King", "Queen", "Twin").

  • Name
    size
    Type
    string
    Description

    Bed size description.

  • Name
    quantity
    Type
    integer
    Description

    Number of beds of this type.

HotelRateFee object

  • Name
    name
    Type
    string
    Description

    Fee name/description.

  • Name
    price
    Type
    number
    Description

    Fee amount.

  • Name
    due_at_hotel
    Type
    boolean
    Description

    Whether this fee is paid at the hotel.

  • Name
    price_currency
    Type
    string
    Description

    Fee currency.

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.

HotelRateElite object

  • Name
    room_upgrade_guaranteed
    Type
    boolean
    Description

    Guaranteed room upgrade.

  • Name
    room_upgrade_subject_availability
    Type
    boolean
    Description

    Room upgrade subject to availability.

  • Name
    late_checkout_guaranteed
    Type
    boolean
    Description

    Guaranteed late checkout.

  • Name
    late_checkout_subject_availability
    Type
    boolean
    Description

    Late checkout subject to availability.

  • Name
    welcome_amenity
    Type
    boolean
    Description

    Welcome amenity included.

  • Name
    description
    Type
    array of strings
    Description

    Elite benefit descriptions.

  • Name
    price_property_credit
    Type
    number
    Description

    Property credit amount.

  • Name
    price_property_credit_currency
    Type
    string
    Description

    Property credit currency.

  • Name
    property_credit_description
    Type
    string
    Description

    Property credit description.

  • Name
    breakfast_included
    Type
    boolean
    Description

    Breakfast included.

  • Name
    breakfast_description
    Type
    string
    Description

    Breakfast details.

  • Name
    breakfast_pax
    Type
    integer
    Description

    Number of guests breakfast covers.

  • Name
    travel_agent
    Type
    boolean
    Description

    Travel agent rate.

HotelDetails object

  • Name
    id
    Type
    integer
    Description

    Unique hotel identifier.

  • Name
    name
    Type
    string
    Description

    Hotel name.

  • Name
    stars
    Type
    number
    Description

    Star rating (1.0-5.0).

  • Name
    rating
    Type
    number
    Description

    Guest rating score.

  • Name
    review_count
    Type
    integer
    Description

    Number of guest reviews.

  • Name
    amenities
    Type
    array of strings
    Description

    List of hotel amenities.

  • Name
    check_in_begin_time
    Type
    string
    Description

    Earliest check-in time (HH:MM format).

  • Name
    check_out_before_time
    Type
    string
    Description

    Check-out deadline (HH:MM format).

  • Name
    images
    Type
    array of strings
    Description

    Array of image URLs.

  • Name
    coordinates
    Type
    Coordinates
    Description

    Geographic coordinates with lat and long.

  • Name
    address
    Type
    HotelAddress
    Description

    Hotel address details.

  • Name
    type
    Type
    string
    Description

    Property type (e.g., "hotel", "resort").

HotelAddress object

  • Name
    address
    Type
    string
    Description

    Street address.

  • Name
    city
    Type
    string
    Description

    City name.

  • Name
    country
    Type
    string
    Description

    Country code or name.

  • Name
    postal_code
    Type
    string
    Description

    Postal/ZIP code.

  • Name
    region
    Type
    string
    Description

    State/province/region.

Coordinates object

  • Name
    lat
    Type
    number
    Description

    Latitude.

  • Name
    long
    Type
    number
    Description

    Longitude.

Handling dropped or timed-out book requests

Booking requests can take up to 5 minutes to complete because they depend on vendor confirmation. If your initial POST /v2/book request is dropped, times out, or you lose the connection before receiving a response, the booking may still have been created on the vendor side.

If you provided a client_reference in your book request, you must poll GET /book?client_reference=YOUR_REF repeatedly for the full duration of the booking timeout (5 minutes from the original request) to determine the actual outcome. Do not assume the booking failed just because your HTTP request did not return a response.

Why this matters

When you send a book request, the API forwards it to the hotel vendor. If your connection drops after the vendor confirms but before our API responds to you, the booking exists — the guest has a reservation, and your account has been charged. Sending a second POST /v2/book with the same rate will be rejected as a duplicate if client_reference was provided, or worse, could create a double booking if it was not.

Recommended retry strategy

  1. Always include client_reference in your book request — this is your idempotency key and your recovery mechanism.
  2. If the POST /v2/book request fails or times out, immediately begin polling:
async function recoverBooking(clientReference, timeoutMs = 300000) {
  const start = Date.now()

  while (Date.now() - start < timeoutMs) {
    const response = await fetch(
      `https://api.tripedge.com/book?client_reference=${clientReference}`,
      { headers: { 'Authorization': 'Bearer {token}' } }
    )
    const data = await response.json()

    if (data.total > 0) {
      // Booking was created — check status
      const booking = data.data[0]
      if (booking.status === 'confirmed' || booking.status === 'failed') {
        return booking // Terminal state — done
      }
      // Status is 'pending' — keep polling
    }

    await new Promise(r => setTimeout(r, 5000)) // Poll every 5 seconds
  }

  // Timeout reached with no booking found — safe to retry or escalate
  return null
}
  1. Do not re-send POST /v2/book until the full timeout has elapsed and no booking was found via GET /book?client_reference=YOUR_REF.
POST/v2/book

Create booking

Creates a booking after a successful V2 prebook. Requires the rate ID, guest information, and contact details.

Required attributes

  • Name
    rate_id
    Type
    string
    Description

    The rate ID from the V2 prebook response.

  • 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.

Error responses

  • 400 Bad Request — Prebook expired and the rate is no longer available
  • 400 Bad Request — Room count mismatch
  • 400 Bad Request — Guest count mismatch (when guests is provided, lead + guests must equal expected occupants)
  • 400 Bad Request — Child age missing or mismatched (child guests must include age matching the search's children_ages)
  • 400 Bad Request — Duplicate client_reference (already used by another booking for this client)
  • 500 Internal Server Error — Insufficient funds or vendor error

Request

POST
/v2/book
curl -X POST https://api.tripedge.com/v2/book \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_id": "eyJhbGciOiJDaGFDaGEyMC1Qb2x5MTMwNSIs...",
    "rooms": [
      {
        "lead_first_name": "John",
        "lead_last_name": "Doe"
      }
    ],
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "client_reference": "ORD-2024-00123"
  }'

Response

{
  "success": true,
  "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": "eyJhbGciOiJDaGFDaGEyMC1Qb2x5MTMwNSIs...",
      "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"
          },
          {
            "title": "Mr",
            "first_name": "Jane",
            "last_name": "Doe"
          }
        ],
        "children": [
          {
            "title": "Mr",
            "first_name": "Billy",
            "last_name": "Doe",
            "age": 5
          }
        ]
      }
    ],
    "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, "long": -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",
    "client_reference": "ORD-2024-00123",
    "price_commission": 75.00,
    "price_commission_paid": null,
    "price_commission_currency": "USD"
  },
  "message": null
}
GET/book

List bookings

V2 does not have its own bookings list. Bookings created with POST /v2/book are retrieved through the V1 list bookings endpoint, using the same bearer token. Filter by client_reference to look up a specific booking — including one whose original book request dropped or timed out (see retry strategy above).

Query parameters

  • Name
    client_reference
    Type
    string
    Description

    Filter by the client reference sent in the book request (exact match).

  • Name
    page
    Type
    integer
    Description

    Page number. Default: 1.

  • Name
    limit
    Type
    integer
    Description

    Results per page. Default: 50.

All other filters (id, hotel_name, first_name, last_name, check_in, check_out, status, payment_method, vendor_reference) and sorting options are documented on the V1 book page.

Response model

  • Name
    data
    Type
    array of Booking
    Description

    Array of booking objects — the same shape as the POST /v2/book response above.

  • Name
    total
    Type
    integer
    Description

    Total number of bookings matching the filters. 0 means no booking exists for this reference.

  • Name
    success
    Type
    boolean
    Description

    Whether the request was successful.

  • Name
    message
    Type
    string
    Description

    Error message if unsuccessful.

Request

GET
/book
curl -G https://api.tripedge.com/book \
  -H "Authorization: Bearer {token}" \
  -d client_reference=ORD-2024-00123

Response

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "status": "confirmed",
      "client_reference": "ORD-2024-00123",
      "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",
      "price_chargeable": 750.00,
      "price_currency": "USD",
      "payment_method": "account",
      "created_at": "2024-03-10T10:30:00Z"
    }
  ],
  "total": 1,
  "message": null
}

Was this page helpful?