POST /bookings

The user selects a room, enters guest details, and confirms the reservation.

Behind that action, the platform may need to:

• Recheck the hotel rate

• Validate cancellation terms

• Apply agency pricing rules

• Send the booking request to an external supplier

• Handle delayed or missing responses

• Store the reservation

• Prevent duplicate bookings

The difficult part is not sending the supplier request.

The difficult part is deciding what to do when the supplier does not return a clear answer.

Key idea: A timeout does not always mean failure.
The supplier may have created the reservation even though the booking platform did not receive the confirmation response.

Retrying the same request without protection can create duplicate reservations.

This article explains how to design an idempotent hotel booking API that handles uncertain supplier responses safely.

The Booking Problem at a Glance

A typical booking workflow may look like this:

Client request → Rate recheck → Supplier booking request → Confirmation

The workflow becomes uncertain when the supplier response is delayed:

Client request → Supplier creates booking → Connection times out → Platform does not know the final result

At that point, the system should not immediately assume that the reservation failed.

Why Booking APIs Need Idempotency

Idempotency means that repeating the same operation produces the same final result.

A GET request is normally idempotent because requesting the same data twice does not create additional records.

Booking creation is different.

Without idempotency, two identical requests may create two reservations.

First request  → Booking A created
Second request → Booking B created

Duplicate booking requests can happen when:

The API needs a reliable way to recognize that multiple requests represent the same intended reservation.

Use an Idempotency Key

The client should send a unique idempotency key whenever it creates a booking.

Request endpoint

POST /bookings

Request headers

Request body

The server stores:

• The idempotency key

• A hash of the request

• The local booking ID

• The current booking status

• The final stored response

When the same request is received again, the platform returns the original booking result instead of creating another supplier booking.

Do Not Trust the Key Alone

An idempotency key should not be accepted for two different request payloads.

This should be rejected:

Store a hash of the normalized request body with the idempotency key.

When an existing key is found:

• Return the stored response when the request hash matches

• Return 409 Conflict when the request hash is different

Rule: One idempotency key should represent one intended booking operation.

Model the Booking as a State Machine

A booking should not be represented only as success or failure.

External supplier calls can produce uncertain states.

A more realistic booking state flow is:

CREATED
   ↓
RATE_RECHECKING
   ↓
READY_TO_BOOK
   ↓
SUBMITTING
   ├── CONFIRMED
   ├── FAILED
   └── PENDING_VERIFICATION

Additional states may include:

The most important uncertain state is:

PENDING_VERIFICATION

Use it when the platform cannot determine whether the supplier created the booking.

Do not automatically mark a timed-out request as failed.

Store the Local Booking First

Create the local booking record before calling the external supplier.

A booking record may contain:

The booking workflow becomes:

1. Validate the request

2. Check the idempotency key

3. Create the local booking record

4. Recheck the selected rate

5. Submit the supplier booking

6. Store the final or uncertain result

7. Return the local booking state

Creating the local record first provides a stable internal reference even if the supplier call fails or the application restarts.

Recheck the Rate Before Booking

Hotel search results are temporary.

Before submitting the booking, the platform should revalidate:

• Availability

• Current price

• Taxes and fees

• Currency

• Room occupancy

• Meal plan

• Cancellation policy

• Payment terms

A recheck response may look like this:

The system must then decide whether it can continue automatically.

Define Rate Change Rules

Not every price change needs the same response.

An agency may define rules such as:

A simple implementation may look like this:

The exact threshold should be a configurable business rule rather than a hard-coded platform assumption.

Keep Net Rate and Client Price Separate

The supplier net rate should be stored separately from the client-facing amount.

Keeping these values separate supports:

• Margin reporting

• Rate-change handling

• Access permissions

• Audit history

• Client-price recalculation

• Protection of internal supplier pricing

If the net rate changes, the platform can recalculate the client price according to the agency’s markup rules.

Protect Against Concurrent Requests

Two identical booking requests may arrive at nearly the same time.

A basic check can still create a race condition:

Request A checks key → not found
Request B checks key → not found
Request A inserts booking
Request B inserts booking

Use a unique database constraint on the idempotency key.

The application may attempt the insert and handle the conflict:

Important: Application-level checks are not enough.
The database should provide the final concurrency protection.

Handle Supplier Timeouts Carefully

Consider this sequence:

Platform sends booking request
          ↓
Supplier creates reservation
          ↓
Supplier response is delayed
          ↓
Platform reaches timeout

The result is uncertain.

Unsafe approach

Mark booking as FAILED
        ↓
Retry immediately

This may create another reservation.

Safer approach

Mark booking as PENDING_VERIFICATION
        ↓
Check supplier booking status
        ↓
Confirm, fail, or escalate for review

The API response may look like this:

{
  "bookingId": "bkg_91c92f40",
  "status": "PENDING_VERIFICATION",
  "message": "The booking request was submitted and is being verified."
}

