Book a hotel

Finish the booking of a rate you locked with pre_book. Booking a hotel confirms it: there is no hold or pay-later option for API keys, and your agency is debited as part of the booking, when it is confirmed (the sandbox debits nothing). The balance is checked before anything is booked (live only: 402 insufficient_balance). You send the booking id (the partnerOrderId of pre_book), the guests of each room and the contact of the booker. The price, the hotel, the dates and the residency come from the offer that pre_book stored, not from this request.

Permission: Read+Write (a read key answers 403 read_write_permission_required)

Request body

POST /api/v1/hotels/book_hotel

The body does not need the hotel, the rate or the dates: FX-Port keeps them under the booking id and always books the pre-booked rate and hotel. Do not send book_hash or hotel_id. If you do, a hash the offer was made from (the bookHash of pre_book or of get_rates, a match hash) and the offer's own hotel (in any case, its numeric hid, the id get_rates was called with) are accepted silently; any other value is ignored, never refused: the answer carries an ignored_field warning (the pre-booked rate was booked, see Conventions).

curl https://api.fx-port.com/api/v1/hotels/book_hotel \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "HMVXX4ZQ3",
  "rooms": [
    {
      "guests": [
        {
          "first_name": "Jane",
          "last_name": "Smith"
        },
        {
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ],
  "user": {
    "email": "[email protected]",
    "phone": "+15555550123"
  },
  "send_email": false
}'

curl https://api.fx-port.com/api/v1/hotels/book_hotel \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "HMVXX4ZQ3",
  "rooms": [
    {
      "guests": [
        {
          "first_name": "Anna",
          "last_name": "Smith"
        },
        {
          "first_name": "Ben",
          "last_name": "Smith"
        },
        {
          "first_name": "Cleo",
          "last_name": "Smith",
          "is_child": true,
          "age": 8
        }
      ]
    },
    {
      "guests": [
        {
          "first_name": "Dan",
          "last_name": "Jones"
        }
      ]
    }
  ],
  "user": {
    "email": "[email protected]",
    "phone": "+15555550123",
    "comment": "Late arrival"
  },
  "send_email": false
}'

curl https://api.fx-port.com/api/v1/hotels/book_hotel \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "HMVXX4ZQ3",
  "rooms": [
    {
      "guests": [
        {
          "first_name": "Jane",
          "last_name": "Smith"
        },
        {
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ],
  "user": {
    "email": "[email protected]",
    "phone": "+15555550123"
  },
  "commission_override": {
    "type": "fixed",
    "value": 50
  },
  "send_email": false
}'

Legacy names

These older spellings still work. The answer carries a deprecated_field warning that names the spelling to use (see Legacy names).

Response: the booking is pending

A real answer of the sandbox, in 3 to 5 seconds:

{
  "environment": "sandbox",
  "success": true,
  "status": "pending",
  "bookingId": "HMVXX4ZQ3",
  "partnerOrderId": "HMVXX4ZQ3",
  "hotelId": "test_hotel_do_not_book",
  "checkinDate": "2026-12-01",
  "checkoutDate": "2026-12-04",
  "pricing": {
    "totalPrice": 1484.97,
    "agencyCommission": 2.97,
    "currency": "DZD",
    "supplierCurrency": "EUR",
    "originalPrice": 3
  },
  "postProcessing": {
    "bookingDbId": "24fec1e5-a09f-48ec-8050-1adaab0a8de1",
    "webhookSent": false,
    "bucketLink": null
  },
  "processingTime": 5.449,
  "balanceDebited": false,
  "transactionCreated": false,
  "payoutCreated": false
}

The keys also come as snake_case twins (booking_id, partner_order_id, hotel_id, checkin, checkout, pricing.total_price, pricing.agency_commission, pricing.agency_currency, pricing.supplier_currency, voucher_url, processing_time, balance_debited ...). See Legacy names.

From pending to confirmed

pending becomes confirmed or failed a few seconds later: 4 to 14 seconds in our measurements (7 to 11 seconds in the last runs). There are no webhooks: you poll.

book_hotel → pending → (4 to 14 s) → confirmed → voucher links (at the same moment, or up to 10 s later)
                                   → failed

Call GET /api/v1/bookings/{booking_id}?product=hotels every 2 seconds (the booking changes within seconds: polling faster only uses your rate limits) until status is no longer pending, and stop after about 90 seconds.

async function waitForBooking(bookingId, headers) {
  const started = Date.now();
  while (Date.now() - started < 90_000) {
    const url = `https://api.fx-port.com/api/v1/bookings/${bookingId}?product=hotels`;
    const { data } = await (await fetch(url, { headers })).json();
    if (data.status !== "pending") return data; // "confirmed" or "failed"
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  throw new Error(`Booking ${bookingId} is still pending: keep polling it, do not book again`);
}

import time
import requests


def wait_for_booking(booking_id, headers, timeout=90):
    started = time.time()
    while time.time() - started < timeout:
        response = requests.get(
            f"https://api.fx-port.com/api/v1/bookings/{booking_id}",
            params={"product": "hotels"},
            headers=headers,
            timeout=30,
        )
        record = response.json()["data"]
        if record["status"] != "pending":
            return record  # "confirmed" or "failed"
        time.sleep(2)
    raise TimeoutError(f"Booking {booking_id} is still pending: keep polling it, do not book again")

When something goes wrong

The supplier documents that a timeout or a 5xx during a booking does not mean that the booking failed: it may exist. So the rule is: never call book_hotel again with the same booking id to see what happens. Read it.

Commission override

commission_override sets your commission for this booking instead of the default one of your agency:

The traveler price becomes what you pay plus the new commission. What you are debited does not change. The answer shows the new pricing.totalPrice and pricing.agencyCommission. Sandbox example: { "type": "fixed", "value": 50 } on a one-room booking costing 1,185.60 DZD gives totalPrice 1,235.60.

Errors

The 409 hotel_not_bookable_in_sandbox belongs to pre_book; this is what it carries:

{
  "test_hotels": [
    {
      "id": "test_hotel_do_not_book",
      "hid": 8473727,
      "residency": "any"
    },
    {
      "id": "test_hotel",
      "hid": 8526976,
      "residency": [
        "dz",
        "ru",
        "us"
      ]
    }
  ]
}

Next step

Poll the booking until it is confirmed, then fetch the voucher. To cancel, see Cancel a hotel booking.

Related