POST /api/v1/hotels/pre_book

Lock in the price of a chosen rate and get a partnerOrderId + booking form ahead of book_hotel. Requires Read+Write permission.

Pre-book a rate to lock in the price and receive a partnerOrderId for the final book_hotel call.

Permission: Read+Write

pre_book re-verifies the rate with the supplier and caches the commission-enriched offer server-side. book_hotel reads from this cache, so the backend — not the client — owns the exact amount that gets debited. Always call pre_book immediately before book_hotel; don't reuse an old partnerOrderId from a previous session.

Request body

Field	Type	Required	Default	Description
`hash`	string	Yes	—	The `bookHash` from a `get_rates` response
`price_increase_percent`	integer	No	`0`	Allowed price increase (%) the supplier may apply before the pre-book is rejected instead of silently charging more

Request example

curl --request POST \
  --url https://api.fx-port.com/api/v1/hotels/pre_book \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "hash": "h-048751d0-ef21-577c-9fcf-2725152d3afc",
    "price_increase_percent": 5
  }'

Response example

{
  "environment": "sandbox",
  "success": true,
  "status": "ok",
  "partnerOrderId": "HMTLZLWGQ",
  "priceChanged": false,
  "data": {
    "hotelId": "test_hotel",
    "hid": 8526976,
    "rates": [
      {
        "bookHash": "p-1e4ec39e-0feb-4f1d-bc14-33e853714c44",
        "room": { "name": "Standard Room", "capacity": 2 },
        "meal": { "type": "nomeal", "included": false },
        "dailyPrices": [145.50, 145.50],
        "cancellationPolicy": { "freeCancellationBefore": "2026-11-13T21:00:00" },
        "pricing": {
          "supplierCurrency": "EUR",
          "agencyCurrency": "DZD",
          "originalPrice": 291.00,
          "agencyCommission": 87.30,
          "totalPrice": 43812.75,
          "b2bPrice": 43725.45
        }
      }
    ]
  },
  "formData": {
    "partnerOrderId": "HMTLZLWGQ",
    "orderId": 150908803,
    "itemId": 139512659,
    "paymentTypes": [
      { "amount": "291.00", "currencyCode": "EUR", "isNeedCreditCard": false, "isNeedCvc": false, "type": "deposit" }
    ]
  }
}

Field reference

Field	Description
`partnerOrderId`	Pass this to `book_hotel` as `partner_order_id`
`priceChanged`	`true` if the supplier's price moved since `get_rates` (within `price_increase_percent`) — the returned `pricing.totalPrice` reflects the new, final price
`data.rates[0].bookHash`	A new, pre-book-scoped hash — you don't need it again; `book_hotel` uses `partnerOrderId`
`formData`	Supplier payment-form metadata — informational, `book_hotel` handles payment internally (always `deposit` from your agency balance)

If the supplier rejects because the live price increased beyond price_increase_percent, re-run get_rates to get the current price and try pre_book again with the new bookHash.

Next step

Call book_hotel with the partnerOrderId and guest details.