Skip to content

BookingNew

POST {base_url}/1.0/bookings

Creates the actual reservation. Final step in the booking flow.

Header Value
Authorization Bearer <access_token>
Content-Type application/json
Accept application/json
{
"bookingKey": "<bookingKey from /bookings/hold>",
"clientReference": "99999",
"client": {
"name": "Jane",
"surname": "Doe",
"contactData": [
{
"email": "jane.doe@example.com",
"phone": {
"countryCode": "+52",
"number": "5512312322"
}
}
]
},
"commentsForHotel": "Special requests..."
}
Field Required Type Notes
bookingKey Yes string From BookingHold (≤ 5 min ago)
clientReference Yes string Partner reference. It cannot be used to look up a booking through the API.
client.name Yes string A-Z, a-z, 0-9. UTF-8
client.surname Yes string A-Z, a-z, 0-9. UTF-8
client.contactData[].email No string Recommended
client.contactData[].phone.countryCode No string E.g. +52
client.contactData[].phone.number No string Digits only
commentsForHotel No string Free-form requests for the hotel

In a sample where client had been sent in BookingHold, a BookingNew request without client was accepted (HTTP 200). See Guest data in the hold.

{
"confirmation": {
"bookingId": 21198221,
"clientReference": "99999",
"amount": 244.02,
"currency": "USD",
"cancellationPolicies": [
{
"startDate": "2023-06-18T00:00:00Z",
"endDate": "2023-06-24T23:59:59.9999999Z",
"amount": 244.02,
"currency": "USD"
}
],
"oldAmount": 244.02,
"status": "CONFIRMED"
},
"eventId": "f4901c59-33eb-4069-97fb-efe85bf891cd"
}

A successful BookingNew response may omit the error property; do not require it.

Status Meaning
CONFIRMED PT has accepted the booking and is responsible for it to the partner.
CREATED The booking is registered but not CONFIRMED. Do not treat it as a confirmed booking.
CANCELLED Booking failed and resources were released

The hotel confirmation number becomes available later in hotels[].confirmationCode through BookingGet. Until it is available, the field is empty. No notification is sent; the partner must query BookingGet to obtain it.

Can be present even when there was no price change between Hold and BookingNew; in that case it equals amount. When there was a price change, it shows the original quoted amount versus the current amount charged. Always check oldAmount against amount to detect drift.

Code HTTP Message Cause What to do
1101 500 The provided key has already been used previously. bookingKey already used Do not obtain a new key to restart the flow — see below
5001 500 Invalid Policy Internal Contact PriceTravel with the request, the response, and the eventId
6001 400 Invalid New Request, can not parse the BookingKey bookingKey corrupted, expired, or empty Send the bookingKey from BookingHold complete and unmodified
7001 400 A valid client data was not provided Missing/invalid name, surname, or contactData Send name, surname, and contactData with valid values
7002 400 A valid credit card was not provided No valid credit card in the Payment object Only relevant if a Payment object is included: check the card data

1101 — The provided key has already been used previously. Reusing a bookingKey after a successful BookingNew has been observed to return 1101 without creating a second booking and without returning the original bookingId. The previous attempt probably processed, but 1101 alone does not prove that a booking exists. Do not obtain a new key to restart the flow. Contact PT with clientReference, the attempt timestamp in UTC, and eventId if available.

Do not treat eventId as a unique identifier for each request: it may repeat across retries of the same booking. Keep the timestamp of each attempt alongside its eventId.

  • The bookingKey must be < 5 minutes old.
  • Once status: CONFIRMED, you cannot modify the booking — only cancel and re-create.
  • A CONFIRMED response is binding; the channel will be charged.
  • Do not retry after a timeout or 5xx until the previous outcome is resolved — see the retry strategy below.

The API does not provide idempotency keys. If you receive a timeout or 5xx after BookingNew:

  1. Do not retry blindly — the booking may have been created.
  2. Wait ~10 seconds.
  3. If you have the numeric bookingId, call GET /1.0/bookings/{bookingId}. The API does not provide a booking lookup by clientReference: it cannot replace bookingId, and GET /1.0/bookings?clientReference=... is not an available route.
  4. If you do not have the bookingId, contact PT with your clientReference, the attempt timestamp in UTC, and eventId if available. PT can locate the booking internally using clientReference. Do not restart the booking flow while the previous outcome remains unresolved.