This response is more accurate than claiming that the booking failed.

Use a Reconciliation Worker

A background worker should investigate uncertain bookings.

Its responsibility is to:

1. Find bookings in PENDING_VERIFICATION

2. Query the supplier using the internal or supplier reference

3. Confirm whether a booking exists

4. Update the local booking status

5. Escalate unresolved cases

A simplified workflow:

Find pending booking
        ↓
Query supplier
        ↓
Confirmed? ───── Yes ───→ Mark CONFIRMED
        │
        No
        ↓
Not found? ───── Yes ───→ Mark FAILED
        │
        No
        ↓
Retry or move to MANUAL_REVIEW

A production reconciliation worker should also support:

• Retry limits

• Exponential backoff

• Dead-letter queues

• Monitoring

• Alerting

• Supplier-specific lookup rules

• Manual-review escalation

Add Exponential Backoff

Repeatedly calling a failing supplier can make the problem worse.

Use increasing retry delays.

A possible retry schedule:

Jitter prevents multiple workers from retrying at exactly the same moment.

After the retry limit is reached, the booking should move to manual review.

Do Not Keep the Public Request Open Indefinitely

The public booking API should not wait forever for a slow supplier.

After a defined timeout, return the current internal booking status.

Possible responses include:

Confirmed

Pending verification

Failed

This keeps infrastructure timeouts separate from the actual booking state.

Record a Complete Audit Trail

Every important transition should be recorded.

Useful booking events include:

An audit event may contain:

An audit trail helps answer:

• Which rate was shown to the client?

• Did the cancellation policy change?

• When was the supplier request sent?

• Why was the booking marked uncertain?

• Which user approved the revised price?

• Did a retry create the confirmed reservation?

Return the Stored Result for Repeated Requests

When the same idempotency key is received again, the server should return the existing booking result.

The supplier booking should not be submitted again simply because the client repeated the API request.

Suggested Booking Endpoint Behaviour

A booking endpoint can follow this sequence:

Receive POST /bookings
        ↓
Validate Idempotency-Key
        ↓
Hash request payload
        ↓
Find existing booking
        ↓
Existing?
   ├── Yes → Compare hash → Return stored result
   └── No  → Create local booking
                    ↓
              Recheck rate
                    ↓
              Submit supplier booking
                    ↓
        Confirmed / Failed / Pending verification

Recommended HTTP responses:

Test the Failure Cases

Testing only successful bookings is not enough.

1. Duplicate client request

Submit the same request twice using the same idempotency key.

Expected result

• One local booking

• One supplier submission

• Same result returned twice

2. Same key with different payload

Reuse the key with another hotel or rate token.

Expected result

• 409 Conflict

• No supplier booking call

3. Supplier timeout after confirmation

Simulate a supplier that creates the booking but delays its response.

Expected result

• Status becomes PENDING_VERIFICATION

• Reconciliation finds the reservation

• Final status becomes CONFIRMED

• No duplicate booking is created

4. Rate change before booking

Return a higher price during rate recheck.

Expected result

• Booking does not continue automatically

• Status becomes CLIENT_REAPPROVAL_REQUIRED

5. Cancellation policy change

Keep the price unchanged but return a non-refundable condition.

Expected result

• Automatic booking is blocked

• Revised terms are stored

• New approval is requested

6. Concurrent requests

Send several identical requests simultaneously.

Expected result

• One booking record

• One supplier submission

• Identical client results

Implementation Checklist

Before releasing an idempotent booking endpoint, verify the following:

• [ ] Every create-booking request requires an idempotency key

• [ ] The request payload is normalized and hashed

• [ ] The idempotency key has a database uniqueness constraint

• [ ] A local booking is created before the supplier call

• [ ] Rates are rechecked before booking

• [ ] Material price changes require approval

• [ ] Cancellation-policy changes require approval

• [ ] Supplier timeouts create an uncertain state

• [ ] Pending bookings are reconciled asynchronously

• [ ] Retries use backoff and jitter

• [ ] Duplicate supplier submissions are prevented

• [ ] Booking events are written to an audit log

• [ ] Repeated requests return the stored result

• [ ] Concurrent-request behaviour is tested

Final Thoughts

A reliable hotel booking API cannot treat every timeout as a failure.

External suppliers may return:

• Delayed responses

• Changed rates

• Updated cancellation conditions

• Temporary errors

• Uncertain booking results

The booking platform must preserve the intended operation while preventing duplicate reservations.

The main design principles are:

1. Require an idempotency key

2. Store a hash of the request

3. Create the local booking record first

4. Recheck rates before submission

5. Model uncertain outcomes explicitly

6. Use database constraints for concurrency protection

7. Reconcile timed-out supplier requests

8. Apply controlled retries

9. Maintain a complete audit history

10. Return stored results for repeated requests

Idempotency is not only an API convenience.

