Skip to content
Gateway Stream

Booking Flow

Cancel

Preview what cancelling would cost, then cancel for real — two uses of the same endpoint, told apart by one required flag.

POST /api/v1/bookings/{bookingId}/cancel x-api-key

Request Body

simulation
boolean required
true previews the fee and changes nothing. false cancels at the supplier.
reason
string (≤500) optional
Why the booking is being cancelled. Recorded against the booking.
Simulate 
{
  "simulation": true
}

Simulating First

A simulation returns the booking's current status, unchanged, with simulation: true and the fee and refund that cancelling at this moment would mean. Nothing is cancelled and, for most distributors, nothing is even sent to the supplier.

200 OK · simulation 
{
  "bookingId": "0b5e1a92-6c3f-4a7d-8e21-9b4f0d3c5a18",
  "status": "CONFIRMED",
  "simulation": true,
  "cancellationFee": 82.00,
  "refundAmount": 82.00,
  "currency": "USD",
  "note": "A fee of 82 USD applies from 2026-11-30T00:00:00Z. Read from the cancellation policy stored at book time, not quoted by the supplier."
}

Where the figure comes from depends on whether the booking's source can price a cancellation without carrying it out:

  • It can: the source is asked, and the figure is its own quote.
  • It cannot — some sources have no preview at all, because asking what a cancellation would cost is the same as doing it, and some record their policy as free text rather than a quotable figure. Nothing is sent to them. The fee is computed here from the cancellation ladder stored with the booking, and a note on the response says so.

In the second case the rung in force is the last deadline already passed; nothing passed, or nothing recorded, reads as free.

Cancelling for Real

With simulation: false the cancel is carried out: the rooms are released, or the cancellation is passed to the hotel's own reservation system, whichever the booking needs.

200 OK · cancelled 
{
  "bookingId": "0b5e1a92-6c3f-4a7d-8e21-9b4f0d3c5a18",
  "status": "CANCELLED",
  "simulation": false,
  "cancellationFee": 82.00,
  "refundAmount": 82.00,
  "currency": "USD"
}

Reading the Answer

Only a definite cancellation moves a booking to CANCELLED. The API never claims an outcome the supplier did not give, which means a 200 is not on its own proof that anything was cancelled — read the status.

200 · status CANCELLED

Cancelled. cancellationFee is what the supplier charges, refundAmount is the supplier’s gross minus that fee.

Booking is now: CANCELLED

200 · status unchanged

The supplier answered, but the reservation is still live — the cancel did not take. Nothing changed.

Booking is now: as it was

502 · cancel_outcome_unknown

No definite outcome. The response says no more than that — quote its requestId. Confirm with Gateway Stream rather than resending.

Booking is now: CANCEL_REQUESTED

502 · supplier_error

The supplier rejected the call outright — already cancelled on their side, unknown reference, and so on.

Booking is now: put back to what it was

502 cancel_outcome_unknown 
{
  "error": {
    "code": "cancel_outcome_unknown",
    "message": "The cancellation could not be confirmed yet. The booking is held as pending cancellation; quote the requestId if you contact support.",
    "requestId": "req_01JD8QB7X2N4K8TD"
  }
}

Status Codes

200
The request was processed. Read status and simulation to know what actually happened.
400 validation_error
simulation missing, or an id in the path that is not a valid uuid.
401 unauthorized
Missing or invalid x-api-key.
404 not_found
No such booking for this key.
409 conflict
The booking is already cancelled. A second real cancel is a conflict, not a no-op.
502 cancel_outcome_unknown
The supplier gave no definite answer. The booking is left in CANCEL_REQUESTED.
502 supplier_error
The supplier rejected the cancel. The booking is put back to what it was.

A Switched-Off Distributor Can Still Cancel

Gateway Stream can stop a distributor from taking new sales without stopping it from servicing what it already sold. So a source being unavailable for search or booking is never a reason a cancellation fails — if a cancel fails, something else is wrong.

Fees Are the Supplier's Figures

cancellationFee and refundAmount describe the supplier side of the booking, not your sell price. If you added markup on top, work out what to refund the guest from your own records — the API does not know what you charged them.