Pattern: modify and cancel

When a guest changes the stay or cancels, your PMS must tell Effective Tours, or availability on the connected channels stays wrong. This pattern changes a reservation you created earlier, and cancels it, with a re-read after each write. See Integration patterns for the shared principles, and Pattern: create a booking safely for how the reservation got there.

Write calls are real. There is no sandbox: a change or a cancellation reaches the connected channels. Practise on bookings you created for the purpose, with dates far in the future, and cancel each one right after.

Steps

1. Change the reservation

PATCH changes only the fields you send. You can change dates (checkin, checkout), guest count (adults, children), guest fields, room_id, rate_id, accommodation, reference, comment and is_accepted. The body must contain id, and it must match the reservation_id in the URL. The server checks that the room is free for the new dates (not counting this reservation). Only the company that owns the reservation's room (the hotel owner) may update it; for any other company the reservation answers 404. See PATCH /hotels/{hotel_id}/reservations/{reservation_id}.

curl "https://api.effectivetours.com/v1/hotels/{hotel_id}/reservations/{reservation_id}" \
  -X PATCH \
  -H "Authorization: Bearer $ET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 4001, "checkin": "2027-06-11", "checkout": "2027-06-14", "adults": 2, "children": 1}'

Example response (abbreviated):

{
  "id": 4001,
  "checkin": "2027-06-11",
  "checkout": "2027-06-14",
  "is_accepted": true,
  "adults": 2,
  "children": 1,
  "reference_code": "PMS-2027-0001"
}

2. Read the reservation again

Compare the answer with what you meant to write. If a field differs, do not assume the write worked. See GET /hotels/{hotel_id}/reservations/{id}.

curl "https://api.effectivetours.com/v1/hotels/{hotel_id}/reservations/{id}" \
  -H "Authorization: Bearer $ET_API_KEY"

Example response (abbreviated):

{
  "id": 4001,
  "checkin": "2027-06-11",
  "checkout": "2027-06-14",
  "is_accepted": true,
  "adults": 2,
  "children": 1,
  "reference_code": "PMS-2027-0001"
}

3. Cancel the reservation

You have two ways to cancel.

By reference: cancels every live reservation your company created with that reference (and its direct children). You do not need to store the numeric id. A repeat cancel after everything is already cancelled is a success no-op. The answer is {"status": "OK", "cancelled": <count>}. See DELETE /hotels/{hotel_id}/reservations.

curl "https://api.effectivetours.com/v1/hotels/{hotel_id}/reservations?reference=PMS-2027-0001" \
  -X DELETE \
  -H "Authorization: Bearer $ET_API_KEY"

Example response:

{
  "status": "OK",
  "cancelled": 1
}

By numeric id: use it when you stored the Effective Tours id. Cancelling an already-cancelled reservation is a success no-op, so a retry is always safe. The answer is {"status": "OK"}. Only the company that created the reservation may delete it (the hotel owner may also delete a reservation that has no author); another company's reservation answers 404. See DELETE /hotels/{hotel_id}/reservations/{reservation_id}.

curl "https://api.effectivetours.com/v1/hotels/{hotel_id}/reservations/{reservation_id}" \
  -X DELETE \
  -H "Authorization: Bearer $ET_API_KEY"

Example response:

{
  "status": "OK"
}

4. Verify through the list

Read the reservation list for the window of the stay and check that the reservation is gone. Use both start and end. If it is still there, the cancellation did not take effect for that reservation: repeat the cancel (it is safe to repeat). See GET /hotels/{hotel_id}/reservations.

curl "https://api.effectivetours.com/v1/hotels/{hotel_id}/reservations?start=2027-06-01&end=2027-06-30" \
  -H "Authorization: Bearer $ET_API_KEY"

Example response (abbreviated: another reservation, and not the cancelled one):

[
  {
    "id": 4002,
    "checkin": "2027-06-20",
    "checkout": "2027-06-22",
    "is_accepted": true,
    "adults": 2,
    "children": 0,
    "is_fake": false,
    "room": {
      "id": 2001,
      "name": "Double Room 1",
      "sgl": false,
      "dbl": true,
      "tpl": false,
      "apartment": false,
      "is_virtual": false
    },
    "rate": {
      "id": 3001,
      "name": "Standard rate",
      "food": "RO"
    },
    "channel": null
  }
]

Related method page: Reservations.

What can go wrong