In booking systems, it is a core safeguard against duplicate reservations, duplicate charges, operational confusion, and difficult client disputes.

A typical workflow may involve supplier portals, spreadsheets, email threads, screenshots, and manually prepared quote documents. Although each tool handles one part of the process, the lack of a shared workflow can create problems with pricing accuracy, data consistency, and client communication.

This article examines how a B2B hotel booking platform can structure the process from property search to final booking confirmation. It covers supplier data, rate review, markup logic, branded quote generation, team workflows, and API connectivity.

DNA Travel is used as one practical example of a platform designed around this type of professional hotel booking workflow.

Travel agencies often manage hotel rates, client details, and quote information across multiple tools.

What Is a B2B Hotel Booking Platform?

A B2B hotel booking platform is designed for travel professionals rather than direct consumers.

It can support:

• Independent travel advisors

• Travel agencies

• Corporate travel teams

• Tour operators

• Travel management companies

• Hotel booking resellers

• Travel technology businesses

The platform connects hotel search, rate review, pricing, quote preparation, and reservation management through a business-focused workflow.

Unlike a consumer booking website, a professional platform may also need to support:

• Net hotel rates

• Agency markup

• User permissions

• Branded client quotes

• Multiple advisors

• Corporate booking requirements

• API connectivity

• Booking status tracking

The goal is not only to find an available hotel. The system must help the travel business manage the commercial and operational parts of the booking.

The Main Workflow Challenges

Running a travel business involves more than searching for a property.

An advisor may need to:

• Search across multiple hotel suppliers

• Compare different room categories

• Review cancellation conditions

• Check whether taxes are included

• Track net rates

• Apply agency markup

• Prepare a final client price

• Create a professional proposal

• Answer client questions

• Complete the reservation

• Share confirmation details

When these tasks are handled across disconnected tools, the workflow becomes difficult to control.

Common problems include:

Inconsistent Data

The same property may appear differently across suppliers. Hotel names, room descriptions, meal plans, and cancellation conditions may not follow a consistent format.

Manual Pricing Errors

If net rates and markup are managed in spreadsheets or notes, an advisor may use the wrong rate or apply an incorrect calculation.

Scattered Client Information

Client preferences may remain buried inside emails, messages, or separate documents.

Unclear Hotel Quotes

Copied text and screenshots can make hotel recommendations difficult for clients to review.

Repeated Communication

Clients may repeatedly ask about room type, dates, inclusions, cancellation terms, and final pricing.

A structured booking platform needs to solve these operational problems rather than simply display hotel inventory.

A shared workflow can improve consistency across travel advisors and operational teams.

A Typical B2B Hotel Booking Workflow

A simplified workflow may look like this:

Hotel Search → Rate Review → Markup → Quote Creation → Client Review → Booking Confirmation

Each step has its own technical and operational requirements.

1. Hotel Search and Supplier Inventory

The first step is retrieving hotel inventory from one or more suppliers.

A hotel search request may include:

• Destination

• Check-in date

• Check-out date

• Number of rooms

• Number of adults

• Number of children

• Child ages

• Nationality

• Currency

• Preferred hotel category

The system then receives hotel availability, room types, rate plans, meal options, and booking conditions.

A platform must present this information clearly enough for the advisor to compare options without reviewing every supplier response manually.

Hotel inventory needs to be organized by property, room type, rate plan, and booking conditions.

2. Property and Room Mapping

Supplier data is rarely identical.

For example, one supplier may return:

• Deluxe King Room

Another may return:

• King Deluxe

A third may return:

• Deluxe Room, One King Bed

These descriptions may refer to the same room category.

A professional booking platform may need property and room mapping logic to reduce duplicate or inconsistent results.

The same applies to:

• Hotel names

• Property addresses

• Meal plans

• Bed types

• Cancellation policies

• Taxes and fees

• Occupancy rules

Without mapping and normalization, advisors may see duplicate properties or unclear room options.

3. Rate Review and Expiration

Hotel rates can change between the initial search and final booking.

Before a reservation is completed, the system may need to perform a rate recheck.

A rate recheck can confirm:

• Current availability

• Current price

• Currency

• Taxes

• Fees

• Cancellation deadline

• Payment conditions

• Room occupancy

This is important because a quote may remain open while the client considers several options.

The platform should clearly show whether the original rate is still valid or whether it has changed.

4. Pricing and Markup Logic

Travel agencies may receive a net rate and apply markup before showing a final price to the client.

Markup may be:

• A fixed amount

• A percentage

• Based on destination

• Based on hotel category

• Based on customer type

• Based on agency rules

A simplified pricing record may look like this:

{
  "propertyId": "HTL-1024",
  "roomType": "Deluxe King",
  "netRate": 1200,
  "markupType": "percentage",
  "markupValue": 20,
  "clientPrice": 1440,
  "currency": "USD",
  "cancellationPolicy": "Free cancellation until 48 hours before check-in"
}